GDAL_FOOTPRINT(1)

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

💖 NAME 💖

gdal_footprint — computes the footprint of a raster. That is genuinely the whole assignment, bestie, and it ate. 🔥

🌸 SYNOPSIS 🌸

   Usage: gdal_footprint [--help] [--long-usage] [--help-general]
                         [-b <band>]... [-combine_bands VAR]
                         [[-ovr <index>]|[-srcnodata "<value>[ <value>]..."]]
                         [-t_cs VAR] [-t_srs <srs_def>] [-split_polys]
                         [-convex_hull] [-densify <value>] [-simplify <value>]
                         [-min_ring_area <value>] [-max_points <value>|unlimited]
                         [--quiet] [-oo <NAME>=<VALUE>]... [-of <output_format>]
                         [[-location_field_name <field_name>]|[-no_location]]
                         [-write_absolute_path] [-lco <NAME>=<VALUE>]...
                         [-dsco <NAME>=<VALUE>]... [-lyr_name <value>] [-overwrite]
                         <src_filename> <dst_filename>

🦋 DESCRIPTION 🦋

Okay so picture this: you have a raster file and you want to know where the actual real data lives inside it. That's the gig. The gdal_footprint utility — yes, from the GDAL manual, GDAL_FOOTPRINT(1), hi bestie 💅 — can be used to compute the footprint of a raster file, and it's lowkey smart about it: it takes nodata values into account (or, more generally, the mask band attached to the raster bands), and generates polygons/multipolygons corresponding to areas where pixels are valid, then writes them to an output vector file. Iconic. ✨

Real talk though: the nearblack utility may be run as a pre-processing step to generate proper mask bands. So if your mask bands are giving nothing, that is the move. 🫶

TIP: Equivalent in the new gdal command line interface: See gdal raster footprint.

🎀 the options, one by one, no skips 🎀

  • --help — shows this help message and exits. Simple. Effective. Periodt.
  • --help-general — gives you a brief usage message for the generic GDAL commandline options and exits. Like a little preview of the whole GDAL cinematic universe. 🌈
  • -q, --quiet — suppresses progress messages and other non-error output. Silence, but make it chic. 🤫
  • -b <band> — the band(s) of interest. Between 1 and the number of bands of the raster. May be specified multiple times. If you don't specify it, all bands are taken into account. The way multiple bands get combined is controlled by -combine_bands 👀
  • -combine_bands union|intersection — defines how the mask bands of the selected bands are combined into a single mask band, before being vectorized. Default value is union: that is, a pixel is valid if it is valid at least for one of the selected bands. intersection means a pixel is valid only if it is valid for all selected bands. Choose your fighter. 💖
  • -ovr <index> — lets you specify which overview level of the 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, so 0 means the first overview level. ✨ This option is mutually exclusive with -srcnodata — they cannot both show up to the party. 🚫
  • -srcnodata "<value>[ <value>]..." — sets 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 this option is not specified, the intrinsic mask band of each selected bands will be used.
  • -t_cs pixel|georef — the target coordinate system. By default, if the input dataset is georeferenced, georef is implied, meaning the footprint geometry will be expressed as coordinates in the CRS of the raster (or the one specified with -t_srs). If you specify pixel, the coordinates of the footprint geometry are column and line indices. 🧚
  • -t_srs <srs_def> — the target CRS of the output file. The <srs_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 -t_cs georef. The footprint is reprojected from the CRS of the source raster to the specified CRS. Glow-up via reprojection, honestly. 💫
  • -split_polys — when specified, multipolygons are split as several features, each with one single polygon. Breaking up is not hard to do when you ask nicely. ✂️
  • -convex_hull — when specified, the convex hull of (multi)polygons is computed. Wrapping your whole situation in one smooth curve. 🔥
  • -densify <value> — the specified value is the maximum distance between 2 consecutive points of the output geometry. The unit of the distance is in pixels if -t_cs equals pixel, or otherwise in georeferenced units of the source raster. This option is applied before the reprojection implied by -t_srs ⏰
  • -simplify <value> — the specified value 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 -t_cs equals pixel, or otherwise in georeferenced units of the target vector dataset. This option is applied after the reprojection implied by -t_srs ⏰
  • -min_ring_area <value> — minimum value for the area of a ring. The unit of the area is in square pixels if -t_cs equals pixel, or otherwise in georeferenced units of the target vector dataset. This option is applied after the reprojection implied by -t_srs 📐
  • -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. No cap, literally. 👑
  • -oo <NAME>=<VALUE> — dataset open option (format specific).
  • -of <ogr_format> — select the output format. Use the short format name. Guessed from the file extension if not specified. 🔍
  • -location_field_name <field_name> — Added in version 3.9.0.

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 📍

  • -no_location — Added in version 3.9.0.

Turns off the writing of the path of the input dataset as a field in the output vector dataset. Bye bestie, no location for you. 👋

  • -write_absolute_path — Added in version 3.9.0.

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

  • -lco <NAME>=<VALUE> — layer creation option (format specific).
  • -dsco <NAME>=<VALUE> — dataset creation option (format specific).
  • -lyr_name <value> — name of the target layer. footprint if not specified. 🎁
  • -overwrite — overwrites the target layer if it exists. Out with the old, in with the new. 💅
  • <src_filename> — the source raster file name.
  • <dst_filename> — the destination vector file name. If the file and the output layer exist, the new footprint is appended to them, unless -overwrite is used. Noted, because that one surprises people. ⚠️

🌈 the order of operations, because it matters 🌈

Post-vectorization geometric operations are applied in this exact order:

  • optional splitting (-split_polys)
  • optional densification (-densify)
  • optional reprojection (-t_srs)
  • optional filtering by minimum ring area (-min_ring_area)
  • optional application of convex hull (-convex_hull)
  • optional simplification (-simplify)
  • limitation of number of points (-max_points)

That pipeline is lowkey the main character here. Do not shuffle it. 🚫🎲

⭐ 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 sad little warning does not count as a fail, bestie, we're still slaying. ✨

💜 C API 💜

This utility is also callable from C with GDALFootprint(). Yes, C girlies get a seat at the table too. 🫶

🍓 EXAMPLES 🍓

Example 1: Compute the footprint of a GeoTIFF file as a GeoJSON file

gdal_footprint -t_srs EPSG:4326 input.tif output.geojson

The footprint will be written using WGS84 longitude, latitude coordinates, regardless of the spatial reference system used by the input raster. Set it and forget it. 💖

👑 AUTHOR 👑

Even Rouault <even.rouault@spatialys.com>

1998-2026

okay that's the whole page, bestie 🎀 fr fr you now know everything GDAL_FOOTPRINT(1) has to say. This legendary drop came from the GDAL manual, dated Aug 18, 2026, and it's still GDAL_FOOTPRINT(1) at the very end because some things never change. go compute a footprint, you've got this 💅💖✨

📦 where this page comes from