All Products
Search
Document Center

PolarDB:ST_MosaicFrom

Last Updated:May 29, 2023

This topic describes the ST_MosaicFrom function. This function performs a mosaic operation to merge specified raster objects into a new raster object.

Syntax

raster ST_MosaicFrom(
  raster source[],
  cstring chunkTableName,
	cstring storageOption default '{}', 
  cstring mosaicOption default '{}'
);

Parameters

Parameter

Description

source

The raster objects that you want to merge.

chunkTableName

The name of the chunk table for storing the new raster object. The name must comply with the database table naming conventions.

storageOption

The storage option that is represented by a JSON string in the returned result.

mosaicOption

The mosaic operation option that is represented by a JSON string in the returned result.

The value of the storageOption parameter is a JSON-formatted string that describes the chunk storage of raster objects. The following table describes the supported fields.

Field

Description

Type

Default value

Remarks

chunking

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

boolean

Same as the raster objects that you want to merge

/

chunkdim

The size of each chunk.

string

Same as the raster objects that you want to merge

This parameter is valid only when the chunking field is set to true. The value must be in the (w, h, b) format.

interleaving

The interleaving type of the raster object.

string

Same as the raster objects that you want to merge

Valid values:

  • bip: pixel interleaving

  • bil: row interleaving

  • bsq: band interleaving

  • auto: an interleaving method that is specified by this function

compression

The format in which the system compresses the data of the new raster object.

string

Same as the raster objects that you want to merge

Valid values:

  • none

  • jpeg

  • zlib

  • png

  • lzo

  • lz4

  • zstd

  • snappy

  • jp2k

quality

The image quality of the new raster after compression.

integer

Same as the raster objects that you want to merge

This field takes effect only when you set the compression field to jpeg or jp2k.

The value of the mosaicOption parameter is a JSON-formatted string that describes the mosaic algorithm. The following table describes the supported fields.

Field

Description

Type

Default value

Remarks

srid

The spatial reference identifier (SRID) of the new raster object.

integer

The SRID of the upper-left raster object.

You must specify both the srid and cell_size fields.

cell_size

The pixel size of the new raster object.

float8[]

The pixel size of the upper-left raster object.

  • The value of this field is an array of two floating-point numbers. Format: [cell_size_x,cell_size_y].

  • You must specify both the srid and cell_size fields.

resample

The method that is used to resample pixels.

text

'Near'

Valid values:

  • 'Near'

  • 'Average'

  • 'Cubic'

  • 'Bilinear'

nodata

Specifies whether nodata values from the original raster objects are valid.

bool

false

  • If you set this field to true, nodata values are valid and pixels with nodata values are not resampled.

  • If you set this field to false, nodata values are invalid and pixels with nodata values are resampled.

nodataValue

The new nodata value that is specified based on the bands of the new raster object.

float8

float8[]

NULL

You can set the nodataValue field to a numeric value or an array. If you set the nodataValue field to a numeric value, all bands of the new raster object use the same nodata value. If you set the nodataValue field to an array, the number of elements in the array must be the same as the number of bands of the raster.

parallel

The degree of parallelism (DOP).

integer

1

Valid values: 1 to 64.

Description

This function merges multiple raster objects into a new one.

All raster objects that you want to merge must meet the following requirements:

  • The raster objects have the same number of bands.

  • The raster objects are geographically referenced, or none of them are geographically referenced. If all raster objects are geographically referenced, the world coordinate is used for the mosaic operation and the SRIDs or affine parameters can be different.

  • Raster objects can have different pixel types.

Examples

-- Example of common merge
Insert Into raster_obj Values(1, ST_MosaicFrom(Array(select raster_obj from raster_table where id < 10), 'chunk_table_mosaic', '', ''))
Update raster_table Set raster_obj = ST_MosaicFrom(Array(select raster_obj from raster_table where id < 10), 'chunk_table_mosaic','{"srid":4326,"cell_size":[0.00002,0.00002]}') where id = 11;

-- nodata
Insert Into rat_mosaicfrom Values(110, ST_MosaicFrom(Array(select rast from rat_mosaicfrom where id < 5), 'rbt_mosaic','{"chunking":true, "chunkdim":"(256,256,3)","compression":"jpeg","quality":75, "interleaving":"bsq","celltype":"8bui"}','{"resample":"Average","srid":4326,"cell_size":[0.00002,0.00002],"nodata":true, "nodataValue":[255,255,255]}'));

-- Example of parallel merge
Insert Into raster_obj Values(1, ST_MosaicFrom(Array(select raster_obj from raster_table where id < 10), 'chunk_table_mosaic', '', '{"srid":4326,"cell_size":[0.00002,0.00002],"parallel":4}'))