金仓数据库 KingbaseGIS 使用手册（8.4. 栅格存取函数）

8.4. 栅格存取函数

8.4.1. ST_GeoReference

ST_GeoReference — 返回栅格的地理参考元数据信息，有GDAL和ESRI格式，默认是GDAL格式。

用法

text ST_GeoReference(raster rast, text format=GDAL);

描述

在一个world file（关于该数据格式参考：https://en.wikipedia.org/wiki/World_file）中返回栅格的地理参考元数据信息，有GDAL和ESRI格式，默认是GDAL格式。

GDAL和ESRI格式的区别如下：

GDAL:

scalex

skewy

skewx

scaley

upperleftx

upperlefty

ESRI:

scalex

skewy

skewx

scaley

upperleftx + scalex*0.5

upperlefty + scaley*0.5

样例

SELECT ST_GeoReference(rast, 'ESRI') As esri_ref, ST_GeoReference(rast, 'GDAL') As gdal_ref
FROM dummy_rast WHERE rid=1;

esri_ref     | gdal_ref
-------------+--------------------
2.0000000000 | 2.0000000000
0.0000000000 : 0.0000000000
0.0000000000 : 0.0000000000
3.0000000000 : 3.0000000000
1.5000000000 : 0.5000000000
2.0000000000 : 0.5000000000

参考

ST_SetGeoReference, ST_ScaleX, ST_ScaleY

8.4.2. ST_Height

ST_Height — 返回一个栅格的以像素数为单位的高度。

用法

integer ST_Height(raster rast);

描述

返回一个栅格的以像素数为单位的高度。

样例

SELECT rid, ST_Height(rast) As rastheight FROM dummy_rast;

rid  | rastheight
-----+------------
1    | 20
2    | 5

参考

ST_Width

8.4.3. ST_IsEmpty

ST_IsEmpty — 如果栅格是空的(width = 0 and height = 0)，返回true，否则返回false。

用法

boolean ST_IsEmpty(raster rast);

描述

如果栅格是空的(width = 0 and height = 0)，返回true，否则返回false。

样例

SELECT ST_IsEmpty(ST_MakeEmptyRaster(100, 100, 0, 0, 0, 0, 0, 0));

st_isempty
-----------
f

SELECT ST_IsEmpty(ST_MakeEmptyRaster(0, 0, 0, 0, 0, 0, 0, 0));

st_isempty
-----------
t

参考

ST_HasNoBand

8.4.4. ST_MetaData

ST_MetaData — 返回栅格对象的基本元数据信息，例如像元大小、旋转信息等等。

用法

record ST_MetaData(raster rast);

描述

返回栅格对象的基本元数据信息，例如像元大小、旋转信息等等。

列的输出格式如下：

upperleftx | upperlefty | width | height | scalex | scaley | skewx| skewy | srid | numbands

样例

SELECT rid, (foo.md).*
FROM (SELECT rid, ST_MetaData(rast) As md FROM dummy_rast) As foo;

rid| upperleftx| upperlefty | width | height | scalex | scaley    | skewx | skewy | srid |numbands
---+-----------+------------+-------+--------+--------+-----------+-------+-------+------+-------
1  |0.5        |0.5         |10     |20      |2       |3          |0      |0      |0     |0
2  |3427927.75 |5793244     |5      |5       |0.05    |-0.05      |0      |0      |0     |3

参考

ST_BandMetaData, ST_NumBands

8.4.5. ST_NumBands

ST_NumBands — 返回栅格对象的波段数。

用法

integer ST_NumBands(raster rast);

描述

返回栅格对象的波段数。

样例

SELECT rid, ST_NumBands(rast) As numbands FROM dummy_rast;

rid | numbands
----+----------
1   | 0
2   | 3

参考

ST_Value

8.4.6. ST_PixelHeight

ST_PixelHeight — 返回像元的高度，单位以空间参考系所规定的几何单位为准。

用法

double precision ST_PixelHeight(raster rast);

描述

