.. _gdal_external:

================================================================================
``gdal external``
================================================================================

.. versionadded:: 3.13

.. only:: html

    Execute an external program as a step of a pipeline

.. Index:: gdal external

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 :option:`--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 :option:`--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 :option:`--input-format`
  is specified.

The directory where temporary files are created can be set with the :config:`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
--------

.. program-output:: gdal pipeline --help-doc=external

Program-Specific Options
------------------------

.. option:: --command <COMMAND>

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


Standard Options
----------------

.. collapse:: Details

    .. include:: gdal_options/if.rst

    .. option:: -f, --of, --format, --output-format <OUTPUT-FORMAT>

        Which output raster format to use.

.. Return status code
.. ------------------

.. include:: return_code.rst

Examples
--------

.. example::
   :title: Pipeline running a `QGIS processing algorithm <https://docs.qgis.org/latest/en/docs/user_manual/processing/standalone.html>`__ to smooth a DEM before computing the hillshade.

   .. code-block:: bash

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