名前
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);
説明
一つ以上の入力ラスター、バンドインデックスと一つのユーザ定義コールバック関数から、一つのバンドからなるラスターを返します。
-
rast,rast1,rast2, rastbandargset -
地図代数処理が行われるラスターです。
rastbandargsetによって、多数のラスターと多数のバンドにおいて地図代数処理が使用できます。一つ目の形式の例を見て下さい。 -
nband, nband1, nband2 -
処理を行うラスターのバンド番号です。nband はバンドを示す整数スカラまたは整数配列です。2ラスター/2バンドの場合では、nband1は rast1のバンド、nband2は rast2のバンドです。
-
callbackfunc -
callbackfunc引数は、SQL または PL/pgSQL 関数の名前とシグニチャでなければならず、regprocedure にキャストしなければなりません。PL/pgSQL 関数の例は次の通りです:コードCREATE OR REPLACE FUNCTION sample_callbackfunc(value double precision[][][], pos integer[][], VARIADIC userargs text[]) RETURNS double precision AS $$ BEGIN RETURN 0; END; $$ LANGUAGE 'plpgsql' IMMUTABLE;callbackfuncは、二つまたは三つの引数を持たなければなりません: 3次元倍精度浮動小数点数配列、2次元整数配列、VARIADIC の 1次元文字列配列です。一つ目の引数valueは、全ての入力ラスターからの値 (倍精度浮動小数点数) の配列です。3次元 (1始まり) は、ラスター番号、行、列です。二つ目の引数positionは、出力ラスターと入力ラスターからのピクセル位置の集合です。一つ目の次元の添え字 (0はじまりです) はラスター番号です。一つ目の次元の添え字が 0の場合に指される位置は、出力ラスターのピクセル位置です。二つ目の次元は X と Y からなる二つの要素を持ちます。三つ目の引数userargsは任意引数でユーザ定義関数特有の引数としてそのまま渡されます。コールバック関数の返り値は出力ピクセルの値として使われます。コールバック関数が
NULLを返す場合には、NODATA 値が設定されているなら出力ピクセルは NODATA に設定されます。NODATA 値が設定されていない場合にはNULLが返されるとエラーが発生します。regprocedure引数を SQL 関数に渡す場合には、渡し先の完全な関数シグネチャが必要で、さらにregprocedureにキャストします。上の例の PL/pgSQL 関数を引数として渡すには、引数の SQL は次のようになります:
コード'sample_callbackfunc(double precision[], integer[], text[])'::regprocedure
PostgreSQL 配列型は関数の引数型では次元を指定できず、コールバック関数の多次元配列は double precision[] と integer[] が regprocedure の型指定として記述されます。
-
mask -
N 次元の数値配列 (行列) で、地図代数コールバック関数に渡すセルを決めるためのフィルタに使われます。0は近隣セル値を NODATA として扱うべきであることを示し、1はデータとして扱うべきであることをそれぞれ意味します。weight が TRUE に指定されいる場合には、この配列の値は、近隣セルのピクセル値に対して掛け算を行うための数になります。
-
weighted -
マスク値に重みづけを施す (元の値に対して乗算を行う) か、施さない (マスク処理だけを行う) かを示す真偽値です。
-
pixeltype -
pixeltypeを渡した場合には、新しいラスターの一つのバンドが、そのピクセルタイプになります。pixeltype に NULL を渡したり指定しなかった場合には、新しいラスターのピクセルタイプは、一つ目のラスター (extenttype がINTERSECTION, UNION, FIRST, CUSTOM の場合) か、適切なラスター (extenttype がSECOND, LAST の場合) の指定したバンドと同じピクセルタイプになります。疑問を感じたら常にpixeltypeを渡します。出力ラスターのピクセルタイプは、必ずST_BandPixelTypeに挙げられたものの一つになるか、省略されるか、NULL に設定されます。
-
extenttype -
INTERSECTION (デフォルト), UNION, FIRST (一つのラスターを取る形式でのデフォルト), SECOND, LAST, CUSTOM のいずれかになります。
-
customextent -
extentypeが CUSTOM である場合には、ラスターはcustomextentで提供されます。一つ目の形式の例 4をご覧下さい。 -
distancex -
参照セルからのピクセル単位の距離です。結果として得られる行列の幅は
2*distancex + 1となります。指定しない場合には、参照セルだけが対象となります (0の距離の近隣ピクセル)。 -
distancey -
参照セルからのピクセル単位の距離です。結果として得られる行列の高さは
2*distancey + 1となります。指定しない場合には、参照セルが対象となります (0の距離の近隣ピクセル)。 -
userargs -
callbackfuncが第 3引数を宣言している場合には、第 3引数はvariadic text配列です。全ての引き渡されるテキスト引数は指定したcallbackfuncに渡され、userargs引数に含まれます。
![[注記]](../images/note.png)
|
|
|
VARIADIC キーワードに関する詳細情報については、PostgreSQL 文書とQuery Language (SQL) Functions (訳注: 日本語版は「問い合わせ言語 （SQL）関数」です) の"SQL Functions with Variable Numbers of Arguments" (訳注: 日本語版は「可変長引数を取る SQL 関数」) 節を参照して下さい。 |
一つ目の形式では、多数のラスターやバンドで地図代数演算が使えるようになるためのrastbandarg配列を受け付けます。一つ目の形式の例をご覧下さい。
二つ目と三つ目の形式では、一つのラスターにおける一つ以上のバンドについて演算を行います。二つ目の形式と三つ目の形式の例をご覧下さい。
四つ目の形式では、二つのラスターにおいて、それぞれ一つずつのバンドについて演算を行います。四つ目の形式の例をご覧下さい。
Availability: 2.2.0: マスクが追加されました。
Availability: 2.1.0
例
マスク無しの平均値と、隣接のみの平均値と重み付き隣接マスクの平均値との比較。重み付きマスクは結果計算前に近隣のピクセル値を 2倍にしています。
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
形式 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
前の例である近隣ピクセルを併用したカバレッジのタイルに似ていますが基本的な 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;
形式 2、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
形式 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