返回像元的高度，单位以空间参考系所规定的几何单位为准。在没有倾斜的情况下，像素宽度只是几何坐标和栅格像素值的比值。

参考函数 ST_PixelWidth来得到栅格关系的可视化结果。

样例 : Rasters with no skew

SELECT ST_Height(rast) As rastheight, ST_PixelHeight(rast) As pixheight,
ST_ScaleX(rast) As scalex, ST_ScaleY(rast) As scaley,
ST_SkewX(rast) As skewx, ST_SkewY(rast) As skewy
FROM dummy_rast;

rastheight | pixheight| scalex| scaley| skewx| skewy
-----------+----------+-------+-------+------+----------
20         | 3        | 2     | 3     | 0    | 0
5          | 0.05     | 0.05  | -0.05 | 0    | 0

样例 : Rasters with skew different than 0

SELECT ST_Height(rast) As rastheight, ST_PixelHeight(rast) As pixheight,
ST_ScaleX(rast) As scalex, ST_ScaleY(rast) As scaley,
ST_SkewX(rast) As skewx, ST_SkewY(rast) As skewy
FROM (SELECT ST_SetSKew(rast,0.5,0.5) As rast
FROM dummy_rast) As skewed;

rastheight | pixheight         | scalex | scaley | skewx |skewy
-----------+-------------------+--------+--------+-------+----------
20         | 3.04138126514911  | 2      | 3      | 0.5   | 0.5
5          | 0.502493781056044 | 0.05   | -0.05  | 0.5   | 0.5

参考

ST_PixelWidth, ST_ScaleX, ST_ScaleY, ST_SkewX, ST_SkewY

8.4.7. ST_PixelWidth

ST_PixelWidth —返回像元的宽度，宽度单位以空间参考系规定的为准。

用法

double precision ST_PixelWidth(raster rast);

描述

返回像元的宽度，宽度单位以空间参考系规定的为准。在没有倾斜的情况下，像素宽度只是几何坐标和栅格像素值的比值。

下图展示了相关关系：

样例 : Rasters with no skew

SELECT ST_Width(rast) As rastwidth, ST_PixelWidth(rast) As pixwidth,
ST_ScaleX(rast) As scalex, ST_ScaleY(rast) As scaley,
ST_SkewX(rast) As skewx, ST_SkewY(rast) As skewy
FROM dummy_rast;

rastwidth  | pixwidth | scalex | scaley | skewx | skewy
-----------+----------+--------+--------+-------+----------
10         | 2        | 2      | 3      | 0     | 0
5          | 0.05     | 0.05   | -0.05  | 0     | 0

样例 : Rasters with skew different than 0

SELECT ST_Width(rast) As rastwidth, ST_PixelWidth(rast) As pixwidth,
ST_ScaleX(rast) As scalex, ST_ScaleY(rast) As scaley,
ST_SkewX(rast) As skewx, ST_SkewY(rast) As skewy
FROM (SELECT ST_SetSkew(rast,0.5,0.5) As rast
FROM dummy_rast) As skewed;

rastwidth  | pixwidth          | scalex | scaley | skewx |skewy
-----------+-------------------+--------+--------+-------+----------
10         | 2.06155281280883  | 2      | 3      | 0.5   | 0.5
5          | 0.502493781056044 | 0.05   | -0.05  | 0.5   | 0.5

参考

ST_PixelHeight, ST_ScaleX, ST_ScaleY, ST_SkewX, ST_SkewY

8.4.8. ST_ScaleX

ST_ScaleX —像素块 x 方向上的像素数应输入整数值，即宽度，坐标单位以空间参考系为准。

用法

float8 ST_ScaleX(raster rast);

描述

像素块 x 方向上的像素数应输入整数值，坐标单位以空间参考系为准。参考World File获取更多信息。

样例

SELECT rid, ST_ScaleX(rast) As rastpixwidth FROM dummy_rast;

rid  | rastpixwidth
-----+--------------
1    | 2
2    | 0.05

参考

ST_Width

