This function clips a raster object by using a specified geometry object and returns the clipped raster object.

Syntax

raster ST_ClipToRast(raster raster_obj,
                     geometry geom,
                     integer pyramidLevel default 0,
                     cstring bands default '',
                     float8[] nodata default NULL,
                     cstring clipOption default '',
                     cstring storageOption default '')

Parameters

ParameterDescription
raster_objThe raster object to be clipped.
pyramidLevelThe pyramid level.
geomThe geometry object that is used for clipping.
bandsThe bands to be clipped, in the format of '0-2' or '1,2,3'. It starts from 0. Default value: ''. The default value indicates that all the bands are clipped.
nodataThe nodata values in the format of float8[]. If the number of the values is less than the number of bands, the nodata values that are specified for the bands are filled. If no nodata value is specified for the bands, the value 0 is filled.
clipOptionThe clipping option that is represented by a JSON string.
storageOptionThe storage option that is represented by a JSON string in the returned result.

The following table describes the parameters of clipOption.

ParameterTypeDefault valueDescription
window_clipboolfalseSpecifies whether to use the bounding box of a geometry for clipping. Valid values:
  • true: uses the minimum bounding rectangle (MBR) of the geometry for clipping.
  • false: uses the geometry object for clipping.
rast_coordboolfalseSpecifies whether the passed geometry uses pixel coordinates. If the pixel coordinates are used, the x coordinate represents the column number of the pixel and the y coordinate represents the row number of the pixel.

The following table describes the parameters of storageOption.

ParameterTypeDefault valueDescription
chunkingbooleanSame as the original rasterSpecifies whether to store data as chunks.
chunkdimstringSame as the original rasterThe dimension information about the chunk. This parameter only takes effect when the chunking parameter is set to true.
chunktablestring''The name of the chunk table. If the '' value is passed, a temporary chunk table that has a random name is generated to store data. This temporary table is valid in only the current session. If you need to retain an accessible clipping object, you must specify the name of the chunk table.
compressionstringlz4The type of the compression algorithm. Valid values:
  • none
  • jpeg
  • zlib
  • png
  • lzo
  • lz4
qualityinteger75The compression quality. This parameter takes effect for only the jpeg compression algorithm.
interleavingstringSame as the original rasterThe interleaving method. Valid values:
  • bip: band interleaved by pixel (BIP)
  • bil: band interleaved by line (BIL)
  • bsq: band sequential (BSQ)
endianstringSame as the original rasterThe endian. Valid values:
  • NDR: little endian
  • XDR: big endian

Description

  • If NULL or '' is passed for the chunktable parameter, a temporary chunk table that has a random name is generated to store data. This temporary table is valid in only the current session. If you need to retain an accessible clipping object, you must specify the name of the chunk table.
  • The default cache size for clipping is 100 MB. This indicates that up to 100 MB of clipping result data can be returned. If you need to adjust the size of the returned result, you can specify the cache size by using the ganos.raster.clip_max_buffer_size parameter.

Examples

DO $$
declare
    rast raster;
    new_rast raster;
begin
    -- Create a permanent table.
    CREATE TEMP TABLE rast_clip_result(id integer, rast raster);
    
    select raster_obj into rast from raster_table where id = 1;
    new_rast = ST_ClipToRast(rast, ST_geomfromtext('Polygon((0 0, 45 45, 90 45, 45 0, 0 0))', 4326), 0);
    Insert into rast_clip_result values(1, new_rast);
end;    
$$ LANGUAGE 'plpgsql';