.. _gdal_raster_blend:

================================================================================
``gdal raster blend``
================================================================================

.. versionadded:: 3.12

.. only:: html

    Blend/compose two raster datasets

.. Index:: gdal raster blend

Synopsis
--------

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

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

:program:`gdal raster blend` allows the user to compose two raster datasets
(of the same size) using a selected blending operation and an opacity setting.

This can be used for example to colorize a hillshade raster generated by
:ref:`gdal_raster_hillshade` with an hypsometric rendering of a DEM generated
by :ref:`gdal_raster_color_map` when using the ``hsv-value`` blending operator.

The more standard ``src-over`` blending operator, which does "alpha blending"
is also available.

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

Standard options
++++++++++++++++

.. include:: gdal_options/of_raster_create_copy.rst

.. include:: gdal_options/co.rst

.. include:: gdal_options/overwrite.rst

.. option:: --input <INPUT>

   Name of the dataset into which to blend the overlay dataset. Required.

   When using the ``hsv-value`` blending operator, this must be a three-band or four-band Byte raster.

.. option:: --overlay <GRAYSCALE>

   Name of the overlay dataset. Required

.. option:: --operator src-over|hsv-value

    Select the blending operator, which defines how the overlay dataset is
    blended into the input dataset. Defaults to ``src-over``.

    - ``src-over`` performs standard alpha blending, by compositing the overlay
      dataset over the input dataset.

      Given :math:`overlay_{C}` the value of one of the red, green or blue
      component of the overlay dataset,
      :math:`overlay_{A}` the value of the alpha component of the overlay dataset,
      :math:`input_{C}` the value of the corresponding component of the input dataset,
      :math:`input_{A}` the value of the alpha component of the input dataset
      and :math:`opacity`, the value of :option:`--opacity`, the resulting
      component :math:`output_{C}` is (all values normalized to [0,1] range):

      .. math::

          output_{C} * output_{A} = (overlay_{C} * overlay_{A} * opacity) + (input_{C} * input_{A} * (1 - overlay_{A} * opacity))

      with

      .. math::

          output_{A} = (overlay_{A} * opacity) + (input_{A} * (1 - overlay_{A} * opacity))

    - ``hsv-value`` creates a color with the value of the overlay and the hue
      and saturation of the input. It performs the following steps:

      * read the RGB (Red,Green,Blue) components of the input dataset

      * transform the RGB components into the HSV (Hue,Saturation,Value) color space

      * compute the output value :math:`output_{V}`, from
        :math:`input_{V}` the input value computed in the previous step,
        :math:`overlay_{V}` the overlay value,
        :math:`overlay_{A}` the value of the alpha component of the overlay dataset
        and :math:`opacity`, the value of :option:`--opacity` (all values normalized to [0,1] range):

        .. math::

            output_{V} = (overlay_{V} * overlay_{A} * opacity) + (input_{V} * (1 - overlay_{A} * opacity))

        If the overlay dataset is a RGB/RGBA dataset, :math:`overlay_{V}` is
        :math:`max(overlay_{R},overlay_{G},overlay_{B})`.

      * transform back (Hue,Saturation,:math:`output_{V}`) to RGB.

      If the the alpha channel of the input dataset is present, it is preserved unchanged.


.. option:: --opacity <OPACITY>

    Opacity to use when blending the overlay dataset, as a percentage
    between 0 and 100. 0 means that the overlay dataset is considered fully
    transparent. 100 means that the overlay dataset is blended at the maximum
    of its alpha channel.
    Defaults to 100.


.. GDALG output (on-the-fly / streamed dataset)
.. --------------------------------------------

.. include:: gdal_cli_include/gdalg_raster_compatible.rst

Examples
--------

.. example::
   :title: Alpha blending of two datasets using 75% opacity for the overlay dataset.

   .. code-block:: bash

        $ gdal raster blend --opacity 75 source.tif overlay.tif out.tif

.. example::
   :title: Combine a hillshade and a hypsometric rendering of a DEM into a colorized hillshade.

   .. image:: ../../images/programs/gdal_raster_blend/hillshade.jpg
       :alt:   Hillshade rendering of a DEM

   .. image:: ../../images/programs/gdal_raster_blend/hypsometric.jpg
       :alt:   Hypsometric rendering of a DEM

   .. code-block:: bash

        $ gdal raster blend --overlay=hillshade.tif --operator=hsv-value \
                            hypsometric.tif hypsometric_combined_with_hillshade.tif


   .. image:: ../../images/programs/gdal_raster_blend/hypsometric_combined_with_hillshade.jpg
       :alt:   Colorized hillshade


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

.. spelling:word-list::
    RGB
    RGBA
    HSV
