`gdal external`

Added in version 3.13.

Execute an external program as a step of a pipeline

Description

external can be used as a step (in any position) in a generic, raster or vector pipeline to execute an arbitrary external process.

For security reasons (in particular when embedded in GDALG pipelines), its execution requires the GDAL_ENABLE_EXTERNAL configuration option to be set to YES.

The command line executed by this step can accept the following optional placeholders:

<INPUT> that is replaced by the name of a temporary file, generated from the input of the previous step. The format used by default to materialize that file is GeoTIFF for raster and GeoPackage for vector, unless the --input-format is specified.
<OUTPUT> that is replaced by the name of a temporary file, generated by the external command. The format used by default to materialize that file is GeoTIFF for raster and GeoPackage for vector, unless the --output-format is specified. Upon the completion of the external command, the temporary file is opened, and passed to the next step of the pipeline.
<INPUT-OUTPUT> that is used for an external program that updates in place a dataset. The format used by default to materialize that file is GeoTIFF for raster and GeoPackage for vector, unless the --input-format is specified.

The directory where temporary files are created can be set with the CPL_TMPDIR configuration option.

If no <OUTPUT> or <INPUT-OUTPUT> placeholder is specified, the output of the step before external is reused as the output of external.

Synopsis

* external [OPTIONS] <COMMAND>
------------------------------

Execute an external program as a step of a pipeline

Positional arguments:
  --command <COMMAND>                                  External command, optionally with <INPUT> and/or <OUTPUT> or <INPUT-OUTPUT> placeholders [required]

Options:
  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format

Advanced Options:
  --if, --input-format <INPUT-FORMAT>                  Input formats

Program-Specific Options

--command <COMMAND>: External command, optionally with <INPUT> and/or <OUTPUT> or <INPUT-OUTPUT> placeholders [required]

Standard Options

Details

--if, --input-format <format>

Format/driver name to be attempted to open the input file(s). It is generally not necessary to specify it, but it can be used to skip automatic driver detection, when it fails to select the appropriate driver. This option can be repeated several times to specify several candidate drivers. Note that it does not force those drivers to open the dataset. In particular, some drivers have requirements on file extensions.

May be repeated.

-f, --of, --format, --output-format <OUTPUT-FORMAT>: Which output raster format to use.

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).

Examples

Example 1: Pipeline running a QGIS processing algorithm to smooth a DEM before computing the hillshade.

$ gdal pipeline --config GDAL_ENABLE_EXTERNAL=YES \
    read dem.tif ! \
    external "qgis_process run native:rasterfeaturepreservingsmoothing -- INPUT=<INPUT> OUTPUT=<OUTPUT>" ! \
    hillshade ! \
    write out.tif

gdal external