Scroll to navigation

GDAL-RASTER-COLOR-BLEND(1) GDAL GDAL-RASTER-COLOR-BLEND(1)

NAME

gdal-raster-color-blend - Use a grayscale raster to replace the intensity of a RGB/RGBA dataset

Added in version 3.12.

SYNOPSIS

Usage: gdal raster blend [OPTIONS] <COLOR-INPUT> <OVERLAY> <OUTPUT>
Blend/compose two raster datasets
Positional arguments:


  -i, --color-input, --input <COLOR-INPUT>             Input raster dataset [required]


  --overlay <OVERLAY>                                  Overlay dataset [required]


  -o, --output <OUTPUT>                                Output raster dataset [required]
Common Options:


  -h, --help                                           Display help message and exit


  --json-usage                                         Display usage as JSON document and exit


  --config <KEY>=<VALUE>                               Configuration option [may be repeated]


  -q, --quiet                                          Quiet mode (no progress bar)
Options:


  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format ("GDALG" allowed)


  --co, --creation-option <KEY>=<VALUE>                Creation option [may be repeated]


  --overwrite                                          Whether overwriting existing output is allowed


                                                       Mutually exclusive with --append


  --append                                             Append as a subdataset to existing output


                                                       Mutually exclusive with --overwrite


  --operator <OPERATOR>                                Composition operator. OPERATOR=src-over|hsv-value (default: src-over)


  --opacity <OPACITY>                                  Opacity percentage to apply to the overlay dataset (0=fully transparent, 100=full use of overlay opacity) (default: 100)
Advanced Options:


  --if, --input-format <INPUT-FORMAT>                  Input formats [may be repeated]


  --oo, --open-option <KEY>=<VALUE>                    Open options [may be repeated]


DESCRIPTION

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 gdal raster hillshade with an hypsometric rendering of a DEM generated by 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 gdal raster pipeline

Standard options

Which output raster format to use. Allowed values may be given by gdal --formats | grep raster | grep rw | sort

Many formats have one or more optional creation options that can be used to control particulars about the file created. For instance, the GeoTIFF driver supports creation options to control compression, and whether the file should be tiled.

May be repeated.

The creation options available vary by format driver, and some simple formats have no creation options at all. A list of options supported for a format can be listed with the --formats command line option but the documentation for the format is the definitive source of information on driver creation options. See Raster drivers format specific documentation for legal creation options for each format.


Allow program to overwrite existing target file or dataset. Otherwise, by default, gdal errors out if the target file or dataset already exists.

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.


Name of the overlay dataset. Required

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 overlay_{C} the value of one of the red, green or blue component of the overlay dataset, overlay_{A} the value of the alpha component of the overlay dataset, input_{C} the value of the corresponding component of the input dataset, input_{A} the value of the alpha component of the input dataset and opacity, the value of --opacity, the resulting component output_{C} is (all values normalized to [0,1] range):


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

    with


    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 output_{V}, from input_{V} the input value computed in the previous step, overlay_{V} the overlay value, overlay_{A} the value of the alpha component of the overlay dataset and opacity, the value of --opacity (all values normalized to [0,1] range):


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

    If the overlay dataset is a RGB/RGBA dataset, overlay_{V} is 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.



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)

This program supports serializing the command line as a JSON file using the GDALG output format. The resulting file can then be opened as a raster dataset using the GDALG: GDAL Streamed Algorithm driver, and apply the specified pipeline in a on-the-fly / streamed way.

EXAMPLES

Example 1: Alpha blending of two datasets using 75% opacity for the overlay dataset.

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


Example 2: Combine a hillshade and a hypsometric rendering of a DEM into a colorized hillshade.

[image: Hillshade rendering of a DEM] [image] [image: Hypsometric rendering of a DEM] [image]

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


                    hypsometric.tif hypsometric_combined_with_hillshade.tif


[image: Colorized hillshade] [image]

AUTHOR

Even Rouault <even.rouault@spatialys.com>

COPYRIGHT

1998-2025

November 7, 2025