Merges an array of raster objects into a new raster object.
Syntax
raster ST_MosaicFrom(
raster source[],
cstring chunkTableName,
cstring storageOption default '{}',
cstring mosaicOption default '{}'
);Parameters
| Parameter | Type | Description |
|---|---|---|
source | raster[] | The raster objects to merge. |
chunkTableName | cstring | The name of the chunk table that stores the output raster object. Must comply with database table naming conventions. |
storageOption | cstring | A JSON string that controls how the output raster is stored. Default: {}. See Storage options. |
mosaicOption | cstring | A JSON string that controls the mosaic algorithm. Default: {}. See Mosaic options. |
Storage options
The storageOption parameter accepts a JSON object with the following fields. All fields default to the same value as the source rasters.
| Field | Type | Default | Description |
|---|---|---|---|
chunking | Boolean | Same as source | Specifies whether to store the output raster as chunks. |
chunkdim | string | Same as source | The chunk dimensions. Valid only when chunking is true. Format: (w,h,b). |
interleaving | string | Same as source | The interleaving type. Valid values: bip (pixel interleaving), bil (row interleaving), bsq (band interleaving), auto. |
compression | string | Same as source | The compression format. Valid values: none, jpeg, zlib, png, lzo, lz4, zstd, snappy, jp2k. |
quality | integer | Same as source | The image quality after compression. Valid only when compression is jpeg or jp2k. |
Mosaic options
The mosaicOption parameter accepts a JSON object with the following fields.
| Field | Type | Default | Description |
|---|---|---|---|
srid | integer | SRID of the upper-left raster | The spatial reference identifier (SRID) of the output raster. Must be specified together with cell_size. |
cell_size | float8[] | Cell size of the upper-left raster | The cell size of the output raster. Format: [cell_size_x, cell_size_y]. Must be specified together with srid. |
resample | text | 'Near' | The resampling method. Valid values: 'Near', 'Average', 'Cubic', 'Bilinear'. |
nodata | bool | false | Specifies whether nodata values are valid. When true, pixels with nodata values are not resampled. When false, they are resampled. |
nodataValue | float8 or float8[] | NULL | The nodata value for the output raster. Pass a single number to apply the same value to all bands, or an array with one value per band. |
color_balance | bool | false | Specifies whether to apply color balancing. |
step | integer | 0.1 | The step size used during color balancing. A larger value speeds up the process but may reduce quality. Valid only when color_balance is true. |
iteration | integer | 50000 | The number of color balancing iterations. More iterations produce better results but take longer. Valid only when color_balance is true. |
parallel | integer | 1 | The degree of parallelism (DOP). Valid values: 1–64. |
Usage notes
Input requirements
All source rasters must meet the following requirements:
Same band count: All rasters must have the same number of bands.
Consistent georeferencing: Either all rasters are geographically referenced, or none are. When all are referenced, world coordinates are used for the merge, and SRIDs or affine parameters can differ.
Pixel types: Rasters can have different pixel types.
Color balancing
ST_MosaicFrom supports color balancing based on gamma correction. The process runs in three steps:
Global color plane: All source rasters are resampled and polynomial fitting is applied to generate a global pixel matrix, which serves as the color reference.
Local color planes: Bilinear interpolation calculates a local color plane for each source raster, aligning it with the global pixel matrix.
Gamma correction: Two pixel values are calculated for each pixel position—one from the local color plane and one from the global. A gamma correction parameter adjusts the pixel colors to achieve balance.
Enable color balancing by setting "color_balance": true in mosaicOption. Use step and iteration to tune the speed-quality trade-off.
Examples
Basic merge
Insert a merged raster into a table using default storage and mosaic settings.
Insert Into raster_obj Values(1, ST_MosaicFrom(Array(select raster_obj from raster_table where id < 10), 'chunk_table_mosaic', '', ''))Merge with custom projection
Specify the output SRID and cell size to control the spatial reference and resolution of the merged raster.
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;Merge with nodata handling
Control chunk storage, compression, and nodata behavior in a single call.
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]}'));Merge with parallelism
Use the parallel field to enable parallel processing and speed up large merges.
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}'))Merge with color balancing
Enable color balancing to normalize color differences across source rasters.
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}'))