GDAL-RASTER-PIPELINE(1)

NAME
gdal-raster-pipeline - Process a raster dataset

Added in version 3.11.

SYNOPSIS

    Usage: gdal raster pipeline [OPTIONS] <PIPELINE>
    Process a raster dataset.
    Positional arguments:
    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]
      --progress              Display progress bar
    <PIPELINE> is of the form: read [READ-OPTIONS] ( ! <STEP-NAME> [STEP-OPTIONS] )* ! write [WRITE-OPTIONS]

A pipeline chains several steps, separated with the ! (exclamation mark) character. The first step must be read, and the last one write. Each step has its own positional or non-positional arguments. Apart from read and write, all other steps can potentially be used several times in a pipeline.

Potential steps are:

•   read

        * read [OPTIONS] <INPUT>
        ------------------------
        Read a raster dataset.
        Positional arguments:
          -i, --input <INPUT>                  Input raster dataset [required]
        Advanced Options:
          --if, --input-format <INPUT-FORMAT>  Input formats [may be repeated]
          --oo, --open-option <KEY>=<VALUE>    Open options [may be repeated]

•   aspect

        * aspect [OPTIONS]
        ------------------
        Generate an aspect map
        Options:
          -b, --band <BAND>              Input band (1-based index) (default: 1)
          --convention <CONVENTION>      Convention for output angles. CONVENTION=azimuth|trigonometric-angle (default: azimuth)
          --gradient-alg <GRADIENT-ALG>  Algorithm used to compute terrain gradient. GRADIENT-ALG=Horn|ZevenbergenThorne (default: Horn)
          --zero-for-flat                Whether to output zero for flat areas
          --no-edges                     Do not try to interpolate values at dataset edges or close to nodata values

    Details for options can be found in gdal raster aspect.

•   clip

        * clip [OPTIONS]
        ----------------
        Clip a raster dataset.
        Options:
          --bbox <BBOX>                    Clipping bounding box as xmin,ymin,xmax,ymax
                                           Mutually exclusive with --geometry, --like
          --bbox-crs <BBOX-CRS>            CRS of clipping bounding box
          --geometry <GEOMETRY>            Clipping geometry (WKT or GeoJSON)
                                           Mutually exclusive with --bbox, --like
          --geometry-crs <GEOMETRY-CRS>    CRS of clipping geometry
          --like <DATASET>                 Dataset to use as a template for bounds
                                           Mutually exclusive with --bbox, --geometry
          --like-sql <SELECT-STATEMENT>    SELECT statement to run on the 'like' dataset
                                           Mutually exclusive with --like-where
          --like-layer <LAYER-NAME>        Name of the layer of the 'like' dataset
          --like-where <WHERE-EXPRESSION>  WHERE SQL clause to run on the 'like' dataset
                                           Mutually exclusive with --like-sql
          --only-bbox                      For 'geometry' and 'like', only consider their bounding box
          --allow-bbox-outside-source      Allow clipping box to include pixels outside input dataset
          --add-alpha                      Adds an alpha mask band to the destination when the source raster have none.

    Details for options can be found in gdal raster clip.

•   color-map

        * color-map [OPTIONS]
        ---------------------
        Generate a RGB or RGBA dataset from a single band, using a color map
        Options:
          -b, --band <BAND>                    Input band (1-based index) (default: 1)
          --color-map <COLOR-MAP>              Color map filename
          --add-alpha                          Adds an alpha mask band to the destination.
          --color-selection <COLOR-SELECTION>  How to compute output colors from input values. COLOR-SELECTION=interpolate|exact|nearest (default: interpolate)

    Details for options can be found in gdal raster color-map.

•   edit

        * edit [OPTIONS]
        ----------------
        Edit a raster dataset.
        Options:
          --crs <CRS>               Override CRS (without reprojection)
          --bbox <BBOX>             Bounding box as xmin,ymin,xmax,ymax
          --nodata <NODATA>         Assign a specified nodata value to output bands ('none', numeric value, 'nan', 'inf', '-inf')
          --metadata <KEY>=<VALUE>  Add/update dataset metadata item [may be repeated]
          --unset-metadata <KEY>    Remove dataset metadata item [may be repeated]

    Details for options can be found in gdal raster edit.

