SDO_UTIL.H3SUM_VECTORTILE

Format

SDO_UTIL.H3SUM_VECTORTILE(
  h3_table         IN VARCHAR2,
  levelnum         IN NUMBER DEFAULT NULL,
  tile_x           IN NUMBER,
  tile_y           IN NUMBER,
  tile_zoom        IN NUMBER,
  layer_name       IN VARCHAR2 DEFAULT 'LAYER',
  tile_extent      IN NUMBER DEFAULT 4096,
  google_ts        IN BOOLEAN DEFAULT TRUE,
  max_features     IN NUMBER DEFAULT 20000
) RETURN BLOB;

or

FUNCTION H3SUM_VECTORTILE(
  h3_table         IN VARCHAR2,
  levelnum         IN NUMBER DEFAULT NULL,
  tile_x           IN NUMBER,
  tile_y_pbf       IN VARCHAR2,
  tile_zoom        IN NUMBER,
  layer_name       IN VARCHAR2 DEFAULT 'LAYER',
  tile_extent      IN NUMBER DEFAULT 4096,
  google_ts        IN BOOLEAN DEFAULT TRUE,
  max_features     IN NUMBER DEFAULT 20000
) RETURN BLOB;

Description

Creates and returns the specified MVT vector tile from an H3 summary table created with SDO_UTIL.H3SUM_CREATE_TABLE.

Parameters

h3_table

The H3 summary table to query.

levelnum

The H3 level to return. If levelnum is larger than the max_H3_level specified when the H3 summary table was created, no data will be returned. If not specified, a default value based on the tile_zoom value will be used.

tile_x

The X ordinate of the origin point of the tile being fetched.

The minimum valid value for this parameter is zero. The maximum valid value is dependent on the zoom specified and can be computed as max(X) = (2^tile_zoom) - 1. Note that specifying a X ordinate outside the valid range raises an exception.

tile_y

The Y ordinate (in NUMBER format) of the origin point of the tile being fetched.

The minimum valid value for this parameter is zero. The maximum valid value is dependent on the zoom specified and can be computed as max(Y) = (2^tile_zoom) - 1. Note that specifying a Y ordinate outside the valid range raises an exception.

tile_y_pbf

The tile_y_pbf value is a VARCHAR2 string that specifies a number followed by any file extension. The Y ordinate value is extracted after stripping the file extension in the string. For example, consider the string value ‘23.pbf’ or ‘23.XYZ’. Then 23 will be extracted as the Y ordinate value and everything after the ‘.’ will be stripped and ignored.

tile_zoom

Determines the number of tiles required to divide a map. These segments can be joined at a higher resolution without having to read in the entire map.

For instance, a tile_zoom of zero is a single tile of the entire map without a lot of details. A tile_zoom of n breaks the map into 2^n x 2^n tiles (that is, the number of tiles along the X axis times the number of tiles along the Y axis). For example, at a tile_zoom of 8 there would be 65,536 tiles. A higher value of n implies more details in a tile. Note that the parameter values outside the valid range raise an exception.

layer_name

Name of the layer in the vector tile.

This is an optional parameter. Only a single layer having a default 'LAYER' value is supported in the vector tile.

tile_extent

Integer coordinates that describe the width and height of the tile.

This is an optional parameter. The default value of 4096 indicates that the vector tile is 4096 units high and 4096 units wide. The actual size of these units varies based on the tiles zoom level. The distance between two coordinates within a tile will be much greater at zoom level zero than it would be at zoom level 12. It is recommended that you change the default parameter value only if using a non-standard tiling scheme.

google_ts

Boolean value that indicates if the Google tiling scheme is used.

This is an optional parameter. The default value is TRUE which indicates a GOOGLE tiling scheme.

The following two tiling schemes are supported when reading tile addresses:

GOOGLE (default): In this tiling scheme, the origin point (X,Y) of a tile is in the northwest corner. The X ordinates increase as tiles are read from west to east. The Y ordinates increase as tiles are read north to south.
TMS: In this tiling scheme, the origin point (X,Y) of a tile is in the southwest corner. The X ordinates still increase as tiles are read west to east, but the Y ordinates increase as tiles are read south to north

max_features

Maximum number of features included in a layer.

This is an optional parameter with a default value 20000.

A vector tile is made up of layers. A layer is made up of features. A feature is a geometry that interacts with the tile envelope and any of its attribute columns. For large tile envelopes covering an entire state or an entire country, the number of buildings and their attributes can be very large. Processing overly large numbers of features can be resource intensive both on the CPU and memory.

Therefore, using this parameter allows you to control the maximum number of features to be included in a layer.

Usage Notes

The SDO_UTIL.H3SUM_VECTORTILE function can accept both the X and Y ordinates in NUMBER format or the X ordinate in NUMBER format and the Y ordinate with a .PBF suffix in VARCHAR2 format at a specific zoom level.

In both cases, the data in the H3 summary table is returned as a set of polygons for the boundaries of the H3 cells (hexes and pentagons) that are visible on the specified tile, along with the associated column values. If the H3 summary table was limited to less than level 15, then there is no data in the summary table to return for values above that specified level, and an empty tile will be returned. Tile parameter values and rendering limits are the same as in SDO_UTIL.GET_VECTORTILE.

Examples

The following example describes the usage of SDO_UTIL.H3SUM_VECTORTILE function by visualization software to render maps.

SQL> SELECT dbms_lob.getlength(SDO_UTIL.H3SUM_VECTORTILE(H3_TABLE=>'WORLD_H3',LEVELNUM=>1,
        TILE_X=>2,TILE_Y=>2,TILE_ZOOM=>2)) "BLOBSIZE" FROM DUAL;

  BLOBSIZE
----------
     14304