ST_LinearStretch Function Syntax & Raster Contrast Overview - PolarDB for Oracle

Applies a linear stretch to a raster and returns a new raster with redistributed pixel values, improving image brightness and contrast.

Two syntaxes are available: Syntax 1 stretches based on calculated percentiles; Syntax 2 stretches based on explicit minimum and maximum values.

Syntax

Syntax 1 — percentile-based stretch

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 — value-based stretch

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

Parameters

Common parameters

Parameter	Type	Default	Description
`raster_obj`	raster	—	The source raster to stretch.
`pyramidLevel`	integer	`0`	The pyramid level to stretch. Valid values start from `0`.
`bands`	cstring	`''`	The band IDs to stretch, for example `'0-2'` or `'1,2,3'`. Band IDs start from `0`. The default value `''` selects all bands.
`storageOption`	cstring	`''`	A JSON string of storage options. See storageOption parameters.
`parallelOption`	cstring	`'{}'`	A JSON string of parallel execution options. See parallelOption parameters.

Syntax 1 parameters

Parameter	Type	Default	Description
`minRatio`	integer	`0`	The lower percentile cutoff for the stretch. Valid values: `0` to `100`. Must be less than `maxRatio`.
`maxRatio`	integer	`100`	The upper percentile cutoff for the stretch. Valid values: `0` to `100`. Must be greater than `minRatio`.

Syntax 2 parameters

Parameter	Type	Default	Description
`minValues`	float8[]	—	The minimum pixel values for the stretch, one per band. The array length must equal the number of bands being stretched.
`maxValues`	float8[]	—	The maximum pixel values for the stretch, one per band. The array length must equal the number of bands being stretched.

storageOption parameters

Parameter	Type	Default	Description
`chunking`	boolean	Same as source raster	Specifies whether to store the output raster as chunks.
`chunkdim`	string	Same as source raster	The chunk dimensions for the output raster. Valid only when `chunking` is `true`.
`chunktable`	string	`''`	The name of the chunk table for the output raster. Set to `''` or `NULL` to create a temporary chunk table with a random name, valid only for the current session. Specify a name to create a permanent chunk table.
`compression`	string	Same as source raster	The compression format for the output raster. Valid values: `NONE`, `JPEG`, `ZLIB`, `PNG`, `LZO`, `LZ4`.
`quality`	integer	Same as source raster	The compression quality of the output raster. Valid values: `1` to `99`. Valid only when `compression` is `JPEG`.
`interleaving`	string	Same as source raster	The interleaving method for the output raster. Valid values: `bip` (band interleaved by pixel, BIP), `bil` (band interleaved by line, BIL), `bsq` (band sequential, BSQ).
`endian`	string	Same as source raster	The byte order of the output raster. Valid values: `NDR` (little endian), `XDR` (big endian).
`celltype`	string	Same as source raster	The pixel type of the output raster. Valid values: `1bb`, `2bui`, `4bui`, `8bsi`, `8bui`, `16bsi`, `16bui`, `32bsi`, `32bui`, `64bsi`, `64bui`, `32bf`, `64bf`.

parallelOption parameters

Parameter	Type	Default	Description
`parallel`	integer	ganos.parallel.degree	The degree of parallelism. Valid values: `1` to `64`.

How it works

Syntax 1 — percentile-based stretch

Use ST_BuildPercentiles or ST_ComputeStatistics to calculate percentiles, then pass minRatio and maxRatio to define the clipping thresholds. Pixel values below the minRatio percentile are mapped to 0, pixel values above the maxRatio percentile are mapped to 255, and all remaining values are redistributed linearly across the full 0–255 range.

For example, if the histogram spans pixel values 33–206 and both minRatio and maxRatio are set to 2:

The bottom 2% of values (33–45) map to 0.
The top 2% of values (198–206) map to 255.
All values between 45 and 198 are redistributed across 0–255.

Syntax 2 — value-based stretch

Pass minValues and maxValues arrays to set explicit clipping bounds per band. Pixel values at or below minValues map to 0, pixel values at or above maxValues map to 255, and all values in between are redistributed linearly.

For example, in an 8-bit dataset with a minimum of 35 and a maximum of 206, the function distributes the full value range across 0–255, improving image brightness and contrast.

Examples

Example 1: Percentile-based stretch (Syntax 1)

Stretch bands 0–2 at pyramid level 1, clipping the bottom and top 2% of pixel values.

INSERT INTO raster_table
SELECT 100, ST_LinearStretch(rast,
                             1,
                             '0-2',
                             2,   -- minRatio: clip bottom 2%
                             98,  -- maxRatio: clip top 2%
                             '{"chunktable":"chunk_table", "chunking":true}',
                             '{"parallel":4}')
FROM raster_table
WHERE id = 1;

Example 2: Value-based stretch (Syntax 2)

Stretch bands 0–2 at pyramid level 0, mapping pixel values 100–200 to the full output range.

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