This topic describes the ST_Rescale function. This function rescales the pixel range of a raster object but leaves the geospatial data range 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 original raster object whose pixel range you want 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 | 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 |
|
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.
|
Note Exercise caution when you specify 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 you want to create a permanent 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:
|
endian | The endian format of the new raster object. | String | Same as the original raster object | Valid values:
|
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 to store the new raster object.
----------------------------------------------------
CREATE TABLE rat_rescale_result(id integer, rast raster);
-- If you do not specify the nodata field:
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;
-- If you specify one nodata value in the nodataValue field and pixels with nodata values are 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;
-- If you specify more than one nodata value in the nodataValue field:
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;
----------------------------------------------------
-- 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_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;