Use ST_AsImage to convert a raster to an image - PolarDB

Converts a raster to a BYTEA image cropped to a specified extent, pyramid level, band selection, and format. Returns up to 100 MB of image data by default.

Syntax

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

Parameters

Parameter	Description
`raster_obj`	The raster to convert.
`extent`	The bounding box of the output image. Uses geographic coordinates by default.
`pyramidLevel`	The pyramid level to read from. Valid values start from 0. Default: `0`.
`bands`	The bands to include in the output image. Valid values start from 0. Accepts a range (`'0-2'`) or a list (`'1,2,3'`). Leave blank to use the first three bands by default. The number of bands determines the output mode: `1` = grayscale, `2` = grayscale + Alpha, `3` = R, G, B, `4` = R, G, B, Alpha. For JPEG, specify 1 or 3 bands. For PNG, specify 1, 2, 3, or 4 bands.
`format`	The output image format. Valid values: `PNG` (default), `JPEG`.
`option`	A JSON string of advanced conversion options. See Options.

Options

The option parameter accepts a JSON string with the following fields:

Field	Type	Default	Description
`nodata`	bool	`false`	Specifies whether to use NoData values. `true`: NoData values are processed. `false`: NoData values are processed 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` parameter 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`	The display enhancement mode. `none` applies no enhancement. `stats` applies histogram stretching based on statistical values.
`quality`	integer	`75`	The quality of compression. Valid values: 1–100.

Usage notes

By default, up to 100 MB of cropped data can be returned. To adjust the limit, set the ganos.raster.clip_max_buffer_size parameter.

Examples

All examples query raster_table and filter by id = 1.

Crop using geographic coordinates (basic)

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

Specify a pyramid level

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

Select a band range

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

Specify the output format

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

Apply histogram stretching using statistical values

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

Crop by pixel coordinates with histogram stretching

SELECT ST_AsImage(rast,
                  '(0,0), (200,100)'::Box,
                  0,
                  '',
                  'PNG',
                  '{"nodata":"false","nodatavalue":"0","rast_coord":"true","strength":"stats","quality":"75"}')
FROM raster_table
WHERE id = 1;