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 | A JSON string that describes the chunks for storing the pyramid of the raster object. |
| data | The raster 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. |
| width | The number of columns of the raster. |
| extent | The three-dimensional 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 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. |
Note 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.
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 parameters in the URL of a MinIO bucket to create a raster object.
Select ST_CreateRast('OSS://<ak>:<ak_secret>@10.0.XX.XX:443/mybucket/data/image.tif');
-- Specify the user_name parameter in the URL of an HDFS file.
Select ST_CreateRast('HDFS://<user_name>@10.0.XX.XX: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"}');
-- 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');
-- 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"}'));