This function clips a raster object.

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

ParameterDescription
raster_objThe raster object.
pyramidLevelThe pyramid level.
extentThe area that you want to clip. Format: '((minX,minY),(maxX,maxY))'.
boxTypeThe coordinate type of the area that you want to clip. Valid values:
  • Raster: pixel coordinates
  • World: world coordinates
destSridThe spatial reference system identifier (SRID) of the output cell subset.
geomThe geometry object that you want to clip.
bandsThe sequence numbers of bands that you want to clip. Format: '0-2' or '1,2,3'. The sequence number starts from 0. Default value: empty string (''). The default value indicates that all bands need to be clipped.
nodataThe array of NoData values in the format of float8[]. If the number of the NoData values is less than the number of the bands to be clipped, the predefined NoData value of a band is used to fill the area after the band is clipped. If a band has no predefined NoData value, the value 0 is used to fill the area after the band is clipped.
clipOptionThe clipping option.
storageOptionThe storage option for the output.
outwindowThe size of the returned raster object.
rasterblobThe binary pixel matrix.

The following table describes the fields of the clipOption parameter.

FieldTypeDefault valueDescription
window_clipboolfalseSpecifies whether to use the bounding box of the geometry object to clip the raster object. Valid values:
  • true: uses the minimum bounding rectangle (MBR) of the geometry object.
  • false: uses the geometry object.
rast_coordboolfalseSpecifies whether the geometry object that you want to clip is in raster coordinates. If the geometry object that you want to clip is in raster coordinates, the x coordinate of the geometry represents the column number and the y coordinate represents the row number. The column number and row number start from 0.

The following table describes fields of the storageOption parameter.

FieldTypeDefault valueDescription
compressionstringlz4The type of the compression algorithm. Valid values:
  • none
  • jpeg
  • zlib
  • png
  • lzo
  • lz4
qualityinteger75The compression quality. This parameter takes effect only when the value of the compression parameter is set to jpeg.
interleavingstringSame as the original rasterThe interleaving type. Valid values:
  • bip: band interleaved by pixel (BIP)
  • bip: band interleaved by pixel (BIP)
  • bsq: band sequential (BSQ)
endianstringSame as the original rasterThe endian format. Valid values:
  • NDR: little endian format
  • XDR: big endian format

Description

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, you can use the ganos.raster.clip_max_buffer_size parameter to set the size of the cache.

Examples

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