ST_InterpolateRaster function for interpolating a raster object from 3D points - PolarDB

ST_InterpolateRaster converts a set of 3D points into a raster surface using Inverse Distance Weighting (IDW) interpolation. Each input point carries an (x, y, z) coordinate, where z is the value to interpolate — for example, elevation, temperature, or sensor readings. The function returns the interpolated surface as a raster object.

Syntax

raster ST_InterpolateRaster(
    geometry input_points,
    integer width,
    integer height,
    cstring interpolateOptions,
    cstring storageOptions);

Parameters

Parameter	Type	Description
`input_points`	geometry	The set of 3D interpolation points. Each point must include a Z value. Use `ST_MakePoint(x, y, z)` to construct individual points, and `ST_Collect()` to combine them into a geometry collection.
`width`	integer	The number of columns in the output raster.
`height`	integer	The number of rows in the output raster.
`interpolateOptions`	cstring	A JSON string that configures the spatial interpolation algorithm. See Interpolation options.
`storageOptions`	cstring	A JSON string that configures how the output raster is stored. See Storage options.

Interpolation options

The interpolateOptions parameter accepts a JSON object with the following fields:

Field	Type	Default	Description
`method`	string	`IDW`	The interpolation method. Only IDW is supported.
`radius`	double	`0.0`	The search radius. When set to `0`, the radius is estimated automatically based on the number of input points and the extent of the point cloud. Specify an explicit value when your points are unevenly distributed and automatic estimation produces poor results.
`power`	double	`2.0`	The IDW power parameter, which controls the weight given to nearby points. Higher values concentrate influence on the nearest points, producing a more localized (less smooth) surface. Lower values spread influence over a wider area, producing a smoother surface.
`max_points`	integer	`10`	The maximum number of points used per grid cell. Must be greater than `min_points`.
`min_points`	integer	`2`	The minimum number of points required to interpolate a grid cell. If fewer than `min_points` points fall within the search radius, that cell is filled with the `nodata` value instead of an interpolated value.
`nodata`	double	`0.0`	The value assigned to grid cells that cannot be interpolated — for example, cells where fewer than `min_points` points are found.
`parallel`	integer	`1`	The degree of parallelism (DOP). Increase this value to use multiple parallel workers for large datasets.

Storage options

The storageOptions parameter accepts a JSON object with the following fields:

Field	Type	Default	Description
`chunkdim`	string	Same as the source raster	The chunk dimensions in `(width, height, bands)` format. For example, `"(256,256,1)"`.
`chunktable`	string	—	The name of the chunk table used to store the output raster. If not specified, a temporary table is created.
`celltype`	string	`16BUI`	The pixel type of the output raster. Valid values: `8BSI`, `8BUI`, `16BSI`, `16BUI`, `32BSI`, `32BUI`, `32BF`, `64BF`.

Usage notes

Input points must include Z values. Use ST_MakePoint(x, y, z) — not ST_MakePoint(x, y) — to make sure each point carries the value to interpolate.
Point density affects output quality. IDW works best when sampling points are reasonably evenly distributed across the area. Sparse or heavily clustered input points produce surfaces that may not reflect the actual spatial variation.
min_points controls nodata regions. When the search radius contains fewer points than min_points, those output cells receive the nodata value. If your output raster has unexpected empty areas, increase radius or decrease min_points.

Examples

Basic interpolation

Interpolate point data from point_table into a 256x256 raster using IDW with a search radius of 3.0:

SELECT ST_InterpolateRaster(
  ST_Collect(ST_MakePoint(ST_X(geom), ST_Y(geom), value)),
  256,
  256,
  '{"method":"IDW","radius":"3.0","max_points":"4","min_points":"1"}',
  '{"chunktable":"rbt","celltype":"8bui"}')
FROM point_table;

Parallel interpolation

Use four parallel workers to speed up interpolation on large point datasets:

SELECT ST_InterpolateRaster(
  ST_Collect(ST_MakePoint(ST_X(geom), ST_Y(geom), value)),
  256,
  256,
  '{"radius":"2.0","max_points":"4","min_points":"1","parallel":"4"}',
  '{"chunktable":"rbt","celltype":"8bui"}')
FROM point_table;