This topic describes the ST_AsImage function. This function converts a raster into a BYTEA-type image.

Syntax

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

Parameters

ParameterDescription
raster_objThe raster that you want to convert.
extentThe extent of the image. By default, the geographic coordinate system is used.
pyramidLevelThe pyramid layer of the image. Valid values start from 0. Default value: 0.
bandsThe list of bands based on which you want to obtain the image. Examples: '0-2' and '1,2,3'. By default, this parameter is empty. If the image is in the JPEG format, set this parameter to 1 or 3. If the image is in the PNG format, set this parameter to 1, 2, 3, or 4. By default, the first three bands are used.
formatThe format of the image. Valid values:
  • PNG
  • JPEG
optionThe options that are used to convert JSON-formatted strings.

The following table describes the fields in the option parameter.

FieldDescriptionTypeDefault ValueConfiguration
nodataSpecifies whether to process NoData values. boolfalse
  • true: NoData values are processed.
  • false: NoData values are processed as normal values.
nodataValueThe NoData value of the raster. integer0If the nodata field is set to true, you must specify the NoData value.
rast_coordSpecifies whether the input box is specified by using pixel coordinates. boolfalseIf pixel coordinates are used, the x-coordinate specifies the column No. of a pixel and the y-coordinate specifies the row No. of a pixel. Both the column No. and the row No. start from 0.
strengthSpecifies whether to implement enhancement in the display. stringnoneValid values:
  • none: Enhancement is not implemented.
  • stats: Enhancement is implemented by using stretching based on statistical values.
qualityThe quality of the compression. integer75Valid values: 1 to 100.

Description

  • This function returns a BYTEA-type image.
  • Up to 100 MB of cropped data can be cached by default, which indicates that up to 100 MB of data can be returned. To adjust the limit on the image size, you can specify the cache size by using the ganos.raster.clip_max_buffer_size parameter.
  • The following values are valid for this parameter:
    • 1: The raster has a single band based on which the raster can be converted into a grayscale image.
    • 2: The raster has a single band, based on which the raster can be converted into a grayscale image, and the Alpha band.
    • 3: The raster has three bands, which are the R band, G band, and B band.
    • 4: The raster has four bands, which are the R band, G band, B band, and Alpha band.

Examples

--Specify the size of cropped data that can be cached. 
SELECT ST_AsImage(raster_obj, 
                  '(-180,-90), (0,0)'::Box) 
FROM raster_table    
WHERE id=1;

--Specify the pyramid layer at which the image resides. 
SELECT ST_AsImage(raster_obj, 
                  '(-180,-90), (0,0)'::Box,
                 1) 
FROM raster_table    
WHERE id=1;

--Specify the range of cropped data that can be cached for a band. 
SELECT ST_AsImage(raster_obj, 
                  '(-180,-90), (0,0)'::Box,
                 1,
                 '0-2') 
FROM raster_table    
WHERE id=1;

--Specify the compression format. 
SELECT ST_AsImage(raster_obj, 
                  '(-180,-90), (0,0)'::Box,
                 1,
                 '0-2',
                 'PNG') 
FROM raster_table    
WHERE id=1;

--Specify whether to implement enhancement by using stretching based on statistical values. 
SELECT ST_AsImage(rast, 
                  '(-180,-90), (0,0)'::Box, 
                  0, 
                  '',
                  'PNG', 
                  '{"nodata":"false", "nodatavalue":"0","rast_coord":"false", "strength":"stats", "quality":"75"}')
FROM raster_table    
WHERE id=1;

--Specify the pixel coordinates based on which you want to crop the cached data. Then, you can implement enhancement by using stretching based on statistical values. 
SELECT ST_AsImage(rast, 
                  '(0,0), (200,100)'::Box, 
                  0, 
                  '',
                  'PNG', 
                  '{"nodata":"false", "nodatavalue":"0","rast_coord":"true", "strength":"stats", "quality":"75"}')
FROM raster_table    
WHERE id=1;