Returns a set of records containing the geographic coordinates and pixel values of all cells in a raster object that intersect with a geometry object. Each row in the result corresponds to one pixel in one band.
Syntax
set of record ST_Values(raster raster_obj,
geometry geom,
integer pyramidLevel default 0,
cstring bands default '', /* All bands */
cstring clipOption default '',
out point cords,
out integer band,
out float8 value)Parameters
| Parameter | Type | Description |
|---|---|---|
raster_obj | raster | The raster object to query. |
geom | geometry | The geometry object used to clip the raster. |
pyramidLevel | integer | The pyramid level. Default value: 0. |
bands | cstring | The band sequence numbers to query, in the format '0-2' or '1,2,3'. Sequence numbers start from 0. Default value: '' (empty string), which queries all bands. |
clipOption | cstring | Clipping options as a JSON-formatted string. |
Output fields
| Field | Type | Description |
|---|---|---|
cords | point | The geographic coordinates of the pixel. |
band | integer | The band sequence number of the pixel. |
value | float8 | The pixel value. |
clipOption parameter
| Parameter | Type | Default value | Description |
|---|---|---|---|
window_clip | Boolean | false | Specifies whether to clip the raster using the bounding box of the geometry object instead of the geometry itself. Valid values: true (uses the minimum bounding rectangle (MBR) of the geometry object) and false (uses the geometry object). |
Usage notes
Both the raster object and the geometry object must have a valid spatial reference system identifier (SRID), and their SRIDs must match.
The default clipping cache is 100 MB. To adjust the output size limit, set the
ganos.raster.clip_max_buffer_sizeparameter to a different value.
Examples
All examples use ST_Values with the .* expansion syntax to return the full set of output fields.
Example 1: Clip with a point geometry
-- Use a geometry object of the point type to clip the raster object.
SELECT ( ST_Values(rast, ST_geomfromtext('POINT(128.135 29.774)', 4326)::geometry, 0,'{"window_clip":"true"}')).*
from rat_clip WHERE id=1;
coord | band | value
--------------+------+-------
(127.8,29.7) | 0 | 11
(127.8,29.7) | 1 | 10
(127.8,29.7) | 2 | 50
(3 rows)Example 2: Clip with a linestring geometry
-- Use a geometry object of the linestring type to clip the raster object.
SELECT ( ST_Values(rast, ST_geomfromtext('LINESTRING(0 0, 45 45, 90 0, 135 45)', 4326)::geometry, 0)).*
from rat_clip WHERE id=1 limit 10;
coord | band | value
-------------+------+-------
(44.1,45) | 0 | 115
(44.1,45) | 1 | 112
(44.1,45) | 2 | 69
(45,45) | 0 | 122
(45,45) | 1 | 117
(45,45) | 2 | 75
(134.1,45) | 0 | 37
(134.1,45) | 1 | 64
(134.1,45) | 2 | 13
(43.2,44.1) | 0 | 66
(10 rows)