GDAL_RASTERIZE(1)

📦
version 3.13.3 · 11 versions
, in alpine 3.24, arch rolling, ubuntu stonking

✨ GDAL_RASTERIZE(1) ✨

okay bestie, welcome to the GDAL manual, page gdal_rasterize (section 1) 💖 this is the one that takes your vector shapes and burns them into a raster. iconic behavior honestly.

🌸 NAME 🌸

gdal_rasterize — burns vector geometries into a raster. 🔥

🦋 SYNOPSIS 🦋

Usage: gdal_rasterize [--help] [--long-usage] [--help-general]
                      [-b <band>]... [-i] [-at]
                      [[-burn <value>]...|[-a <attribute_name>]|[-3d]]
                      [-add]
                      [[-l <layer_name>]...|[-sql <sql_statement>]]
                      [-where <expression>] [-dialect <sql_dialect>]
                      [-a_nodata <value>] [-init <value>]... [-a_srs <srs_def>]
                      [-to <NAME>=<VALUE>]... [-te <xmin> <ymin> <xmax> <ymax>]
                      [[-tr <xres> <yres>]|[-ts <width> <height>]]
                      [-tap] [-optim AUTO|VECTOR|RASTER] [-co <NAME>=<VALUE>]...
                      [-ot Byte|Int8|[U]Int{16|32|64}|CInt{16|32}|[C]Float{32|64}]
                      [-of <output_format>] [--quiet] [-oo <NAME>=<VALUE>]...
                      <src_datasource> <dst_filename>

💅 DESCRIPTION 💅

So like. This program burns vector geometries — points, lines, and polygons — into the raster band(s) of a raster image. The vectors get read from any OGR supported vector format. And if the output raster already exists? The affected pixels get updated in-place. no fuss, no mess. ✨

On the fly reprojection of vector data to the coordinate system of the raster data is supported. slay.

TIP: there's an equivalent in the new gdal command line interface — go peep gdal vector rasterize. 🫶

🎀 the big options list 🎀

  • --help — shows this help message and dips. 👋
  • --help-general — gives you a brief usage message for the generic GDAL commandline options, then exits.
  • -q, --quiet — suppress progress messages and other non-error output. shhh. 🤫
  • -b <band> — the band(s) to burn values into. You can stack multiple -b arguments to burn into a whole list of bands. Default is to burn into band 1. Not used when creating a new raster.
  • -i — invert rasterization. Burns the fixed burn value, or the burn value associated with the first feature, into all parts of the image not inside the provided polygon.
