Syntax, parameters, and examples of ST_ClipToRast-ApsaraDB RDS(RDS)-阿里云帮助中心

Clips a raster object to the shape of a geometry and returns the result as a new raster object.

Syntax

raster ST_ClipToRast(raster raster_obj,
                     geometry geom,
                     integer pyramidLevel default 0,
                     cstring bands default '',
                     float8[] nodata default NULL,
                     cstring clipOption default '',
                     cstring storageOption default '')

Parameters

Parameter	Description
`raster_obj`	The raster object to clip.
`geom`	The geometry object used for clipping.
`pyramidLevel`	The pyramid level. Default value: `0`.
`bands`	The bands to clip. Accepts range format (`'0-2'`) or list format (`'1,2,3'`). Band index starts at `0`. Default value: `''` (all bands).
`nodata`	The NoData values as a `float8[]` array. If fewer values are provided than the number of bands being clipped, the predefined NoData value for each remaining band is used. If a band has no predefined NoData value, `0` is used. Default value: `NULL`.
`clipOption`	Clipping options as a JSON string. See clipOption fields. Default value: `''`.
`storageOption`	Storage options for the returned raster as a JSON string. See storageOption fields. Default value: `''`.

clipOption fields

Field	Type	Default	Description
`window_clip`	bool	`false`	Specifies whether to clip using the bounding box of the geometry instead of the geometry shape itself. Set to `true` to clip using the minimum bounding rectangle (MBR); set to `false` to clip using the geometry directly.
`rast_coord`	bool	`false`	Specifies whether the geometry uses pixel coordinates. When `true`, the x coordinate maps to the column number and the y coordinate maps to the row number of the pixel.

storageOption fields

Field	Type	Default	Description
`chunking`	boolean	Same as the original raster	Specifies whether to store the new raster data as chunks.
`chunkdim`	string	Same as the original raster	The chunk dimensions for the new raster. Takes effect only when `chunking` is `true`.
`chunktable`	string	`''`	The name of the chunk table for the new raster. If set to `''`, a temporary chunk table with a random name is created and is valid only for the current session. Specify a name to create a permanent chunk table.
`compression`	string	`lz4`	The compression algorithm. Valid values: `none`, `jpeg`, `zlib`, `png`, `lzo`, `lz4`.
`quality`	integer	`75`	The compression quality. Takes effect only when `compression` is `jpeg`.
`interleaving`	string	Same as the original raster	The interleaving type. Valid values: `bip` (band interleaved by pixel, BIP), `bil` (band interleaved by line, BIL), `bsq` (band sequential, BSQ).
`endian`	string	Same as the original raster	The byte order. Valid values: `NDR` (little-endian), `XDR` (big-endian).

Usage notes

If chunktable is set to NULL or '', a temporary chunk table with a random name is created. The table is valid only for the current session. Specify a name to create a permanent chunk table.
The default cache size for clipping is 100 MB. To adjust this limit, run:
```
SET ganos.raster.clip_max_buffer_size = <cache size in bytes>;
```

Examples

-- Create a permanent result table.
CREATE TABLE rast_clip_result(id integer, rast raster);

-- Create a temporary result table.
CREATE TEMP TABLE rast_clip_result_temp(id integer, rast raster);

-- Clip using default settings and store the result in the temporary table.
INSERT INTO rast_clip_result_temp(id, rast)
SELECT 1, ST_ClipToRast(rast, ST_GeomFromText('Polygon((0 0, 45 45, 90 45, 45 0, 0 0))', 4326), 0)
FROM clip_table
WHERE id = 1;

-- Clip with a white background (NoData = 254) and store the result in the permanent table.
INSERT INTO rast_clip_result(id, rast)
SELECT 2, ST_ClipToRast(rast, ST_GeomFromText('Polygon((0 0, 45 45, 90 45, 45 0, 0 0))', 4326), 0, '', ARRAY[254,254,254], '', '{"chunktable":"clip_rbt"}')
FROM clip_table
WHERE id = 1;

-- Clip using the bounding box (MBR) of the geometry.
INSERT INTO rast_clip_result_temp(id, rast)
SELECT 3, ST_ClipToRast(rast, ST_GeomFromText('Polygon((0 0, 45 45, 90 45, 45 0, 0 0))', 4326), 0, '', NULL, '{"window_clip":true}', '')
FROM clip_table
WHERE id = 1;