This topic describes the ST_MapAlgebra function. This function uses algebraic expressions in compliance with Algebra Computing Language to transform multiple original raster objects into one raster object.

Syntax

raster ST_MapAlgebra(raster[] rasters ,
        cstring algebraExpr  default NULL,
        cstring storageoption default '')

Parameters

Parameter Description
rasters The original raster objects that you want to transform.
algebraExpr The JSON string that specifies the algebraic expressions that you want to use.
storageOption The JSON string that specifies how to store the new raster object.
Note The system only requires that the lengths and widths of the original raster objects are in the same unit of measurement. It does not check their spatial reference systems or resolutions. If the lengths and widths of the original raster objects are in different units of measurement, you can use the ST_Tranform, ST_Resize, and ST_Clip functions to convert them into the same unit.

Each child JSON object in the JSON string specified by the algebraExpr parameter represents a field dictated to an algebraic expression. The following table describes these fields.

Field Description Type Default value Setting notes
algebraExpr The algebraic expression that you want to use. String N/A N/A.
nodata Specifies whether nodata values are valid. Boolean false
  • If you set this field to true, nodata values are valid and pixels with nodata values are not transformed.
  • If you set this field to false, nodata values are invalid and pixels with nodata values are transformed.
nodataValue The nodata value to return for the new raster object. float8 0 N/A.

The algebraic expression specified by the algebraExpr field contains the following keywords:

  • [r, b]
    • r: indicates the ID of the new raster object in the array specified by the rasters parameter. Format: 0-n-1.
    • b: indicates the band number of the new raster object. Format: 0-n-1.
  • x

    The sequence number of the column where the specified pixel resides.

  • y

    The sequence number of the row where the specified pixel resides.

The following table lists the operations that you can incorporate in an algebraic expression.

Type Operator or function Remarks
Operators
  • +
  • -
  • *
  • /
  • % (remainder)
  • ** (power)
N/A.
Bitwise operations
  • <<
  • >>
  • &
  • |
  • ^
N/A.
Logical operations
  • <
  • >
  • ==
  • ! =
  • <=
  • >=
  • &&
  • ||
  • !
N/A.
Operations on functions
  • abs
  • sqrt
  • exp
  • log
  • ln
  • sin
  • cos
  • tan
  • sinh
  • cosh
  • tanh
  • arcsin
  • arccos
  • arctan
  • ceil
  • floor
  • round
You can specify only one operation on a function.
Statistical functions
  • min
  • max
  • sum
  • mean
  • majority
  • minority
  • std
  • median
  • range
  • variety
You must specify two or more statistical functions.
  • Example 1

    Transform the original raster object into a new raster object that only has one band. The return result is as follows: raster[0]band[0] + raster[1]band[0] * raster[1]band[1].

    [
        {
            "expr":"([0,0] + [1,0] * [1,1]) ",
            "nodata": true,
            "nodataValue":999
        }
    ]
  • Example 2

    Compute the variance of three bands.

    [
        {
            "expr":"(std([0,0],[0,1],[0,2]))",
            "nodata": true,
            "nodataValue":999
        }
    ]
  • Example 3

    Transform the original raster objects into a new raster object that has three bands. Each band is transformed by using a unique expression.

    [
        {
            "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
        }
    ]

The following table describes fields in the storageOption parameter.

Field Description Type Default value Setting notes
chunking Specifies whether to store the new raster object as chunks. Boolean Same as the original raster object N/A.
chunkdim The dimensions used to store the new raster object as chunks. String Same as the original raster object This field only takes effect when the chunking field is set to true.
chunktable The name of the chunk table. String Null string ('') By default, a temporary chunk table with a random name is generated to store data. This temporary chunk table is only valid in the current session. To save the new raster object permanently, you must specify you want to create a permanent chunk table in the chunktable field.
compression The format used for image compression. String Same as the original raster object Six compression formats are supported: None, JPEG, Zlib, PNG, LZO, and LZ4.
quality The image quality of the new raster object. Integer Same as the original raster object This field only takes effect in JPEG format.
interleaving The interleaving type of the new raster object. String Same as the original raster object Valid values:
  • bip: band interleaved by pixel (BIP)
  • bil: band interleaved by line (BIL)
  • bsq: band sequential (BSQ)
endian The endian format of the new raster object. String Same as the original raster object Valid values:
  • NDR: specifies little endian format.
  • XDR: specifies big endian format.

Examples

-- Create a permanent chunk table.
CREATE TABLE rast_mapalgebra_result(id integer, rast raster);

-- Insert data into a chunk table.
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"}'
);