GDAL-RASTER-PIXEL-INFO(1)

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

👑 gdal-raster-pixel-info 👑

okay so this is a page from the GDAL manual — the GDAL-RASTER-PIXEL-INFO(1) one specifically — and bestie, it's a whole moment. Sit down, grab a strawberry 🍓, we're doing pixel lore.

🌸 NAME 🌸

gdal-raster-pixel-info — returns information on a pixel of a raster dataset. that's it, that's the job, and it does it iconically ✨

Added in version 3.11. 💅

🌈 SYNOPSIS 🌈

here's the whole shape of the command, copied character for character so nothing gets lost in the group chat:

Usage: gdal raster pixel-info [OPTIONS] <INPUT> [<column,line> or <X,Y>]

Return information on a pixel of a raster dataset.

Positional arguments:
  -i, --dataset, --input <INPUT>                       Input raster datasets [required]
  -p, --pos, --position <column,line> or <X,Y>         Pixel position [may be repeated]
                                                       Mutually exclusive with --position-dataset

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]

Options:
  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format (default is 'GeoJSON' if 'position-dataset' not specified) [not available in pipelines]
  --position-dataset <POSITION-DATASET>                Vector dataset with coordinates
                                                       Mutually exclusive with --position
  -l, --layer, --input-layer <INPUT-LAYER>             Input layer name
  -o, --output <OUTPUT>                                Output vector dataset (created by algorithm)
  --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]
  --overwrite                                          Whether overwriting existing output dataset is allowed [not available in pipelines]
  -b, --band <BAND>                                    Input band(s) (1-based index) [may be repeated]
  --overview <OVERVIEW>                                Which overview level of source file must be used
  --position-crs <POSITION-CRS>                        CRS of position (default is 'pixel' if 'position-dataset' not specified)
  -r, --resampling <RESAMPLING>                        Resampling algorithm for interpolation. RESAMPLING=nearest|bilinear|cubic|cubicspline (default: nearest)
  --promote-pixel-value-to-z                           Whether to set the pixel value as Z component of GeoJSON geometry
  --include-field <INCLUDE-FIELD>                      Fields from coordinate dataset to include in output (special values: ALL and NONE) (default: ALL) [may be repeated]

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]

no cap, that block is the whole energy of this tool. the rest of this page is just me explaining it with way too much enthusiasm. 🫶

🦋 DESCRIPTION 🦋

gdal raster pixel-info is a whole mechanism for asking "hey what's up with this specific pixel" — you give it a location, and it works in a bunch of different coordinate systems to figure out what you mean. main character behaviour, honestly.

here's everything it'll report back (when known):

  • Input coordinates
  • Input coordinates converted to column, line
  • Pixel value per selected band(s), with unscaled value
  • For VRT files, which file(s) contribute to the pixel value — (only for GeoJSON output)

the way that there are 3 possible ways of giving it input location(s):

  • from input stream, with a "X Y" pair per line, potentially followed by other text. 📥
  • through the --position argument.
  • through a GDAL vector dataset through the --position-dataset argument.

and there are 2 possibilities for outputting pixel info:

  • either on the output stream as CSV or GeoJSON (default to GeoJSON)
  • or as a GDAL vector dataset whose name is specified with the --output argument.

okay and lowkey important: since GDAL 3.13, this algorithm can be part of a gdal pipeline. in that case, only reading coordinates from a GDAL vector dataset and outputting results to one is supported. that's the deal, that's the rule. periodt. 💅

Added in version 3.13.

🧚 GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET) 🧚

so 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. ✨ streamed. iconic.

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. not me warning you, that's just what the page says. plan accordingly bestie 😭

the following options are available:

🎀 PROGRAM-SPECIFIC OPTIONS 🎀

  • -b <band> — selects a band to query. multiple bands can be listed. by default, all bands are queried. 🎯
  • -f, --of, --format, --output-format <FORMAT> — which vector output format to use.
    • when --output is not specified, csv or geojson are the only two supported choices, with geojson being the default. only two, pick wisely!
    • otherwise, any GDAL-supported vector format with write capabilities is supported. the whole buffet 🔥
  • --position-dataset <COORDINATE-DATASET> — GDAL-compatible vector dataset from which input coordinates are read. if the input feature has a point geometry, its location is used to query the raster. for other geometry types, the centroid is used. to read all pixel values for non-point geometries, use gdal raster zonal-stats instead. by default, all attribute fields are copied to the output.

