GDAL-RASTER-FOOTPRINT(1) GDAL GDAL-RASTER-FOOTPRINT(1)
gdal-raster-footprint - Compute the footprint of a raster dataset
Added in version 3.11.
Usage: gdal raster footprint [OPTIONS] <INPUT>... <OUTPUT>
Compute the footprint of a raster dataset.
Positional arguments:
-i, --input <INPUT> Input raster datasets [may be repeated] [required]
-o, --output <OUTPUT> Output vector 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]
--lco, --layer-creation-option <KEY>=<VALUE> Layer creation option [may be repeated]
--append Whether appending to existing layer is allowed
--overwrite Whether overwriting existing output is allowed
--output-layer <OUTPUT-LAYER> Output layer name (default: footprint)
-b, --band <BAND> Input band(s) (1-based index) [may be repeated]
--combine-bands <COMBINE-BANDS> Defines how the mask bands of the selected bands are combined to generate a single mask band, before being vectorized.. COMBINE-BANDS=union|intersection (default: union)
--overview <OVERVIEW> Which overview level of source file must be used
Mutually exclusive with --src-nodata
--src-nodata <SRC-NODATA> Set nodata values for input bands. [1.. values]
Mutually exclusive with --overview
--coordinate-system <COORDINATE-SYSTEM> Target coordinate system. COORDINATE-SYSTEM=georeferenced|pixel
--dst-crs <DST-CRS> Destination CRS
--split-multipolygons Whether to split multipolygons as several features each with one single polygon
--convex-hull Whether to compute the convex hull of the footprint
--densify-distance <DENSIFY-DISTANCE> Maximum distance between 2 consecutive points of the output geometry.
--simplify-tolerance <SIMPLIFY-TOLERANCE> Tolerance used to merge consecutive points of the output geometry.
--min-ring-area <MIN-RING-AREA> Minimum value for the area of a ring
--max-points <MAX-POINTS> Maximum number of points of each output geometry (default: 100)
--location-field <LOCATION-FIELD> Name of the field where the path of the input dataset will be stored. (default: location)
Mutually exclusive with --no-location-field
--no-location-field Disable creating a field with the path of the input dataset
Mutually exclusive with --location-field
--absolute-path Whether the path to the input dataset should be stored as an absolute path
Advanced Options:
--oo, --open-option <KEY>=<VALUE> Open options [may be repeated]
--if, --input-format <INPUT-FORMAT> Input formats [may be repeated]
gdal raster footprint computes the footprint of a raster file, taking
into account nodata values (or more generally the mask band attached
to the raster bands), and generating polygons/multipolygons
corresponding to areas where pixels are valid, and write to an output
vector file.
Since GDAL 3.12, this algorithm can be part of a gdal pipeline.
The gdal raster clean-collar utility may be run as a pre-processing
step to generate proper mask bands.
[image]
Example footprint calculated with default options of gdal raster
footprint.
The following options are available:
-f, --of, --format, --output-format <OUTPUT-FORMAT>
Which output vector format to use. Allowed values may be given
by gdal --formats | grep vector | 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.
--lco, --layer-creation-option <NAME>=<VALUE>
Many formats have one or more optional layer creation options
that can be used to control particulars about the layer
created. For instance, the GeoPackage driver supports layer
creation options to control the feature identifier or geometry
column name, setting the identifier or description, etc.
May be repeated.
The layer creation options available vary by format driver,
and some simple formats have no layer 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 Vector drivers format specific
documentation for legal creation options for each format.
Note that layer creation options are different from dataset
creation options.
--output-layer <OUTPUT-LAYER>
Output layer name. Defaults to footprint.
--overwrite
Allow program to overwrite existing target file or dataset.
Otherwise, by default, gdal errors out if the target file or
dataset already exists.
--append
Whether appending features to existing layer(s) is allowed
-b <band>
Select an input <band> to be processed. Bands are numbered
from 1. Multiple -b switches may be used to select a set of
input bands. If not specified, all bands are taken into
account. The way multiple bands are combined is controlled by
--combine-bands
--combine-bands union|intersection
Defines how the mask bands of the selected bands are combined
to generate a single mask band, before being vectorized. The
default value is union: that is a pixel is valid if it is
valid at least for one of the selected bands. intersection
means that a pixel is valid only if it is valid for all
selected bands.
--overview <index>
To specify which overview level of source file must be used,
when overviews are available on the source raster. By default
the full resolution level is used. The index is 0-based, that
is 0 means the first overview level. This option is mutually
exclusive with --src-nodata.
--src-nodata <value>
Set nodata values for input bands (different values can be
supplied for each band). If a single value is specified, it
applies to all selected bands. If more than one value is
supplied, there should be as many values as the number of
selected bands, and all values should be quoted to keep them
together as a single operating system argument. If the option
is not specified, the intrinsic mask band of each selected
bands will be used.
--coordinate-system pixel|georeferenced
Target coordinate system. By default if the input dataset is
georeferenced, georeferenced is implied, that is the footprint
geometry will be expressed as coordinates in the CRS of the
raster (or the one specified with --dst-crs). If specifying
pixel, the coordinates of the footprint geometry are column
and line indices.
--dst-crs <CRS_DEF>
Target CRS of the output file. The <CRS_DEF> may be any of
the usual GDAL/OGR forms, complete WKT, PROJ.4, EPSG:n or a
file containing the WKT. Specifying this option implies
--coordinate-system=georeferenced. The footprint is
reprojected from the CRS of the source raster to the specified
CRS.
--split-multipolygons
When specified, multipolygons are split as several features
each with one single polygon.
--convex-hull
When specified, the convex hull of (multi)polygons is
computed.
--densify-distance <value>
The specified value of this option is the maximum distance
between 2 consecutive points of the output geometry. The unit
of the distance is in pixels if --coordinate-system equals
pixel, or otherwise in georeferenced units of the source
raster. This option is applied before the reprojection
implied by --dst-crs.
--simplify-tolerance <value>
The specified value of this option is the tolerance used to
merge consecutive points of the output geometry using the
OGRGeometry::Simplify() method. The unit of the distance is
in pixels if --coordinate-system equals pixel, or otherwise in
georeferenced units of the target vector dataset. This option
is applied after the reprojection implied by --dst-crs.
--min-ring-area <value>
Minimum value for the area of a ring The unit of the area is
in square pixels if --coordinate-system equals pixel, or
otherwise in georeferenced units of the target vector dataset.
This option is applied after the reprojection implied by
--dst-crs
--max-points <value>|unlimited
Maximum number of points of each output geometry (not counting
the closing point of each ring, which is always identical to
the first point). The default value is 100. unlimited can be
used to remove that limitation.
--location-field <field_name>
Specifies the name of the field in the resulting vector
dataset where the path of the input dataset will be stored.
The default field name is "location". To prevent writing the
path of the input dataset, use --no-location-field
--no-location-field
Turns off the writing of the path of the input dataset as a
field in the output vector dataset.
--absolute-path
Enables writing the absolute path of the input dataset. By
default, the filename is written in the location field exactly
as specified on the command line.
Post-vectorization geometric operations are applied in the following
order:
+o optional splitting (--split-multipolygons)
+o optional densification (--densify-distance)
+o optional reprojection (--dst-crs)
+o optional filtering by minimum ring area (--min-ring-area)
+o optional application of convex hull (--convex-hull)
+o optional simplification (--simplify-tolerance)
+o limitation of number of points (--max-points)
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 vector 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 in-memory temporary dataset will be generated,
which may cause significant processing time at opening.
Example 1: Write the footprint of a GeoTIFF file into a GeoJSON file.
gdal raster footprint my_raster.tif footprint.geojson
Even Rouault <even.rouault@spatialys.com>
1998-2026
March 20, 2026 GDAL-RASTER-FOOTPRINT(1)
NAME
gdal-raster-footprint - Compute the footprint of a raster dataset
Added in version 3.11.
SYNOPSIS
Usage: gdal raster footprint [OPTIONS] <INPUT>... <OUTPUT>
Compute the footprint of a raster dataset.
Positional arguments:
-i, --input <INPUT> Input raster datasets [may be repeated] [required]
-o, --output <OUTPUT> Output vector 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]
--lco, --layer-creation-option <KEY>=<VALUE> Layer creation option [may be repeated]
--append Whether appending to existing layer is allowed
--overwrite Whether overwriting existing output is allowed
--output-layer <OUTPUT-LAYER> Output layer name (default: footprint)
-b, --band <BAND> Input band(s) (1-based index) [may be repeated]
--combine-bands <COMBINE-BANDS> Defines how the mask bands of the selected bands are combined to generate a single mask band, before being vectorized.. COMBINE-BANDS=union|intersection (default: union)
--overview <OVERVIEW> Which overview level of source file must be used
Mutually exclusive with --src-nodata
--src-nodata <SRC-NODATA> Set nodata values for input bands. [1.. values]
Mutually exclusive with --overview
--coordinate-system <COORDINATE-SYSTEM> Target coordinate system. COORDINATE-SYSTEM=georeferenced|pixel
--dst-crs <DST-CRS> Destination CRS
--split-multipolygons Whether to split multipolygons as several features each with one single polygon
--convex-hull Whether to compute the convex hull of the footprint
--densify-distance <DENSIFY-DISTANCE> Maximum distance between 2 consecutive points of the output geometry.
--simplify-tolerance <SIMPLIFY-TOLERANCE> Tolerance used to merge consecutive points of the output geometry.
--min-ring-area <MIN-RING-AREA> Minimum value for the area of a ring
--max-points <MAX-POINTS> Maximum number of points of each output geometry (default: 100)
--location-field <LOCATION-FIELD> Name of the field where the path of the input dataset will be stored. (default: location)
Mutually exclusive with --no-location-field
--no-location-field Disable creating a field with the path of the input dataset
Mutually exclusive with --location-field
--absolute-path Whether the path to the input dataset should be stored as an absolute path
Advanced Options:
--oo, --open-option <KEY>=<VALUE> Open options [may be repeated]
--if, --input-format <INPUT-FORMAT> Input formats [may be repeated]
DESCRIPTION
gdal raster footprint computes the footprint of a raster file, taking
into account nodata values (or more generally the mask band attached
to the raster bands), and generating polygons/multipolygons
corresponding to areas where pixels are valid, and write to an output
vector file.
Since GDAL 3.12, this algorithm can be part of a gdal pipeline.
The gdal raster clean-collar utility may be run as a pre-processing
step to generate proper mask bands.
[image]
Example footprint calculated with default options of gdal raster
footprint.
The following options are available:
-f, --of, --format, --output-format <OUTPUT-FORMAT>
Which output vector format to use. Allowed values may be given
by gdal --formats | grep vector | 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.
--lco, --layer-creation-option <NAME>=<VALUE>
Many formats have one or more optional layer creation options
that can be used to control particulars about the layer
created. For instance, the GeoPackage driver supports layer
creation options to control the feature identifier or geometry
column name, setting the identifier or description, etc.
May be repeated.
The layer creation options available vary by format driver,
and some simple formats have no layer 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 Vector drivers format specific
documentation for legal creation options for each format.
Note that layer creation options are different from dataset
creation options.
--output-layer <OUTPUT-LAYER>
Output layer name. Defaults to footprint.
--overwrite
Allow program to overwrite existing target file or dataset.
Otherwise, by default, gdal errors out if the target file or
dataset already exists.
--append
Whether appending features to existing layer(s) is allowed
-b <band>
Select an input <band> to be processed. Bands are numbered
from 1. Multiple -b switches may be used to select a set of
input bands. If not specified, all bands are taken into
account. The way multiple bands are combined is controlled by
--combine-bands
--combine-bands union|intersection
Defines how the mask bands of the selected bands are combined
to generate a single mask band, before being vectorized. The
default value is union: that is a pixel is valid if it is
valid at least for one of the selected bands. intersection
means that a pixel is valid only if it is valid for all
selected bands.
--overview <index>
To specify which overview level of source file must be used,
when overviews are available on the source raster. By default
the full resolution level is used. The index is 0-based, that
is 0 means the first overview level. This option is mutually
exclusive with --src-nodata.
--src-nodata <value>
Set nodata values for input bands (different values can be
supplied for each band). If a single value is specified, it
applies to all selected bands. If more than one value is
supplied, there should be as many values as the number of
selected bands, and all values should be quoted to keep them
together as a single operating system argument. If the option
is not specified, the intrinsic mask band of each selected
bands will be used.
--coordinate-system pixel|georeferenced
Target coordinate system. By default if the input dataset is
georeferenced, georeferenced is implied, that is the footprint
geometry will be expressed as coordinates in the CRS of the
raster (or the one specified with --dst-crs). If specifying
pixel, the coordinates of the footprint geometry are column
and line indices.
--dst-crs <CRS_DEF>
Target CRS of the output file. The <CRS_DEF> may be any of
the usual GDAL/OGR forms, complete WKT, PROJ.4, EPSG:n or a
file containing the WKT. Specifying this option implies
--coordinate-system=georeferenced. The footprint is
reprojected from the CRS of the source raster to the specified
CRS.
--split-multipolygons
When specified, multipolygons are split as several features
each with one single polygon.
--convex-hull
When specified, the convex hull of (multi)polygons is
computed.
--densify-distance <value>
The specified value of this option is the maximum distance
between 2 consecutive points of the output geometry. The unit
of the distance is in pixels if --coordinate-system equals
pixel, or otherwise in georeferenced units of the source
raster. This option is applied before the reprojection
implied by --dst-crs.
--simplify-tolerance <value>
The specified value of this option is the tolerance used to
merge consecutive points of the output geometry using the
OGRGeometry::Simplify() method. The unit of the distance is
in pixels if --coordinate-system equals pixel, or otherwise in
georeferenced units of the target vector dataset. This option
is applied after the reprojection implied by --dst-crs.
--min-ring-area <value>
Minimum value for the area of a ring The unit of the area is
in square pixels if --coordinate-system equals pixel, or
otherwise in georeferenced units of the target vector dataset.
This option is applied after the reprojection implied by
--dst-crs
--max-points <value>|unlimited
Maximum number of points of each output geometry (not counting
the closing point of each ring, which is always identical to
the first point). The default value is 100. unlimited can be
used to remove that limitation.
--location-field <field_name>
Specifies the name of the field in the resulting vector
dataset where the path of the input dataset will be stored.
The default field name is "location". To prevent writing the
path of the input dataset, use --no-location-field
--no-location-field
Turns off the writing of the path of the input dataset as a
field in the output vector dataset.
--absolute-path
Enables writing the absolute path of the input dataset. By
default, the filename is written in the location field exactly
as specified on the command line.
Post-vectorization geometric operations are applied in the following
order:
+o optional splitting (--split-multipolygons)
+o optional densification (--densify-distance)
+o optional reprojection (--dst-crs)
+o optional filtering by minimum ring area (--min-ring-area)
+o optional application of convex hull (--convex-hull)
+o optional simplification (--simplify-tolerance)
+o limitation of number of points (--max-points)
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 vector 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 in-memory temporary dataset will be generated,
which may cause significant processing time at opening.
EXAMPLES
Example 1: Write the footprint of a GeoTIFF file into a GeoJSON file.
gdal raster footprint my_raster.tif footprint.geojson
AUTHOR
Even Rouault <even.rouault@spatialys.com>
COPYRIGHT
1998-2026
March 20, 2026 GDAL-RASTER-FOOTPRINT(1)