8.4.9. ST_ScaleY

ST_ScaleY — 像素块Y方向上的像素数应输入整数值，即高度，坐标单位以空间参考系为准。

用法

float8 ST_ScaleY(raster rast);

描述

像素块Y方向上的像素数应输入整数值，即高度，坐标单位以空间参考系为准，参考World File获取更多信息。

样例

SELECT rid, ST_ScaleY(rast) As rastpixheight FROM dummy_rast;

rid  | rastpixheight
-----+---------------
1    | 3
2    | -0.05

参考

ST_Height

8.4.10. ST_RasterToWorldCoord

ST_RasterToWorldCoord — 根据给定点的行和列的位置值，返回栅格的左上角点的几何值X和Y（即经度和维度），行和列从1开始。

用法

record ST_RasterToWorldCoord(raster rast, integer xcolumn, integer yrow);
返回的X和Y的值是根据参考栅格的几何单位定的。列和行的计数从1开始，
但如果其中任意一个参数传递的参数是0或者一个负数或者大于参考栅格的维度值，那么返回的坐标会在栅格之外，因为这样的参数值会被假定超出了参考栅格的边界。

样例

-- non-skewed raster
SELECT
rid,
(ST_RasterToWorldCoord(rast,1, 1)).*,
(ST_RasterToWorldCoord(rast,2, 2)).* FROM dummy_rast;

rid  | longitude  | latitude | longitude |latitude
-----+------------+----------+-----------+------------
1    | 0.5        | 0.5      | 2.5       | 3.5
2    | 3427927.75 | 5793244  | 3427927.8 |5793243.95

-- skewed raster
SELECT rid,
(ST_RasterToWorldCoord(rast, 1, 1)).*,
(ST_RasterToWorldCoord(rast, 2, 3)).*
FROM ( SELECT rid,
ST_SetSkew(rast, 100.5, 0) As rast
FROM dummy_rast
) As foo;

rid  | longitude  | latitude | longitude |latitude
-----+------------+----------+-----------+-----------
1    | 0.5        | 0.5      | 203.5     | 6.5
2    | 3427927.75 | 5793244  | 3428128.8 | 5793243.9

参考

ST_RasterToWorldCoordX, ST_RasterToWorldCoordY, ST_SetSkew

8.4.11. ST_RasterToWorldCoordX

ST_RasterToWorldCoordX —根据给定点的行和列的位置值，返回栅格的左上角点的X坐标（即经度），行和列从1开始。

用法

float8 ST_RasterToWorldCoordX(raster rast, integer xcolumn);
float8 ST_RasterToWorldCoordX(raster rast, integer xcolumn, integer yrow);

描述

根据给定点的行和列的位置值，返回栅格的左上角点的X坐标（即经度），行和列从1开始。 列和行的计数从1开始，但如果其中任意一个参数传递的参数是0或者一个负数或者大于参考栅格的维度值，那么返回的坐标会在栅格之外，因为这样的参数值会被假定超出了参考栅格的边界。

注意

对于非倾斜栅格，提供X列就足够了，对于倾斜栅格，其地理参考坐标是函数ST_ScaleX 和 ST_SkewX返回值，需要提供行和列的参数值。 对于倾斜的栅格，如果值提供参数X值，那么将会抛出一个错误。

样例

-- non-skewed raster providing column is sufficient
SELECT rid, ST_RasterToWorldCoordX(rast,1) As x1coord,
ST_RasterToWorldCoordX(rast,2) As x2coord,
ST_ScaleX(rast) As pixelx
FROM dummy_rast;

rid| x1coord    | x2coord   |pixelx
---+------------+-----------+--------
1  | 0.5        | 2.5       | 2
2  | 3427927.75 | 3427927.8 | 0.05

-- for fun lets skew it
SELECT rid, ST_RasterToWorldCoordX(rast, 1, 1) As x1coord,
ST_RasterToWorldCoordX(rast, 2, 3) As x2coord,ST_ScaleX(rast) As pixelx
FROM (SELECT rid, ST_SetSkew(rast, 100.5, 0) As rast FROM dummy_rast) As foo;