how the coordinates get interpreted goes in this exact order:

  • if the --position-crs argument is specified, the coordinates of the point are interpreted according to the value of that argument.
  • otherwise, if the input vector layer has a CRS, coordinates are assumed to be expressed in it.
  • otherwise, coordinates are assumed to be in the CRS raster dataset if it has a CRS.
  • otherwise, coordinates are assumed to be expressed in the column,line raster space.
Added in version 3.13.
  • -l, --layer, --input-layer <INPUT-LAYER> — input layer name of the dataset specified with --position-dataset to use. 🗂️
Added in version 3.13.
  • -o, --output <OUTPUT> — output vector dataset (created by algorithm). ✨
Added in version 3.13.
  • --include-field <FIELD> — name of the field(s) from --position-dataset to include into the output. by default, all fields are included (which corresponds to special value ALL). special value NONE can be used to mean that no field from the position dataset must be included in the output. bestie said either all of me or none of me 💅
Added in version 3.13.
  • --ovr, --overview <index> — query the (overview_level)th overview (overview_level=0 is the 1st overview), instead of the base band. note that the x,y location (if the coordinate system is pixel/line) must still be given with respect to the base band. yes, still base band. don't get cute. 🌸
  • -p, --pos, --position <column,line> or <X,Y> — required, if --position-dataset is not specified and no content is provided through the input stream.
    • this can be specified either as an option, a positional value after the dataset name, or when called from gdal, as (space separated) values provided on the standard input.
    • by default, when --position-crs is not specified, or set to pixel, this is a column, line tuple (possibly with fractional part). if --position-crs is set to dataset, this is a georeferenced coordinate expressed in the CRS of the dataset. if --position-crs is specified to a CRS definition, this is a georeferenced coordinate expressed in this CRS.
    • X means always longitude or easting, Y means always latitude or northing. 🧭
    • several x,y tuples may be specified. go off, give it a list.
  • --position-crs pixel|dataset|<crs-def> — CRS of position, or one of two following special values:
    • pixel means that the position is set as column, line (default). 🖼️
    • dataset means that the position is a georeferenced coordinate expressed in the CRS of the dataset.
  • --promote-pixel-value-to-z — whether to set the pixel value as Z component of GeoJSON geometry. only applies if a single band is selected, and for GeoJSON output format. one band only, iykyk. ⭐
Added in version 3.13.
  • -r, --resampling nearest|bilinear|cubic|cubicspline — select a sampling algorithm. the default is nearest.

the available methods are:

  • nearest applies a nearest neighbour.
  • bilinear applies a bilinear convolution kernel.
  • cubic applies a cubic convolution kernel.
  • cubicspline applies a B-Spline convolution kernel.

four kernels, zero notes, pick your fighter. 🔥

✨ STANDARD OPTIONS ✨

