.. _gdal_raster_pipeline:

================================================================================
``gdal raster pipeline``
================================================================================

.. versionadded:: 3.11

.. only:: html

    Process a raster dataset.

.. Index:: gdal raster pipeline

Synopsis
--------

.. program-output:: gdal raster pipeline --help-doc=main

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

.. program-output:: gdal raster pipeline --help-doc=read

* aspect

.. program-output:: gdal raster pipeline --help-doc=aspect

Details for options can be found in :ref:`gdal_raster_aspect`.

* clip

.. program-output:: gdal raster pipeline --help-doc=clip

Details for options can be found in :ref:`gdal_raster_clip`.

* color-map

.. program-output:: gdal raster pipeline --help-doc=color-map

Details for options can be found in :ref:`gdal_raster_color_map`.

* edit

.. program-output:: gdal raster pipeline --help-doc=edit

Details for options can be found in :ref:`gdal_raster_edit`.

* hillshade

.. program-output:: gdal raster pipeline --help-doc=hillshade

Details for options can be found in :ref:`gdal_raster_hillshade`.

* reproject

.. program-output:: gdal raster pipeline --help-doc=reproject

Details for options can be found in :ref:`gdal_raster_reproject`.

* resize

.. program-output:: gdal raster pipeline --help-doc=resize

Details for options can be found in :ref:`gdal_raster_resize`.

* roughness

.. program-output:: gdal raster pipeline --help-doc=roughness

Details for options can be found in :ref:`gdal_raster_roughness`.

* scale

.. program-output:: gdal raster pipeline --help-doc=scale

Details for options can be found in :ref:`gdal_raster_scale`.

* select

.. program-output:: gdal raster pipeline --help-doc=select

Details for options can be found in :ref:`gdal_raster_select`.

* set-type

.. program-output:: gdal raster pipeline --help-doc=set-type

Details for options can be found in :ref:`gdal_raster_set_type`.

* slope

.. program-output:: gdal raster pipeline --help-doc=slope

Details for options can be found in :ref:`gdal_raster_slope`.

* tpi

.. program-output:: gdal raster pipeline --help-doc=tpi

Details for options can be found in :ref:`gdal_raster_tpi`.

* tri

.. program-output:: gdal raster pipeline --help-doc=tri

Details for options can be found in :ref:`gdal_raster_tri`.

* unscale

.. program-output:: gdal raster pipeline --help-doc=unscale

Details for options can be found in :ref:`gdal_raster_unscale`.

* write

.. program-output:: gdal raster pipeline --help-doc=write

Description
-----------

:program:`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
:ref:`raster.gdalg` 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``.

.. code-block:: 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.

.. code-block:: json

    {
        "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::
   :title: Reproject a GeoTIFF file to CRS EPSG:32632 ("WGS 84 / UTM zone 32N") and adding a metadata item

   .. code-block:: bash

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

.. example::
   :title: Serialize the command of a reprojection of a GeoTIFF file in a GDALG file, and later read it

   .. code-block:: bash

        $ 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



.. below is an allow-list for spelling checker.

.. spelling:word-list::
    tpi
    tri
