13.16 SDO_GEOR_UTL.get_rasterTile
Format
SDO_GEOR_UTL.get_rasterTile( table_name IN VARCHAR2, geor_col_name IN VARCHAR2, simple_predicate IN MDSYS.SDO_STRING_ARRAY DEFAULT NULL, tile_x IN NUMBER, tile_y IN NUMBER, tile_zoom IN NUMBER, outSRID IN NUMBER DEFAULT 3857, bounds IN MDSYS.SDO_NUMBER_ARRAY DEFAULT MDSYS.SDO_NUMBER_ARRAY(-180, -85.051129, 180, 85.051129), zoom_range IN MDSYS.SDO_RANGE DEFAULT MDSYS.SDO_RANGE(0,22), tile_extent IN MDSYS.SDO_NUMBER_ARRAY DEFAULT MDSYS.SDO_NUMBER_ARRAY(256), google_ts IN BOOLEAN DEFAULT TRUE, out_format IN VARCHAR2 DEFAULT ‘PNG’, layer_numbers IN VARCHAR2 DEFAULT ‘1-3’, mosaic_param IN VARCHAR2 DEFAULT NULL, nodata_mapping IN SDO_NUMBER_ARRAYSET DEFAULT NULL, image_processing IN VARCHAR2 DEFAULT NULL, bg_values IN MDSYS.SDO_NUMBER_ARRAY DEFAULT NULL ) RETURN BLOB;
or
SDO_GEOR_UTL.get_rasterTile( georasters IN VARCHAR2, tile_x IN NUMBER, tile_y IN NUMBER, tile_zoom IN NUMBER, outSRID IN NUMBER DEFAULT 3857, bounds IN MDSYS.SDO_NUMBER_ARRAY DEFAULT MDSYS.SDO_NUMBER_ARRAY(-180, -85.051129, 180, 85.051129), zoom_range IN MDSYS.SDO_RANGE DEFAULT MDSYS.SDO_RANGE(0,22), tile_extent IN MDSYS.SDO_NUMBER_ARRAY DEFAULT MDSYS.SDO_NUMBER_ARRAY(256), google_ts IN BOOLEAN DEFAULT TRUE, out_format IN VARCHAR2 DEFAULT ‘PNG’, layer_numbers IN VARCHAR2 DEFAULT ‘1-3’, mosaic_param IN VARCHAR2 DEFAULT NULL, nodata_mapping IN SDO_NUMBER_ARRAYSET DEFAULT NULL, image_processing IN VARCHAR2 DEFAULT NULL, bg_values IN MDSYS.SDO_NUMBER_ARRAY DEFAULT NULL ) RETURN BLOB;
Description
Generate a raster tile in a BLOB from a GeoRaster object or a set of GeoRaster objects (that is, a virtual mosaic).
By default, the generated tile is based on the OGC (Open Geospatial Consortium) WebMercatorQuad tiling scheme. See Common TileMatrixSet definitions for more information.
Parameters
- table_name
-
Name of a valid table or view containing a column of SDO_GEORASTER object type.
- geor_col_name
-
Name of the SDO_GEORASTER type column where the GeoRaster object is to be retrieved.
- simple_predicate
-
A formatted SDO_STRING array of triplets (operand, operator, value) which form a predicate.
Note the following regarding the elements that form the triplet:
- The
operand
, the first element in the triplet, must be a valid column name in the table (table_name
). If the column name is not valid, an exception is raised. - The
operator
is the second element in the triplet, and only one of the following operators are supported:=
,!=
,<
,>
,<=
,>=
IS [NOT] NULL
AND
[NOT] LIKE
- The
value
, the third element in the triplet, must be a string or a number. For example,‘answer’
is treated as a string. However, both‘42’
and42
are treated as numbers. - Multiple triplets form multiple predicates joined by the
AND
operator. For example, consider the followingSIMPLE_PREDICATE
array:SIMPLE_PREDICATE => sdo_string_array('GEORID', '>=', '100', 'GEORID', '<', '200')
This forms the predicate where
"GEORID">=100
and"GEORID" < 200
.
- The
- georasters
-
A cursor that returns one or more GeoRaster objects.
- tile_x
-
The X ordinate of the tile that is to be fetched for the given zoom level (
tile_zoom
).The minimum valid value for this parameter is zero. The maximum valid value is
(2^tile_zoom)-1
. - tile_y
-
The Y ordinate of the tile that is to be fetched for the given zoom level.
The minimum valid value for this parameter is zero. The maximum valid value is
(2^tile_zoom)-1
. - tile_zoom
-
The zoom level of the current retrieval. It determines the number of tiles that can be retrieved for this zoom level, which is
2^tile_zoom x 2^tile_zoom
. Its value must be within the range defined byzoom_range
. - outSRID
-
The SRID of the generated tile.
The default value is 3857.
- bounds
-
The lower-left and upper-right corner coordinates in SRID 4326 of the whole map area.
The default value is the Maplibre’s display bounds:
(-180, -85.051129, 180, 85.051129)
. - zoom_range
-
The range of the valid zoom level.
The default range is
[0,22]
. - tile_extent
-
The dimension in pixels (height, width) of the generated tile.
If only one number is specified in the
sdo_number_array
, the generated tile is a square. Otherwise, the generated tile may be a rectangle. The default tile size is256x256
. - google_ts
-
Boolean value that indicates if OGC WebMercatorQuad tiling schema is used. The default value is TRUE.
The following two tiling schemes are supported when reading tile addresses:
OGC WebMarcatorQuad (default)
: In this tiling scheme, the origin (0,0) of the tile coordinate system is in the northwest corner. The X tile ordinates increase as tiles are read from west to east. The Y tile ordinates increase as tiles are read north to south.OSGeo Tile Map Service (TMS)
: In this tiling scheme, the origin (0,0) of the tile coordinate system is in the southwest corner. The X tile ordinates still increase as tiles are read west to east, but the Y tile ordinates increase as tiles are read south to north.
- out_format
-
The image format of the generated tile.
The valid values are
“PNG”
,“JPEG”
and“TIFF”
. The default value is“PNG”
. - layer_numbers
-
The bands of the GeoRaster objects that are used in generating the tile.
The default value is
‘1-3’
, which means the first three bands of the raster. - mosaic_param
-
The mosaic parameter that is used in generating the tile.
See
mosaicParam
parameter in SDO_GEOR_AGGR.mosaicSubset section. - nodataMapping
-
Specify how
NODATA
cell value is rendered in the generated tile.This parameter is in the format of an array of number set. Each element of the array is a set of 4 numbers: (
val1
,val2
,val3
,val4
).val1
andval2
: Specifies theNODATA
cell value range as[val1, val2)
, which means any cell value that falls in this range is considered asNODATA
cell value.val3
: Specifies the replacement value for the specifiedNODATA
cell values.val3
can be null if no replacement is needed.val4
: This can have a value of 1 or 0.1
: This means the specifiedNODATA
cell is rendered as transparent in the generated tile.0
: This means the specifiedNODATA
cell is not rendered as transparent in the generated tile.
- imageProcessing
-
Specifies the image processing method that is to be applied on the retrieved raster data.
The valid values are:
"stretch"
: Stretch the raster data cell values range to[0,255]
."piecewisestretch"
: Stretch the raster data cell values range to[0,255]
, but enhance the brightness and contrast of the image area with low cell values."normalize"
: Process the raster data cell values to have a mean value of 128 and a standard deviation of 64."equalize"
: Apply the equalization on the raster data cells based on its histogram."terrainRGB"
: Generate the Mapbox TerrainRGB image based on the one band DEM (Digital Elevation Model) raster data. This is used to configure raster-DEM source in Maplibre or Mapbox.
All the image processing methods except
“terrainRGB”
are based on the statistics of the virtual mosaic defined by thetable_name
,geor_col_name
,simple_predicate
, orgeorasters
parameter. - bg_values
-
Background values for the empty area of the generated tile.
The number of elements in the
SDO_NUMBER_ARRAY
object must be either one (same filling value used for all bands) or the band dimension size of the generated tile (a different filling value for each band, respectively). The default background value is zero.
Usage Notes
There are two formats of the SDO_GEOR_UTL.get_rasterTile function. One format uses the combination of table_name
,
geor_col_name
and simple_predicate
parameters to define
a virtual mosaic. The other one uses the GeoRaster objects returned by the cursor
georasters
parameter to define a virtual mosaic. In both cases, the
virtual mosaic can contain a single GeoRaster object only. Both formats of this function
retrieve the raster data from the virtual mosaic and generate a raster tile in an image
format and return it as a BLOB.
The default parameter values of this function are set to use OGC
WebMercatorQuad tiling scheme, that is, the generated tiles are of size 256 x
256
, in SRID 3857, in PNG format, with the map boundary as WGS84 (-180,
-85.051129, 180, 85.051129)
, and with the maximum zoom level as
22
.
The tile generation considers a 2-band raster data as a 1-band image with the second band
as the alpha band. It also considers a 4-band raster data as a 3-band image with the fourth
band as the alpha band. If the source raster has one band and has colormap
or grayscale
table stored in the GeoRaster object metadata, the
colormap
or grayscale
table is automatically added to
the generated image tile.
If there is no raster data at the specified tile location (tile_x,
tile_y, tile_zoom
) and ‘terrainRGB’
is not specified as the
image processing method, a fully transparent PNG tile is returned.
Note:
If you are using the Autonomous AI Database environment, then Oracle Java needs to be enabled for this feature. See Enable Oracle Java for more information.Examples
The following example generates a raster tile at zoom 0 from the GeoRaster object in
table world_image
, in column georaster
, from the row with
georid=2
:
select sdo_geor_utl.get_rastertile(‘world_image’, ‘georaster’, sdo_string_array(‘georid’, ‘=’, ‘2’), 0, 0, 0) from dual;
The following example generates a raster tile from a virtual mosaic from the
GeoRaster table landsat_images
, with the specified mosaic parameter and
image processing method:
select sdo_geor_utl.get_rastertile(‘landsat_images’, ‘image’, null, 10, 24, 6, mosaic_param=>’resFilter=false, commonPointRule=high’, image_processing=>’normalize’, bg_values=>sdo_number_array(255, 0, 0)) from dual;
The following example generates a Mapbox TerrainRGB tile from a DEM table
dem_table
:
select sdo_geor_utl.get_rastertile(‘dem_table’, ‘raster’, sdo_string_array(‘id’, ‘=’, ‘1’), 1, 1, 1, image_processing=>’TerrainRGB’) from dual;
Parent topic: SDO_GEOR_UTL Package Reference