NOTE: when your vector features contain a polygon nested within another polygon (like an island in a lake 🏝️), GDAL must be built against GEOS to get correct results. no GEOS, no correct island. that's just how it is.
  • -at — enables the ALL_TOUCHED rasterization option, so all pixels touched by lines or polygons get updated, not just the ones on the line render path or whose center point is inside the polygon. (behavior is unspecified when the polygon is just touching the pixel center, so like… don't be weird about it). Defaults to disabled for normal rendering rules.
NOTE: when this option is enabled, the order of the input features (lines or polygons) can affect the results. When two features touch each other, the last one (i.e. topmost) determines the burned pixel value at the edge. You may wish to use the -sql option to reorder the features (ORDER BY) to get a more predictable result. predictability is self-care.
  • -burn <value> — a fixed value to burn into a band for all objects. You can hand it a list of -burn options, one per band being written to. 🔥
  • -a <attribute_name> — names an attribute field on the features to use as the burn-in value. That value gets burned into all output bands.
  • -3d — says "hey, pull the burn value from the "Z" values of the feature." Works with points and lines (linear interpolation along each segment). For polygons it only works properly if they're flat (same Z value for all vertices). 🧊
  • -add — instead of burning a new value, this adds the new value to the existing raster. Perfect for heatmaps, bestie. 🌡️
  • -l <layername> — names the layer(s) from the datasource that'll be used for input features. Can be specified multiple times, but you need at least one layer name or a -sql option — not both. pick a lane. 🚦
  • -where <expression> — an optional SQL WHERE style query expression to narrow down which features to burn in from the input layer(s).
  • -sql <select_statement> — an SQL statement evaluated against the datasource to produce a virtual layer of features to be burned in. Starting with GDAL 3.7, the @filename syntax can be used to indicate that the content is in the pointed filename.
NOTE: this option gets ignored if the -l option has been set as well. yeah. they don't share.
  • -dialect <dialect> — SQL dialect. Sometimes you can use it to make it use (unoptimized) OGR SQL instead of the native SQL of an RDBMS by passing OGRSQL. The "SQLITE" dialect can also be used with any datasource. 💅
  • -of <format> — select the output format. If you don't specify it, the format is guessed from the extension. Use the short format name.
  • -a_nodata <value> — assign a specified nodata value to output bands.
  • -init <value> — pre-initialize the output image bands with these values. However, it is not marked as the nodata value in the output file. If only one value is given, the same value is used in all the bands.
  • -a_srs <srs_def> — override the projection for the output file. If not specified, the projection of the input vector file is used if available. When using this option, no reprojection of features from the SRS of the input vector to the specified SRS of the output raster happens — so only use this option to correct an invalid source SRS. The <srs_def> may be any of the usual GDAL/OGR forms: complete WKT, PROJ.4, EPSG:n or a file containing the WKT.
  • -to <NAME>=<VALUE> — set a transformer option suitable to pass to GDALCreateGenImgProjTransformer2(). This is used when converting geometries coordinates to target raster pixel space. For example it can be used to specify RPC related transformer options.
  • -co <NAME>=<VALUE> — lots of formats have one or more optional creation options that control particulars about the file created. For instance, the GeoTIFF driver supports creation options to control compression, and whether the file should be tiled.

The creation options available vary by format driver, and some simple formats have no creation options at all. A list of options supported for a format can be listed with the --format command line option, but the documentation for the format is the definitive source of information on driver creation options. See Raster drivers format specific documentation for legal creation options for each format.

  • -te <xmin> <ymin> <xmax> <ymax> — set georeferenced extents. The values must be expressed in georeferenced units. If you don't specify, the extent of the output file will be the extent of the vector layers.
  • -tr <xres> <yres> — set target resolution. The values must be expressed in georeferenced units. Both must be positive values. 🔥
  • -tap — (target aligned pixels) aligns the coordinates of the extent of the output file to the values of the -tr, such that the aligned extent includes the minimum extent. Alignment means that xmin / resx, ymin / resy, xmax / resx and ymax / resy are integer values. math ate that. 🧮
  • -ts <width> <height> — set output file size in pixels and lines. Note that -ts cannot be used with -tr. If one of the two values is set to 0, it'll be computed from the other value in order to preserve the aspect ratio. thoughtful. 🫶
  • -ot <type> — force the output bands to be of the indicated data type. Defaults to Float64, unless the attribute field to burn is of type Int64, in which case Int64 is used for the output raster data type if the output driver supports it.
  • -optim {AUTO|VECTOR|RASTER} — force the algorithm used (results are identical, it's giving same energy either way ✨). Raster mode is used in most cases and optimizes read/write operations. The vector mode is useful with a large amount of input features and optimizes CPU use — provided that the output image is tiled. Auto mode (the default) will choose the algorithm based on input and output properties.
  • -oo <NAME>=<VALUE> — added in version 3.7. Source dataset open option (format specific). 🆕
  • <src_datasource> — any OGR supported readable datasource.
  • <dst_filename> — the GDAL supported output file. Must support update mode access. This file will be created if it does not already exist. If the output raster already exists, the affected pixels are updated in-place.

The program creates a new target raster image when any of the -of, -a_nodata, -init, -a_srs, -co, -te, -tr, -tap, -ts, or -ot options are used. The resolution or size must be specified using the -tr or -ts option for all new rasters. The target raster will be overwritten if it already exists and any of these creation-related options are used. bestie. be careful. 💀

🌈 RETURN STATUS CODE 🌈

The program returns status code 0 in case of success, and non-zero in case of error (non-blocking errors emitted as warnings are considered as a successful execution). so a warning is not a fail, it's just a lil note. 💌

🧚 C API 🧚

This utility is also callable from C with GDALRasterize().

👑 EXAMPLES 👑

Example 1

The following would burn all polygons from mask.shp into the RGB TIFF file work.tif with the color red (RGB = 255,0,0).

gdal_rasterize -b 1 -b 2 -b 3 -burn 255 -burn 0 -burn 0 -l mask mask.shp work.tif

Example 2

The following would burn all "class A" buildings into the output elevation file, pulling the top elevation from the ROOF_H attribute.

gdal_rasterize -a ROOF_H -where "class='A'" -l footprints footprints.shp city_dem.tif

Example 3

The following would burn all polygons from footprint.shp into a new 1000x1000 rgb TIFF as the color red. Note that -b is not used; the order of the -burn options determines the bands of the output raster. ✨

gdal_rasterize -burn 255 -burn 0 -burn 0 -ot Byte -ts 1000 1000 -l footprints footprints.shp mask.tif

💜 AUTHOR 💜

Frank Warmerdam <warmerdam@pobox.com>

1998-2026

and that's the whole page, bestie!! 💖 this was GDAL, page GDAL_RASTERIZE(1), from GDAL, dated Aug 18, 2026. go burn some polygons into a raster, you absolute icon. 🦋✨👑

📦 where this page comes from