名称
ST_MapAlgebra (callback function version) — 回调函数版本 - 给定一个或多个输入栅格、波段索引和一个用户指定的回调函数，返回单波段栅格。
大纲
raster ST_MapAlgebra(rastbandarg[] rastbandargset, regprocedure callbackfunc, text pixeltype=NULL, text extenttype=INTERSECTION, raster customextent=NULL, integer distancex=0, integer distancey=0, text[] VARIADIC userargs=NULL);
raster ST_MapAlgebra(raster rast, integer[] nband, regprocedure callbackfunc, text pixeltype=NULL, text extenttype=FIRST, raster customextent=NULL, integer distancex=0, integer distancey=0, text[] VARIADIC userargs=NULL);
raster ST_MapAlgebra(raster rast, integer nband, regprocedure callbackfunc, text pixeltype=NULL, text extenttype=FIRST, raster customextent=NULL, integer distancex=0, integer distancey=0, text[] VARIADIC userargs=NULL);
raster ST_MapAlgebra(raster rast1, integer nband1, raster rast2, integer nband2, regprocedure callbackfunc, text pixeltype=NULL, text extenttype=INTERSECTION, raster customextent=NULL, integer distancex=0, integer distancey=0, text[] VARIADIC userargs=NULL);
raster ST_MapAlgebra(raster rast, integer nband, regprocedure callbackfunc, float8[] mask, boolean weighted, text pixeltype=NULL, text extenttype=INTERSECTION, raster customextent=NULL, text[] VARIADIC userargs=NULL);
Description
给定一个或多个输入栅格、波段索引和一个用户指定的回调函数，返回单波段栅格。
-
rast,rast1,rast2, rastbandargset -
评估地图代数过程的栅格。
rastbandargset允许在许多栅格和/或许多波段上使用地图代数运算。 请参见示例变体 1。 -
nband, nband1, nband2 -
要评估的栅格的波段号。 nband 可以是表示波段的整数或整数[]。 对于 the 2 raster/2band 情况，nband1 是 rast1 上的波段，nband2 是 rast2 上的波段。
-
callbackfunc -
callbackfunc参数必须是 SQL 或 PL/pgSQL 函数的名称和签名，转换为 regprocedure。 PL/pgSQL 函数示例如下：CodeCREATE OR REPLACE FUNCTION sample_callbackfunc(value double precision[][][], pos integer[][], VARIADIC userargs text[]) RETURNS double precision AS $$ BEGIN RETURN 0; END; $$ LANGUAGE 'plpgsql' IMMUTABLE;The
callbackfuncmust have two or three arguments: a 3-dimension double precision array, a 2-dimension integer array and, optionally, a variadic 1-dimension text array. The first argumentvalueis the set of values (as double precision) from all input rasters. The three dimensions (where indexes are 1-based) are: raster #, row y, column x. The second argumentpositionis the set of pixel positions from the output raster and input rasters. The outer dimension (where indexes are 0-based) is the raster #. The position at outer dimension index 0 is the output raster's pixel position. For each outer dimension, there are two elements in the inner dimension for X and Y. The optional third argumentuserargsis for passing through any user-specified arguments.The callback return value is used as the value of the output pixel. If the callback returns
NULL, the output pixel is set to NODATA when the output band has a NODATA value. If the output band has no NODATA value, aNULLcallback result raises an error.将 regprocedure 参数传递给 SQL 函数需要传递完整的函数签名，然后转换为 regprocedure 类型。 要将上述示例 PL/pgSQL 函数作为参数传递，参数的 SQL 为：
Code'sample_callbackfunc(double precision[], integer[], text[])'::regprocedure
Note that PostgreSQL array types do not encode dimensions in function signatures, so multidimensional callback arguments are written as double precision[] and integer[] in the regprocedure signature.
-
mask -
n 维数字数组（矩阵），用于过滤传递给映射代数回调函数的单元格。 0 表示相邻像元值应被视为无数据，1 表示值应被视为数据。 如果权重设置为 true，则这些值将用作乘数，以乘以邻域位置中该值的像素值。
-
weighted -
布尔值（true/false）表示掩码值是否应该加权（乘以原始值）（仅适用于采用掩码的原型）。
-
pixeltype -
如果传入
像素类型，则新栅格的一个波段将属于该像素类型。 如果将像素类型传递为 NULL 或省略，则新栅格波段将具有与第一个栅格的指定波段（对于范围类型：INTERSECTION、UNION、FIRST、CUSTOM）或相应栅格的指定波段（对于范围）相同的像素类型。 类型：第二个、最后一个）。 如果有疑问，请始终指定像素类型。输出栅格的结果像素类型必须是ST_BandPixelType 中列出的类型，或者省略或设置为 NULL。
-
extenttype -
可能的值为 INTERSECTION（默认）、UNION、FIRST（一个栅格变体的默认值）、SECOND、LAST、CUSTOM。
-
customextent -
如果
extenttype是CUSTOM，则必须为customextent提供栅格。 请参见变体 1 的示例 4。 -
distancex -
x 方向上距参考单元格的距离（以像素为单位）。 因此，结果矩阵的宽度将为
2*distancex + 1。如果未指定，则仅考虑参考单元（0 的邻域）。 -
distancey -
y 方向上距参考单元的距离（以像素为单位）。 结果矩阵的高度将为
2*distancey + 1。如果未指定，则仅考虑参考单元格（0 的邻域）。 -
userargs -
If the
callbackfuncdeclares a third argument, that argument is a variadic text array. All trailing text arguments are passed through to the specifiedcallbackfunc, and are contained in theuserargsargument.
![[注意]](../images/note.png)
|
|
|
有关 VARIADIC 关键字的更多信息，请参阅 PostgreSQL 文档和查询语言 (SQL) 函数的“具有可变参数数量的 SQL 函数”部分。 |
变体 1 接受 rastbandarg 数组，允许在许多栅格和/或许多波段上使用地图代数运算。 请参见示例变体 1。
变体 2 和 3 对一个栅格的一个或多个波段进行操作。 请参阅示例变体 2 和 3。
变体 4 对两个栅格进行操作，每个栅格一个波段。 请参见示例变体 4。
可用性：2.2.0：能够添加遮罩
可用性：2.1.0
示例
Compare an unmasked mean with neighbor-only and weighted-neighbor masks. The weighted mask multiplies neighboring values by 2 before computing the result.
WITH foo AS (
SELECT ST_SetBandNoDataValue(
ST_SetValue(
ST_SetValue(
ST_AsRaster(
ST_Buffer('LINESTRING(50 50,100 90,100 50)'::geometry, 5, 'join=bevel'),
200, 200, ARRAY['8BUI'], ARRAY[100], ARRAY[0]
),
ST_Buffer('POINT(70 70)'::geometry, 10, 'quad_segs=1'),
50
),
'LINESTRING(20 20,100 100,150 98)'::geometry,
1
),
0
) AS rast
), variants AS (
SELECT 'original' AS title, rast
FROM foo
UNION ALL
SELECT 'unmasked mean' AS title,
ST_MapAlgebra(rast, 1, 'ST_Mean4ma(double precision[], int[], text[])'::regprocedure) AS rast
FROM foo
UNION ALL
SELECT 'neighbor-only mean' AS title,
ST_MapAlgebra(
rast,
1,
'ST_Mean4ma(double precision[], int[], text[])'::regprocedure,
'{{1,1,1}, {1,0,1}, {1,1,1}}'::double precision[],
false
) AS rast
FROM foo
UNION ALL
SELECT 'weighted neighbor mean' AS title,
ST_MapAlgebra(
rast,
1,
'ST_Mean4ma(double precision[], int[], text[])'::regprocedure,
'{{2,2,2}, {2,0,2}, {2,2,2}}'::double precision[],
true
) AS rast
FROM foo
)
SELECT title, ST_AsPNG(rast) AS image
FROM variants;
title | image
------------------------+--------------------------------
original | PNG image, 200 x 200 pixels
unmasked mean | PNG image, 200 x 200 pixels
neighbor-only mean | PNG image, 200 x 200 pixels
weighted neighbor mean | PNG image, 200 x 200 pixels
Variant 1.
一个栅格，一个波段
WITH foo AS (
SELECT 1 AS rid, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0) AS rast
)
SELECT
ST_MapAlgebra(ARRAY[ROW(rast, 1)]::rastbandarg[],
'sample_callbackfunc(double precision[], int[], text[])'::regprocedure
) AS rast
FROM foo
一个栅格，多个波段
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', 100, 0) AS rast
)
SELECT
ST_MapAlgebra(ARRAY[ROW(rast, 3), ROW(rast, 1), ROW(rast, 3), ROW(rast, 2)]::rastbandarg[],
'sample_callbackfunc(double precision[], int[], text[])'::regprocedure
) AS rast
FROM foo
多个栅格，多个波段
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', 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', 300, 0) AS rast
)
SELECT
ST_MapAlgebra(ARRAY[ROW(t1.rast, 3), ROW(t2.rast, 1), ROW(t2.rast, 3), ROW(t1.rast, 2)]::rastbandarg[],
'sample_callbackfunc(double precision[], int[], text[])'::regprocedure
) AS rast
FROM foo t1
CROSS JOIN foo t2
WHERE t1.rid = 1
AND t2.rid = 2
完整示例：带邻域的覆盖示例。
WITH foo AS (
SELECT 0 AS rid, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0) AS rast UNION ALL
SELECT 1, ST_AddBand(ST_MakeEmptyRaster(2, 2, 2, 0, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0) AS rast UNION ALL
SELECT 2, ST_AddBand(ST_MakeEmptyRaster(2, 2, 4, 0, 1, -1, 0, 0, 0), 1, '16BUI', 3, 0) AS rast UNION ALL
SELECT 3, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, -2, 1, -1, 0, 0, 0), 1, '16BUI', 10, 0) AS rast UNION ALL
SELECT 4, ST_AddBand(ST_MakeEmptyRaster(2, 2, 2, -2, 1, -1, 0, 0, 0), 1, '16BUI', 20, 0) AS rast UNION ALL
SELECT 5, ST_AddBand(ST_MakeEmptyRaster(2, 2, 4, -2, 1, -1, 0, 0, 0), 1, '16BUI', 30, 0) AS rast UNION ALL
SELECT 6, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, -4, 1, -1, 0, 0, 0), 1, '16BUI', 100, 0) AS rast UNION ALL
SELECT 7, ST_AddBand(ST_MakeEmptyRaster(2, 2, 2, -4, 1, -1, 0, 0, 0), 1, '16BUI', 200, 0) AS rast UNION ALL
SELECT 8, ST_AddBand(ST_MakeEmptyRaster(2, 2, 4, -4, 1, -1, 0, 0, 0), 1, '16BUI', 300, 0) AS rast
)
SELECT
t1.rid,
ST_MapAlgebra(ARRAY[ROW(ST_Union(t2.rast), 1)]::rastbandarg[],
'sample_callbackfunc(double precision[], int[], text[])'::regprocedure,
'32BUI',
'CUSTOM', t1.rast,
1, 1
) AS rast
FROM foo t1
CROSS JOIN foo t2
WHERE t1.rid = 4
AND t2.rid BETWEEN 0 AND 8
AND ST_Intersects(t1.rast, t2.rast)
GROUP BY t1.rid, t1.rast
示例：与前一个带邻域的覆盖 tile 示例类似，但只使用基础 SQL 特性来实现。
WITH src AS (
SELECT 0 AS rid, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0) AS rast UNION ALL
SELECT 1, ST_AddBand(ST_MakeEmptyRaster(2, 2, 2, 0, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0) AS rast UNION ALL
SELECT 2, ST_AddBand(ST_MakeEmptyRaster(2, 2, 4, 0, 1, -1, 0, 0, 0), 1, '16BUI', 3, 0) AS rast UNION ALL
SELECT 3, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, -2, 1, -1, 0, 0, 0), 1, '16BUI', 10, 0) AS rast UNION ALL
SELECT 4, ST_AddBand(ST_MakeEmptyRaster(2, 2, 2, -2, 1, -1, 0, 0, 0), 1, '16BUI', 20, 0) AS rast UNION ALL
SELECT 5, ST_AddBand(ST_MakeEmptyRaster(2, 2, 4, -2, 1, -1, 0, 0, 0), 1, '16BUI', 30, 0) AS rast UNION ALL
SELECT 6, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, -4, 1, -1, 0, 0, 0), 1, '16BUI', 100, 0) AS rast UNION ALL
SELECT 7, ST_AddBand(ST_MakeEmptyRaster(2, 2, 2, -4, 1, -1, 0, 0, 0), 1, '16BUI', 200, 0) AS rast UNION ALL
SELECT 8, ST_AddBand(ST_MakeEmptyRaster(2, 2, 4, -4, 1, -1, 0, 0, 0), 1, '16BUI', 300, 0) AS rast
), foo AS (
SELECT
t1.rid,
ST_Union(t2.rast) AS rast
FROM src t1
JOIN src t2
ON ST_Intersects(t1.rast, t2.rast)
AND t2.rid BETWEEN 0 AND 8
WHERE t1.rid = 4
GROUP BY t1.rid
), bar AS (
SELECT
t1.rid,
ST_MapAlgebra(
ARRAY[ROW(t2.rast, 1)]::rastbandarg[],
'sample_callbackfunc(double precision[], int[], text[])'::regprocedure,
'32BUI',
'CUSTOM', t1.rast,
1, 1
) AS rast
FROM src t1
JOIN foo t2
ON t1.rid = t2.rid
)
SELECT
rid,
(ST_MetaData(rast)),
(ST_BandMetaData(rast, 1)),
ST_Value(rast, 1, 1, 1)
FROM bar;
Variants 2 and 3.
一个栅格，多个波段
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', 100, 0) AS rast
)
SELECT
ST_MapAlgebra(
rast,
ARRAY[3, 1, 3, 2]::integer[],
'sample_callbackfunc(double precision[], int[], text[])'::regprocedure
) AS rast
FROM foo
一个栅格，一个波段
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', 100, 0) AS rast
)
SELECT
ST_MapAlgebra(
rast,
2,
'sample_callbackfunc(double precision[], int[], text[])'::regprocedure
) AS rast
FROM foo
Variant 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', 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', 300, 0) AS rast
)
SELECT
ST_MapAlgebra(
t1.rast,
2,
t2.rast,
1,
'sample_callbackfunc(double precision[], int[], text[])'::regprocedure
) AS rast
FROM foo t1
CROSS JOIN foo t2
WHERE t1.rid = 1
AND t2.rid = 2