ST_MapAlgebra (expression version)
Prev | 12.12. Raster Processing: Map Algebra | Next

## Name

ST_MapAlgebra (expression version) — Expression version - Returns a one-band raster given one or two input rasters, band indexes and one or more user-specified SQL expressions.

## Synopsis

`raster ST_MapAlgebra(`raster rast, integer nband, text pixeltype, text expression, double precision nodataval=NULL`)`;

`raster ST_MapAlgebra(`raster rast, text pixeltype, text expression, double precision nodataval=NULL`)`;

`raster ST_MapAlgebra(`raster rast1, integer nband1, raster rast2, integer nband2, text expression, text pixeltype=NULL, text extenttype=INTERSECTION, text nodata1expr=NULL, text nodata2expr=NULL, double precision nodatanodataval=NULL`)`;

`raster ST_MapAlgebra(`raster rast1, raster rast2, text expression, text pixeltype=NULL, text extenttype=INTERSECTION, text nodata1expr=NULL, text nodata2expr=NULL, double precision nodatanodataval=NULL`)`;

## Description

Expression version - Returns a one-band raster given one or two input rasters, band indexes and one or more user-specified SQL expressions.

Availability: 2.1.0

## Description: Variants 1 and 2 (one raster)

Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation defined by the `expression` on the input raster (`rast`). If `nband` is not provided, band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band.

If `pixeltype` is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input `rast` band.

- Keywords permitted for `expression`

  1. `[rast]` - Pixel value of the pixel of interest

  2. `[rast.val]` - Pixel value of the pixel of interest

  3. `[rast.x]` - 1-based pixel column of the pixel of interest

  4. `[rast.y]` - 1-based pixel row of the pixel of interest

## Description: Variants 3 and 4 (two raster)

Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation to the two bands defined by the `expression` on the two input raster bands `rast1`, (`rast2`). If no `band1`, `band2` is specified band 1 is assumed. The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster. The resulting raster will have the extent defined by the `extenttype` parameter.

expression

  A PostgreSQL algebraic expression involving the two rasters and PostgreSQL defined functions/operators that will define the pixel value when pixels intersect. e.g. (([rast1] + [rast2])/2.0)::integer

pixeltype

  The resulting pixel type of the output raster. Must be one listed in ST_BandPixelType, left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the first raster.

extenttype

  Controls the extent of resulting raster

  1. `INTERSECTION` - The extent of the new raster is the intersection of the two rasters. This is the default.

  2. `UNION` - The extent of the new raster is the union of the two rasters.

  3. `FIRST` - The extent of the new raster is the same as the one of the first raster.

  4. `SECOND` - The extent of the new raster is the same as the one of the second raster.

nodata1expr

  An algebraic expression involving only `rast2` or a constant that defines what to return when pixels of `rast1` are nodata values and spatially corresponding rast2 pixels have values.

nodata2expr

  An algebraic expression involving only `rast1` or a constant that defines what to return when pixels of `rast2` are nodata values and spatially corresponding rast1 pixels have values.

nodatanodataval

  A numeric constant to return when spatially corresponding rast1 and rast2 pixels are both nodata values.

- Keywords permitted in `expression`, `nodata1expr` and `nodata2expr`

  1. `[rast1]` - Pixel value of the pixel of interest from `rast1`

  2. `[rast1.val]` - Pixel value of the pixel of interest from `rast1`

  3. `[rast1.x]` - 1-based pixel column of the pixel of interest from `rast1`

  4. `[rast1.y]` - 1-based pixel row of the pixel of interest from `rast1`

  5. `[rast2]` - Pixel value of the pixel of interest from `rast2`

  6. `[rast2.val]` - Pixel value of the pixel of interest from `rast2`

  7. `[rast2.x]` - 1-based pixel column of the pixel of interest from `rast2`

  8. `[rast2.y]` - 1-based pixel row of the pixel of interest from `rast2`

## Examples: Variants 1 and 2

    WITH foo AS (
        SELECT ST_AddBand(ST_MakeEmptyRaster(10, 10, 0, 0, 1, 1, 0, 0, 0), '32BF'::text, 1, -1) AS rast
    )
    SELECT
        ST_MapAlgebra(rast, 1, NULL, 'ceil([rast]*[rast.x]/[rast.y]+[rast.val])')
    FROM foo;

## Examples: Variant 3 and 4

    WITH foo AS (
        SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI'::text, 100, 0) AS rast UNION ALL
        SELECT 2 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 1, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0), 2, '8BUI', 20, 0), 3, '32BUI'::text, 300, 0) AS rast
    )
    SELECT
        ST_MapAlgebra(
            t1.rast, 2,
            t2.rast, 1,
            '([rast2] + [rast1.val]) / 2'
        ) AS rast
    FROM foo t1
    CROSS JOIN foo t2
    WHERE t1.rid = 1
        AND t2.rid = 2;

## See Also

rastbandarg, ST_Union, ST_MapAlgebra (callback function version)

Prev | Up | Next
ST_MapAlgebra (callback function version) | Home | ST_MapAlgebraExpr