rid| x1coord    | x2coord   |pixelx
---+------------+-----------+--------
1  | 0.5        | 203.5     | 2
2  | 3427927.75 | 3428128.8 | 0.05

参考

ST_ScaleX, ST_RasterToWorldCoordY, ST_SetSkew, ST_SkewX

8.4.12. ST_RasterToWorldCoordY

ST_RasterToWorldCoordY —根据给定点的行和列的位置值，返回栅格的左上角点的Y坐标（即维度），行和列从1开始。

用法

float8 ST_RasterToWorldCoordY(raster rast, integer yrow);
float8 ST_RasterToWorldCoordY(raster rast, integer xcolumn, integer yrow);

描述

根据给定点的行和列的位置值，返回栅格的左上角点的Y坐标（即经度），行和列从1开始。 列和行的计数从1开始，但如果其中任意一个参数传递的参数是0或者一个负数或者大于参考栅格的维度值，那么返回的坐标会在栅格之外，因为这样的参数值会被假定超出了参考栅格的边界。

注意

对于非倾斜栅格，提供Y参数就足够了，对于倾斜栅格，其地理参考坐标是函数ST_ScaleY和ST_SkewY返回值，需要提供行和列的参数值。 对于倾斜的栅格，如果值提供参数Y值，那么将会抛出一个错误。

样例

-- non-skewed raster providing row is sufficient
SELECT rid, ST_RasterToWorldCoordY(rast,1) As y1coord,
ST_RasterToWorldCoordY(rast,3) As y2coord,ST_ScaleY(rast) As pixely
FROM dummy_rast;

rid| y1coord | y2coord   | pixely
---+---------+-----------+--------
1  | 0.5     | 6.5       | 3
2  | 5793244 | 5793243.9 | -0.05

-- for fun lets skew it
SELECT rid, ST_RasterToWorldCoordY(rast,1,1) As y1coord,
ST_RasterToWorldCoordY(rast,2,3) As y2coord,
ST_ScaleY(rast) As pixely
FROM (SELECT rid, ST_SetSkew(rast,0,100.5) As rast FROM dummy_rast) As foo;

rid| y1coord | y2coord   | pixely
---+---------+-----------+--------
1  | 0.5     | 107       | 3
2  | 5793244 | 5793344.4 | -0.05

参考

ST_ScaleY, ST_RasterToWorldCoordX, ST_SetSkew, ST_SkewY

8.4.13. ST_Rotation

ST_Rotation — 返回栅格的旋转角度，单位是弧度。

用法

float8 ST_Rotation(raster rast);

描述

返回栅格的旋转角度，单位是弧度。如果栅格旋转角度不唯一，那么返回NAN。参考World File（https://en.wikipedia.org/wiki/World_file）获取更多信息。

样例

SELECT rid, ST_Rotation(ST_SetScale(ST_SetSkew(rast, sqrt(2)), sqrt(2)))
as rot
FROM dummy_rast;

rid| rot
---+-------------------
1  | 0.785398163397448
2  | 0.785398163397448

参考

ST_SetRotation, ST_SetScale, ST_SetSkew

8.4.14. ST_SkewX

ST_SkewX — 返回栅格的skew X值。

用法

float8 ST_SkewX(raster rast);

描述

返回栅格的skew X值。参考World File（https://en.wikipedia.org/wiki/World_file）获取更多信息。

样例

SELECT rid, ST_SkewX(rast) As skewx, ST_SkewY(rast) As skewy,
ST_GeoReference(rast) as georef
FROM dummy_rast;

rid|skewx | skewy|georef
---+------+------+-----------------------------------------------------------------------------
1  | 0    | 0    | 2.0000000000: 0.0000000000: 0.0000000000 : 3.0000000000 : 0.5000000000: 0.5000000000 :
2  | 0    | 0    | 0.0500000000: 0.0000000000: 0.0000000000: -0.0500000000: 3427927.7500000000: 5793244.0000000000

