GDAL-VECTOR-RASTERIZE(1) GDAL GDAL-VECTOR-RASTERIZE(1)
gdal-vector-rasterize - Burn vector geometries into a raster
Added in version 3.11.
Usage: gdal vector rasterize [OPTIONS] <INPUT> <OUTPUT>
Burns vector geometries into a raster.
Positional arguments:
-i, --input <INPUT> Input vector datasets [required]
-o, --output <OUTPUT> Output raster dataset [required]
Common Options:
-h, --help Display help message and exit
--json-usage Display usage as JSON document and exit
--config <KEY>=<VALUE> Configuration option [may be repeated]
-q, --quiet Quiet mode (no progress bar)
Options:
-f, --of, --format, --output-format <OUTPUT-FORMAT> Output format
--co, --creation-option <KEY>=<VALUE> Creation option [may be repeated]
--overwrite Whether overwriting existing output is allowed
-b, --band <BAND> The band(s) to burn values into (1-based index) [may be repeated]
--invert Invert the rasterization
--all-touched Enables the ALL_TOUCHED rasterization option
--burn <BURN> Burn value [may be repeated]
-a, --attribute-name <ATTRIBUTE-NAME> Attribute name
--3d Indicates that a burn value should be extracted from the Z values of the feature
-l, --input-layer <INPUT-LAYER> Input layer name
Mutually exclusive with --sql
--where <WHERE> SQL where clause
--sql <SQL> SQL select statement
Mutually exclusive with --input-layer
--dialect <DIALECT> SQL dialect
--nodata <NODATA> Assign a specified nodata value to output bands
--init <INIT> Pre-initialize output bands with specified value [may be repeated]
--crs <CRS> Override the projection for the output file
--transformer-option <NAME>=<VALUE> Set a transformer option suitable to pass to GDALCreateGenImgProjTransformer2 [may be repeated]
--extent <xmin>,<ymin>,<xmax>,<ymax> Set the target georeferenced extent [4 values]
--resolution <xres>,<yres> Set the target resolution [2 values]
Mutually exclusive with --size
--tap, --target-aligned-pixels (target aligned pixels) Align the coordinates of the extent of the output file to the values of the resolution
--size <xsize>,<ysize> Set the target size in pixels and lines [2 values]
Mutually exclusive with --resolution
--ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE> Output data type. OUTPUT-DATA-TYPE=Byte|Int8|UInt16|Int16|UInt32|Int32|UInt64|Int64|CInt16|CInt32|Float16|Float32|Float64|CFloat32|CFloat64
--optimization <OPTIMIZATION> Force the algorithm used (results are identical). OPTIMIZATION=AUTO|RASTER|VECTOR (default: AUTO)
--add Add to existing raster
--update Whether to open existing dataset in update mode
Advanced Options:
--oo, --open-option <KEY>=<VALUE> Open options [may be repeated]
--if, --input-format <INPUT-FORMAT> Input formats [may be repeated]
gdal vector rasterize burns vector geometries into a raster.
Since GDAL 3.12, this algorithm can be part of a gdal pipeline.
The left figure illustrates the default rasterization behavior, where
only pixels on the line render path are included.
The right figure shows the effect of --all-touched, where every pixel
that touches the input polygons is included.
The following options are available:
-f, --of, --format, --output-format <OUTPUT-FORMAT>
Which output raster format to use. Allowed values may be given
by gdal --formats | grep raster | grep rw | sort
--co, --creation-option <NAME>=<VALUE>
Many formats have one or more optional creation options that
can be used to control particulars about the file created. For
instance, the GeoTIFF driver supports creation options to
control compression, and whether the file should be tiled.
May be repeated.
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
--formats 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.
--band, -b <BAND>
The band(s) to burn values into. May be repeated.
--invert
Invert rasterization. Burn 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 the 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.
--all-touched
Enables the ALL_TOUCHED rasterization option.
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)
will determine the burned pixel value at the edge. You may
wish to use the --sql option to reorder the features (ORDER
BY) to achieve a more predictable result.
--burn <BURN>
Burn value. May be repeated.
-a, --attribute-name <ATTRIBUTE-NAME>
Attribute name.
--3d Indicates that a burn value should be extracted from the "Z"
values of the feature. Works with points and lines (linear
interpolation along each segment). For polygons, works
properly only if they are flat (same Z value for all
vertices).
--add Instead of burning a new value, this adds the new value to the
existing raster, implies --update. Suitable for heatmaps for
instance.
-l, --input-layer <INPUT-LAYER>
Indicates the layer(s) from the datasource that will be used
for input features. May be specified multiple times, but at
least one layer name or a -sql option must be specified (not
both).
--where <WHERE>
An optional SQL WHERE style query expression to be applied to
select features to burn in from the input layer(s).
--sql <SQL>|@<filename>
An SQL statement to be evaluated against the datasource to
produce a virtual layer of features to be burned in. The
@filename syntax can be used to indicate that the content is
in the pointed filename.
--dialect <DIALECT>
SQL dialect.
By default the native SQL of an RDBMS is used when using gdal
vector sql. If using sql as a step of gdal vector pipeline,
this is only true if the step preceding sql is read, otherwise
the OGRSQL dialect is used.
If a datasource does not support SQL natively, the default is
to use the OGRSQL dialect, which can also be specified with
any data source.
The SQL SQLite dialect dialect can be chosen with the SQLITE
and INDIRECT_SQLITE dialect values, and this can be used with
any data source. Overriding the default dialect may be
beneficial because the capabilities of the SQL dialects vary.
Supported dialects can be checked with gdal --format. For
example:
$ gdal --format "PostgreSQL"
[...]
Supported SQL dialects: NATIVE OGRSQL SQLITE
[...]
$ gdal --format "ESRI Shapefile"
[...]
Supported SQL dialects: OGRSQL SQLITE
[...]
--nodata <NODATA>
Assign a specified nodata value to output bands.
--init <INIT>
Pre-initialize output bands with specified value. May be
repeated.
--crs <CRS>
Override the projection for the output file. If not specified,
the projection of the input vector file will be used if
available. When using this option, no reprojection of features
from the CRS of the input vector to the specified CRS of the
output raster, so use only this option to correct an invalid
source CRS. The <CRS> may be any of the usual GDAL/OGR forms,
complete WKT, PROJ.4, EPSG:n or a file containing the WKT.
--transformer-option <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 this can be used to specify RPC related
transformer options.
--extent <xmin>,<ymin>,<xmax>,<ymax>
Set georeferenced extents. The values must be expressed in
georeferenced units. If not specified, the extent of the
output file will be the extent of the vector layers.
--resolution <xres>,<yres>
Set target resolution. The values must be expressed in
georeferenced units. Both must be positive values. Note that
--resolution cannot be used with --size.
--tap, --target-aligned-pixels
(target aligned pixels) Align the coordinates of the extent of
the output file to the values of --resolution, such that the
aligned extent includes the minimum extent. Alignment means
that xmin / resx, ymin / resy, xmax / resx and ymax / resy are
integer values.
--size <xsize>,<ysize>
Set output file size in pixels and lines. Note that --size
cannot be used with --resolution.
--ot, --datatype, --output-data-type <OUTPUT-DATA-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.
--optimization <OPTIMIZATION>
Force the algorithm used (results are identical). The raster
mode is used in most cases and optimise read/write operations.
The vector mode is useful with a decent amount of input
features and optimise the CPU use. That mode have to be used
with tiled images to be efficient. The auto mode (the default)
will chose the algorithm based on input and output properties.
--update
Whether to open existing dataset in update mode.
--overwrite
Whether overwriting existing output is allowed.
--oo, --open-option <NAME>=<VALUE>
Dataset open option (format specific).
May be repeated.
--if, --input-format <format>
Format/driver name to be attempted to open the input file(s).
It is generally not necessary to specify it, but it can be
used to skip automatic driver detection, when it fails to
select the appropriate driver. This option can be repeated
several times to specify several candidate drivers. Note that
it does not force those drivers to open the dataset. In
particular, some drivers have requirements on file extensions.
May be repeated.
Added in version 3.12.
GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET)
This program supports serializing the command line as a JSON file
using the GDALG output format. The resulting file can then be opened
as a raster dataset using the GDALG: GDAL Streamed Algorithm driver,
and apply the specified pipeline in a on-the-fly / streamed way.
NOTE:
However this algorithm is not natively streaming compatible.
Consequently a temporary dataset will be generated, which may
cause significant processing time at opening.
Example 1: Burn a shapefile into a raster
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 vector rasterize -b 1,2,3 --burn 255,0,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.
Burn a shapefile into a raster using a specific where condition to
select features
gdal vector 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:
-b is not used; the order of the --burn options determines the
bands of the output raster.
gdal vector rasterize --burn 255,0,0 --ot Byte --size 1000,1000 -l footprints footprints.shp mask.tif
Alessandro Pasotti <elpaso@itopen.it>
1998-2026
March 20, 2026 GDAL-VECTOR-RASTERIZE(1)
NAME
gdal-vector-rasterize - Burn vector geometries into a raster
Added in version 3.11.
SYNOPSIS
Usage: gdal vector rasterize [OPTIONS] <INPUT> <OUTPUT>
Burns vector geometries into a raster.
Positional arguments:
-i, --input <INPUT> Input vector datasets [required]
-o, --output <OUTPUT> Output raster dataset [required]
Common Options:
-h, --help Display help message and exit
--json-usage Display usage as JSON document and exit
--config <KEY>=<VALUE> Configuration option [may be repeated]
-q, --quiet Quiet mode (no progress bar)
Options:
-f, --of, --format, --output-format <OUTPUT-FORMAT> Output format
--co, --creation-option <KEY>=<VALUE> Creation option [may be repeated]
--overwrite Whether overwriting existing output is allowed
-b, --band <BAND> The band(s) to burn values into (1-based index) [may be repeated]
--invert Invert the rasterization
--all-touched Enables the ALL_TOUCHED rasterization option
--burn <BURN> Burn value [may be repeated]
-a, --attribute-name <ATTRIBUTE-NAME> Attribute name
--3d Indicates that a burn value should be extracted from the Z values of the feature
-l, --input-layer <INPUT-LAYER> Input layer name
Mutually exclusive with --sql
--where <WHERE> SQL where clause
--sql <SQL> SQL select statement
Mutually exclusive with --input-layer
--dialect <DIALECT> SQL dialect
--nodata <NODATA> Assign a specified nodata value to output bands
--init <INIT> Pre-initialize output bands with specified value [may be repeated]
--crs <CRS> Override the projection for the output file
--transformer-option <NAME>=<VALUE> Set a transformer option suitable to pass to GDALCreateGenImgProjTransformer2 [may be repeated]
--extent <xmin>,<ymin>,<xmax>,<ymax> Set the target georeferenced extent [4 values]
--resolution <xres>,<yres> Set the target resolution [2 values]
Mutually exclusive with --size
--tap, --target-aligned-pixels (target aligned pixels) Align the coordinates of the extent of the output file to the values of the resolution
--size <xsize>,<ysize> Set the target size in pixels and lines [2 values]
Mutually exclusive with --resolution
--ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE> Output data type. OUTPUT-DATA-TYPE=Byte|Int8|UInt16|Int16|UInt32|Int32|UInt64|Int64|CInt16|CInt32|Float16|Float32|Float64|CFloat32|CFloat64
--optimization <OPTIMIZATION> Force the algorithm used (results are identical). OPTIMIZATION=AUTO|RASTER|VECTOR (default: AUTO)
--add Add to existing raster
--update Whether to open existing dataset in update mode
Advanced Options:
--oo, --open-option <KEY>=<VALUE> Open options [may be repeated]
--if, --input-format <INPUT-FORMAT> Input formats [may be repeated]
DESCRIPTION
gdal vector rasterize burns vector geometries into a raster.
Since GDAL 3.12, this algorithm can be part of a gdal pipeline.
The left figure illustrates the default rasterization behavior, where
only pixels on the line render path are included.
The right figure shows the effect of --all-touched, where every pixel
that touches the input polygons is included.
The following options are available:
Standard options
-f, --of, --format, --output-format <OUTPUT-FORMAT>
Which output raster format to use. Allowed values may be given
by gdal --formats | grep raster | grep rw | sort
--co, --creation-option <NAME>=<VALUE>
Many formats have one or more optional creation options that
can be used to control particulars about the file created. For
instance, the GeoTIFF driver supports creation options to
control compression, and whether the file should be tiled.
May be repeated.
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
--formats 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.
--band, -b <BAND>
The band(s) to burn values into. May be repeated.
--invert
Invert rasterization. Burn 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 the 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.
--all-touched
Enables the ALL_TOUCHED rasterization option.
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)
will determine the burned pixel value at the edge. You may
wish to use the --sql option to reorder the features (ORDER
BY) to achieve a more predictable result.
--burn <BURN>
Burn value. May be repeated.
-a, --attribute-name <ATTRIBUTE-NAME>
Attribute name.
--3d Indicates that a burn value should be extracted from the "Z"
values of the feature. Works with points and lines (linear
interpolation along each segment). For polygons, works
properly only if they are flat (same Z value for all
vertices).
--add Instead of burning a new value, this adds the new value to the
existing raster, implies --update. Suitable for heatmaps for
instance.
-l, --input-layer <INPUT-LAYER>
Indicates the layer(s) from the datasource that will be used
for input features. May be specified multiple times, but at
least one layer name or a -sql option must be specified (not
both).
--where <WHERE>
An optional SQL WHERE style query expression to be applied to
select features to burn in from the input layer(s).
--sql <SQL>|@<filename>
An SQL statement to be evaluated against the datasource to
produce a virtual layer of features to be burned in. The
@filename syntax can be used to indicate that the content is
in the pointed filename.
--dialect <DIALECT>
SQL dialect.
By default the native SQL of an RDBMS is used when using gdal
vector sql. If using sql as a step of gdal vector pipeline,
this is only true if the step preceding sql is read, otherwise
the OGRSQL dialect is used.
If a datasource does not support SQL natively, the default is
to use the OGRSQL dialect, which can also be specified with
any data source.
The SQL SQLite dialect dialect can be chosen with the SQLITE
and INDIRECT_SQLITE dialect values, and this can be used with
any data source. Overriding the default dialect may be
beneficial because the capabilities of the SQL dialects vary.
Supported dialects can be checked with gdal --format. For
example:
$ gdal --format "PostgreSQL"
[...]
Supported SQL dialects: NATIVE OGRSQL SQLITE
[...]
$ gdal --format "ESRI Shapefile"
[...]
Supported SQL dialects: OGRSQL SQLITE
[...]
--nodata <NODATA>
Assign a specified nodata value to output bands.
--init <INIT>
Pre-initialize output bands with specified value. May be
repeated.
--crs <CRS>
Override the projection for the output file. If not specified,
the projection of the input vector file will be used if
available. When using this option, no reprojection of features
from the CRS of the input vector to the specified CRS of the
output raster, so use only this option to correct an invalid
source CRS. The <CRS> may be any of the usual GDAL/OGR forms,
complete WKT, PROJ.4, EPSG:n or a file containing the WKT.
--transformer-option <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 this can be used to specify RPC related
transformer options.
--extent <xmin>,<ymin>,<xmax>,<ymax>
Set georeferenced extents. The values must be expressed in
georeferenced units. If not specified, the extent of the
output file will be the extent of the vector layers.
--resolution <xres>,<yres>
Set target resolution. The values must be expressed in
georeferenced units. Both must be positive values. Note that
--resolution cannot be used with --size.
--tap, --target-aligned-pixels
(target aligned pixels) Align the coordinates of the extent of
the output file to the values of --resolution, such that the
aligned extent includes the minimum extent. Alignment means
that xmin / resx, ymin / resy, xmax / resx and ymax / resy are
integer values.
--size <xsize>,<ysize>
Set output file size in pixels and lines. Note that --size
cannot be used with --resolution.
--ot, --datatype, --output-data-type <OUTPUT-DATA-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.
--optimization <OPTIMIZATION>
Force the algorithm used (results are identical). The raster
mode is used in most cases and optimise read/write operations.
The vector mode is useful with a decent amount of input
features and optimise the CPU use. That mode have to be used
with tiled images to be efficient. The auto mode (the default)
will chose the algorithm based on input and output properties.
--update
Whether to open existing dataset in update mode.
--overwrite
Whether overwriting existing output is allowed.
Advanced options
--oo, --open-option <NAME>=<VALUE>
Dataset open option (format specific).
May be repeated.
--if, --input-format <format>
Format/driver name to be attempted to open the input file(s).
It is generally not necessary to specify it, but it can be
used to skip automatic driver detection, when it fails to
select the appropriate driver. This option can be repeated
several times to specify several candidate drivers. Note that
it does not force those drivers to open the dataset. In
particular, some drivers have requirements on file extensions.
May be repeated.
Added in version 3.12.
GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET)
This program supports serializing the command line as a JSON file
using the GDALG output format. The resulting file can then be opened
as a raster dataset using the GDALG: GDAL Streamed Algorithm driver,
and apply the specified pipeline in a on-the-fly / streamed way.
NOTE:
However this algorithm is not natively streaming compatible.
Consequently a temporary dataset will be generated, which may
cause significant processing time at opening.
EXAMPLES
Example 1: Burn a shapefile into a raster
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 vector rasterize -b 1,2,3 --burn 255,0,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.
Burn a shapefile into a raster using a specific where condition to
select features
gdal vector 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:
-b is not used; the order of the --burn options determines the
bands of the output raster.
gdal vector rasterize --burn 255,0,0 --ot Byte --size 1000,1000 -l footprints footprints.shp mask.tif
AUTHOR
Alessandro Pasotti <elpaso@itopen.it>
COPYRIGHT
1998-2026
March 20, 2026 GDAL-VECTOR-RASTERIZE(1)