Convert a raster object to a file using ST_AsDatasetFile - ApsaraDB RDS

Extracts a spatial extent from a raster object and returns it as a file in BYTEA format.

Syntax

setof record ST_AsDatasetFile(raster raster_obj,
                              box extent,
                              integer pyramidLevel default 0,
                              cstring bands default '',
                              cstring format default 'GTiff',
                              cstring create_option default '{}',
                              cstring process_option default '{}',
                              out ext cstring,
                              out data bytea);

Parameters

Parameter	Description
raster_obj	The raster object to extract data from.
extent	The bounding box of the area to extract. Coordinates default to the geographic coordinate system (GCS).
pyramidLevel	The pyramid level to read from. Valid values start from 0. Default value: `0`.
bands	The band IDs to extract. Valid band IDs start from 0. Specify a range (`'0-2'`) or a comma-separated list (`'1,2,3'`). Default value: `''` (all bands).
format	The output file format. For supported formats, see ST_RasterDrivers. Default value: `'GTiff'`.
create_option	A JSON string of creation options for the output dataset. Valid values come from the `create_options` field returned by ST_RasterDrivers. Default value: `'{}'`.
process_option	A JSON string of processing options. The `rast_coord` option specifies whether the `extent` parameter uses pixel coordinates. When set to `"true"`, the x-coordinate maps to a pixel column and the y-coordinate maps to a pixel row, both starting from 0. Default value: `'{}'`.
ext (out)	The file extension of the returned data. Supported values: `TIF`, `XML`.
data (out)	The file content in bytea format.

Usage notes

The output format must be supported by a Ganos driver with can_asfile set to true. To check supported formats, call ST_RasterDrivers.
By default, the function returns up to 100 MB of extracted data. To adjust this limit, change the cache size by using ganos.raster.clip_max_buffer_size.
The valid values for create_option come from the create_options field in the ST_RasterDrivers output.

Examples

Extract a geographic extent using default settings:

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

Extract from a specific pyramid level:

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

Extract specific bands:

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

Save the extracted data as a GIF file:

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

Specify the file format and creation options for the extracted data:

SELECT ST_AsDatasetFile(raster_obj,
                        '(-180,-90), (0,0)'::Box,
                        1,
                        '0-2',
                        'GTiff',
                        '{"blockxsize":256, "blockysize":256, "compress": "DEFLATE"}')
FROM raster_table
WHERE id = 1;

Use pixel coordinates to define the bounding box:

SELECT ST_AsDatasetFile(raster_obj,
                        '(0,0), (100,100)'::Box,
                        1,
                        '0-2',
                        'GTiff',
                        '{}',
                        '{"rast_coord":"true"}')
FROM raster_table
WHERE id = 1;