PolarDB:ST_ClipToRast - PolarDB

Clips a raster object to a geometry boundary 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 '')

The minimum viable call requires only the raster object and a geometry:

ST_ClipToRast(raster_obj, geom)

Parameters

Parameter	Type	Default	Description
`raster_obj`	raster	—	The raster object to clip.
`geom`	geometry	—	The geometry used as the clip boundary.
`pyramidLevel`	integer	`0`	The pyramid level to clip.
`bands`	cstring	`''`	The bands to clip. Use the format `'0-2'` for a range or `'1,2,3'` for a list. Band numbering starts at 0. An empty string clips all bands.
`nodata`	float8[]	`NULL`	The nodata values for output pixels outside the clip boundary. If fewer values are specified than there are bands, remaining bands are filled with `0`.
`clipOption`	cstring	`''`	Clipping behavior, specified as a JSON string. See clipOption parameters.
`storageOption`	cstring	`''`	Output storage settings, specified as a JSON string. See storageOption parameters.

clipOption parameters

Parameter	Type	Default	Description
`window_clip`	bool	`false`	Controls the clip boundary shape. `true` clips to the minimum bounding rectangle (MBR) of `geom`, producing a rectangular output. `false` clips to the exact geometry shape, masking pixels outside the polygon.
`rast_coord`	bool	`false`	Controls the coordinate space of `geom`. `true` interprets `geom` in pixel space, where x is the column number and y is the row number. `false` interprets `geom` in geographic coordinates (the same coordinate reference system as the raster).

storageOption parameters

Parameter	Type	Default	Description
`chunking`	boolean	Same as source raster	Specifies whether to store the output as chunks.
`chunkdim`	string	Same as source raster	The chunk dimensions. Takes effect only when `chunking` is `true`.
`chunktable`	string	`''`	The name of the chunk table for the output. If NULL or blank, a temporary chunk table with a random name is created and is valid only for the current session. To retain the clipping result across sessions, specify a permanent chunk 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 `jpeg` compression.
`interleaving`	string	Same as 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 source raster	The byte order. Valid values: `NDR` (little endian), `XDR` (big endian).

Usage notes

Important

If chunktable is NULL or blank, the output is stored in a temporary chunk table that exists only for the current session. To retain the clipping result after the session ends, set chunktable to a permanent table name.

Output buffer limit: The default maximum output size is 100 MB. To adjust this limit, set the ganos.raster.clip_max_buffer_size parameter.

Examples

All examples clip raster rows from clip_table (where id = 1) using a polygon in SRID 4326.

Example 1: Default clipping to a temporary table

Uses the exact geometry shape 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;

Example 2: Custom nodata and permanent storage

Fills clipped-out pixels with white (254, 254, 254) and stores the result in a named chunk table so it persists beyond the session.

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;

Example 3: Window clipping (MBR)

Clips to the minimum bounding rectangle of the geometry rather than the exact polygon 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;