Merges multiple raster objects into a single raster object by applying pixel-level algebraic expressions in Algebra Computing Language.
Syntax
raster ST_MapAlgebra(raster[] rasters,
cstring algebraExpr DEFAULT NULL,
cstring storageOption DEFAULT '')Parameters
| Parameter | Description |
|---|---|
rasters | An array of source raster objects to process. |
algebraExpr | A JSON array that defines the algebraic expressions to apply. Each JSON object in the array produces one output band. |
storageOption | A JSON object that controls how the output raster object is stored. |
The function only requires that all source raster objects share the same unit of measurement for width and height. It does not validate spatial reference systems or resolutions. If your source rasters use different units, use ST_Transform, ST_Resize, and ST_Clip to normalize them first.
algebraExpr parameter
algebraExpr accepts a JSON array. Each object in the array defines one output band.
Expression keywords
Use the following keywords to reference pixel values and positions inside an expression:
| Keyword | Description |
|---|---|
[r, b] | Pixel value at band b of raster r. Both r and b are zero-based indexes (0 to n−1). |
x | Zero-based column index of the current pixel. |
y | Zero-based row index of the current pixel. |
JSON fields
| Field | Type | Default | Description |
|---|---|---|---|
algebraExpr | String | — | The algebraic expression to evaluate for each pixel. |
nodata | Boolean | false | Controls how pixels with a nodata value are handled. Set to true to skip those pixels; their output value is set to nodataValue. Set to false to include them in the computation. |
nodataValue | float8 | 0 | The value written to output pixels that are skipped because nodata is true. |
Supported operators and functions
| Type | Operators / functions | Notes |
|---|---|---|
| Arithmetic | +, -, *, /, % (remainder), ** (power) | |
| Bitwise | <<, >>, &, |, ^ | |
| Logical | <, >, ==, !=, <=, >=, &&, ||, ! | |
| Math functions | abs, sqrt, exp, log, ln, sin, cos, tan, sinh, cosh, tanh, arcsin, arccos, arctan, ceil, floor, round | Specify only one math function. |
| Statistical functions | min, max, sum, mean, majority, minority, std, median, range, variety | Specify two or more statistical functions. |
algebraExpr examples
Example 1: Band linear combination (single output band)
Produces a single-band raster. The expression combines band 0 of raster[0] with bands 0 and 1 of raster[1]:
[
{
"expr": "([0,0] + [1,0] * [1,1])",
"nodata": true,
"nodataValue": 999
}
]Example 2: Standard deviation across bands
Computes the standard deviation of three bands from the same raster object:
[
{
"expr": "(std([0,0],[0,1],[0,2]))",
"nodata": true,
"nodataValue": 999
}
]Example 3: Multi-band output with per-band expressions
Produces a three-band raster. Each JSON object drives one output band — minimum, maximum, and mean of three source bands respectively:
[
{
"expr": "(min([0,0],[0,1],[0,2]))",
"nodata": true,
"nodataValue": 999
},
{
"expr": "(max([0,0],[0,1],[0,2]))",
"nodata": true,
"nodataValue": 999
},
{
"expr": "(mean([0,0],[0,1],[0,2]))",
"nodata": true,
"nodataValue": 999
}
]storageOption parameter
storageOption accepts a JSON object with the following fields. All fields are optional and default to the same setting as the source raster objects.
| Field | Type | Default | Description |
|---|---|---|---|
chunking | Boolean | Same as source | Whether to store the output as chunks. |
chunkdim | String | Same as source | Chunk dimensions. Takes effect only when chunking is true. |
chunktable | String | '' (empty) | Name of the chunk table. By default, a temporary table with a random name is created and is valid only for the current session. Specify a name to make the output raster object permanent. |
compression | String | Same as source | Compression format. Valid values: None, JPEG, Zlib, PNG, LZO, LZ4. |
quality | Integer | Same as source | Image quality. Takes effect only when compression is JPEG. |
interleaving | String | Same as source | Interleaving format. Valid values: bip (band interleaved by pixel, BIP), bil (band interleaved by line, BIL), bsq (band sequential, BSQ). |
endian | String | Same as source | Byte order. NDR for little-endian; XDR for big-endian. |
Example
The following example reads rasters from two tables, applies a linear band expression, and writes the result to a permanent chunk table.
-- Create a permanent chunk table to hold the output raster object.
CREATE TABLE rast_mapalgebra_result(id integer, rast raster);
-- Merge rasters from t1 and t2, then write the result to the permanent chunk table.
-- Expression: band[0] of raster[0] + 0.5 × band[0] of raster[1] − band[1] of raster[1]
WITH foo AS (
SELECT 1 AS rid, rast AS rast FROM t1 WHERE id = 1
UNION ALL
SELECT 2 AS rid, rast AS rast FROM t2 WHERE id = 2
)
INSERT INTO rast_mapalgebra_result
SELECT 1, ST_MapAlgebra(
ARRAY(SELECT rast FROM foo ORDER BY rid),
'[{"expr":"([0,0] + 0.5 * [1,0] - ([1,1])","nodata": true, "nodataValue":999}]',
'{"chunktable":"algebra_rbt"}' -- Store output in the permanent chunk table "algebra_rbt"
);