参考

ST_GeoReference, ST_SkewY, ST_SetSkew

8.4.15. ST_SkewY

ST_SkewY —返回栅格的skew Y值。

用法

float8 ST_SkewY(raster rast);

描述

返回栅格的skew Y值。参考World File（https://en.wikipedia.org/wiki/World_file）获取更多信息。

样例

SELECT rid, ST_SkewX(rast) As skewx, ST_SkewY(rast) As skewy,ST_GeoReference(rast) as georef
FROM dummy_rast;

rid|skewx|skewy|georef
---+-----+-----+-------------------------------------------------------------------------
1  | 0   | 0   | 2.0000000000: 0.0000000000 : 0.0000000000: 3.0000000000 : 0.5000000000: 0.5000000000 :
2  | 0   | 0   | 0.0500000000: 0.0000000000: 0.0000000000: -0.0500000000: 3427927.7500000000: 5793244.0000000000

参考

ST_GeoReference, ST_SkewX, ST_SetSkew

8.4.16. ST_SRID

ST_SRID — 返回栅格的SRID值。

用法

integer ST_SRID(raster rast);

描述

返回栅格的SRID值

样例

SELECT ST_SRID(rast) As srid FROM dummy_rast WHERE rid=1;

srid
----------------
0

参考

3.3.1节, ST_SRID

8.4.17. ST_Summary

ST_Summary — 返回一个栅格内容的文本描述。

用法

text ST_Summary(raster rast);

描述

返回一个栅格内容的文本描述。

样例

SELECT ST_Summary( ST_AddBand(
ST_AddBand(
ST_AddBand(
ST_MakeEmptyRaster(10, 10, 0, 0, 1, -1, 0, 0, 0)
, 1, '8BUI', 1, 0
)
, 2, '32BF', 0, -9999
)
, 3, '16BSI', 0, NULL
)
);

st_summary
------------------------------------------------------------------
Raster of 10x10 pixels has 3 bands and extent of BOX(0 -10,10 0)+ band 1
of pixtype 8BUI is in-db with NODATA value of 0 +
band 2 of pixtype 32BF is in-db with NODATA value of -9999 +
band 3 of pixtype 16BSI is in-db with no NODATA value
(1 row)

参考

ST_MetaData, ST_BandMetaData, ST_Summary ST_Extent

8.4.18. ST_UpperLeftX

ST_UpperLeftX — 返回投影系中栅格的左上角X坐标。

用法

float8 ST_UpperLeftX(raster rast);

描述

返回投影系中栅格的左上角X坐标。

样例

SELECt rid, ST_UpperLeftX(rast) As ulx FROM dummy_rast;

rid| ulx
---+------------
1  | 0.5
2  | 3427927.75

参考

ST_UpperLeftY, ST_GeoReference, Box3D

8.4.19. ST_UpperLeftY

ST_UpperLeftY —返回投影系中栅格的左上角Y坐标。

用法

float8 ST_UpperLeftY(raster rast);

描述

返回投影系中栅格的左上角Y坐标。

样例

SELECT rid, ST_UpperLeftY(rast) As uly FROM dummy_rast;

rid| uly
---+---------
1  | 0.5
2  | 5793244

参考

ST_UpperLeftX, ST_GeoReference, Box3D

8.4.20. ST_Width

ST_Width — 返回栅格的宽度，宽度以像素个数计数。

用法

integer ST_Width(raster rast);

描述

返回栅格的宽度，宽度以像素个数计数。

样例

SELECT ST_Width(rast) As rastwidth FROM dummy_rast WHERE rid=1;

rastwidth
----------------
10

参考

ST_Height

8.4.21. ST_WorldToRasterCoord

ST_WorldToRasterCoord — 根据给定X和Y值（通常是经度和维度），返回左上角的位置信息作为一条记录的行和列，或者栅格所在空间参考系中的一个点几何对象。

用法

