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’ and 42 are treated as numbers.
  • Multiple triplets form multiple predicates joined by the AND operator. For example, consider the following SIMPLE_PREDICATE array:

    SIMPLE_PREDICATE => sdo_string_array('GEORID', '>=', '100', 'GEORID', '<', '200')

    This forms the predicate where "GEORID">=100 and "GEORID" < 200.

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 by zoom_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 is 256x256.

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 and val2: Specifies the NODATA cell value range as [val1, val2), which means any cell value that falls in this range is considered as NODATA cell value.
  • val3: Specifies the replacement value for the specified NODATA 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 specified NODATA cell is rendered as transparent in the generated tile.
    • 0: This means the specified NODATA 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 the table_name, geor_col_name, simple_predicate, or georasters 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;