ST_ClipToRast Raster Clipping Function Reference - PolarDB

Clips a raster object to a geometry boundary and returns the result as a new raster object. By default, all bands are clipped using the exact geometry shape, and the result is stored in a session-scoped temporary chunk table.

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	Type	Default	Description
`raster_obj`	raster	—	The raster object to clip.
`geom`	geometry	—	The geometry object used for clipping.
`pyramidLevel`	integer	0	The pyramid level of the raster to clip.
`bands`	cstring	`''`	The bands to clip. Use `'0-2'` for a range or `'1,2,3'` for a list. Band index starts at 0. Leave blank to clip all bands.
`nodata`	float8[]	NULL	The nodata values for pixels outside the geometry, specified as a `float8[]` array. If fewer values are provided than the number of bands, the remaining bands use `0`.
`clipOption`	cstring	`''`	Clipping options as a JSON string. See clipOption parameters.
`storageOption`	cstring	`''`	Storage options for the returned raster as a JSON string. See storageOption parameters.

clipOption parameters

Parameter	Type	Default	Description
`window_clip`	bool	false	Specifies whether to clip using the bounding box of the geometry instead of its exact shape. When set to `true`, uses the minimum bounding rectangle (MBR); when set to `false`, uses the geometry object.
`rast_coord`	bool	false	Specifies whether the geometry coordinates are in pixel space. When set to `true`, the x coordinate is the column number and the y coordinate is the row number.

storageOption parameters

Parameter	Type	Default	Description
`chunking`	boolean	Same as original raster	Specifies whether to store the result as chunks.
`chunkdim`	string	Same as original raster	The chunk dimension. Takes effect only when `chunking` is `true`.
`chunktable`	string	`''`	The name of the chunk table for storing the result. If left blank, a temporary chunk table with a random name is created and is valid only for the current session. To retain the clipped raster across sessions, specify a table name.
`compression`	string	lz4	The compression algorithm. Valid values: `none`, `jpeg`, `zlib`, `png`, `lzo`, `lz4`.
`quality`	integer	75	The compression quality. Applies only to the `jpeg` algorithm.
`interleaving`	string	Same as original raster	The interleaving method. Valid values: `bip` (band interleaved by pixel, BIP), `bil` (band interleaved by line, BIL), `bsq` (band sequential, BSQ).
`endian`	string	Same as original raster	The byte order. Valid values: `NDR` (little endian), `XDR` (big endian).

Usage notes

Session persistence: If chunktable is left blank or set to '', the result is stored in a temporary chunk table that is automatically dropped at the end of the session. Specify a chunk table name to retain the clipped raster across sessions.
Result size limit: The default cache size for clipping is 100 MB. To adjust this limit, set the ganos.raster.clip_max_buffer_size parameter.

Examples

All examples clip from a source table named clip_table using a polygon geometry.

Clip to a temporary table using default settings

Uses the exact geometry shape, clips all bands, and stores the result in a session-scoped temporary table.

CREATE TEMP TABLE rast_clip_result_temp(id integer, rast raster);

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 custom nodata fill and persist the result

Uses white (RGB 254, 254, 254) as the background fill for clipped areas and stores the result in a named permanent chunk table clip_rbt.

CREATE TEMP TABLE rast_clip_result(id integer, rast raster);

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 of the geometry

Sets window_clip to true to clip using the minimum bounding rectangle (MBR) of the geometry instead of its exact shape.

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;