ST_ClipToRast-AnalyticDB(AnalyticDB)-阿里云帮助中心

Clips a raster object using a geometry object and returns the clipped 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	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 at which to perform the clip.
`bands`	cstring	`''`	The bands to clip, in the format `'0-2'` or `'1,2,3'`. Band index starts at 0. An empty string clips all bands.
`nodata`	float8[]	NULL	The nodata values for clipped areas, one per band. If fewer values are provided than the number of bands, the remaining bands use 0 as the nodata value.
`clipOption`	cstring	`''`	Clipping behavior, specified as a JSON string. See clipOption parameters.
`storageOption`	cstring	`''`	Storage configuration for the returned raster, specified as a JSON string. See storageOption parameters.

clipOption parameters

Parameter	Type	Default	Description
`window_clip`	bool	false	Specifies whether to clip using the minimum bounding rectangle (MBR) of the geometry instead of the geometry shape. Set to `true` to use the MBR; set to `false` to use the geometry shape.
`rast_coord`	bool	false	Specifies whether the geometry uses pixel coordinates. When `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 the source raster	Specifies whether to store the clipped raster as chunks.
`chunkdim`	string	Same as the source raster	The chunk dimensions. Takes effect only when `chunking` is `true`.
`chunktable`	string	`''`	The name of the chunk table used to store the clipped raster. If blank or NULL, a temporary chunk table with a random name is created and is valid only for the current session. To keep the clipped raster accessible after the session ends, specify a table name.
`compression`	string	lz4	The compression algorithm. Valid values: `none`, `jpeg`, `zlib`, `png`, `lzo`, `lz4`.
`quality`	integer	75	The compression quality level. Applies only to `jpeg` compression.
`interleaving`	string	Same as the source raster	The band interleaving method. Valid values: `bip` (band interleaved by pixel, BIP), `bil` (band interleaved by line, BIL), `bsq` (band sequential, BSQ).
`endian`	string	Same as the source raster	The byte order. Valid values: `NDR` (little endian), `XDR` (big endian).

Usage notes

By default, window_clip is false, so clipping follows the geometry shape exactly. Set window_clip to true to clip using the minimum bounding rectangle (MBR) instead. MBR clipping is faster but produces a rectangular result regardless of the geometry shape.
By default, chunktable is blank, so the clipped raster is stored in a temporary chunk table that exists only for the duration of the current session. To retain the clipped raster across sessions, set chunktable to a persistent table name.
The default cache size for a clip operation is 100 MB. If the clipped result exceeds this limit, adjust the limit using the ganos.raster.clip_max_buffer_size parameter.

Examples

The following example clips a raster object from raster_table using a polygon geometry, then stores the result in a temporary table.

DO $$
declare
    rast raster;
    new_rast raster;
begin
    -- Create a permanent table.
    CREATE TEMP TABLE rast_clip_result(id integer, rast raster);

    select raster_obj into rast from raster_table where id = 1;
    new_rast = ST_ClipToRast(rast, ST_geomfromtext('Polygon((0 0, 45 45, 90 45, 45 0, 0 0))', 4326), 0);
    Insert into rast_clip_result values(1, new_rast);
end;
$$ LANGUAGE 'plpgsql';