ST_Transform

Reprojects a raster object from one spatial reference system to another using a specified resampling algorithm. Available resampling methods are Near (default), Average, Cubic, and Bilinear.

Syntax

raster ST_Transform(raster rast,
           integer outSrid,
           cstring processExpr default '',
           cstring storageOption default '')

Parameters

Parameter	Type	Default	Description
`rast`	raster	—	The raster object to reproject.
`outSrid`	integer	—	The SRID of the target spatial reference system. Must be a valid SRID from the `spatial_ref_sys` table.
`processExpr`	cstring	`''`	A JSON string controlling the resampling method and nodata handling.
`storageOption`	cstring	`''`	A JSON string controlling how the output raster is stored.

processExpr fields

Field	Type	Default	Description
`resample`	Text	`Near`	The resampling algorithm. Valid values: `Near`, `Average`, `Cubic`, `Bilinear`.
`nodata`	Boolean	`false`	Specifies whether nodata pixels in the source raster are treated as valid. Set to `true` to skip resampling nodata pixels. Set to `false` to resample them.
`nodataValue`	float8 or float8[]	`NULL`	The nodata value(s) to assign in the output raster. Specify one value to apply to all bands, or one value per band. If specifying one value per band, the count must match the number of bands.

Warning

If the source raster contains no nodata pixels, set nodata to false and omit nodataValue to avoid image artifacts.

Choosing a resampling algorithm

Algorithm	Characteristics	Use when
`Near`	Fastest; preserves original pixel values exactly	Categorical or classified data (land cover, labels)
`Bilinear`	Smooth interpolation using 4 surrounding pixels	Continuous data where smoothness matters
`Cubic`	Higher-quality interpolation using 16 surrounding pixels	High-resolution imagery requiring fine detail
`Average`	Computes the mean of contributing pixels	Downsampling or reducing noise

storageOption fields

Field	Type	Default	Description
`chunking`	Boolean	Same as source	Whether to store the output raster as chunks.
`chunkdim`	String	Same as source	Chunk dimensions. Takes effect only when `chunking` is `true`.
`chunktable`	String	`''`	The name of the chunk table. If blank or `NULL`, a temporary chunk table with a random name is created for the current session and deleted when the session ends. Specify a name to persist the output raster permanently.
`compression`	String	Same as source	Compression format. Supported values: `None`, `JPEG`, `Zlib`, `PNG`, `LZO`, `LZ4`.
`quality`	Integer	Same as source	Image quality. Applies only when `compression` is `JPEG`.
`interleaving`	String	Same as source	Band interleaving format. Valid values: `bip` (band interleaved by pixel, BIP), `bil` (band interleaved by line, BIL), `bsq` (band sequential, BSQ).
`endian`	String	Same as source	Byte order. `NDR` for little-endian; `XDR` for big-endian.

Warning

If chunktable is blank or NULL, the output raster exists only for the current session. To save the raster permanently, specify a chunk table name in the chunktable field.

Examples

The examples below load source data and write transformed results in two ways: to a permanent chunk table, and to a session-only temporary table.

-- Set up the source table and load a sample raster
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', '{}')
);

Write to a permanent chunk table

All three INSERT statements below use the chunktable field to persist the output raster. They differ in how nodata is handled.

CREATE TABLE rat_transform_result (id integer, rast raster);

-- No nodataValue specified
INSERT INTO rat_transform_result (id, rast)
SELECT 10, ST_Transform(
  rast,
  32652,
  '{"resample":"Near","nodata":false}',
  '{"chunking":true,"chunkdim":"(256,256,1)","compression":"none","interleaving":"bsq","chunktable":"result_rbt"}'
)
FROM datasource_table
WHERE id = 1;

-- Single nodataValue; nodata pixels are skipped during resampling
INSERT INTO rat_transform_result (id, rast)
SELECT 11, ST_Transform(
  rast,
  32652,
  '{"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 nodataValues (one per band)
INSERT INTO rat_transform_result (id, rast)
SELECT 12, ST_Transform(
  rast,
  32652,
  '{"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;

Write to a session-only temporary table

Omit chunktable to store the result in a temporary chunk table. Use this approach for intermediate computations within a session.

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

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