GDAL-RASTER-FOOTPRINT(1)

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

✨ NAME ✨

gdal-raster-footprint — bestie, this is how you compute the footprint of a raster dataset 💖

Added in version 3.11. (yes it's a baby, but it EATS.)

This one lives in the GDAL manual, section 1. Okurrr let's get into it 🦋

🌸 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] [not available in pipelines]
  -o, --output <OUTPUT>                                Output vector dataset [required] [not available in pipelines]

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 or warning message) [not available in pipelines]

Options:
  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format [not available in pipelines]
  --co, --creation-option <KEY>=<VALUE>                Creation option [may be repeated] [not available in pipelines]
  --lco, --layer-creation-option <KEY>=<VALUE>         Layer creation option [may be repeated] [not available in pipelines]
  --append                                             Whether appending to existing layer is allowed [not available in pipelines]
  --overwrite                                          Whether overwriting existing output dataset is allowed [not available in pipelines]
  --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 --input-nodata
  --input-nodata <INPUT-NODATA>                        Set nodata values for input bands. [1.. values]
                                                       Mutually exclusive with --overview
  --coordinate-system <COORDINATE-SYSTEM>              Target coordinate system. COORDINATE-SYSTEM=georeferenced|pixel
  --output-crs <OUTPUT-CRS>                            Output 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] [not available in pipelines]
  --if, --input-format <INPUT-FORMAT>                  Input formats [may be repeated] [not available in pipelines]

💅 DESCRIPTION 💅

So gdal raster footprint computes the footprint of a raster file. And like — it's not just a bounding box, bestie, it actually cares about nodata values (or more generally the mask band attached to the raster bands). It generates polygons/multipolygons that correspond to the areas where pixels are valid, and writes them to an output vector file. Periodt ✨

Since GDAL 3.12, this algorithm can be part of a gdal pipeline. Iconic behaviour honestly.

Also lowkey a pro tip from the universe itself: the gdal raster clean-collar utility may be run as a pre-processing step to generate proper mask bands 💖

📸 [image] — the caption situation: "Example footprint calculated with default options of gdal raster footprint."

The post-vectorization geometric operations get applied in this exact order, no cap, don't rearrange them:

  1. optional splitting (--split-multipolygons)
  2. optional densification (--densify-distance)
  3. optional reprojection (--output-crs)
  4. optional filtering by minimum ring area (--min-ring-area)
  5. optional application of convex hull (--convex-hull)
  6. optional simplification (--simplify-tolerance)
  7. 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. That resulting file can then be opened as a vector dataset using the GDALG: GDAL Streamed Algorithm driver, and it'll apply the specified pipeline in an on-the-fly / streamed way. So slay, streaming 💫

⚠️ NOTE, bestie, read this one: However this algorithm is not natively streaming compatible. Consequently an in-memory temporary dataset will be generated, which may cause significant processing time at opening. 😭 So like… she works but she takes a sec to wake up.

👑 PROGRAM-SPECIFIC OPTIONS 👑

  • --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. So no sneaky rewriting, what you typed is what you get.
  • -b, --band <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 you don't specify any, all bands are taken into account. The way multiple bands get combined is controlled by --combine-bands. (iykyk 🧚)
  • --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 for at least one of the selected bands. intersection means a pixel is valid only if it is valid for all selected bands. Choose your fighter 💅
  • --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 --output-crs). If you specify pixel, the coordinates of the footprint geometry are column and line indices. Cute and simple.
  • --convex-hull — When specified, the convex hull of (multi)polygons is computed. Like wrapping your shape in a lil rubber band 🌈
  • --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. Heads up: this option is applied before the reprojection implied by --output-crs ⭐
  • --input-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 band will be used. 🍓
  • --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.
  • --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. Live your truth 🦋
  • --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 --output-crs. ✨
  • --no-location-field — Turns off the writing of the path of the input dataset as a field in the output vector dataset.
  • --output-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. 🌈
  • --output-layer <OUTPUT-LAYER> — Output layer name. Defaults to footprint.
  • --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 --input-nodata. 🫶
  • --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 --output-crs. 💜
  • --split-multipolygons — When specified, multipolygons are split as several features each with one single polygon.

💖 STANDARD OPTIONS 💖

okay bestie these are the options literally every gdal program gets, so they're the shared starter pack 🎀 no cap, learn these once and you're set for life.

  • --append — lets you add features onto layer(s) that already exist. and bonus: if the output dataset isn't there yet, this will just create it for you. ✨
  • --co, --creation-option <NAME>=<VALUE> — a whole bunch of formats have optional creation options that let you control little particulars about the file being made. think of it like, the GeoTIFF driver has creation options for controlling compression, and for whether the file should be tiled. slay.

May be repeated. 🔁

which creation options exist depends entirely on the format driver, and some simple formats have literally zero creation options, rip. you can get a list of options a format supports with the --formats command line option, but ngl the format's own documentation is the definitive source of truth on driver creation options. so go look at the Raster drivers format specific documentation for the legal creation options for each format. 💅

  • --if, --input-format <format> — the format/driver name you want it to try when opening the input file(s). usually you do NOT need to specify this, it's just there so you can skip automatic driver detection when that detection fails to pick the right driver. 🙈 you can repeat this option several times to list several candidate drivers.
heads up: it does not force those drivers to open the dataset. like, some drivers have requirements around file extensions, so it's giving "suggestion" not "demand". 😭

May be repeated. 🔁

  • --lco, --layer-creation-option <NAME>=<VALUE> — same energy as --co but for layers. lots of formats have optional layer creation options that control particulars about the layer you're creating. for instance, the GeoPackage driver supports layer creation options to control the feature identifier or geometry column name, setting the identifier or description, etc. iconic.

May be repeated. 🔁

the layer creation options available vary by format driver, and again, some simple formats have none 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.

real talk: layer creation options are different from dataset creation options. do not mix them up babe. 💀
  • --oo, --open-option <NAME>=<VALUE> — a dataset open option (format specific).

May be repeated. 🔁

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

run it, it's so satisfying. 🌈

  • --overwrite — lets the program overwrite an existing target file or dataset.
otherwise, by default, gdal errors out if the target file or dataset already exists. so if it's yelling at you, this is your girl. 💅

🔥 RETURN STATUS CODE 🔥

  • the program returns status code 0 when it succeeds 🎀
  • and non-zero when there's an error

ngl a very important little footnote: non-blocking errors that get emitted as warnings still count as a successful execution. so don't panic, bestie. 🫶

🌸 EXAMPLES 🌸

✨ Example 1: Write the footprint of a GeoTIFF file into a GeoJSON file. ✨

gdal raster footprint my_raster.tif footprint.geojson

one line. one W. periodt. 👑

💜 AUTHOR 💜

Even Rouault <even.rouault@spatialys.com>

1998-2026

and that's the whole page bestie, you ate it up fr fr 💖 this was the GDAL-RASTER-FOOTPRINT(1) manual, dated Aug 18, 2026 — go make some footprints, the map is yours 🦋✨

📦 where this page comes from