PolarDB:ST_MosaicFrom - PolarDB

Merges an array of raster objects into a single new raster object, with optional resampling, nodata handling, color balance, and parallel processing.

Syntax

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

Parameters

Parameter	Description
`source`	The raster objects to merge.
`chunkTableName`	The name of the chunk table that stores the output raster. Must comply with database table naming conventions.
`storageOption`	A JSON string that controls how the output raster is stored. Default: `'{}'`. See Storage options.
`mosaicOption`	A JSON string that controls the mosaic algorithm. Default: `'{}'`. See Mosaic options.

Storage options

The storageOption parameter accepts the following JSON fields.

Field	Type	Default	Description
`chunking`	boolean	Same as source rasters	Specifies whether to store the output raster as chunks.
`chunkdim`	string	Same as source rasters	The chunk dimensions. Valid only when `chunking` is `true`. Format: `(w,h,b)`.
`interleaving`	string	Same as source rasters	The interleaving type. Valid values: `bip` (pixel interleaving), `bil` (row interleaving), `bsq` (band interleaving), `auto` (determined automatically).
`compression`	string	Same as source rasters	The compression format. Valid values: `none`, `jpeg`, `zlib`, `png`, `lzo`, `lz4`, `zstd`, `snappy`, `jp2k`.
`quality`	integer	Same as source rasters	The image quality after compression. Takes effect only when `compression` is `jpeg` or `jp2k`.

Mosaic options

The mosaicOption parameter accepts the following JSON 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[]	Pixel size of the upper-left raster	The pixel size of the output raster as `[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 from the source rasters are treated as valid. If `true`, pixels with nodata values are not resampled. If `false`, pixels with nodata values are resampled.
`nodataValue`	float8 or float8[]	`NULL`	The nodata value to assign to the output raster. Set to a scalar to apply the same value to all bands, or to an array whose length equals the number of bands.
`color_balance`	bool	`false`	Specifies whether to apply color balancing.
`step`	integer	`0.1`	The step size used during color balancing. Valid only when `color_balance` is `true`. A larger step speeds up processing but may reduce accuracy.
`iteration`	integer	`50000`	The number of color balancing iterations. Valid only when `color_balance` is `true`. More iterations produce better results but take longer.
`parallel`	integer	`1`	The degree of parallelism (DOP). Valid values: `1` to `64`.

Description

ST_MosaicFrom merges multiple raster objects into a single output raster.

Source raster requirements

All source rasters must satisfy the following conditions:

Same number of bands.
All georeferenced, or none georeferenced. When all rasters are georeferenced, world coordinates are used for the mosaic operation; SRIDs and affine parameters may differ across rasters.
Pixel types may differ.

How color balancing works

ST_MosaicFrom uses gamma correction-based color balancing, applied in three steps:

Generate a global color plane. All source rasters are resampled and polynomial fitting is applied to produce a global pixel matrix, which serves as the color reference.
Calculate a local color plane. For each source raster, bilinear interpolation derives a local color plane that maps individual raster colors to the global pixel matrix.
Apply gamma correction. For each pixel position, two values are computed—one from the local color plane and one from the global color plane. The gamma correction parameter is then calculated to align the two values, producing a color-balanced output.

Examples

Basic mosaic

INSERT INTO raster_obj
VALUES (
  1,
  ST_MosaicFrom(
    ARRAY(SELECT raster_obj FROM raster_table WHERE id < 10),
    'chunk_table_mosaic',
    '',
    ''
  )
);

Mosaic with SRID and cell size

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;

Mosaic with nodata handling

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

Mosaic with parallelism

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

Mosaic with color balancing and parallelism

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