these are the ✨universal✨ ones, bestie — the options that basically every gdal CLI tool speaks. learn them once, use them forever. it's giving reusable. 💅

  • --oo, --open-option <NAME>=<VALUE> — a dataset open option, and yes it's format specific so the meaning depends entirely on which driver you're talking to. it can be repeated as many times as you want (stack 'em up, queen 👑).
  • --if, --input-format <format> — the format/driver name that gdal should attempt to use to open the input file(s). lowkey you usually don't need this at all, but it's here for when automatic driver detection is being a hater and picks the wrong driver — then you use this to skip detection entirely. you can repeat this option several times to hand over a whole roster of candidate drivers. ⚠️ BUT — and this is the important part — it does not force those drivers to actually open the dataset. some drivers have requirements on file extensions, so your fave might still ghost you. 👻

May be repeated.

  • --co, --creation-option <NAME>=<VALUE> — soooo many formats have optional creation options, and they control the little particulars of the file being created. like, the GeoTIFF driver has creation options for controlling compression, and for whether the file should be tiled. very "you had my curiosity, now you have my attention" energy. 🎀

May be repeated — go off, add as many as you need.

The creation options available vary by format driver, and some simple formats have no creation options at all (they're minimalists, respect it). 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. fr fr, read the docs, they ate. 📚

  • --lco, --layer-creation-option <NAME>=<VALUE> — the layer creation options, which are like --co but for the layer being created rather than the dataset. lots of formats have one or more of these optional cuties to control the particulars of the layer. for instance, the GeoPackage driver supports layer creation options to control the feature identifier or the geometry column name, setting the identifier or description, etc. iconic behaviour honestly. 💖

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

🚨 okay important plot twist: layer creation options are different from dataset creation options. do not mix them up, bestie, i'm begging. --co ≠ --lco. know the difference, iykyk.
  • --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 you're getting yelled at about a file that's already there? that's why. this is the "yeah yeah i know, do it anyway" flag. 💀

🌈 RETURN STATUS CODE 🌈

the tea on exit codes, bestie:

  • the program returns status code 0 in case of success ✨
  • and non-zero in case of error 🚫

and here's the little nuance that trips people up: non-blocking errors that get emitted as warnings are still considered a successful execution. so warnings ≠ failure. she's fine, she's just dramatic. 😌

🦋 EXAMPLES 🦋

Example 1: Reporting on pixel column=5, line=10 on the file byte.tif

$ gdal raster pixel-info byte.tif 5 10
{
  "type":"FeatureCollection",
  "crs":{
    "type":"name",
    "properties":{
      "name":"urn:ogc:def:crs:EPSG::26711"
    }
  },
  "features":[
    {
      "type":"Feature",
      "properties":{
        "input_coordinate":[
          5.0,
          10.0
        ],
        "column":5.0,
        "line":10.0,
        "bands":[
          {
            "band_number":1,
            "raw_value":132,
            "unscaled_value":132.0
          }
        ]
      },
      "geometry":{
        "type":"Point",
        "coordinates":[
          441020.0,
          3750720.0
        ]
      }
    }
  ]
}

Example 2: Reporting on point at UTM 11N coordinates easting=441320 and northing=3750720 on the file byte.tif

$ gdal raster pixel-info --position-crs=dataset byte.tif 441320 3750720
{
  "type":"FeatureCollection",
  "crs":{
    "type":"name",
    "properties":{
      "name":"urn:ogc:def:crs:EPSG::26711"
    }
  },
  "features":[
    {
      "type":"Feature",
      "properties":{
        "input_coordinate":[
          441320.0,
          3750720.0
        ],
        "column":10.0,
        "line":10.0,
        "bands":[
          {
            "band_number":1,
            "raw_value":115,
            "unscaled_value":115.0
          }
        ]
      },
      "geometry":{
        "type":"Point",
        "coordinates":[
          441320.0,
          3750720.0
        ]
      }
    }
  ]
}

Example 3: Reporting on point at WGS84 coordinates longitude=-117.6355 and latitude=33.8970 on the file byte.tif, with CSV output format

$ gdal raster pixel-info --of=csv --position-crs=WGS84 byte.tif -117.6355 33.8970
geom_x,geom_y,extra_content,column,line,band_1_raw_value,band_1_unscaled_value
-117.6355,33.897,,10.020546288988,9.98330473474925,115,115

Example 4: Reporting on point at WGS84 coordinates provided on the standard input with longitude, latitude order.

$ echo -117.6355 33.8970 | gdal raster pixel-info --of=csv --position-crs=WGS84 byte.tif
geom_x,geom_y,extra_content,column,line,band_1_raw_value,band_1_unscaled_value
-117.6355,33.897,,10.020546288988,9.98330473474925,115,115

yes bestie, that pipeline fed straight into stdin and it just worked. that's the vibe. 🌸

Example 5: Reading coordinates to extract from an input GeoPackage file and writing the output to a GeoPackage file

gdal raster pixel-info --position-dataset input.gpkg --input byte.tif --output output.gpkg

Example 6: Getting pixel values from a on-the-fly resized raster dataset from coordinates in input.gpkg.

gdal pipeline read byte.tif ! resize --size 50%,50% -r cubic ! pixel-info input.gpkg ! write output.gpkg

the ! separators are doing so much heavy lifting here. pipeline girlies understand. 🔥

Example 7: Getting pixel values from coordinates in a piped vector dataset, using the _ placeholder dataset name

gdal pipeline read input.gml ! swap-xy ! pixel-info --input byte.tif --position-dataset _ ! write output.gpkg

_ is the placeholder name for "the thing that's currently being piped in." cute, right? 🎀

👑 AUTHOR 👑

Even Rouault <even.rouault@spatialys.com>

1998-2026

and that's the whole page, bestie, we made it. 🫶 this one's from GDAL-RASTER-PIXEL-INFO(1), dated Aug 18, 2026 — go forth and read those pixels, you absolute legend. ✨💅

📦 where this page comes from