ST_MapAlgebraFct
Prev | 12.12. Raster Processing: Map Algebra | Next

## Name

ST_MapAlgebraFct — 1 band version - Creates a new one band raster formed by applying a valid PostgreSQL function on the input raster band and of pixeltype prodived. Band 1 is assumed if no band is specified.

## Synopsis

`raster ST_MapAlgebraFct(`raster rast, regprocedure onerasteruserfunc`)`;

`raster ST_MapAlgebraFct(`raster rast, regprocedure onerasteruserfunc, text[] VARIADIC args`)`;

`raster ST_MapAlgebraFct(`raster rast, text pixeltype, regprocedure onerasteruserfunc`)`;

`raster ST_MapAlgebraFct(`raster rast, text pixeltype, regprocedure onerasteruserfunc, text[] VARIADIC args`)`;

`raster ST_MapAlgebraFct(`raster rast, integer band, regprocedure onerasteruserfunc`)`;

`raster ST_MapAlgebraFct(`raster rast, integer band, regprocedure onerasteruserfunc, text[] VARIADIC args`)`;

`raster ST_MapAlgebraFct(`raster rast, integer band, text pixeltype, regprocedure onerasteruserfunc`)`;

`raster ST_MapAlgebraFct(`raster rast, integer band, text pixeltype, regprocedure onerasteruserfunc, text[] VARIADIC args`)`;

## Description

ST_MapAlgebraFct is deprecated as of 2.1.0. Use ST_MapAlgebra (callback function version) instead.

Creates a new one band raster formed by applying a valid PostgreSQL function specified by the `onerasteruserfunc` on the input raster (`rast`). If no `band` is specified, 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.

The `onerasteruserfunc` parameter must be the name and signature of a SQL or PL/pgSQL function, cast to a regprocedure. A very simple and quite useless PL/pgSQL function example is:

    CREATE OR REPLACE FUNCTION simple_function(pixel FLOAT, pos INTEGER[], VARIADIC args TEXT[])
        RETURNS FLOAT
        AS $$ BEGIN
            RETURN 0.0;
        END; $$
        LANGUAGE 'plpgsql' IMMUTABLE;

The `userfunction` may accept two or three arguments: a float value, an optional integer array, and a variadic text array. The first argument is the value of an individual raster cell (regardless of the raster datatype). The second argument is the position of the current processing cell in the form '{x,y}'. The third argument indicates that all remaining parameters to ST_MapAlgebraFct shall be passed through to the `userfunction`.

Passing a regprodedure argument to a SQL function requires the full function signature to be passed, then cast to a regprocedure type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:

    'simple_function(float,integer[],text[])'::regprocedure

Note that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a regprocedure.

The third argument to the `userfunction` is a variadic text array. All trailing text arguments to any ST_MapAlgebraFct call are passed through to the specified `userfunction`, and are contained in the `args` argument.

For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of Query Language (SQL) Functions.

The text[] argument to the `userfunction` is required, regardless of whether you choose to pass any arguments to your user function for processing or not.

Availability: 2.0.0

## Examples

Create a new 1 band raster from our original that is a function of modulo 2 of the original raster band.

    ALTER TABLE dummy_rast ADD COLUMN map_rast raster;
    CREATE FUNCTION mod_fct(pixel float, pos integer[], variadic args text[])
    RETURNS float
    AS $$
    BEGIN
        RETURN pixel::integer % 2;
    END;
    $$
    LANGUAGE 'plpgsql' IMMUTABLE;

    UPDATE dummy_rast SET map_rast = ST_MapAlgebraFct(rast,NULL,'mod_fct(float,integer[],text[])'::regprocedure) WHERE rid = 2;

    SELECT ST_Value(rast,1,i,j) As origval, ST_Value(map_rast, 1, i, j) As mapval
    FROM dummy_rast CROSS JOIN generate_series(1, 3) AS i CROSS JOIN generate_series(1,3) AS j
    WHERE rid = 2;

     origval | mapval
    ---------+--------
         253 |      1
         254 |      0
         253 |      1
         253 |      1
         254 |      0
         254 |      0
         250 |      0
         254 |      0
         254 |      0

Create a new 1 band raster of pixel-type 2BUI from our original that is reclassified and set the nodata value to a passed parameter to the user function (0).

    ALTER TABLE dummy_rast ADD COLUMN map_rast2 raster;
    CREATE FUNCTION classify_fct(pixel float, pos integer[], variadic args text[])
    RETURNS float
    AS
    $$
    DECLARE
        nodata float := 0;
    BEGIN
        IF NOT args[1] IS NULL THEN
            nodata := args[1];
        END IF;
        IF pixel < 251 THEN
            RETURN 1;
        ELSIF pixel = 252 THEN
            RETURN 2;
        ELSIF pixel > 252 THEN
            RETURN 3;
        ELSE
            RETURN nodata;
        END IF;
    END;
    $$
    LANGUAGE 'plpgsql';
    UPDATE dummy_rast SET map_rast2 = ST_MapAlgebraFct(rast,'2BUI','classify_fct(float,integer[],text[])'::regprocedure, '0') WHERE rid = 2;

    SELECT DISTINCT ST_Value(rast,1,i,j) As origval, ST_Value(map_rast2, 1, i, j) As mapval
    FROM dummy_rast CROSS JOIN generate_series(1, 5) AS i CROSS JOIN generate_series(1,5) AS j
    WHERE rid = 2;

     origval | mapval
    ---------+--------
         249 |      1
         250 |      1
         251 |
         252 |      2
         253 |      3
         254 |      3

    SELECT ST_BandPixelType(map_rast2) As b1pixtyp
    FROM dummy_rast WHERE rid = 2;

     b1pixtyp
    ----------
     2BUI

original (column rast-view) | rast_view_ma

Create a new 3 band raster same pixel type from our original 3 band raster with first band altered by map algebra and remaining 2 bands unaltered.

    CREATE FUNCTION rast_plus_tan(pixel float, pos integer[], variadic args text[])
    RETURNS float
    AS
    $$
    BEGIN
        RETURN tan(pixel) * pixel;
    END;
    $$
    LANGUAGE 'plpgsql';

    SELECT ST_AddBand(
        ST_AddBand(
            ST_AddBand(
                ST_MakeEmptyRaster(rast_view),
                ST_MapAlgebraFct(rast_view,1,NULL,'rast_plus_tan(float,integer[],text[])'::regprocedure)
            ),
            ST_Band(rast_view,2)
        ),
        ST_Band(rast_view, 3) As rast_view_ma
    )
    FROM wind
    WHERE rid=167;

## See Also

ST_MapAlgebraExpr, ST_BandPixelType, ST_GeoReference, ST_SetValue

Prev | Up | Next
ST_MapAlgebraExpr | Home | ST_MapAlgebraFct