Clips a raster object using a rectangular extent or a geometry object. By default, all bands are clipped and the geometry shape (not its bounding box) is used as the clip boundary.
Syntax
Two overload families are available: one for clipping by a rectangular extent, and one for clipping by a geometry object.
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
Shared parameters
| Parameter | Description |
|---|---|
raster_obj | The raster object to clip. |
pyramidLevel | The pyramid level. |
Bounding box parameters
| Parameter | Description |
|---|---|
extent | The rectangular area to clip, in the format '((minX,minY),(maxX,maxY))'. |
boxType | The coordinate system of extent. Valid values: Raster (pixel coordinates) and World (world coordinates). |
destSrid | The spatial reference system identifier (SRID) of the output. |
Geometry parameters
| Parameter | Default | Description |
|---|---|---|
geom | — | The geometry object used as the clip boundary. |
bands | '' (all bands) | The bands to clip, in the format '0-2' or '1,2,3'. Band numbering starts at 0. An empty string clips all bands. |
nodata | NULL | NoData fill values as a float8[] array, one value per band. If the array has fewer values than the number of bands being clipped, the predefined NoData value of each remaining band is used. If a band has no predefined NoData value, 0 is used. |
clipOption | '' | Clipping options as a JSON string. See the clipOption fields table below. |
storageOption | '' | Output storage options as a JSON string. See the storageOption fields table below. |
clipOption fields
| Field | Type | Default | Description |
|---|---|---|---|
window_clip | Boolean | false | When true, clips using the minimum bounding rectangle (MBR) of the geometry instead of the geometry shape itself. |
rast_coord | Boolean | false | When true, interprets the geometry coordinates as raster coordinates, where x is the column number and y is the row number. |
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 format of the output. 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) and XDR (big endian). |
Usage notes
Output size limit
The default clipping buffer is 100 MB. To increase the limit, set the ganos.raster.clip_max_buffer_size parameter to a larger value.
window_clip behavior
By default (window_clip=false), the raster is clipped to the exact shape of the geometry. 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');Clip by bounding box and reproject the output
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 using the geometry shape as the boundary.
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 custom NoData and PNG output
Uses white (254, 254, 254) as the NoData fill color and compresses the output as a PNG image 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 geometry's bounding box
Clips to the MBR of the geometry instead of the geometry shape. Use this when a rectangular output is acceptable and performance matters.
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;