Big-Data-HPC-Platform/plugins/h3

H3 Plugin

This plugin exposes a hexagonal hierarchical geospatial indexing system to ECL. It is a wrapper around Uber's H3 library:

• H3: Uber's Hexagonal Hierarchical Spatial Index
• Documentation

Installation and Dependencies

The h3 plugin has a dependency on https://github.com/uber/h3 which has been added to the HPCC-Platform repository as a git submodule. To install:

git submodule update --init --recursive

Quick Start

Import the h3 plugin library and calculate a H3 index at the specified lat/long and at maximum resolution (15):

IMPORT h3 from lib_h3; 

h3_index := h3.index(40.689167, -74.044444, 15);

API

Type Declarations

EXPORT h3_index_t := UNSIGNED8;
EXPORT h3_degrees_t := REAL8;
EXPORT h3_rads_t := REAL8;
EXPORT h3_resolution_t := UNSIGNED4;
EXPORT h3_point_t := RECORD 
    h3_degrees_t lat;
    h3_degrees_t lon;
END;

Indexing functions

index

h3_index_t index(CONST h3_degrees_t lat, CONST h3_degrees_t lng, CONST h3_resolution_t resolution)

Indexes the location at the specified lat, lng and resolution (0->15).

Returns 0 on error.

center

DATASET(h3_point_t) center(CONST h3_index_t idx) : cpp,action,context,fold,entrypoint='center';

Calculates the centroid of the idx and returns the latitude / longitude as a 1 row dataset.

boundary

DATASET(h3_point_t) boundary(CONST h3_index_t idx) : cpp,action,context,fold,entrypoint='boundary';

Calculates the center and boundary (hexagon) of the idx and returns them as 5 or 6 row dataset.

Inspection functions

resolution

h3_resolution_t resolution(CONST h3_index_t idx)

Returns the resolution of the idx.

baseCell

UNSIGNED4 baseCell(CONST h3_index_t idx)

Returns the base cell number of the idx.

toString

STRING toString(CONST h3_index_t idx)

Converts the H3Index representation of idx to the string representation.

fromString

h3_index_t fromString(CONST VARSTRING strIdx) : cpp,action,context,fold,entrypoint='fromString';

Converts the string representation of strIdx to the H3Index representation.

Returns 0 on error.

isValid

BOOLEAN isValid(CONST h3_index_t idx)

Returns TRUE if this is a valid H3 idx.

Grid traversal functions

kRing

SET OF h3_index_t kRing(CONST h3_index_t idx, CONST INTEGER4 k)

k-rings produces indices within k distance of the origin idx.

k-ring 0 is defined as the origin index, k-ring 1 is defined as k-ring 0 and all neighboring indices, and so on.

Output is placed in the returned SET in no particular order.

hexRing

SET OF h3_index_t hexRing(CONST h3_index_t idx, CONST UNSIGNED4 k)

Produces the hollow hexagonal ring centered at idx with distance of k.

h3Distance

SIGNED4 distance(CONST h3_index_t fromIdx, CONST h3_index_t toIdx)

Returns the distance in grid cells between fromIdx and toIdx.

Returns a negative number if finding the distance failed. Finding the distance can fail because the two indexes are not comparable (different resolutions), too far apart, or are separated by pentagonal distortion. This is the same set of limitations as the local IJ coordinate space functions.

Hierarchical grid functions

parent

h3_index_t parent(CONST h3_index_t idx, CONST h3_resolution_t resolution)

Returns the parent (coarser) index containing idx at resolution resolution.

children

SET OF h3_index_t children(CONST h3_index_t idx, CONST h3_resolution_t resolution)

Returns children with the indexes contained by idx at resolution resolution.

compact

SET OF h3_index_t compact(CONST SET OF h3_index_t indexes)

Compacts the set indexes as best as possible, and returns the compacted set.

uncompact

SET OF h3_index_t uncompact(CONST SET OF h3_index_t indexes, CONST h3_resolution_t resolution)

Uncompacts the compacted set of indexes to the resolution resolution and returns the uncompacted set.

Regions

SET OF h3_index_t polyfill(CONST LINKCOUNTED DATASET(h3_point_t) boundary, CONST h3_resolution_t resolution)

polyfill takes an array of lat/long representing a polygon (open ended) and returns a dataset of hexagons that are contained by the polygon.

Miscellaneous functions

degsToRads

h3_rads_t degsToRads(CONST h3_degrees_t degrees)

Converts degrees to radians.

radsToDegs

h3_degrees_t radsToDegs(CONST h3_rads_t radians)

Converts radians to degrees.

hexAreaKm2

REAL8 hexAreaKm2(CONST h3_resolution_t resolution)

Average hexagon area in square kilometers at the given resolution.

hexAreaM2

REAL8 hexAreaM2(CONST h3_resolution_t resolution)

Average hexagon area in square meters at the given resolution.

numHexagons

UNSIGNED8 numHexagons(CONST h3_resolution_t resolution)

Number of unique H3 indexes at the given resolution.

ECL Optimized

The following functions provide an ECL friendly representation of the h3 index. Specifically, it is a STRING16 format where each character represents a finer precision coordinate location (one character per resolution). This allows for quick equality and parentage checking using string slicing techniques.

ECLIndex

STRING16 ECLIndex(CONST h3_degrees_t lat, CONST h3_degrees_t lng, CONST h3_resolution_t resolution)

Indexes the location at the specified lat, lng and resolution (0->15).

toECLIndex

STRING16 toECLIndex(CONST h3_index_t h3Idx)

Converts a h3Index to an ECL Index.

fromECLIndex

h3_index_t fromECLIndex(CONST STRING16 eclIdx)

Converts an ECL Index to a h3Index.

ECLIndexResolution

h3_resolution_t ECLIndexResolution(CONST STRING16 eclIdx)

Returns the resolution of the eclIdx. This is equivilant to: LENGTH(TRIM(eclIdx)) - 1

ECLIndexParent

STRING16 ECLIndexParent(CONST STRING16 eclIdx, CONST h3_resolution_t resolution)

Returns the parent (coarser) index containing eclIdx at resolution resolution. This is equivilant to eclIdx[1..resolution + 1]