This topic describes the ST_AsJPEG function. This function 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 Description
raster_obj The raster object that 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 bands that you want to obtain.
You must configure this parameter based on the number of bands of the JPEG image. The following list describes the configuration rules:
  • The number of bands of the JPEG image is 3.
  • You can specify a continuous band range that starts from 0 for this parameter. For example, you can set this parameter to '0-2' to specify the 0, 1, and 2 bands.
  • You can specify a value that consists of band sequence numbers for this parameter. The first sequence number in the value must start from 0. For example, you can set this parameter to '0,2,4' to specify the 0, 2, and 4 bands.
  • If you leave this parameter empty, the first three bands, 0, 1, and 2, are used.
option The options that are used to convert JSON-formatted strings.

The following table describes the fields in the option parameter.

Field Description Type Default Description
nodata Specifies whether to process NoData values. bool false
  • true: NoData values need to be processed.
  • false: NoData values are used as normal values.
nodataValue The NoData value of the raster. integer 0 If the nodata parameter is set to true, you must also specify this parameter.
rast_coord Specifies whether the input box is specified by using pixel coordinates. bool false If 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.
strength Specifies whether to implement enhancement in the display. string none Valid values:
  • none: Enhancement is not implemented.
  • stats: Enhancement is implemented by using stretching based on statistical values.
quality The image quality of the new raster after compression. integer 75 Valid values: 1 to 100.

Description

  • This function returns a BYTEA-type JEPG image.
  • 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 following values are valid for the number of bands:
    • 1: The raster has a single band based on which the raster can be converted into a grayscale image.
    • 3: The raster has three bands, which are the R band, G band, and B band.

Examples

--Specify the part of data that you want to extract. 
SELECT ST_AsJPEG(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_AsJPEG(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_AsJPEG(raster_obj, 
                  '(-180,-90), (0,0)'::Box,
                 1,
                 '0-2') 
FROM raster_table    
WHERE id =1;

--Implement enhancement by using stretching based on statistical values. 
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;