ST_LinearStretch - PolarDB - Alibaba Cloud Documentation Center

Syntax

Syntax 1

raster ST_LinearStretch(raster raster_obj ,
                        integer pyramidLevel default 0,    
                        cstring bands default '', 
                        integer minRatio default 0,
                        integer maxRatio default 100, 
                        cstring storageOption  default '',
                        cstring parallelOption default '{}')

Syntax 2

raster ST_LinearStretch(raster raster_obj ,
                        float8[] minValues,
                        float8[] maxValues,
                        integer pyramidLevel default 0,    
                        cstring bands default '',  
                        cstring storageOption  default '',
                        cstring parallelOption default '{}')

Parameters


Parameter	Description
raster_obj	The raster that you want to query.
pyramidLevel	The pyramid level that you want to stretch. Valid values start from 0. Default value: 0.
bands	The IDs of the bands that you want to stretch. Examples: `'0-2'` and `'1,2,3'`. Valid band IDs start from `0`. Default value: `''`. The default value specifies all bands of the raster.
storageOption	A JSON string that consists of storage options. For more information, see the "storageOption" table of this topic.
parallelOption	A JSON string that consists of parallel operation options. For more information, see the " parallelOption" table of this topic.
minRatio	The minimum percentile based on which the raster is stretched. Valid values: 0 to 100.
maxRatio	The maximum percentile based which the raster is stretched. Valid values: 0 to 100. The value of this parameter must be greater than the value of the minRatio parameter.
minValues	An array that consists of minimum values. The number of minimum values must be the same as the number of bands that you want to stretch.
maxValues	An array that consists of maximum values. The number of maximum values must be the same as the number of bands that you want to stretch.

The following table describes the parameters in storageOption parameter.


Parameter	Description	Type	Default value	Remarks
chunking	Specifies whether to store the data of the new raster as chunks.	boolean	Same as the value for the original raster.	None.
chunkdim	The dimensions based on which the system chunks the data of the new raster.	string	Same as the value for the original raster.	This parameter is valid only when you set the `chunking` parameter to true.
chunktable	The name of the chunk table that stores the data of the new raster.	string	`''`	If you specify `''` or the value NULL, a temporary chunk table with a random name is generated to store the data. The temporary chunk table is valid only in the current session. To create a permanent chunk table for the new raster, you must specify a name for the chunk table.
compression	The format in which the system compresses the data of the new raster.	string	Same as the value for the original raster.	Valid values: NONE JPEG ZLIB PNG LZO LZ4
quality	The image quality of the new raster after compression.	integer	Same as the value for the original raster.	Valid values: 1 to 99. This parameter is valid only when you set the compression parameter to JPEG.
interleaving	The method that is used to interleave the data of the new raster.	string	Same as the value for the original raster.	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.	string	Same as the value for the original raster.	Valid values: NDR: little endian XDR: big endian
celltype	The pixel type of the new raster.	string	Same as the value for the original raster.	Valid values: 1bb: 1-bit Boolean value 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 in the parallelOptions parameter.


Parameter	Description	Type	Default value	Remarks
parallel	The degree of parallelism that is allowed.	integer	ganos.parallel.degree	Valid values: 1 to 64.

Description

This function linearly stretches a raster and returns a new raster.

Method 1: Use the ST_BuildPercentiles function or the ST_ComputeStatistics function to calculate percentiles. Then, stretch the original raster based on the percentiles.
For example, the pixel values in the histogram are within the range of 33 to 206, and the minimum percentile and the maximum percentile are set to 2%. This means that 2% of the pixel values below the minimum percentile are within the range of 33 to 45, and 2% of the pixel values above the maximum percentile are within the range of 198 to 206. In this case, the pixel values within the range of 33 to 45 are converted into 0, the pixel values within the range of 198 to 206 are converted into 255, and all the other pixel values in the histogram are redistributed within the range of 0 to 255.
Method 2: Stretch the original raster based on the minimum extent that is specified by the minValues parameter and the maximum extent that is specified by the maxValues parameter.
For example, in an 8-bit data set, a minimum value can be 35, and a maximum value can be 206. This function distributes the pixel values of the original raster within the range of 0 to 255 across the histogram. This way, the brightness and contrast of the image are improved, and the elements in the image are easier to distinguish.

Examples

Example 1: Linearly stretch a raster whose minimum percentage and maximum percentage are set to 2%.

INSERT INTO raster_table
SELECT 100, ST_LinearStretch(rast,
                             1,
                             '0-2',
                             2,  -- min ratio
                             98, -- max ratio
                             '{"chunktable":"chunk_table", "chunking":true}',
                             '{"parallel":4}')
FROM raster_table
WHERE id=1;

Example 2: Stretch a raster to the range of 100 to 200 on all specified bands.

INSERT INTO raster_table
SELECT 200, ST_LinearStretch(rast,
                             ARRAY[100,100, 100]::float8[],  -- min values
                             ARRAY[200,200, 200]::float8[],  -- max values
                             0,
                             '0-2',
                             '{"chunktable":"chunk_table", "chunking":true}',
                             '{"parallel":4}')
FROM raster_table
WHERE id=1;