ST_Clip Function Overview for Raster Geometry Extraction - AnalyticDB for PostgreSQL

Clips a raster object by a bounding box or a geometry object. By default, all bands are clipped. If no NoData value is specified, the predefined NoData value of each band is used; if no predefined value exists, 0 fills the clipped area.

Syntax

-- Overload 1: clip by bounding box
bytea ST_Clip(raster raster_obj, integer pyramidLevel, box extent, BoxType boxType);

-- Overload 2: clip by bounding box and reproject output
bytea ST_Clip(raster raster_obj, integer pyramidLevel, box extent, BoxType boxType, integer destSrid);

-- Overload 3: clip by geometry object
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	Type	Description
`raster_obj`	raster	The raster object to clip.
`pyramidLevel`	integer	The pyramid level.
`extent`	box	The area to clip. Format: `'((minX,minY),(maxX,maxY))'`.
`boxType`	BoxType	The coordinate type of the clipping area. Valid values: `Raster` (pixel coordinates), `World` (world coordinates).
`destSrid`	integer	The spatial reference system identifier (SRID) of the output cell subset.
`geom`	geometry	The geometry object used to clip the raster.
`bands`	cstring	The band sequence numbers to clip. Format: `'0-2'` or `'1,2,3'`. Sequence numbers start from `0`. Default: `''` (all bands).
`nodata`	float8[]	NoData values for the clipped area, one per band. If the array contains fewer values than the number of bands, the predefined NoData value of each remaining band is used. If a band has no predefined NoData value, `0` is used.
`clipOption`	cstring	Clipping options. See clipOption fields.
`storageOption`	cstring	Storage options for the output. See storageOption fields.
`outwindow`	box	Output parameter. The size of the returned raster object.
`rasterblob`	bytea	Output parameter. The binary pixel matrix.

clipOption fields

Field	Type	Default	Description
`window_clip`	bool	`false`	Whether to clip using the bounding box of the geometry object instead of the geometry itself. `true` uses the minimum bounding rectangle (MBR); `false` uses the geometry shape.
`rast_coord`	bool	`false`	Whether the geometry is in raster coordinates. When `true`, the x coordinate represents the column number and the y coordinate represents the row number, both starting from `0`.

storageOption fields

Field	Type	Default	Description
`compression`	string	`lz4`	Compression algorithm for the output. Valid values: `none`, `jpeg`, `zlib`, `png`, `lzo`, `lz4`.
`quality`	integer	`75`	Compression quality. Applies only when `compression` is `jpeg`.
`interleaving`	string	Same as the source raster	Interleaving type. Valid values: `bip` (band interleaved by pixel), `bil` (band interleaved by line), `bsq` (band sequential).
`endian`	string	Same as the source raster	Byte order of the output. Valid values: `NDR` (little-endian), `XDR` (big-endian).

Usage notes

The default clipping cache is 100 MB, which indicates that only 100 MB of data can be returned. To adjust the limit on the output size, set the ganos.raster.clip_max_buffer_size parameter.

Examples

Clip by world coordinates (bounding box)

Clips a raster object at pyramid level 0 using a world-coordinate bounding box.

DO $$
DECLARE
    rast raster;
BEGIN
    SELECT raster_obj INTO rast FROM raster_table WHERE id = 1;
    SELECT ST_Clip(rast, 0, '((128.980,30.0),(129.0,30.2))', 'World');
END;
$$ LANGUAGE 'plpgsql';

Clip by geometry object (all bands)

Clips all bands of a raster object using a geometry object. The output window and binary pixel data are returned as separate fields.

SELECT outwindow, rasterblob
FROM ST_Clip(
    rast,
    ST_GeomFromText('POLYGON((128.98 30.0, 129.0 30.0, 129.0 30.2, 128.98 30.2, 128.98 30.0))'),
    0,       -- pyramid level
    '',      -- all bands
    NULL,    -- use predefined NoData values
    '',      -- default clip options
    ''       -- default storage options
);

Clip by geometry object with custom options

Clips band 0 only, fills the clipped area with NoData value 0, and uses the MBR of the geometry instead of the geometry shape.

SELECT outwindow, rasterblob
FROM ST_Clip(
    rast,
    ST_GeomFromText('POLYGON((128.98 30.0, 129.0 30.0, 129.0 30.2, 128.98 30.2, 128.98 30.0))'),
    0,                          -- pyramid level
    '0',                        -- band 0 only
    ARRAY[0.0]::float8[],       -- NoData value for the clipped area
    '{"window_clip": true}',    -- use MBR of the geometry
    '{"compression": "lz4"}'    -- lz4 compression
);