Convert raster objects to JPEG images using ST_AsJPEG - PolarDB

Converts a raster object to a BYTEA JPEG image. If no band is specified, bands 0, 1, and 2 are used by default. If one band is provided, the output is a grayscale image. If three bands are provided, they map to R, G, and B channels.

Syntax

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

Parameters

Parameter	Type	Default	Description
`raster_obj`	raster	Required	The raster object to convert.
`extent`	box	Required	The spatial extent of data to extract. By default, coordinates are interpreted as geographic coordinate system (GCS) values.
`pyramidLevel`	integer	`0`	The pyramid level from which to extract data. Valid values start from `0`.
`bands`	cstring	`''`	The bands to include in the output. See Band selection for syntax.
`option`	cstring	`''`	Conversion options as a JSON string. See Option fields for details.

Band selection

The bands parameter controls which raster bands are included in the JPEG output. JPEG supports exactly 1 or 3 bands.

Syntax	Description	Example
Continuous range	Specify a range starting from band index `0`.	`'0-2'` selects bands 0, 1, and 2
Index list	Specify individual band indexes. The first index must be `0`.	`'0,2,4'` selects bands 0, 2, and 4
Empty string	Uses bands 0, 1, and 2 by default.	`''`

Option fields

Pass options as a JSON string to control NoData handling, coordinate interpretation, image enhancement, and quality.

Field	Type	Default	Description
`nodata`	Boolean	`false`	Specifies whether to process NoData values. Set to `true` to enable special NoData handling; `false` treats NoData values as normal pixel values.
`nodataValue`	integer	`0`	The NoData value of the raster. Required when `nodata` is `true`.
`rast_coord`	Boolean	`false`	Specifies whether the `extent` box uses pixel coordinates. When `true`, the x-coordinate is the column index and the y-coordinate is the row index, both starting from `0`.
`strength`	string	`none`	Image enhancement method. `none` disables enhancement; `stats` applies contrast stretching based on statistical values.
`quality`	integer	`75`	JPEG compression quality. Valid values: `1` to `100`. Higher values produce crisper images.

Usage notes

Returns a BYTEA JPEG image.
The output band count must be 1 (grayscale) or 3 (R, G, B). Other band counts are not supported.
Extracted data is buffered in memory. The default buffer size is 100 MB. To adjust the limit, set the ganos.raster.clip_max_buffer_size parameter.

Examples

-- Export a geographic extent using default settings (bands 0, 1, 2 at quality 75)
SELECT ST_AsJPEG(raster_obj,
                 '(-180,-90), (0,0)'::Box)
FROM raster_table
WHERE id = 1;

-- Export at a lower resolution by using pyramid level 1
SELECT ST_AsJPEG(raster_obj,
                 '(-180,-90), (0,0)'::Box,
                 1)
FROM raster_table
WHERE id = 1;

-- Export specific bands by range (bands 0, 1, and 2 from pyramid level 1)
SELECT ST_AsJPEG(raster_obj,
                 '(-180,-90), (0,0)'::Box,
                 1,
                 '0-2')
FROM raster_table
WHERE id = 1;

-- Improve image visibility with contrast stretching and custom NoData handling
SELECT ST_AsJPEG(rast,
                 '(-180,-90), (0,0)'::Box,
                 0,
                 '',
                 '{"nodata":"false","nodatavalue":"0","rast_coord":"false","strength":"stats","quality":"75"}')
FROM raster_table
WHERE id = 1;

What's next

ST_AsPNG: Exports a raster object as a PNG image. Use PNG when you need lossless output or transparency support.
ST_AsTIFF: Exports a raster object as a TIFF image. Use TIFF for multi-band exports or when downstream tools require GeoTIFF format.