Use ST_AsImage to convert raster to BYTEA image - ApsaraDB RDS

Converts a raster object to a bytea image within a specified geographic or pixel extent. When bands is not specified, the first three bands are used, and the output format defaults to PNG.

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	Type	Default	Description
`raster_obj`	raster	—	The raster object to convert.
`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 in the output. Accepts ranges (`'0-2'`) and comma-separated lists (`'1,2,3'`). When left blank, the first three bands are used. Valid band counts: PNG supports 1, 2, 3, or 4 bands; JPEG supports 1 or 3 bands.
`format`	cstring	`'PNG'`	The output image format. Valid values: `PNG`, `JPEG`.
`option`	cstring	`''`	A JSON string with additional rendering options. See Option fields.

Option fields

Field	Type	Default	Description
`nodata`	bool	`false`	Controls NoData handling. `true`: process NoData values. `false`: treat NoData values 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`, the x-axis maps to the column number and the y-axis maps to the row number, both starting from 0.
`strength`	string	`'none'`	Display enhancement mode. `none`: no enhancement. `stats`: apply stretching based on statistical values.
`quality`	integer	`75`	The quality of the compression. Valid values: 1–100.

Usage notes

ST_AsImage returns a bytea value.
By default, up to 100 MB of cropped data can be cached per query. To adjust this limit, set the ganos.raster.clip_max_buffer_size parameter.
The bands parameter controls which bands are included in the output image. The following band counts are supported:
- 1: single band — exported as a grayscale image.
- 2: single band + Alpha band — exported as a grayscale image with transparency.
- 3: R band, G band, and B band — exported as an RGB image.
- 4: R band, G band, B band, and Alpha band — exported as an RGBA image.

Examples

All examples read from a raster_table and filter by id = 1. The geographic extent '(-180,-90), (0,0)'::box covers the lower-left quadrant of the globe.

Export with default settings

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

Export from a specific pyramid level

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

Export bands 0, 1, and 2

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

Export as PNG with explicit format

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

Export with statistics-based display enhancement

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;

Export a pixel-coordinate region with display enhancement

Use rast_coord: true to specify the extent in pixel coordinates instead of geographic coordinates.

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;