•   hillshade

        * hillshade [OPTIONS]
        ---------------------
        Generate a shaded relief map
        Options:
          -b, --band <BAND>              Input band (1-based index) (default: 1)
          -z, --zfactor <ZFACTOR>        Vertical exaggeration used to pre-multiply the elevations
          --xscale <XSCALE>              Ratio of vertical units to horizontal X axis units
          --yscale <YSCALE>              Ratio of vertical units to horizontal Y axis units
          --azimuth <AZIMUTH>            Azimuth of the light, in degrees (default: 315)
          --altitude <ALTITUDE>          Altitude of the light, in degrees (default: 45)
          --gradient-alg <GRADIENT-ALG>  Algorithm used to compute terrain gradient. GRADIENT-ALG=Horn|ZevenbergenThorne (default: Horn)
          --variant <VARIANT>            Variant of the hillshading algorithm. VARIANT=regular|combined|multidirectional|Igor (default: regular)
          --no-edges                     Do not try to interpolate values at dataset edges or close to nodata values

    Details for options can be found in gdal raster hillshade.

•   reproject

        * reproject [OPTIONS]
        ---------------------
        Reproject a raster dataset.
        Options:
          -s, --src-crs <SRC-CRS>                    Source CRS
          -d, --dst-crs <DST-CRS>                    Destination CRS
          -r, --resampling <RESAMPLING>              Resampling method. RESAMPLING=nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum (default: nearest)
          --resolution <xres>,<yres>                 Target resolution (in destination CRS units)
                                                     Mutually exclusive with --size
          --size <width>,<height>                    Target size in pixels
                                                     Mutually exclusive with --resolution
          --bbox <BBOX>                              Target bounding box (in destination CRS units)
          --bbox-crs <BBOX-CRS>                      CRS of target bounding box
        Advanced Options:
          --target-aligned-pixels                    Round target extent to target resolution
          --src-nodata <SRC-NODATA>                  Set nodata values for input bands ('None' to unset). [1.. values]
          --dst-nodata <DST-NODATA>                  Set nodata values for output bands ('None' to unset). [1.. values]
          --add-alpha                                Adds an alpha mask band to the destination when the source raster have none.
          --wo, --warp-option <NAME>=<VALUE>         Warping option(s) [may be repeated]
          --to, --transform-option <NAME>=<VALUE>    Transform option(s) [may be repeated]
          --et, --error-threshold <ERROR-THRESHOLD>  Error threshold

    Details for options can be found in gdal raster reproject.

•   resize

        * resize [OPTIONS]
        ------------------
        Resize a raster dataset without changing the georeferenced extents.
        Options:
          --size <width[%]>,<height[%]>  Target size in pixels (or percentage if using '%' suffix) [required]
          -r, --resampling <RESAMPLING>  Resampling method. RESAMPLING=nearest|bilinear|cubic|cubicspline|lanczos|average|mode (default: nearest)

    Details for options can be found in gdal raster resize.

•   roughness

        * roughness [OPTIONS]
        ---------------------
        Generate a roughness map
        Options:
          -b, --band <BAND>       Input band (1-based index) (default: 1)
          --no-edges              Do not try to interpolate values at dataset edges or close to nodata values

    Details for options can be found in gdal raster roughness.

•   scale

        * scale [OPTIONS]
        -----------------
        Scale the values of the bands of a raster dataset.
        Options:
          --ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE>  Output data type. OUTPUT-DATA-TYPE=Byte|Int8|UInt16|Int16|UInt32|Int32|UInt64|Int64|CInt16|CInt32|Float16|Float32|Float64|CFloat32|CFloat64
          -b, --band <BAND>                                        Select band to restrict the scaling (1-based index)
          --src-min <SRC-MIN>                                      Minimum value of the source range
          --src-max <SRC-MAX>                                      Maximum value of the source range
          --dst-min <DST-MIN>                                      Minimum value of the destination range
          --dst-max <DST-MAX>                                      Maximum value of the destination range
          --exponent <EXPONENT>                                    Exponent to apply non-linear scaling with a power function
          --no-clip                                                Do not clip input values to [srcmin, srcmax]

    Details for options can be found in gdal raster scale.

•   select

        * select [OPTIONS] <BAND>
        -------------------------
        Select a subset of bands from a raster dataset.
        Positional arguments:
          -b, --band <BAND>       Band(s) (1-based index, 'mask' or 'mask:<band>') [1.. values] [required]
        Options:
          --mask <MASK>           Mask band (1-based index, 'mask', 'mask:<band>' or 'none')

    Details for options can be found in gdal raster select.

