Clip a raster object with the ST_Clip function - ApsaraDB RDS

Clips a raster object by a bounding box or geometry and returns the clipped result as a binary blob. All bands are clipped by default. Control the output format and compression through storageOption.

Syntax

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);

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 of the raster object.
`extent`	The bounding box to clip. Format: `'((minX,minY),(maxX,maxY))'`.
`boxType`	The coordinate system of the bounding box. 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.
`bands`	The bands to clip, as a range (`'0-2'`) or a comma-separated list (`'1,2,3'`). Band numbering starts at 0. Default: `''` (all bands).
`nodata`	An array of NoData fill values (type `float8[]`) for areas outside the clip region. If fewer values are provided than the number of bands, the predefined NoData value for each remaining band is used. If a band has no predefined NoData value, `0` is used.
`clipOption`	A JSON string that controls clipping behavior. See clipOption fields.
`storageOption`	A JSON string that controls the output format. See storageOption fields.
`outwindow`	(OUT) The bounding box of the returned raster object.
`rasterblob`	(OUT) The binary pixel matrix.

clipOption fields

Field	Type	Default	Description
`window_clip`	bool	`false`	Controls the clip region. `true`: clips to the minimum bounding rectangle (MBR) of the geometry. `false`: clips to the exact geometry shape.
`rast_coord`	bool	`false`	Interprets the geometry coordinates as raster coordinates (column and row numbers, both starting at 0) instead of world coordinates.

storageOption fields

Field	Type	Default	Description
`compression`	string	`lz4`	The compression algorithm. Valid values: `none`, `jpeg`, `zlib`, `png`, `lzo`, `lz4`.
`quality`	integer	`75`	The JPEG compression quality. Applies only when `compression` is set to `jpeg`.
`interleaving`	string	Same as source	The interleaving format. Valid values: `bip` (band interleaved by pixel) and `bsq` (band sequential).
`endian`	string	Same as source	The byte order. Valid values: `NDR` (little endian) and `XDR` (big endian).

Usage notes

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

NoData fallback behavior: The nodata array is matched to bands in order. If the array is shorter than the number of bands being clipped, Ganos uses each band's predefined NoData value for the remaining bands. If a band has no predefined NoData value, 0 is used.

Clip region vs. bounding box: By default (window_clip: false), the raster is clipped to the exact geometry shape. Set window_clip: true to clip to the geometry's MBR instead, which produces a rectangular result.

Examples

Clip by bounding box using world coordinates

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

Clip by bounding box and reproject the output

Specify destSrid to set the spatial reference system of the output.

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

Clip by geometry using default settings

All bands are clipped to the exact polygon shape. The result includes both the output window and the binary pixel matrix.

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 a white background and PNG output

Set nodata to ARRAY[254, 254, 254] to fill clipped areas with white. Use storageOption to compress 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 using the bounding box of a geometry (window clip)

Setting window_clip to true clips to the MBR of the polygon rather than the polygon shape itself, producing a rectangular output.

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;