This topic describes the ST_SubRaster function. This function is used to convert the specified pyramid level or bands of an original raster object into a new raster object.

Syntax

raster ST_SubRaster(raster raster_obj ,
                    integer pyramidLevel default 0,
                    cstring bands default '',
                    cstring storageOption  default '',
                    cstring options default '{}')

Parameters

Parameter Description
raster_obj The name of the original raster object.
pyramidLevel The pyramid level that you want to convert.
bands The bands that you want to convert. The value of this parameter can be an array of integers or an integer range. The integers start from 0. Examples: '0-2' and '1,2,3'. Default value: ". The default value specifies to generate a new raster object based on all bands.
storageOption The JSON string that specifies how to store the new raster object. For more information, see the storageOption parameter.
options The JSON string that specifies how to generate the new raster object. For more information, see the options parameter.

The following table describes the parameters that are contained in the value of the storageOption parameter.

Parameter Description Type Default value Remarks
chunking Specifies whether to store the new raster object as chunks. boolean Same as the original raster object. None.
chunkdim The dimensions that are used to store the new raster object as chunks. string Same as the original raster object. This parameter is valid only if the chunking parameter is set to true.
chunktable The name of the chunk table that is used to store the new raster object. string '' If '' or the value NULL is specified, a temporary chunk table with a random name is generated to store data. This temporary chunk table is valid only in the current session. To create a permanent chunk table for the new raster object, you must specify a name for the chunk table.
compression The format that is used to compress the raster object. string Same as the original raster object. Valid values:
  • NONE
  • JPEG
  • ZLIB
  • PNG
  • LZO
  • LZ4
quality The image quality of the new raster object after compression. integer Same as the original raster object. Valid values: 1 to 99.

This parameter is valid only if the compression parameter is set to JPEG.

interleaving The interleaving type of the new raster object. string Same as the original raster object. Valid values:
  • bip: band interleaved by pixel (BIP)
  • bil: band interleaved by line (BIL)
  • bsq: band sequential (BSQ)
endian The endian format of the new raster object. string Same as the original raster object. Valid values:
  • NDR: little endian
  • XDR: big endian
celltype The pixel type of the new raster object. string Same as the original raster object. Valid value:
  • 1bb: 1-bit Boolean
  • 2bui: 2-bit unsigned integer
  • 4bui: 4-bit unsigned integer
  • 8bsi: 8-bit signed integer
  • 8bui: 8-bit unsigned integer
  • 16bsi: 16-bit signed integer
  • 16bui: 16-bit unsigned integer
  • 32bsi: 32-bit signed integer
  • 32bui: 32-bit unsigned integer
  • 64bsi: 64-bit signed integer
  • 64bui: 64-bit unsigned integer
  • 32bf: 32-bit floating number
  • 64bf: 64-bit floating number

The following table describes the parameters that are contained in the value of the options parameter.

Parameter Description Type Default value Remarks
parallel The degree of parallelism that is allowed. integer ganos.parallel.degree Valid values: 1 to 64.
stretch The method that is used to stretch pixel values. string none Valid values:
  • none: This function does not stretch pixel values. If a pixel value is beyond the value range that is supported by the pixel type, this function replaces the pixel value with the specified extremum. This extremum can be either the maximum or minimum value, depending on the pixel value.
  • stats: This function stretches pixel values based on the statistics of the original raster. The statistics of the original raster object must be obtained. Before you invoke this function, you can use the ST_SummaryStats function to obtain the statistics.
  • data_type: This function stretches pixel values based on the extrema that are specified for the pixel type.

Examples:

Convert the specified band into a new raster object. 

SELECT ST_SubRaster(rast, 1, '0-2', '{"chunktable":"chunk_table", "chunking":true}')
FROM raster_sub
WHERE id=1;

Convert the pixel type and stretch pixel values in parallel. 

SELECT ST_SubRaster(rast, 1, '0-2', '{"chunktable":"chunk_table", "chunking":true, "celltype": "8BUI"}', '{"stretch": "data_type", "parallel": 4}')
FROM raster_sub
WHERE id=1;