ST_AsPNG function to convert a raster to a PNG image - PolarDB

Exports a clipped region of a raster as a PNG image (BYTEA). If no bands are specified, the first three bands are used as R, G, and B by default.

Syntax

bytea ST_AsPNG(raster raster_obj, box extent,
               integer pyramidLevel default 0,
               cstring bands default '',
               cstring option default '');

Parameters

Parameter	Type	Default	Description
`raster_obj`	raster	—	The raster to export.
`extent`	box	—	The spatial extent of the output image. Uses the geographic coordinate system by default.
`pyramidLevel`	integer	0	The pyramid level to read from. Valid values start from 0.
`bands`	cstring	`''`	The bands to include, specified as a range (for example, `'0-2'`) or a comma-separated list (for example, `'1,2,3'`). Band indices start from 0. Because the image is in PNG format, set this parameter to 1, 2, 3, or 4. Defaults to the first three bands.
`option`	cstring	`''`	A JSON string of rendering options. See Option fields.

Option fields

Field	Type	Default	Description
`nodata`	bool	`false`	Specifies whether to apply NoData processing. Set to `true` to process NoData values; set to `false` to treat them as normal values.
`nodataValue`	integer	`0`	The NoData value of the raster. Required when `nodata` is `true`.
`rast_coord`	bool	`false`	Specifies whether the `extent` box uses pixel coordinates instead of geographic coordinates. When `true`, x is the column number and y is the row number, both starting from 0.
`strength`	string	`none`	Display enhancement mode. Valid values: `none` (no enhancement) and `stats` (stretching based on statistical values).
`quality`	integer	`75`	PNG compression quality. Valid values: 1 to 100.

Usage notes

Returns a BYTEA value containing the PNG image data.
By default, up to 100 MB of clipped data can be returned. To change this limit, set ganos.raster.clip_max_buffer_size.
The number of bands determines the PNG color mode:
- 1 band — grayscale image
- 2 bands — grayscale image with Alpha band
- 3 bands — R, G, B
- 4 bands — R, G, B, Alpha band

Examples

Export a geographic region as PNG

Clip the raster to the extent (-180,-90), (0,0) at the default pyramid level, using the first three bands.

SELECT ST_AsPNG(raster_obj,
                '(-180,-90), (0,0)'::Box)
FROM raster_table
WHERE id = 1;

Read from a lower-resolution pyramid level

Specify pyramid level 1 to retrieve a lower-resolution overview of the same region.

SELECT ST_AsPNG(raster_obj,
                '(-180,-90), (0,0)'::Box,
                1)
FROM raster_table
WHERE id = 1;

Specify the band range

Export bands 0, 1, and 2 from the raster.

SELECT ST_AsPNG(raster_obj,
                '(-180,-90), (0,0)'::Box,
                1,
                '0-2')
FROM raster_table
WHERE id = 1;

Improve visual contrast with statistical enhancement

Apply stats-based stretching to enhance the dynamic range of the output image.

SELECT ST_AsPNG(rast,
                '(-180,-90), (0,0)'::Box,
                0,
                '',
                '{"nodata":"false","nodatavalue":"0","rast_coord":"false","strength":"stats","quality":"75"}')
FROM raster_table
WHERE id = 1;