This topic describes the ST_AsDatasetFile function. This function is used to convert a specific part of a raster object into a BYTEA-type file.

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 whose part you want to convert.
extent The part of data that you want to extract. By default, the part of data is specified based on a geographic coordinate system (GCS).
pyramidLevel The pyramid level from which you want to extract data. Valid values start from 0. Default value: 0.
bands The IDs of the bands from which you want to extract data. Valid band IDs start from 0. The value of this parameter can be a range or array of band IDs. Examples: '0-2' and '1,2,3'. Default value: ''. The default value specifies that Ganos extracts data from all bands.
format The format of the file. For more information, see ST_RasterDrivers.
create_option The options based on which you want to create a dataset by using the extracted data. The value of this parameter is a JSON string. For more information, see ST_RasterDrivers.
process_option The options based on which you want to process the extracted data. The value of this parameter is a JSON string.

The rast_coord option specifies whether pixel coordinates are used to specify the input bounding box.

If pixel coordinates are used to specify the input bounding box, the x-coordinate specifies the column No. of a pixel and the y-coordinate specifies the row No. of a pixel. The valid values of the x-coordinate and y-coordinate start from 0.

ext The format of the file. The supported file formats include TIF and XML.
data The BYTEA-type data of the file.

Description

  • The file format that you specify must be supported by a driver in Ganos. Therefore, you must set the can_asfile parameter in the ST_RasterDrivers function to true. For more information, see ST_RasterDrivers.
  • The default size of the cache that stores the extracted data is 100 MB. This means that up to 100 MB of extracted data can be returned. If you want to adjust the size of the extracted data that is returned, you can change the cache size by using the ganos.raster.clip_max_buffer_size parameter.
  • The value of the create_option parameter can be obtained from the create_options parameter of the ST_RasterDrivers function. For more information, see ST_RasterDrivers.

Examples

--Specify the part of data that you want to extract. 
SELECT ST_AsDatasetFile(raster_obj, 
                  '(-180,-90), (0,0)'::Box) 
FROM raster_table    
WHERE id =1;

--Specify the pyramid level from which you want to extract data. 
SELECT ST_AsDatasetFile(raster_obj, 
                  '(-180,-90), (0,0)'::Box,
                 1) 
FROM raster_table
WHERE id =1;

--Specify the IDs of the bands from which you want to extract data. 
SELECT ST_AsDatasetFile(raster_obj, 
                  '(-180,-90), (0,0)'::Box,
                 1,
                 '0-2') 
FROM raster_table    
WHERE id =1;

--Specify that Ganos saves 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 options that are used to process 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;

--Specify that pixel coordinates are used to specify the input 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;