•   set-type

        * set-type [OPTIONS]
        --------------------
        Modify the data type of bands of a raster dataset.
        Options:
          --ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE>  Output data type. OUTPUT-DATA-TYPE=Byte|Int8|UInt16|Int16|UInt32|Int32|UInt64|Int64|CInt16|CInt32|Float16|Float32|Float64|CFloat32|CFloat64 [required]

    Details for options can be found in gdal raster set-type.

•   slope

        * slope [OPTIONS]
        -----------------
        Generate a slope map
        Options:
          -b, --band <BAND>              Input band (1-based index) (default: 1)
          --unit <UNIT>                  Unit in which to express slopes. UNIT=degree|percent (default: degree)
          --xscale <XSCALE>              Ratio of vertical units to horizontal X axis units
          --yscale <YSCALE>              Ratio of vertical units to horizontal Y axis units
          --gradient-alg <GRADIENT-ALG>  Algorithm used to compute terrain gradient. GRADIENT-ALG=Horn|ZevenbergenThorne (default: Horn)
          --no-edges                     Do not try to interpolate values at dataset edges or close to nodata values

    Details for options can be found in gdal raster slope.

•   tpi

        * tpi [OPTIONS]
        ---------------
        Generate a Topographic Position Index (TPI) map
        Options:
          -b, --band <BAND>       Input band (1-based index) (default: 1)
          --no-edges              Do not try to interpolate values at dataset edges or close to nodata values

    Details for options can be found in gdal raster tpi.

•   tri

        * tri [OPTIONS]
        ---------------
        Generate a Terrain Ruggedness Index (TRI) map
        Options:
          -b, --band <BAND>        Input band (1-based index) (default: 1)
          --algorithm <ALGORITHM>  Algorithm to compute TRI. ALGORITHM=Riley|Wilson (default: Riley)
          --no-edges               Do not try to interpolate values at dataset edges or close to nodata values

    Details for options can be found in gdal raster tri.

•   unscale

        * unscale [OPTIONS]
        -------------------
        Convert scaled values of a raster dataset into unscaled values.
        Options:
          --ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE>  Output data type. OUTPUT-DATA-TYPE=Byte|Int8|UInt16|Int16|UInt32|Int32|UInt64|Int64|CInt16|CInt32|Float16|Float32|Float64|CFloat32|CFloat64

    Details for options can be found in gdal raster unscale.

•   write

        * write [OPTIONS] <OUTPUT>
        --------------------------
        Write a raster dataset.
        Positional arguments:
          -o, --output <OUTPUT>                                Output raster dataset [required]
        Options:
          -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format ("GDALG" allowed)
          --co, --creation-option <KEY>=<VALUE>                Creation option [may be repeated]
          --overwrite                                          Whether overwriting existing output is allowed

DESCRIPTION

gdal raster pipeline can be used to process a raster dataset and perform various processing steps.

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

A pipeline can be serialized as a JSON file using the GDALG output format. The resulting file can then be opened as a raster dataset using the GDALG: GDAL Streamed Algorithm driver, and apply the specified pipeline in a on-the-fly / streamed way.

The command_line member of the JSON file should nominally be the whole command line without the final write step, and is what is generated by gdal raster pipeline ! .... ! write out.gdalg.json.

    {
        "type": "gdal_streamed_alg",
        "command_line": "gdal raster pipeline ! read in.tif ! reproject --dst-crs=EPSG:32632"
    }

The final write step can be added but if so it must explicitly specify the stream output format and a non-significant output dataset name.

    {
        "type": "gdal_streamed_alg",
        "command_line": "gdal raster pipeline ! read in.tif ! reproject --dst-crs=EPSG:32632 ! write --output-format=streamed streamed_dataset"
    }

EXAMPLES

  Example 1: Reproject a GeoTIFF file to CRS EPSG:32632 ("WGS 84 / UTM zone 32N") and adding a metadata item

    $ gdal raster pipeline --progress ! read in.tif ! reproject --dst-crs=EPSG:32632 ! edit --metadata AUTHOR=EvenR ! write out.tif --overwrite

  Example 2: Serialize the command of a reprojection of a GeoTIFF file in a GDALG file, and later read it

    $ gdal raster pipeline --progress ! read in.tif ! reproject --dst-crs=EPSG:32632 ! write in_epsg_32632.gdalg.json --overwrite
    $ gdal raster info in_epsg_32632.gdalg.json

AUTHOR
Even Rouault <even.rouault@spatialys.com>

COPYRIGHT
1998-2025