This function returns the geographic coordinates and values of all the cells in a raster object that intersect with a geometry object.

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 coords,
                     out integer band,
                     out float8 value)

Parameters

Parameter Description
raster_obj The raster object.
pyramidLevel The pyramid level.
geometry The geometry object used for clipping.
bands The sequence numbers of bands to be clipped, in the format of '0-2' or '1,2,3'. The sequence number starts from 0. Default value: null string (''). It indicates that all bands are to be clipped.
clipOption The clipping options. The value is a JSON-formatted string.
coords The output field that indicates the geographic coordinates of a pixel value.
band The output field that indicates the band sequence number of a pixel value.
value The output field that indicates a pixel value.

The following table describes the clipOption parameter.

Parameter Type Default value Description
window_clip Boolean false Specifies whether to use the bounding box of the geometry object to clip the raster object. Valid values:
  • true: uses the minimum bounding rectangle (MBR) of the geometry object.
  • false: uses the geometry object.

Description

  • Both the geometry object and the raster object must have a valid spatial reference system identifier (SRID). Their SRIDs must be consistent.
  • The default clipping cache is 100 MB, which indicates that only 100 MB of data can be returned. To adjust the limit on the output size, you can use the ganos.raster.clip_max_buffer_size parameter to set the size of the cache.

Examples

-- 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)

-- 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)