Use ST_AsTile to crop a tile from a raster object and convert it to a binary stream - PolarDB

Crops a tile from a raster object within a specified geometry boundary and returns it as a binary stream in the requested image format.

Syntax

record ST_AsTile(raster raster_obj, geometry geom, cstring export_options default '');

Return values

Returns a record with the following fields:

Field	Type	Description
`ext`	—	The image format of the output tile. For example, `PNG`, `JPEG`, or `GTiff`.
`data`	bytea	The binary image data of the tile (256 or 512 pixel-sized).

Parameters

Parameter	Description
`raster_obj`	The input raster object.
`geom`	The geometry that defines the tile boundary.
`export_options`	A JSON string that controls the output format and rendering. Defaults to `''` (empty).

export_options

Pass export_options as a JSON string. The following options are supported.

Option	Type	Default	Description
`format`	cstring	`PNG`	The output image format. Valid values: `PNG`, `JPEG`, `GTiff`.
`bands`	cstring	`''`	The bands to include in the output, specified as a comma-separated list (for example, `"0,1,2"`). If not set, all bands are returned.
`quality`	integer	`75`	The compression quality. Valid values: `0` to `100`, where `0` is the lowest quality and `100` is the highest.
`dim`	integer	`256`	The tile size in pixels. Valid values: `256`, `512`.
`pyramid_level`	integer	`-1`	The pyramid level to read from. Defaults to `-1`, which selects the optimal level automatically.
`nodata`	boolean	`true`	Specifies whether to apply nodata masking. If not set, the raster object's own nodata value is used.
`nodatavalue`	f8	`0`	The nodata value to apply. Takes effect only when `nodata` is `true`.
`strength`	string	`none`	The image enhancement mode. Valid values: `none` (no enhancement), `stats` (contrast stretch based on statistical values), `ratio` (contrast stretch based on ratios).
`ratio_offset`	integer	`2`	The clip percentage used when `strength` is `ratio`. A value of `2` clips the darkest 2% and brightest 2% of pixel values before stretching, which prevents extreme outliers from compressing the visible range.
`alpha`	boolean	`false`	Specifies whether to add an alpha channel for transparency.

Examples

Export a PNG tile with RGB bands

SELECT ST_AsTile(
    rast,
    ST_GeomFromText('POLYGON((-80 30,-100 30,-100 100,-80 100,-80 30))', 4326),
    '{"format":"PNG","bands":"0,1,2"}'
)
FROM raster_table;

Export a GeoTIFF tile at a specific pyramid level

SELECT ST_AsTile(
    rast,
    ST_GeomFromText('POLYGON((-80 30,-100 30,-100 100,-80 100,-80 30))', 4326),
    '{"format":"GTiff","bands":"0,1,2","pyramid_level":7}'
)
FROM raster_table;

Export a JPEG tile with compression quality and enhancement

SELECT ST_AsTile(
    rast,
    ST_GeomFromText('POLYGON((-80 30,-100 30,-100 100,-80 100,-80 30))', 4326),
    '{"format":"JPEG","bands":"0,1,2","quality":85,"strength":"stats"}'
)
FROM raster_table;

Export a PNG tile with transparency

SELECT ST_AsTile(
    rast,
    ST_GeomFromText('POLYGON((-80 30,-100 30,-100 100,-80 100,-80 30))', 4326),
    '{"format":"PNG","bands":"0,1,2","alpha":true}'
)
FROM raster_table;