Builds a pyramid for a raster object to accelerate multi-resolution rendering and zoom-level queries.
Syntax
raster ST_BuildPyramid(raster source,
integer pyramidLevel default -1,
ResampleAlgorithm algorithm default 'Near',
cstring chunkTableName default '',
cstring storageOption default '{}',
cstring buildOption default '{}');Parameters
| Parameter | Description |
|---|---|
| source | The raster object to build the pyramid for. |
| pyramidLevel | The number of pyramid levels to create. Set to -1 to create the maximum number of levels based on the image size. Default value: -1. |
| algorithm | The resampling algorithm. Valid values: Near, Average, Bilinear, Cubic. Default value: Near. |
| chunkTableName | The name of the chunk table in which to store pyramid data. Takes effect only when the raster object is stored in an Object Storage Service (OSS) bucket. |
| storageOption | A JSON string that specifies chunk storage settings for the pyramid. Takes effect only when the raster object is stored in an OSS bucket. For details, see Storage options. |
| buildOption | A JSON string that specifies pyramid build settings. Supports the parallel parameter to control the degree of parallelism. For details, see Build options. |
Storage options
The storageOption parameter accepts a JSON object with the following fields:
| Field | Type | Description |
|---|---|---|
| chunkdim | string | The chunk dimensions in (w, h, b) format. Defaults to the chunk size of the original image data. |
| interleaving | string | The band interleaving method. Valid values: bip (band interleaved by pixel, BIP), bil (band interleaved by line, BIL), bsq (band sequential, BSQ), auto (determined automatically). Default value: bsq. |
| compression | string | The compression format. Valid values: none, jpeg, zlib, png, lzo, LZ4, zstd, snappy, jp2k. Default value: LZ4. |
| quality | integer | The compression quality. Applies only to JPEG and JPEG 2000 (jp2k) compression. Valid values: 1–99. Default value: 75. |
Build options
The buildOption parameter accepts a JSON object with the following fields:
| Field | Type | Description |
|---|---|---|
| parallel | integer | The degree of parallelism for pyramid construction. Valid values: 1–64. If not specified, the value of the GUC parameter ganos.parallel.degree is used. |
Parallel pyramid construction does not support transactions. If the build fails or you need to roll back, call ST_deletePyramid to remove the incomplete pyramid.
Description
This function supports GPU-accelerated computing. By default, in environments with available GPUs, Ganos automatically enables GPU-accelerated computing for this function.
Examples
Build a pyramid with default settings:
UPDATE raster_table SET raster_obj = ST_BuildPyramid(raster_obj) WHERE id = 1;Build a pyramid and store pyramid data in a named chunk table:
UPDATE raster_table SET raster_obj = ST_BuildPyramid(raster_obj, 'chunk_table') WHERE id = 2;Build a pyramid with JPEG 2000 compression, a fixed chunk size of 256×256 with 4 bands per chunk, and automatic band interleaving:
UPDATE raster_table SET raster_obj = ST_BuildPyramid(
raster_obj,
-1,
'Near',
'chunk_table',
'{"compression":"jp2k", "quality": 75, "chunkdim":"(256,256,4)", "interleaving":"auto"}'
) WHERE id = 3;Build the same pyramid using 4 parallel threads:
UPDATE raster_table SET raster_obj = ST_BuildPyramid(
raster_obj,
-1,
'Near',
'chunk_table',
'{"compression":"jp2k", "quality": 75, "chunkdim":"(256,256,4)", "interleaving":"auto"}',
'{"parallel":4}'
) WHERE id = 3;