All Products
Search
Document Center

ApsaraDB RDS:ST_MosaicFrom

Last Updated:Apr 17, 2024

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 field 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.

color_balance

Specifies whether to perform color balancing.

bool

false

This field determines whether to perform color balancing.

step

Specifies the step size that is used during the color balancing process.

integer

0.1

This field is valid when the color_balance field is set to true. A larger step size can speed up the color balancing process, but the results may not be optimal.

iteration

Specifies the number of times color balancing is iterated.

integer

50000

This field is valid when the color_balance field is set to true. The greater the number of iterations, the longer time the color balancing process will take.

parallel

The degree of parallelism (DOP).

integer

1

The degree of parallelism that is allowed. 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.

The ST_MosaicFrom function provides the ability to balance colors based on gamma correction technology. The following list describes the color balancing process:

  1. A global color plane is generated. All raster objects that you want to merge in the mosaic operation are resampled. After resampling, polynomial fitting is used to generate a global pixel matrix. The global pixel matrix is used as a reference to balance the colors of each raster object.

  2. The local color plane that corresponds to each raster object is calculated by using bilinear interpolation. The local color plane can be used to align the color of individual raster objects with the global pixel matrix.

  3. Two different pixel values that correspond to each pixel position within a raster object are calculated. One pixel value is calculated based on the local color plane, and the other is calculated based on the global color plane. Then, the colors of pixels are adjusted by calculating the gamma correction parameter to achieve color balancing.

Examples:

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]}'));

-- Parallel
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}'))

-- Color balancing
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], "color_balance":true, "parallel":4}'))