PolarDB:ST_MosaicFrom - PolarDB

Merges an array of raster objects into a single new raster object stored in a specified chunk table.

Syntax

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

Parameters

Parameter	Description
`source`	An array of raster objects to merge.
`chunkTableName`	The name of the chunk table that stores the output raster. Must follow database table naming conventions.
`storageOption`	A JSON string that controls how the output raster is stored. Defaults to `'{}'`.
`mosaicOption`	A JSON string that controls the mosaic algorithm. Defaults to `'{}'`.

storageOption fields

When omitted or set to '{}', each field defaults to the value from the source raster objects.

Field	Type	Default	Description
`chunking`	boolean	Same as source	Specifies whether to store the output raster as chunks.
`chunkdim`	string	Same as source	Chunk dimensions in `(w, h, b)` format. Valid only when `chunking` is `true`.
`interleaving`	string	Same as source	Pixel interleaving method. Valid values: `bip` (Band Interleaved by Pixel), `bil` (Band Interleaved by Line), `bsq` (Band Sequential), `auto`.
`compression`	string	Same as source	Compression format. Valid values: `none`, `jpeg`, `zlib`, `png`, `lzo`, `lz4`, `zstd`, `snappy`, `jp2k`.
`quality`	integer	Same as source	Compression quality for JPEG and JPEG 2000 output. Valid only when `compression` is `jpeg` or `jp2k`.

mosaicOption fields

When omitted or set to '{}', each field defaults as noted below.

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	Output pixel size as `[cell_size_x, cell_size_y]`. Must be specified together with `srid`.
`resample`	text	`'Near'`	Resampling method. Valid values: `'Near'`, `'Average'`, `'Cubic'`, `'Bilinear'`.
`nodata`	bool	`false`	Specifies whether nodata values from source rasters are treated as valid. If `true`, pixels with nodata values are not resampled. If `false`, they are resampled.
`nodataValue`	float8 \| float8[]	`NULL`	Nodata value(s) for the output raster. Set to a single number to apply the same value to all bands, or to an array whose length matches the band count.
`color_balance`	bool	`false`	Specifies whether to apply color balancing using gamma correction.
`step`	integer	`0.1`	Step size for the color balancing process. Larger values converge faster but may produce less accurate results. Valid only when `color_balance` is `true`.
`iteration`	integer	`50000`	Number of iterations for color balancing. More iterations improve accuracy but increase processing time. Valid only when `color_balance` is `true`.
`parallel`	integer	`1`	Degree of parallelism (DOP). Valid values: `1` to `64`.

Description

ST_MosaicFrom merges multiple raster objects into one new raster object.

Input requirements

All source raster objects must meet the following conditions:

Same band count: All rasters must have the same number of bands.
Consistent georeferencing: All rasters must be georeferenced, or none of them can be. If all are georeferenced, world coordinates are used for the mosaic — SRIDs and affine parameters do not need to match.
Pixel type: Rasters can have different pixel types.

How color balancing works

Color balancing uses gamma correction to reduce visible seams between rasters with different exposure or color profiles. Enable it by setting color_balance to true in mosaicOption.

Use color balancing when merging multi-temporal imagery or data from different sensors where color consistency matters. For homogeneous datasets with no visible seams, leaving color_balance at its default (false) reduces processing time. Increasing iteration improves color accuracy at the cost of longer processing time; increasing step speeds up convergence but may produce less optimal results.

The process runs in three stages:

Global color plane: All source rasters are resampled and combined using polynomial fitting to produce a global pixel matrix, which serves as the color reference.
Local color planes: A local color plane for each raster is computed using bilinear interpolation to align individual raster colors with the global matrix.
Gamma correction: For each pixel position, two values are computed — one from the local plane and one from the global plane. The gamma correction parameter is derived from these values to balance the colors.

Examples

Basic mosaic

Inserts a new raster object by merging all rows with id < 10 into a chunk table:

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

Set target SRID and cell size

Updates an existing row with a mosaic at a specified SRID and pixel resolution:

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;

Control storage and handle nodata

Uses custom chunk storage settings and treats [255, 255, 255] as the nodata value, with Average resampling:

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

Enable parallelism

Runs the mosaic with a degree of parallelism (DOP) of 4 to speed up processing on large datasets:

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

Enable color balancing

Applies color balancing to produce a seamless mosaic from rasters with different color profiles:

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