Stretches the pixel values of a raster linearly and returns a new raster. Linear stretching redistributes pixel values across the full output range to improve image brightness and contrast, making features easier to distinguish visually.
Two stretching methods are available:
Percentile-based stretch — clips extreme pixel values at the specified low and high percentiles, then redistributes the remaining values across the full output range (0–255). Use this method when the raster's actual value distribution matters more than absolute thresholds.
Fixed-range stretch — maps a specified minimum and maximum value directly to the output range. Use this method when you know the exact input bounds for each band.
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: Fixed-range 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 | Description | Default |
|---|---|---|
raster_obj | The raster to stretch. | — |
pyramidLevel | The pyramid level to stretch. Valid values start from 0. | 0 |
bands | The band IDs to stretch. Use '0-2' for a range or '1,2,3' for individual bands. Valid IDs start from 0. An empty string selects all bands. | '' (all bands) |
storageOption | Storage options for the output raster, as a JSON string. See Storage options. | '' |
parallelOption | Parallel execution options, as a JSON string. See Parallel options. | '{}' |
Syntax 1 parameters (percentile-based)
| Parameter | Description |
|---|---|
minRatio | The low-end percentile cutoff. Pixel values below this percentile are mapped to 0. Valid values: 0–100. |
maxRatio | The high-end percentile cutoff. Pixel values above this percentile are mapped to 255. Valid values: 0–100. Must be greater than minRatio. |
To use this syntax, you can use ST_BuildPercentiles or ST_ComputeStatistics to compute the raster's percentile statistics first.
Syntax 2 parameters (fixed-range)
| Parameter | Description |
|---|---|
minValues | An array of minimum values, one per band. The array length must equal the number of bands being stretched. |
maxValues | An array of maximum values, one per band. The array length must equal the number of bands being stretched. |
Storage options
Pass these fields as a JSON string in the storageOption parameter.
| Field | Type | Default | Description |
|---|---|---|---|
chunking | boolean | Same as input raster | Specifies whether to store the output raster as chunks. |
chunkdim | string | Same as input raster | The chunk dimensions. Valid only when chunking is true. |
chunktable | string | '' | The name of the chunk table for the output raster. If empty or NULL, a temporary chunk table with a random name is created and is valid only for the current session. Specify a name to create a permanent chunk table. |
compression | string | Same as input raster | The compression format. Valid values: NONE, JPEG, ZLIB, PNG, LZO, LZ4. |
quality | integer | Same as input raster | The image quality after compression. Valid values: 1–99. Valid only when compression is JPEG. |
interleaving | string | Same as input raster | The data interleaving method. Valid values: bip (band interleaved by pixel, BIP), bil (band interleaved by line, BIL), bsq (band sequential, BSQ). |
endian | string | Same as input raster | The byte order. Valid values: NDR (little endian), XDR (big endian). |
celltype | string | Same as input raster | The pixel type. Valid values: 1bb, 2bui, 4bui, 8bsi, 8bui, 16bsi, 16bui, 32bsi, 32bui, 64bsi, 64bui, 32bf, 64bf. |
Parallel options
Pass these fields as a JSON string in the parallelOption parameter.
| Field | Type | Default | Description |
|---|---|---|---|
parallel | integer | Value of ganos.parallel.degree | The degree of parallelism. Valid values: 1–64. |
How it works
Percentile-based stretch
Pixel values in the bottom minRatio percentile are clamped to 0, and pixel values in the top (100 - maxRatio) percentile are clamped to 255. All remaining values are linearly redistributed across the full 0–255 range.
Example: A raster's histogram spans values 33–206. With minRatio=2 and maxRatio=98:
The bottom 2% of values (33–45) are mapped to 0.
The top 2% of values (198–206) are mapped to 255.
All values between 45 and 198 are redistributed linearly across 0–255.
Fixed-range stretch
The pixel values of each band are linearly mapped from the [minValues[i], maxValues[i]] range to 0–255. This redistributes values across the full histogram range, improving brightness and contrast.
Example: In an 8-bit dataset, setting minValues=[35] and maxValues=[206] maps value 35 to 0 and value 206 to 255, with all intermediate values distributed proportionally.
Examples
Example 1: Percentile-based stretch
Stretch bands 0–2 at pyramid level 1, clipping the bottom 2% and top 2% of pixel values.
INSERT INTO raster_table
SELECT 100, ST_LinearStretch(rast,
1, -- pyramid level
'0-2', -- bands
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: Fixed-range stretch
Stretch bands 0–2 at pyramid level 0, mapping the fixed range [100, 200] to [0, 255] for all three bands.
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, -- pyramid level
'0-2', -- bands
'{"chunktable":"chunk_table", "chunking":true}',
'{"parallel":4}')
FROM raster_table
WHERE id = 1;What's next
ST_BuildPercentiles — compute percentiles to use as input for the percentile-based stretch
ST_ComputeStatistics — collect full raster statistics including histograms and percentiles