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 |
interleaving | The interleaving type of the raster object. | string | Same as the raster objects that you want to merge | Valid values:
|
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:
|
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. |
|
resample | The method that is used to resample pixels. | text | 'Near' | Valid values:
|
nodata | Specifies whether nodata values from the original raster objects are valid. | bool | false |
|
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:
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.
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.
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}'))