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