This topic describes the ST_CreateRast function. This function creates a raster object by using the data stored in an Alibaba Cloud Object Storage Service (OSS) bucket, a self-managed Multi-Cloud Object Storage (MinIO) bucket, or a Hadoop Distributed File System (HDFS) file. Alternatively, this function generates a raster object by using the raster object represented by the specified one-dimensional array.
Syntax
raster ST_CreateRast(cstring url);
raster ST_CreateRast(cstring url, cstring storageOption);
raster ST_CreateRast(anyarray data , integer width, cstring storageOption, geometry extent);Parameters
Parameter | Description |
url | The path of the OSS object based on which you want to create a raster object. For more information, see Object storage paths. |
storageOption | The JSON string that describes the chunks for storing the pyramid of the raster object. |
createOption | The JSON string that is used to specify the storage information about the import option. |
data | The raster data represented by a one-dimensional array. The number of elements in the one-dimensional array is the product of the number of columns and the number of rows of the raster data. |
width | The number of columns of the raster data. |
extent | The 3D space represented by using a geometry. This parameter is optional. |
The following table describes the fields of the storageOption parameter.
Field | Description | Type | Format | Default value | Description |
chunkdim | The size of each chunk that is used to store the data of the raster object. | string | (w, h, b) | Same as the size of each chunk in the original object | None |
interleaving | The interleaving type of the new raster object. | string | None | bsq | Valid values:
|
chunk_table | The name of the chunk table that you want to specify. | string | None | None | If you want to call this function to generate a raster object by using the raster object represented by a specified one-dimensional array, you must specify this parameter. |
You need to change the default values of the chunkdim and interleaving fields only in some cases:
Users want to view the raster object based on multiband red, green, and blue (RGB) combination, but the value of the interleaving field is bsq. In this case, you must change the value of the interleaving field to bip.
The chunks of some images that are used to render the raster object contain 1 row and n columns in size. However, users request chunks that contain 256 rows and 256 columns in size. In this case, you must change the value of the chunkdim field to the requested chunk size.
The following table describes the fields of the createOption parameter.
Field | Description | Type | Default value | Description |
compute_stats | Specifies whether to automatically calculate band statistics during the import process. | boolean | false | None |
approx | Specifies whether to use a sampling method. | boolean | false | If this field is set to true, the statistical value is calculated in a sampling method. The result may be inaccurate. |
factor | The sampling factor. | integer | 4 | A sampling factor of n indicates that each sampling unit is composed of n pixels during the sampling process. The setting is valid only when the approx field is set to true. |
exclusive_nodata | Specifies whether to exclude nodata values. | boolean | true | Nodata values are excluded from the calculation. |
Description
You can obtain the supported data types by using the ST_RasterDrivers function.
Examples:
-- Specify the AccessKey ID, AccessKey secret, and endpoint in the URL of an OSS object to create a raster object.
Select ST_CreateRast('OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.tif');
-- Specify the host and port in the URL of the MinIO object.
Select ST_CreateRast('MIO://<ak>:<ak_secret>@10.0.0.1:443/mybucket/data/image.tif');
-- Specify the user_name parameter in the URL of the HDFS file.
Select ST_CreateRast('HDFS://<user_name>@10.0.0.1:8020/path/image.tif');
-- Specify the chunkdim and interleaving parameters of a raster object.
Select ST_CreateRast('OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.tif', '{"chunkdim":"(256,256,3)","interleaving":"auto"}');
-- Automatically calculate band statistics after the import.
Select ST_CreateRast('OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.tif', '{"chunkdim":"(256,256,3)","interleaving":"auto"}','{"compute_stats":true}');
-- Specify a NetCDF image that contains subsets.
Select ST_CreateRast('OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.nc:hcc');
-- Specify an HDF5 image that contains subsets.
Select ST_CreateRast('OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.hdf5://ds/hcc');
-- Generate a raster object from an array.
select ST_FixedRid(ST_CreateRast(ARRAY[10, 11, 8, 12], 2, '{"chunktable":"rbt"}',ST_GeomFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))', 4326)));
-- Use array_agg to aggregate multiple records to generate a raster object.
select ST_FixedRid(ST_CreateRast((select array_agg(value) from point_table), 300, '{"chunktable":"rbt"}'));