@crossbind/port-gdal-wasi 2.0.0-beta.50

package/dist/prebuilt/wasi-wasm32-st-release/share/man/man1/gdal-raster-color-blend.1

@@ -0,0 +1,630 @@
+'\" t
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "GDAL-RASTER-COLOR-BLEND" "1" "Aug 18, 2026" "" "GDAL"
+.SH NAME
+gdal-raster-color-blend \- Use a grayscale raster to replace the intensity of a RGB/RGBA dataset
+.sp
+Added in version 3.12.
+
+.SH SYNOPSIS
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+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] [not available in pipelines]
+  \-\-overlay <OVERLAY>                                  Overlay dataset [required]
+  \-o, \-\-output <OUTPUT>                                Output raster dataset [required] [not available in pipelines]
+
+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 or warning message) [not available in pipelines]
+
+Options:
+  \-f, \-\-of, \-\-format, \-\-output\-format <OUTPUT\-FORMAT>  Output format (\(dqGDALG\(dq allowed) [not available in pipelines]
+  \-\-co, \-\-creation\-option <KEY>=<VALUE>                Creation option [may be repeated] [not available in pipelines]
+  \-\-overwrite                                          Whether overwriting existing output dataset is allowed [not available in pipelines]
+                                                       Mutually exclusive with \-\-append
+  \-\-append                                             Append as a subdataset to existing output [not available in pipelines]
+                                                       Mutually exclusive with \-\-overwrite
+  \-\-operator <OPERATOR>                                Composition operator. OPERATOR=src\-over|hsv\-value|multiply|screen|overlay|hard\-light|darken|lighten|color\-dodge|color\-burn (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] [not available in pipelines]
+  \-\-oo, \-\-open\-option <KEY>=<VALUE>                    Open options [may be repeated] [not available in pipelines]
+.EE
+.UNINDENT
+.UNINDENT
+.SH DESCRIPTION
+.sp
+\fBgdal raster blend\fP allows the user to compose two raster datasets
+(of the same size) using a selected blending operation and an opacity setting.
+.sp
+This can be used for example to colorize a hillshade raster generated by
+\fI\%gdal raster hillshade\fP with an hypsometric rendering of a DEM generated
+by \fI\%gdal raster color\-map\fP when using the \fBhsv\-value\fP blending operator.
+.sp
+The more standard \fBsrc\-over\fP blending operator, which does \(dqalpha blending\(dq
+is also available.
+.sp
+This subcommand is also available as a potential step of \fI\%gdal raster pipeline\fP
+.SH GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET)
+.sp
+This program supports serializing the command line as a JSON file using the \fBGDALG\fP output format.
+The resulting file can then be opened as a raster dataset using the
+\fI\%GDALG: GDAL Streamed Algorithm\fP driver, and apply the specified pipeline in a on\-the\-fly /
+streamed way.
+.SH PROGRAM-SPECIFIC OPTIONS
+.INDENT 0.0
+.TP
+.B \-\-input <INPUT>
+Name of the dataset into which to blend the overlay dataset. Required.
+.sp
+When using the \fBhsv\-value\fP blending operator, this must be a three\-band or four\-band Byte raster.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-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.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-operator src\-over|hsv\-value|multiply|screen|overlay|hard\-light|lighten|darken
+Select the blending operator, which defines how the overlay dataset is
+blended into the input dataset. Defaults to \fBsrc\-over\fP\&.
+.sp
+See \fI\%Details of blending operations\fP below for details about each operator.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-overlay <OVERLAY>
+Name of the overlay dataset. Required
+.UNINDENT
+.SH STANDARD OPTIONS
+.INDENT 0.0
+.TP
+.B \-\-append
+Append input raster as a new subdataset to an existing output file.
+Only works with drivers that support adding subdatasets such as
+\fI\%GTiff \-\- GeoTIFF File Format\fP and \fI\%GPKG \-\- GeoPackage raster\fP
+This also creates the output dataset if it does not exist yet.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-co, \-\-creation\-option <NAME>=<VALUE>
+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.
+.sp
+May be repeated.
+.sp
+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
+\fI\%\-\-formats\fP
+command line option but the documentation for the format is the
+definitive source of information on driver creation options.
+See \fI\%Raster drivers\fP format
+specific documentation for legal creation options for each format.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-if, \-\-input\-format <format>
+Format/driver name to be attempted to open the input file(s). It is generally
+not necessary to specify it, but it can be used to skip automatic driver
+detection, when it fails to select the appropriate driver.
+This option can be repeated several times to specify several candidate drivers.
+Note that it does not force those drivers to open the dataset. In particular,
+some drivers have requirements on file extensions.
+.sp
+May be repeated.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-oo, \-\-open\-option <NAME>=<VALUE>
+Dataset open option (format specific).
+.sp
+May be repeated.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-f, \-\-of, \-\-format, \-\-output\-format <OUTPUT\-FORMAT>
+Which output raster format to use. Allowed values may be given by
+\fBgdal \-\-formats | grep raster | grep rw | sort\fP
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-overwrite
+Allow program to overwrite existing target file or dataset.
+Otherwise, by default, \fBgdal\fP errors out if the target file or
+dataset already exists.
+.UNINDENT
+.SH DETAILS OF BLENDING OPERATIONS
+.sp
+In the description of the blending operations, all values are normalized to [0,1] range
+and each channel value is premultiplied with the alpha channel value.
+.sp
+The following notations are used:
+.INDENT 0.0
+.IP \(bu 2
+overlay_{C} is the value of one of the red, green or blue
+component of the overlay dataset,
+.IP \(bu 2
+overlay_{A} is the value of the alpha component of the overlay dataset premultiplied by \fI\%\-\-opacity\fP,
+.IP \(bu 2
+input_{C} is the value of the corresponding component of the input dataset,
+.IP \(bu 2
+input_{A} is the value of the alpha component of the input dataset
+.IP \(bu 2
+output_{C} is the resulting component of the output dataset,
+.IP \(bu 2
+opacity is the value of \fI\%\-\-opacity\fP
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+For efficiency, the implementation uses integer arithmetic on
+[0,255] range rather than floating point arithmetic on [0,1] range.
+This can explain minor differences with the formulas described below.
+.UNINDENT
+.UNINDENT
+.sp
+For all operator (unless otherwise specified) the alpha channel is computed as:
+.sp
+.ce
+output_{A} = overlay_{A} + input_{A} \- overlay_{A} * input_{A}
+.ce 0
+.sp
+The following blending operators are available:
+.SH OVERVIEW OF RASTER BLEND OPERATORS
+.TS
+box center;
+l|l|l.
+T{
+Operator
+T}	T{
+Description
+T}	T{
+Example
+T}
+_
+T{
+\fBsrc\-over\fP
+T}	T{
+Standard alpha blending (overlay composited over input)
+T}	T{
+[image: src-over blending example]
+[image]
+T}
+_
+T{
+\fBhsv\-value\fP
+T}	T{
+Uses value from overlay and hue/saturation from input
+T}	T{
+[image: hsv-value blending example]
+[image]
+T}
+_
+T{
+\fBmultiply\fP
+T}	T{
+Multiplies input and overlay colors
+T}	T{
+[image: multiply blending example]
+[image]
+T}
+_
+T{
+\fBscreen\fP
+T}	T{
+Complement then multiply colors
+T}	T{
+[image: screen blending example]
+[image]
+T}
+_
+T{
+\fBoverlay\fP
+T}	T{
+Combines multiply and screen
+T}	T{
+[image: overlay blending example]
+[image]
+T}
+_
+T{
+\fBhard\-light\fP
+T}	T{
+Multiply or screen depending on overlay brightness
+T}	T{
+[image: hard-light blending example]
+[image]
+T}
+_
+T{
+\fBdarken\fP
+T}	T{
+Keeps the minimum of input and overlay components
+T}	T{
+[image: darken blending example]
+[image]
+T}
+_
+T{
+\fBlighten\fP
+T}	T{
+Keeps the maximum of input and overlay components
+T}	T{
+[image: lighten blending example]
+[image]
+T}
+_
+T{
+\fBcolor\-dodge\fP
+T}	T{
+Brightens input based on overlay
+T}	T{
+[image: color-dodge blending example]
+[image]
+T}
+_
+T{
+\fBcolor\-burn\fP
+T}	T{
+Darkens input based on overlay
+T}	T{
+[image: color-burn blending example]
+[image]
+T}
+.TE
+.INDENT 0.0
+.IP \(bu 2
+.INDENT 2.0
+.TP
+.B \fBsrc\-over\fP performs standard alpha blending, by compositing the overlay
+dataset over the input dataset.
+.sp
+The following formula is applied for each of the red, green and blue
+components:
+.sp
+.ce
+output_{C} * output_{A} = (overlay_{C} * overlay_{A} * opacity) + (input_{C} * input_{A} * (1 \- overlay_{A} * opacity))
+.ce 0
+.UNINDENT
+.IP \(bu 2
+.INDENT 2.0
+.TP
+.B \fBhsv\-value\fP creates a color with the value of the overlay and the hue
+and saturation of the input. It performs the following steps:
+.INDENT 7.0
+.IP \(bu 2
+read the RGB (Red,Green,Blue) components of the input dataset
+.IP \(bu 2
+transform the RGB components into the HSV (Hue,Saturation,Value) color space
+.IP \(bu 2
+compute the output value output_{V}, using the following formula:
+.UNINDENT
+.sp
+.ce
+output_{V} = (overlay_{V} * overlay_{A} * opacity) + (input_{V} * (1 \- overlay_{A} * opacity))
+.ce 0
+.sp
+If the overlay dataset is a RGB/RGBA dataset, overlay_{V} is
+max(overlay_{R},overlay_{G},overlay_{B})\&.
+.INDENT 7.0
+.IP \(bu 2
+transform back (Hue,Saturation,:math:\fIoutput_{V}\fP) to RGB.
+.UNINDENT
+.sp
+If the the alpha channel of the input dataset is present, it is preserved unchanged.
+.UNINDENT
+.IP \(bu 2
+.INDENT 2.0
+.TP
+.B \fBmultiply\fP multiplies the input and overlay colors.
+The resulting color is always at least as dark as either of the two
+constituent colors.
+.sp
+The following formula is applied for each of the red, green and blue
+components:
+.sp
+.ce
+output_{C} = overlay_{C} * input_{C} + input_{C} * (1 \- overlay_{A}) + overlay_{C} * (1 \- input_{A})
+.ce 0
+.UNINDENT
+.IP \(bu 2
+\fBscreen\fP The overlay and input are complemented and then multiplied. The resultant color is always at least as light as either of the two constituent colors. Screening any color with white produces white. Screening any color with black leaves the original color unchanged.
+.INDENT 2.0
+.INDENT 3.5
+The following formula is applied for each of the red, green and blue
+components:
+.sp
+.ce
+output_{C} = overlay_{C} + input_{C} \- overlay_{C} * input_{C}
+.ce 0
+.UNINDENT
+.UNINDENT
+.IP \(bu 2
+\fBoverlay\fP Overlay combines Multiply and Screen blend modes, at half strength. The parts of the overlay layer where the input layer is light become lighter, the parts where the input layer is dark become darker. Areas where the overlay layer are mid grey are unaffected.
+.INDENT 2.0
+.INDENT 3.5
+The following formula is applied for each of the red, green and blue
+components:
+.sp
+If the input component is less than 0.5 (dark):
+.sp
+.ce
+output_{C} = 2 * overlay_{C} * input_{C} + input_{C} * (1 \- overlay_{A}) + overlay_{C} * (1 \- input_{A})
+.ce 0
+.sp
+If the input component is greater than or equal to 0.5 (light):
+.sp
+.ce
+output_{C} = overlay_{A} *  input_{A} \- 2 * (input_{A} \- input_{C}) * (overlay_{A} \- overlay_{C}) + input_{C} * (1 \- overlay_{A}) + overlay_{C} * (1 \- input_{A})
+.ce 0
+.UNINDENT
+.UNINDENT
+.IP \(bu 2
+\fBhard\-light\fP The overlay is used to either multiply or screen the input, depending on the overlay color value. If the overlay color value is lighter than 50% gray, the input is screened, otherwise it is multiplied. This is useful for adding highlights or shadows to an image. The implementation is the same of \fBoverlay\fP but with the roles of input and overlay swapped.
+.INDENT 2.0
+.INDENT 3.5
+The following formula is applied for each of the red, green and blue
+components:
+.sp
+If the overlay component is less than 0.5 (dark):
+.sp
+.ce
+output_{C} = overlay_{A} *  input_{A} \- 2 * (input_{A} \- input_{C}) * (overlay_{A} \- overlay_{C}) + input_{C} * (1 \- overlay_{A}) + overlay_{C} * (1 \- input_{A})
+.ce 0
+.sp
+If the overlay component is greater than or equal to 0.5 (light):
+.sp
+.ce
+output_{C} = 2 * overlay_{C} * input_{C} + input_{C} * (1 \- overlay_{A}) + overlay_{C} * (1 \- input_{A})
+.ce 0
+.UNINDENT
+.UNINDENT
+.IP \(bu 2
+\fBdarken\fP Creates a image that retains the smallest components of the overlay and input pixels. If the overlay pixel has the components r1, g1, and b1, and the input pixel has r2, g2, b2, the resultant pixel is [min(r1,r2), min(g1,g2), min(b1,b2)]
+.INDENT 2.0
+.INDENT 3.5
+The following formula is applied for each of the red, green and blue
+components:
+.sp
+.ce
+output_{C} = min(overlay_{C}, input_{C}) + input_{C} * (1 \- overlay_{A}) + overlay_{C} * (1 \- input_{A})
+.ce 0
+.UNINDENT
+.UNINDENT
+.IP \(bu 2
+\fBlighten\fP Lighten has the opposite action of Darken. It selects the maximum of each component from the overlay and input pixels. If the overlay pixel has the components r1, g1, and b1, and the input pixel has r2, g2, b2, the resultant pixel is [max(r1,r2), max(g1,g2), max(b1,b2)]
+.INDENT 2.0
+.INDENT 3.5
+The following formula is applied for each of the red, green and blue
+components:
+.sp
+.ce
+output_{C} = max(overlay_{C}, input_{C}) + input_{C} * (1 \- overlay_{A}) + overlay_{C} * (1 \- input_{A})
+.ce 0
+.UNINDENT
+.UNINDENT
+.IP \(bu 2
+\fBcolor\-dodge\fP Divides the input layer by the inverted overlay layer. This lightens the input layer depending on the value of the overlay layer: the brighter the overlay layer, the more its color affects the input layer. Blending any color with white gives white. Blending with black does not change the image.
+.INDENT 2.0
+.INDENT 3.5
+The following formula is applied for each of the red, green and blue
+components:
+.sp
+If the overlay_{C} * input_{A} is greater than or equal to
+overlay_{A} * input_{A} then:
+.sp
+.ce
+output_{C} = overlay_{A} * input_{A} + input_{C} * (1 \- overlay_{A}) + overlay_{C} * (1 \- input_{A})
+.ce 0
+.sp
+If the overlay_{C} * input_{A} is less than
+overlay_{A} * input_{A} then:
+.sp
+.ce
+output_{C} = input_{C} * overlay_{A} / (1 \- overlay_{C} / overlay_{A}) + overlay_{C} * (1 \- input_{A}) + input_{C} * (1 \- overlay_{A})
+.ce 0
+.UNINDENT
+.UNINDENT
+.IP \(bu 2
+\fBcolor\-burn\fP Divides the inverted input layer by the overlay layer, and then inverts the result. This darkens the overlay layer increasing the contrast to reflect the color of the input layer. The darker the input layer, the more its color is used.
+.INDENT 2.0
+.INDENT 3.5
+The following formula is applied for each of the red, green and blue
+components:
+.sp
+If the overlay_{C} * input_{A} is greater than or equal to
+overlay_{A} * input_{A} then:
+.sp
+.ce
+output_{C} = overlay_{A} * input_{A} + input_{C} * (1 \- overlay_{A}) + overlay_{C} * (1 \- input_{A})
+.ce 0
+.sp
+If the overlay_{C} * input_{A} is greater than
+overlay_{A} * input_{A} then:
+.sp
+.ce
+output_{C} = input_{C} * overlay_{A} / (1 \- overlay_{C} / overlay_{A}) + overlay_{C} * (1 \- input_{A}) + input_{C} * (1 \- overlay_{A})
+.ce 0
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SH RETURN STATUS CODE
+.sp
+The program returns status code 0 in case of success, and non\-zero in case of
+error (non\-blocking errors emitted as warnings are considered as a successful
+execution).
+.SH EXAMPLES
+.SS Example 1: Alpha blending of two datasets using 75% opacity for the overlay dataset.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ gdal raster blend \-\-opacity 75 source.tif overlay.tif out.tif
+.EE
+.UNINDENT
+.UNINDENT
+.SS Example 2: Combine a hillshade and a hypsometric rendering of a DEM into a colorized hillshade using the hsv\-value blending operator.
+[image: Hillshade rendering of a DEM]
+[image]
+[image: Hypsometric rendering of a DEM]
+[image]
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ gdal raster blend \-\-overlay=hillshade.tif \-\-operator=hsv\-value \e
+                    hypsometric.tif hypsometric_combined_with_hillshade.tif
+.EE
+.UNINDENT
+.UNINDENT
+[image: Colorized hillshade]
+[image]
+.SS Example 3: Combine a hillshade and a hypsometric rendering of a DEM into a colorized hillshade using the multiply blending operator.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ gdal raster blend \-\-overlay=hillshade.tif \-\-operator=multiply \e
+                    hypsometric.tif hypsometric_combined_with_hillshade.tif
+.EE
+.UNINDENT
+.UNINDENT
+[image: Colorized hillshade]
+[image]
+.SS Example 4: Combine a hillshade and a hypsometric rendering of a DEM into a colorized hillshade using the screen blending operator.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ gdal raster blend \-\-overlay=hillshade.tif \-\-operator=screen \e
+                    hypsometric.tif hypsometric_combined_with_hillshade.tif
+.EE
+.UNINDENT
+.UNINDENT
+[image: Colorized hillshade]
+[image]
+.SS Example 5: Combine a hillshade and a hypsometric rendering of a DEM into a colorized hillshade using the overlay blending operator.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ gdal raster blend \-\-overlay=hillshade.tif \-\-operator=overlay \e
+                    hypsometric.tif hypsometric_combined_with_hillshade.tif
+.EE
+.UNINDENT
+.UNINDENT
+[image: Colorized hillshade]
+[image]
+.SS Example 6: Combine a hillshade and a hypsometric rendering of a DEM into a colorized hillshade using the hard\-light blending operator.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ gdal raster blend \-\-overlay=hillshade.tif \-\-operator=hard\-light \e
+                    hypsometric.tif hypsometric_combined_with_hillshade.tif
+.EE
+.UNINDENT
+.UNINDENT
+[image: Colorized hillshade]
+[image]
+.SS Example 7: Combine a hillshade and a hypsometric rendering of a DEM into a colorized hillshade using the darken blending operator.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ gdal raster blend \-\-overlay=hillshade.tif \-\-operator=darken \e
+                    hypsometric.tif hypsometric_combined_with_hillshade.tif
+.EE
+.UNINDENT
+.UNINDENT
+[image: Colorized hillshade]
+[image]
+.SS Example 8: Combine a hillshade and a hypsometric rendering of a DEM into a colorized hillshade using the lighten blending operator.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ gdal raster blend \-\-overlay=hillshade.tif \-\-operator=lighten \e
+                    hypsometric.tif hypsometric_combined_with_hillshade.tif
+.EE
+.UNINDENT
+.UNINDENT
+[image: Colorized hillshade]
+[image]
+.SS Example 9: Combine a hillshade and a hypsometric rendering of a DEM into a colorized hillshade using the color\-dodge blending operator.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ gdal raster blend \-\-overlay=hillshade.tif \-\-operator=color\-dodge \e
+                    hypsometric.tif hypsometric_combined_with_hillshade.tif
+.EE
+.UNINDENT
+.UNINDENT
+[image: Colorized hillshade]
+[image]
+.SS Example 10: Combine a hillshade and a hypsometric rendering of a DEM into a colorized hillshade using the color\-burn blending operator.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ gdal raster blend \-\-overlay=hillshade.tif \-\-operator=color\-burn \e
+                    hypsometric.tif hypsometric_combined_with_hillshade.tif
+.EE
+.UNINDENT
+.UNINDENT
+[image: Colorized hillshade]
+[image]
+.SH AUTHOR
+Even Rouault <even.rouault@spatialys.com>
+.SH COPYRIGHT
+1998-2026
+.\" Generated by docutils manpage writer.
+.