Converts a raster object into a BYTEA-type JPEG image.
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 | — | The raster object to convert. |
extent | box | — | The spatial extent of the data to extract. Interpreted using a geographic coordinate system (GCS) by default. |
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. JPEG requires exactly 3 bands. See Band selection rules. |
option | cstring | '' | A JSON-formatted string for output conversion options. See Option fields. |
Band selection rules
JPEG output requires exactly 3 bands.
Specify bands using one of the following formats:
| Format | Example | Effect |
|---|---|---|
| Range | '0-2' | Selects bands 0, 1, and 2. |
| List | '0,2,4' | Selects bands 0, 2, and 4. The first value must be 0. |
| Empty string | '' | Defaults to bands 0, 1, and 2. |
Option fields
Pass options as a JSON-formatted string. All field names are lowercase.
Boolean values must be passed as JSON strings ("true"or"false"), not as JSON booleans.
| Field | Type | Default | Description |
|---|---|---|---|
nodata | bool | "false" | Specifies whether to process NoData values. Set to "true" to activate NoData processing. Set to "false" to treat NoData as normal pixel values. |
nodataValue | integer | 0 | The NoData value of the raster. Required when nodata is "true". |
rast_coord | bool | "false" | Specifies whether the input extent uses pixel coordinates. When "true", the x-coordinate is the column number and the y-coordinate is the row number, both starting from 0. |
strength | string | "none" | The display enhancement mode. "none" applies no enhancement. "stats" stretches pixel values based on statistical distribution. |
quality | integer | 75 | The JPEG compression quality. Valid values: 1–100. |
Usage notes
Returns a BYTEA-type JPEG image.
Valid band counts for output:
1: Produces a grayscale image from a single-band raster.
3: Produces an RGB image from three bands.
The default buffer size for extracted data is 100 MB. To change this limit, set the
ganos.raster.clip_max_buffer_sizeparameter.
Examples
-- Extract the geographic extent (-180,-90) to (0,0) using default pyramid level and bands 0–2
SELECT ST_AsJPEG(raster_obj,
'(-180,-90), (0,0)'::Box)
FROM raster_table
WHERE id = 1;
-- Use pyramid level 1 to read from a lower-resolution overview
SELECT ST_AsJPEG(raster_obj,
'(-180,-90), (0,0)'::Box,
1)
FROM raster_table
WHERE id = 1;
-- Map bands 0, 1, 2 to Red, Green, Blue respectively
SELECT ST_AsJPEG(raster_obj,
'(-180,-90), (0,0)'::Box,
1,
'0-2')
FROM raster_table
WHERE id = 1;
-- Apply statistical stretching at 75% quality; NoData processing disabled
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;