This function clips a raster object by using a specified geometry object and returns the clipping result as a new 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

Parameter Description
raster_obj The raster object to be clipped.
pyramidLevel The pyramid level.
geometry The geometry object that is used for clipping.
bands The 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.
nodata The 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.
clipOption The clipping option that is represented by a JSON string.
storageOption The storage option that is represented by a JSON string in the returned result.

The following table describes the parameters of clipOption.

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

Parameter Type Default value Description
chunking boolean Same as the original raster Specifies whether to store data as chunks.
chunkdim string Same as the original raster The dimension information about the chunk. This parameter only takes effect when the chunking parameter is set to true.
chunktable string '' 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.
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 for only the jpeg compression algorithm.
interleaving string Same as the original raster The interleaving method. Valid values:
  • bip: band interleaved by pixel (BIP)
  • bil: band interleaved by line (BIL)
  • bsq: band sequential (BSQ)
endian string Same as the original raster The 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

-- 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 result 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 for padding and store the result 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 for clipping.
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;