gdal raster pipeline
Added in version 3.11.
Process a raster dataset.
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 ! (quotation 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