Use ST_Clip to clip a raster object - PolarDB

Clips a raster object by a bounding box or geometry. By default, all bands are clipped, NoData areas are filled with 0 if no NoData value is defined, and output is compressed with lz4. The default output cache is 100 MB.

Syntax

-- Clip by bounding box
bytea ST_Clip(raster raster_obj, integer pyramidLevel, box extent, BoxType boxType);
bytea ST_Clip(raster raster_obj, integer pyramidLevel, box extent, BoxType boxType, integer destSrid);

-- Clip by geometry
record ST_Clip(raster raster_obj,
               geometry geom,
               integer pyramidLevel default 0,
               cstring bands default '',
               float8[] nodata default NULL,
               cstring clipOption default '',
               cstring storageOption default '',
               out box outwindow,
               out bytea rasterblob)

Parameters

Parameter	Description
`raster_obj`	The raster object to clip.
`pyramidLevel`	The pyramid level.
`extent`	The bounding box to clip by, in the format `'((minX,minY),(maxX,maxY))'`. Used only in the bounding box overloads.
`boxType`	The coordinate type of `extent`. Valid values: `Raster` (pixel coordinates) and `World` (world coordinates).
`destSrid`	The spatial reference system identifier (SRID) of the output cell subset.
`geom`	The geometry object to clip by. Used only in the geometry overload.
`bands`	The bands to clip, in the format `'0-2'` or `'1,2,3'`. Band numbering starts at 0. Default: `''` (all bands).
`nodata`	NoData fill values as a `float8[]` array, one per band. See NoData fill behavior.
`clipOption`	Clipping options as a JSON string. See clipOption parameters.
`storageOption`	Output storage options as a JSON string. See storageOption parameters.

clipOption parameters

Parameter	Type	Default	Description
`window_clip`	BOOLEAN	`false`	Controls the clipping region. `true`: clips by the minimum bounding rectangle (MBR) of the geometry. `false`: clips by the geometry itself.
`rast_coord`	BOOLEAN	`false`	Interprets the geometry in raster coordinates. `true`: the x coordinate is the column number and the y coordinate is the row number.

storageOption parameters

Parameter	Type	Default	Description
`compression`	STRING	`lz4`	Compression algorithm. Valid values: `none`, `jpeg`, `zlib`, `png`, `lzo`, `lz4`.
`quality`	INTEGER	`75`	JPEG compression quality. Applies only when `compression` is `jpeg`.
`interleaving`	STRING	Same as the original raster object	Interleaving type. Valid values: `bip` (band interleaved by pixel), `bil` (band interleaved by line), `bsq` (band sequential).
`endian`	STRING	Same as the original raster object	Byte order. Valid values: `NDR` (little-endian format), `XDR` (big-endian format).

Usage notes

Output size limit: The default clipping cache is 100 MB. To adjust the limit, set ganos.raster.clip_max_buffer_size to the desired value.

quality and compression interaction: The quality parameter takes effect only when compression is set to jpeg. For all other compression types, quality is ignored.

window_clip behavior: When window_clip is false (default), the raster is clipped to the exact geometry shape. When window_clip is true, the raster is clipped to the geometry's MBR instead.

NoData fill behavior

When the clipped area falls outside the raster's data extent, ST_Clip fills it using the following priority:

The value from the nodata array for that band.
If the nodata array has fewer values than bands, the band's predefined NoData value is used for the remaining bands.
If a band has no predefined NoData value, 0 is used.

Examples

Clip by bounding box in world coordinates

SELECT ST_Clip(raster_obj, 0, '((128.980,30.0),(129.0,30.2))', 'World');

Clip by bounding box with output SRID

SELECT ST_Clip(raster_obj, 0, '((128.980,30.0),(129.0,30.2))', 'World', 4326);

Clip by geometry with default settings

All bands are clipped, NoData areas are filled with 0, and output uses lz4 compression.

SELECT (ST_Clip(rast, ST_GeomFromText('Polygon((0 0, 45 45, 90 45, 45 0, 0 0))', 4326), 0)).*
FROM clip_table
WHERE id = 1;

Clip by geometry with white background and PNG output

Sets all NoData areas to white (254, 254, 254) and compresses the output as PNG with BIP interleaving.

SELECT (ST_Clip(rast,
                ST_GeomFromText('Polygon((0 0, 45 45, 90 45, 45 0, 0 0))', 4326),
                0,
                '',
                ARRAY[254, 254, 254],
                '',
                '{"compression":"png","interleaving":"bip"}')).*
FROM clip_table
WHERE id = 1;

Clip by the MBR of a geometry

Uses window_clip to clip by the geometry's minimum bounding rectangle instead of the geometry itself.

SELECT (ST_Clip(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;