This topic describes the ST_Transform function. This function transforms the underlying coordinates of a raster object from one known spatial reference system to another.

Syntax

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

Parameters

Parameter Description
rast The original raster object whose coordinates you want to transform.
outSrid The spatial reference system of the new raster object. The value of this parameter must be a valid SIRD that can be queried from the spatial_ref_sys table.
processExpr The JSON string that specifies how to resample pixels and process nodata values.
storageOption The JSON string that specifies how to store the new raster object.

Each child JSON object in the JSON string specified by the processExpr parameter represents a field. The following table describes these fields.

Field Description Type Default value Setting notes
resample The method used to resample pixels. Text Near Valid values: Near | Average | Cubic | Bilinear.
nodata Specifies whether nodata values from the original raster object are valid. Boolean false
  • If you set this field to true, nodata values are valid and pixels with nodata values are not resampled.
  • If you set this field to false, nodata values are invalid and pixels with nodata values are resampled.
nodataValue The new nodata value specified based on the bands in the new raster object.

float8

float8[]

 NULL You can specify one or more nodata values in the nodataValue field.
  • If you specify one nodata value, this nodata value is used for all bands in the new raster object.
  • If you specify more than one nodata value, the number of specified nodata values must be the same as the number of bands in the new raster object.
Note Exercise caution when specifying the nodata and nodataValue fields. If the original raster object does not have pixels with nodata values, we recommend that you set the nodata field to false and do not specify the nodataValue field. Otherwise, image artifacts may occur.

The following table describes fields in the storageOption parameter.

Field Description Type Default value Setting notes
chunking Specifies whether to store the new raster object as chunks. Boolean Same as the original raster object N/A.
chunkdim The dimensions used to store the new raster object as chunks. String Same as the original raster object This field only takes effect when the chunking field is set to true.
chunktable The name of the chunk table. String Null string ('') By default, a temporary chunk table with a random name is generated to store data. This temporary chunk table is only valid in the current session. To save the new raster object permanently, you must specify a name for the chunk table in the chunktable field.
compression The format used for image compression. String Same as the original raster object Six compression formats are supported: None, JPEG, Zlib, PNG, LZO, and LZ4.
quality The image quality of the new raster object. Integer Same as the original raster object This field only takes effect in JPEG format.
interleaving The interleaving type of the new raster object. String Same as the original raster object 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 object. String Same as the original raster object Valid values:
  • NDR: specifies little endian format.
  • XDR: specifies big endian format.
Note If you set the chunktable field to NULL or a null string (''), a temporary chunk table with a random name is generated in the current session to store the new raster object. The temporary chunk table is only valid in the current session, and is deleted immediately after the current session ends. To save the new raster object permanently, you must specify you want to create a permanent chunk table in the chunktable field.

Examples

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', '{}'));

----------------------------------------------------
-- Method 1: Specify the chunktable field to create a permanent chunk table for storing the new raster object.
----------------------------------------------------
CREATE TABLE rat_transform_result(id integer, rast raster);

-- If you do not specify the nodata field:
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;

-- If you specify one nodata value in the nodataValue field and pixels with nodata values are resampled:
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;

-- If you specify more than one nodata value in the nodataValue field:
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;

----------------------------------------------------
-- Method 2: Do not specify the chunktable field. The new raster object is saved to a temporary chunk table with a random name and can only be used for nested computations in the current 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;