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 '', /* All bands */
                     float8[] nodata default NULL,
                     cstring clipOption default '',
                     cstring storageOption default '')

Parameters

Parameter Description
raster_obj The raster object.
pyramidLevel The pyramid level.
geometry The geometry object used for clipping.
bands The sequence numbers of bands to be clipped, in the format of '0-2' or '1,2,3'. The sequence number starts from 0. Default value: null string (''). It indicates that all bands are to be clipped.
nodata The array of NoData values in the format of float8[]. If the number of NoData values is fewer than the number of 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.
clipOption The clipping options. The value is a JSON-formatted string.
storageOption The storage options for the output. The value is a JSON-formatted string.

The following table describes the clipOption parameter.

Parameter Type Default value Description
window_clip Boolean false Specifies 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.

The following table describes the storageOption parameter.

Parameter Type Default value Description
chunking Boolean Same as that of the original raster object Specifies whether to store data by chunk.
chunkdim String Same as that of the original raster object The dimension information of the chunk. This parameter takes effect only when the value of the chunking parameter is set to true.
chunktable String Null string ('') The name of the chunk table. By default, a temporary chunk table with a random table name is generated to store data. This temporary table is valid only in the current session. To ensure that the clipped raster object is permanently accessible, you must specify the name of the chunk table.
compression string lz4 The type of the compression algorithm. Valid values:
  • none
  • jpeg
  • zlib
  • png
  • lzo
  • lz4
quality Integer 75 The compression quality. This parameter takes effect only when the value of the compression parameter is set to jpeg.
interleaving String Same as that of the original raster object The interleaving type. Valid values:
  • bip: band interleaved by pixel (BIP)
  • bil: band interleaved by line (BIL)
  • bsq: band sequential (BSQ)
endian String Same as that of the original raster object The endian format. Valid values:
  • NDR: little endian format
  • XDR: big endian format

Description

  • If no data is stored in the chunk table or the name of the chunk table is set to the null string (''), a temporary chunk table with a random table name is generated to store data. This temporary table is valid only in the current session. To ensure that the clipped raster object is permanently accessible, you must specify the name of the chunk table.
  • 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

-- Create a permanent table.
CREATE TEMP TABLE rast_clip_result(id integer, rast raster);
-- Create a temporary table.
CREATE TEMP TABLE rast_clip_result_temp(id integer, rast raster);

-- Use the default clipping settings and store the output in a temporary table.
INSERT INTO rast_clip_result_temp(id, rast) 
select 1, ST_ClipToRast(rast, ST_geomfromtext('Polygon((0 0, 45 45, 90 45, 45 0, 0 0))', 4326), 0) 
from clip_table 
where id =1;

-- Use white as the background color and store the output in a permanent table.
INSERT INTO rast_clip_result(id, rast) 
select 2, ST_ClipToRast(rast, ST_geomfromtext('Polygon((0 0, 45 45, 90 45, 45 0, 0 0))', 4326), 0, '', ARRAY[254,254,254], '', '{"chunktable":"clip_rbt"}') 
from clip_table 
where id =1;

-- Use the window of a geometry object to clip a raster object.
INSERT INTO rast_clip_result_temp(id, rast) 
SELECT 3, ST_ClipToRast(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;