DocsICP FilingConsole
Documentation
Home Page ApsaraDB RDS RDS PostgreSQL Database Extensions Spatio Temporal Engine (GanosBase) Raster SQL reference Algebra and analysis functions ST_MapAlgebra

ST_MapAlgebra

Updated at:
Copy as MD
Product
My Favorites

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"
);
Previous：ST_ReclassifyNext：Raster image processing