GDAL_RASTERIZE(1) GDAL GDAL_RASTERIZE(1)

NAME

gdal_rasterize - Burns vector geometries into a raster.

SYNOPSIS

gdal_rasterize [--help] [--help-general]
[-b <band>]... [-i] [-at]
[-oo <NAME>=<VALUE>]...
{[-burn <value>]... | [-a <attribute_name>] | [-3d]} [-add]
[-l <layername>]... [-where <expression>] [-sql <select_statement>|@<filename>]
[-dialect <dialect>] [-of <format>] [-a_srs <srs_def>] [-to <NAME>=<VALUE>]...
[-co <NAME>=<VALUE>]... [-a_nodata <value>] [-init <value>]...
[-te <xmin> <ymin> <xmax> <ymax>] [-tr <xres> <yres>] [-tap] [-ts <width> <height>]
[-ot {Byte/Int8/Int16/UInt16/UInt32/Int32/UInt64/Int64/Float32/Float64/
CInt16/CInt32/CFloat32/CFloat64}] [-optim {AUTO|VECTOR|RASTER}] [-q]
<src_datasource> <dst_filename>

DESCRIPTION

This program burns vector geometries (points, lines, and polygons)
into the raster band(s) of a raster image. Vectors are read from OGR
supported vector formats. If the output raster already exists, the
affected pixels are updated in-place.

Note that on the fly reprojection of vector data to the coordinate
system of the raster data is only supported since GDAL 2.1.0.

--help Show this help message and exit

--help-general
Gives a brief usage message for the generic GDAL commandline
options and exit.

-b <band>
The band(s) to burn values into. Multiple -b arguments may be
used to burn into a list of bands. The default is to burn
into band 1. Not used when creating a new raster.

-i 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.

-at Enables the ALL_TOUCHED rasterization option so that all
pixels touched by lines or polygons will be updated, not just
those on the line render path, or whose center point is within
the polygon (behavior is unspecified when the polygon is just
touching the pixel center). 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)
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 <value>
A fixed value to burn into a band for all objects. A list of
-burn options can be supplied, one per band being written to.

-a <attribute_name>
Identifies an attribute field on the features to be used for a
burn-in value. The value will be burned into all output
bands.

-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 the are flat (same Z value for all vertices).

-add Instead of burning a new value, this adds the new value to the
existing raster. Suitable for heatmaps for instance.

-l <layername>
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 <expression>
An optional SQL WHERE style query expression to be applied to
select features to burn in from the input layer(s).

-sql <select_statement>
An SQL statement to be 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 will be ignored if the -l option has been set
as well.

-dialect <dialect>
SQL dialect. In some cases can be used to 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.

New in version 2.1.


-of <format>
Select the output format. Starting with GDAL 2.3, if not
specified, the format is guessed from the extension
(previously was GTiff). 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 will be 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, so use only 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 this can be used to specify RPC related
transformer options.

New in version 2.3.


-co <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.

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.

-te <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.

-tr <xres> <yres>
Set target resolution. The values must be expressed in
georeferenced units. Both must be positive values.

-tap (target aligned pixels) Align 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.

-ts <width> <height>
Set output file size in pixels and lines. Note that -ts cannot
be used with -tr

-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). 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.

New in version 2.3.


-oo <NAME>=<VALUE>
New in version 3.7.


Source dataset open option (format specific)

-q Suppress progress monitor and other non-error output.

<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.

C API

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

New in version 2.1.

EXAMPLES

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

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

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>

COPYRIGHT

1998-2025

January 8, 2025 GDAL_RASTERIZE(1)