All Products
Search
Document Center

ApsaraDB RDS:ST_ClipToRast

Last Updated:Dec 13, 2023

This topic describes the ST_ClipToRast function. 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 that you want to clip.

pyramidLevel

The pyramid level.

geom

The geometry object that is used for clipping.

bands

The bands to be clipped. The value is in the format of '0-2' or '1,2,3'. It starts from 0. Default value: ". The default value indicates that all bands are clipped.

nodata

The 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 filled. If a band has no predefined NoData value, 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 fields of the clipOption parameter.

Parameter

Type

Default

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 specified 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 fields of the storageOption parameter.

Parameter

Type

Default

Description

chunking

boolean

Same as the original raster

Specifies whether to store the data of the new raster object as chunks.

chunkdim

string

Same as the original raster

The dimensions based on which the system chunks the data of the new raster object. This parameter only takes effect when the chunking parameter is set to true.

chunktable

string

''

The name of the chunk table that stores the data of the new raster. If you set this parameter to '', a temporary chunk table that has a random name is generated to store data. The temporary chunk table is valid only in the current session. To create a permanent chunk table for the new raster, you must specify a name for 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 the original raster

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 the original raster

The endian format. Valid values:

  • NDR: little endian

  • XDR: big endian

Description

  • If you set the chunkTable prameter to NULL or '', a temporary chunk table that has a random name is generated to store data. This temporary table is valid only for the current session. To create a permanent chunk table for the new raster, you must specify a name for the chunk table.

  • The default cache size for clipping is 100 MB. This indicates that up to 100 MB of clipping data can be returned. If you want to adjust the size of the returned result, you can execute the SET ganos.raster.clip_max_buffer_size = <Cache size in bytes>; statement.

Examples

-- Create a permanent table.
CREATE 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;