ST_Rescale

ST_Rescale changes the pixel size of a raster object by resampling its pixels while keeping the geospatial extent unchanged.

Syntax

raster ST_Rescale(raster rast,
           f8 scale_x,
           f8 scale_y,
           cstring processexpr default '',
           cstring storageOption default '');

raster ST_Rescale(raster raster,
           f8 scale_xy,
           cstring processexpr default '',
           cstring storageOption default '')

Parameters

Parameter	Description
`rast`	The raster object to rescale.
`scale_x`	The proportional ratio to rescale the original raster object in the x direction.
`scale_y`	The proportional ratio to rescale the original raster object in the y direction.
`scale_xy`	The proportional ratio to rescale the original raster object in both the x and y directions.
`processExpr`	A JSON string specifying the resampling method and nodata handling. See processExpr fields.
`storageOption`	A JSON string specifying how to store the output raster object. See storageOption fields.

processExpr fields

Field	Type	Default	Description
`resample`	text	`Near`	Resampling algorithm. Valid values: `Near`, `Average`, `Cubic`, `Bilinear`.
`nodata`	Boolean	`false`	Specifies whether nodata values in the input raster are treated as valid. Set to `true` to preserve nodata pixels without resampling them. Set to `false` to resample nodata pixels like regular pixels.
`nodataValue`	float8 or float8[]	`NULL`	The nodata value to assign in the output raster. Specify one value to apply it to all bands, or specify one value per band. The number of values must match the number of bands.

Set nodata to false and omit nodataValue when the input raster has no nodata pixels. Specifying a nodata value on a raster that has none can introduce image artifacts.

storageOption fields

Field	Type	Default	Description
`chunking`	Boolean	Same as input	Specifies whether to store the output raster as chunks.
`chunkdim`	String	Same as input	Chunk dimensions for the output raster (for example, `"(256,256,1)"`). Takes effect only when `chunking` is `true`.
`chunktable`	String	`''` (empty string)	Name of the chunk table for the output raster. By default, a temporary chunk table with a random name is created and is valid only for the current session. To persist the output raster beyond the session, specify a permanent chunk table name.
`compression`	String	Same as input	Compression format. Valid values: `None`, `JPEG`, `Zlib`, `PNG`, `LZO`, `LZ4`.
`quality`	Integer	Same as input	JPEG image quality. Takes effect only when `compression` is `JPEG`.
`interleaving`	String	Same as input	Interleaving type. Valid values: `bip` (band interleaved by pixel, BIP), `bil` (band interleaved by line, BIL), `bsq` (band sequential, BSQ).
`endian`	String	Same as input	Byte order. Valid values: `NDR` (little endian), `XDR` (big endian).

If chunktable is NULL or an empty string, the output raster is saved to a temporary chunk table with a random name. That table exists only for the current session and is deleted when the session ends. Specify a chunk table name to save the output raster permanently.

Examples

The examples below use a 512x512 single-band BSQ raster loaded from a GeoTIFF file, and rescale it to 1024x1024 pixels. All examples use chunking:true with 256x256x1 chunks and bsq interleaving.

-- Load source data
CREATE TABLE IF NOT EXISTS datasource_table (id integer, rast raster);
INSERT INTO datasource_table VALUES (
  1,
  ST_ImportFrom('rbt', '$(RAST_DATA_DIR)/512_512_1_bsq_8u_geo.tif', '{}')
);

Rescale with permanent storage

Specify chunktable to save the output raster permanently.

CREATE TABLE rat_rescale_result (id integer, rast raster);

-- No nodata handling: resample all pixels with nearest-neighbor
INSERT INTO rat_rescale_result (id, rast)
SELECT 10, ST_Rescale(
  rast, 1024, 1024,
  '{"resample":"Near","nodata":false}',
  '{"chunking":true,"chunkdim":"(256,256,1)","compression":"none","interleaving":"bsq","chunktable":"result_rbt"}'
)
FROM datasource_table
WHERE id = 1;

-- Single nodata value: pixels with nodata are preserved (not resampled)
INSERT INTO rat_rescale_result (id, rast)
SELECT 11, ST_Rescale(
  rast, 1024, 1024,
  '{"resample":"Near","nodata":true,"nodatavalue":255}',
  '{"chunking":true,"chunkdim":"(256,256,1)","compression":"none","interleaving":"bsq","chunktable":"result_rbt"}'
)
FROM datasource_table
WHERE id = 1;

-- Multiple nodata values: one per band (band count must match)
INSERT INTO rat_rescale_result (id, rast)
SELECT 12, ST_Rescale(
  rast, 1024, 1024,
  '{"resample":"Near","nodata":false,"nodatavalue":[255,255,255]}',
  '{"chunking":true,"chunkdim":"(256,256,1)","compression":"none","interleaving":"bsq","chunktable":"result_rbt"}'
)
FROM datasource_table
WHERE id = 1;

Rescale with temporary storage

Omit chunktable to store the output in a session-scoped temporary table. Use this for nested computations in the current session.

CREATE TEMP TABLE rat_rescale_result_temp (id integer, rast raster);

INSERT INTO rat_rescale_result_temp (id, rast)
SELECT 1, ST_Rescale(
  rast, 1024, 1024,
  '{"resample":"Near","nodata":false,"nodataValue":[255,255,255]}',
  '{"chunking":true,"chunkdim":"(256,256,1)","compression":"none","interleaving":"bsq"}'
)
FROM datasource_table
WHERE id = 1;