.. _gdal_raster_edit:

================================================================================
``gdal raster edit``
================================================================================

.. versionadded:: 3.11

.. only:: html

    Edit in place a raster dataset.

.. Index:: gdal raster edit

Synopsis
--------

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

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

:program:`gdal raster edit` can be used to edit a raster dataset.

This subcommand is also available as a potential step of :ref:`gdal_raster_pipeline`

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

.. option:: --approx-stats

    Compute raster band statistics for all bands. They may be computed
    based on overviews or a subset of all tiles. Useful if you are in a
    hurry and don't need precise stats.

    .. note:: This option is not available when the command is part of a pipeline.

.. option:: --auxiliary

    Force opening the dataset in read-only mode. For drivers that implement the
    Persistent Auxiliary Metadata (PAM) mechanism, changes will be
    saved in an auxiliary side car file of extension ``.aux.xml``.

.. option:: -b, --band <BAND>

    .. versionadded:: 3.13

    Index (starting at 1) of the band to which the following options apply:
    :option:`--color-map`, :option:`--unset-color-table`. Defaults to one if
    not specified.

.. option:: --bbox <xmin>,<ymin>,<xmax>,ymax>

    Override the spatial bounding box, in CRS units, without reprojecting or subsetting.
    'x' is longitude values for geographic CRS and easting for projected CRS.
    'y' is latitude values for geographic CRS and northing for projected CRS.

.. option:: --color-map <COLOR-MAP>

    .. versionadded:: 3.13

    Color map filename containing the association between various raster
    values and the corresponding wished color to set on the first band, or the
    one specified by :option:`--band`. This can be either a GDAL dataset
    with a color table attached to its first band or a text-based color configuration

    The text-based color configuration file generally contains 4 columns
    per line: the raster value and the corresponding Red, Green, Blue
    component (between 0 and 255). The raster value mus be an integer value
    between 0 and 65535.
    The raster value can also be expressed as a percentage: 0% being the minimum
    value found in the raster, 100% the maximum value.

    An extra column can be optionally added for the alpha component.
    If it is not specified, full opacity (255) is assumed.

    Various field separators are accepted: comma, tabulation, spaces, ':'.

    Common colors used by GRASS can also be specified by using their name,
    instead of the RGB triplet. The supported list is: white, black, red,
    green, blue, yellow, magenta, cyan, aqua, grey/gray, orange, brown,
    purple/violet and indigo.

        GMT :file:`.cpt` palette files are also supported (COLOR_MODEL = RGB only).

    Note: the syntax of the color configuration file is derived from the one
    supported by GRASS r.colors utility. ESRI HDR color table files (.clr)
    also match that syntax. The alpha component and the support of tab and
    comma as separators are GDAL specific extensions.

    For example:

    ::

        3500   white
        2500   235:220:175
        50%   190 185 135
        700    240 250 150
        0      50  180  50

.. option:: --crs <CRS>

    Override CRS, without reprojecting.

    The coordinate reference systems that can be passed are anything supported by the
    :cpp:func:`OGRSpatialReference::SetFromUserInput` call, which includes EPSG Projected,
    Geographic or Compound CRS (i.e. EPSG:4296), a well known text (WKT) CRS definition,
    PROJ.4 declarations, or the name of a .prj file containing a WKT CRS definition.

    ``null`` or ``none`` can be specified to unset an existing CRS.

    Note that the spatial extent is also left unchanged.

.. option:: --dataset <DATASET>

    Dataset name, to be updated in-place, unless :option:`--auxiliary` is set. Required.

.. option:: --gcp <GCP>

    .. versionadded:: 3.12

    Set ground control point(s), replacing any existing GCPs. Each GCP must be formatted as a string
    "pixel,line,easting,northing" or "pixel,line,easting,northing,elevation".
    Each GCP must be specified with a ``--gcp`` argument.

    It is also possible to provide a single ``--gcp`` argument whose value is
    the filename of a vector dataset, prefixed with `@`. This dataset must have
    a single layer with the following required fields ``column``, ``line``, ``x``, ``y``,
    and optionally ``id``, ``info`` and ``z``.