record ST_WorldToRasterCoord(raster rast, geometry pt);
record ST_WorldToRasterCoord(raster rast, double precision longitude,
   double precision latitude);

描述

根据给定X和Y值（通常是经度和维度），返回左上角的位置信息作为一条记录的行和列，或者栅格所在空间参考系中的一个点几何对象。 无论几何位置（X，Y）或者Point几何对象是否在栅格上，该函数都可以使用。几何位置（X,Y）必须是栅格所在空间参考系所规定的格式。

样例

SELECT rid,
(ST_WorldToRasterCoord(rast, 3427927.8, 20.5)).*,
(ST_WorldToRasterCoord(rast,ST_GeomFromText('POINT(3427927.8 20.5)',ST_SRID(rast)))).* FROM dummy_rast;

rid| columnx |rowy       | columnx |rowy
---+---------+-----------+---------+-----------
1  | 1713964 | 7         | 1713964 | 7
2  | 2       | 115864471 | 2       | 115864471

参考

ST_WorldToRasterCoordX, ST_WorldToRasterCoordY, ST_RasterToWorldCoordX, ST_RasterToWorldCoordY, ST_SRID

8.4.22. ST_WorldToRasterCoordX

ST_WorldToRasterCoordX — 返回点几何对象在栅格中的列位置，或则栅格的空间参考系统中的X和Y空间坐标。

用法

integer ST_WorldToRasterCoordX(raster rast, geometry pt);
integer ST_WorldToRasterCoordX(raster rast, double precision xw);
integer ST_WorldToRasterCoordX(raster rast, double precision xw,
   double precision yw);

描述

返回点几何对象在栅格中的列位置，或则栅格的空间参考系统中的X和Y空间坐标。如果栅格是倾斜的，那么参数pt或者参数xw/yw坐标是需要的。 如果栅格是非倾斜的，那么参数xw就已经足够了。空间坐标的参考标准都是栅格所在的空间参考系。

样例

SELECT rid, ST_WorldToRasterCoordX(rast,3427927.8) As xcoord,
ST_WorldToRasterCoordX(rast, 3427927.8, 20.5) As xcoord_xwyw,
ST_WorldToRasterCoordX(rast,ST_GeomFromText('POINT(3427927.8 20.5)',ST_SRID(rast))) As
ptxcoord
FROM dummy_rast;

rid| xcoord  | xcoord_xwyw | ptxcoord
---+---------+-------------+----------
1  | 1713964 | 1713964     | 1713964
2  | 1       | 1           | 1

参考

ST_RasterToWorldCoordX, ST_RasterToWorldCoordY, ST_SRID

8.4.23. ST_WorldToRasterCoordY

ST_WorldToRasterCoordY —返回点几何对象在栅格中的行位置，或则栅格的空间参考系统中的X和Y空间坐标。

用法

integer ST_WorldToRasterCoordY(raster rast, geometry pt);
integer ST_WorldToRasterCoordY(raster rast, double precision xw);
integer ST_WorldToRasterCoordY(raster rast, double precision xw,
   double precision yw);

描述

返回点几何对象在栅格中的行位置，或则栅格的空间参考系统中的X和Y空间坐标。 如果栅格是倾斜的，那么参数pt或者参数xw/yw坐标是需要的。如果栅格是非倾斜的，那么参数xw就已经足够了。 空间坐标的参考标准都是栅格所在的空间参考系。

样例

SELECT rid, ST_WorldToRasterCoordY(rast,20.5) As ycoord,
ST_WorldToRasterCoordY(rast, 3427927.8, 20.5) As ycoord_xwyw,
ST_WorldToRasterCoordY(rast,ST_GeomFromText('POINT(3427927.8 20.5)',ST_SRID(rast))) As
ptycoord
FROM dummy_rast;

rid| ycoord    | ycoord_xwyw |ptycoord
---+-----------+-------------+-----------
1  | 7         | 7           | 7
2  | 115864471 | 115864471   | 115864471

参考

ST_RasterToWorldCoordX, ST_RasterToWorldCoordY, ST_SRID