This topic describes the ST_Reclassify function, which reclassifies a raster object. The new raster object has the same spatial reference system and resolution as the original raster object, but its number of bands must be specified in the relassexpr parameter.

Syntax

raster ST_Reclassify(raster raster_obj,
                 cstring reclassexpr default NULL
                 cstring storageOption default '')

Parameters

Parameter Description
raster_obj The original raster object that you want to reclassify.
reclassexpr The JSON string that specifies the number of bands in the new raster object and how to map the bands from the original to new raster objects.
storageOption The JSON string that specifies how to store the new raster object.

Each child JSON object in the JSON string specified by the reclassexpr parameter represents a field dictated to an operation on a specific band. The following table describes these fields.

Field Description Type Default value Setting notes
band The sequence number of the specific band. Integer None The band number starts from 0.
remap The method used to reclassify the specified band. Object N/A N/A.
nodata Specifies whether nodata values are valid. Boolean false
  • If you set this parameter to true, nodata values are valid and pixels with nodata values are not reclassified.
  • If you set this parameter to false, nodata values are invalid and pixels with nodata values are reclassified.
nodataValue The nodata value to return for the new raster object. float8 0 None.

The remap parameter is a key-value pair that specifies how to map original to new pixels.

  • The key indicates the original pixel range and can contain one or more values separated with commas (,). You can specify an open "()", closed "[]", semi-open semi-closed "(]", or semi-closed semi-open "[)" range by using parentheses or brackets.
    • A left parenthesis "(" indicates that the pixel value must be greater than the start value of the range.
    • A right parenthesis ")" indicates that the pixel value must be less than the end value of the range.
    • A right bracket "]" indicates that the pixel value must be less than or equal to the end value of the range.
    • A left bracket "[" indicates that the pixel value must be greater than or equal to the start value of the range.

    By default, the range is semi-open semi-closed "(]".

  • The value indicates the mapping result from original to new pixels and can contain one or more values separated with commas (,).
  • The mapping methods are as follows:
    • Range-to-range mapping: The original and new pixel ranges have the same number of values. Examples: "300,400,500":"80,90,100" and "[300,400,500]":"80,90,100".
    • Range-to-value mapping: The original pixel range has one more value than the new pixel range. Example: "(300,400,500]":"80,90".
    • Value-to-value mapping: The original and new pixel ranges both have only one value. Example: "10":"1".
  • If a pixel does not fall into any specified range, it is considered a nodata value.
  • Each pixel can only be included in one range.
  • Examples are as follows:
    • Example 1

      Reclassify band 0:

      if 0<old_value<=100
    new_value = 20
else if 100<old_value<=200
    new_value = 50
else
    new_value = 0
      [ 
   { 
      "band":0,
      "remap":{ 
            "(0,100,200]":"20,50"
      }
   }
]
    • Example 2

      Remap a segmented range on band 0, where pixels beyond the range are considered nodata values: 

      [ 
   { 
      "band":0,
      "remap":{ 
            "(0,100,200]":"20,50",
            "(300,400,500]":"80,90,100"
      }
   }
]
    • Example 3

      Reclassify band 0:

      if 0<old_value<=100
    new_value = 20
else if 100<old_value<=200
    new_value = 50
else
    new_value = 999

      Reclassify band 1:

      if 400<old_value<=600
    new_value = 20+(old_value-400)/200 * (90-20)
else if 600<old_value<=800
    new_value = 90+(old_value-600)/200 * (130-90)
else
    new_value = 0
      [ 
   { 
      "band":0,
      "remap":{
         "(0,100,200]":"20,50"
      },
      "nodata":true,
      "nodataValue":999
   },
   { 
      "band":1,
      "remap":{
        "(400,600,800]":"20,90,130"
      },
      "nodata":false,
      "nodataValue":0
   }
]

The following table describes fields in the storageOption parameter.

Field Description Type Default value Setting notes
chunking Specifies whether to store the new raster object as chunks. Boolean Same as the original raster object N/A.
chunkdim The dimensions used to store the new raster object as chunks. String Same as the original raster object This field only takes effect when the chunking field is set to true.
chunktable The name of the chunk table. String Null string ('') By default, a temporary chunk table with a random name is generated to store data. This temporary chunk table is only valid in the current session. To save the new raster object permanently, you must specify you want to create a permanent chunk table in the chunktable field.
compression The format used for image compression. String Same as the original raster object Six compression formats are supported: None, JPEG, Zlib, PNG, LZO, and LZ4.
quality The image quality of the new raster object. Integer Same as the original raster object This field only takes effect in JPEG format.
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: specifies little endian format.
  • XDR: specifies big endian format.
celltype The pixel type of the new raster object. String Same as the original raster object N/A.

Examples

-- Create a permanent chunk table.
CREATE TABLE rast_reclassify_result(id integer, rast raster);
-- Create a temporary chunk table.
CREATE TEMP TABLE rast_reclassify_result_temp(id integer, rast raster);

-- Store the new raster object in the temporary chunk table.
INSERT INTO rast_reclassify_result_temp(id, rast) 
select 1, ST_Reclassify(rast, '[{"band":0,"remap":{"(0,100,200]":"20,50"}}]') 
from reclass_table