.. option:: --hist

    Compute histogram information for all bands.

    .. note:: This option is not available when the command is part of a pipeline.

.. option:: --color-interpretation [all|<BAND>=]<COLOR-INTERPRETATION>

    .. versionadded:: 3.13

    Set band color interpretation. May be repeated.

    ``<COLOR-INTERPRETATION>`` is one of ``red``, ``green``, ``blue``, ``alpha``,
    ``gray``, ``undefined``, ``pan``, ``coastal``, ``rededge``, ``nir``, ``swir``, ``mwir`` or ``lwir``.

    Several syntaxes are supported:

    - specifying ``all=<COLOR-INTERPRETATION>``: set the color interpretation on all bands.

    - specifying as many ``<COLOR-INTERPRETATION>`` as there are bands, starting from band 1 to the last band.

    - specifying the color interpretation on a subset of bands with ``<BAND>=<COLOR-INTERPRETATION>``
      where band is the band number starting at 1.

.. option:: --scale [<BAND>=]<SCALE>

    .. versionadded:: 3.13

    Set band scale factor. May be repeated.

    Several syntaxes are supported:

    - specifying one single ``<SCALE>``: set the scale on all bands.

    - specifying as many ``<SCALE>`` as there are bands, starting from band 1 to the last band.

    - specifying the scale on a subset of bands with ``<BAND>=<SCALE>``
      where band is the band number starting at 1.

.. option:: --offset [<BAND>=]<OFFSET>

    .. versionadded:: 3.13

    Set band offset constant. May be repeated.

    Several syntaxes are supported:

    - specifying one single ``<OFFSET>``: set the offset on all bands.

    - specifying as many ``<OFFSET>`` as there are bands, starting from band 1 to the last band.

    - specifying the offset on a subset of bands with ``<BAND>=<OFFSET>``
      where band is the band number starting at 1.

.. option:: --metadata <KEY>=<VALUE>

    Add/update metadata item, at the dataset level. May be repeated.

.. option:: --nodata <value>

    Override nodata value.

    ``null`` or ``none`` can be specified to unset an existing nodata value.

.. option:: --stats

    Compute raster band statistics for all bands.

.. option:: --unset-color-table

    .. versionadded:: 3.13

    Remove the color table associated to the first band, or the one specified
    by :option:`--band`.

.. option:: --unset-metadata <KEY>

    Remove metadata item, at the dataset level. May be repeated.

.. option:: --unset-metadata-domain <DOMAIN>

    .. versionadded:: 3.12

    Remove metadata domain, at the dataset level. May be repeated.

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

.. collapse:: Details

    .. include:: gdal_options/oo.rst

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

.. include:: return_code.rst

Examples
--------

.. example::
   :title: Override (without reprojecting) the CRS of a dataset

   .. code-block:: bash

        $ gdal raster edit --crs=EPSG:32632 my.tif

.. example::
   :title: Override (without reprojecting or subsetting) the bounding box of a dataset

   .. code-block:: bash

        $ gdal raster edit --bbox=2,49,3,50 my.tif

.. example::
   :title: Add a metadata item

   .. code-block:: bash

        $ gdal raster edit --metadata AUTHOR=EvenR my.tif

.. example::
   :title: Remove a metadata item

   .. code-block:: bash

        $ gdal raster edit --unset-metadata AUTHOR my.tif

.. example::
   :title: Add 2 ground control point (GCP) for (column=0,line=0,X=2,Y=49) and (column=50,line=100,X=3,Y=48)

   .. code-block:: bash

        $ gdal raster edit --gcp 0,0,2,49 --gcp 50,100,3,48 my.tif

.. example::
   :title: Add ground control point (GCP) from :file:`gcps.csv`, that must have fields named ``column``, ``line``, ``x`` and  ``y``.

   .. code-block:: bash

        $ gdal raster edit --gcp @gcps.csv my.tif

.. example::
   :title: Set red, green, blue, NIR color interpretation to a 4-band dataset

   .. code-block:: bash

        $ gdal raster edit --color-interpretation red,green,blue,nir 4band.tif
