H3

H3 is a Hexagonal hierarchical geospatial indexing system.

This system divides the surface of the Earth into 12 pentagons and n hexagons. The number of n depends on the resolution.

The centers of each cell have the same distance to the centers of the adjacent cells which makes H3 suitable for modelling movements through the grid.

H3 uses the dymaxion orientation which means that all centers of the 12 pentagons are located in water.

The DGGS that underlies H3 is based on an aperture 7 hexagonal tessalation of the icosahedron.

The github repository is here.

Resolutions

There are 16 possible resolutions which vary from 0 (110 hexagons of approx 4,3 million km²) to 15 (Approx 569 trillions (10¹²) hexagons of approx 0,895 m²), see cell statistics.

Sometimes, the buzz about H3 gives the impression that a resolution's cell size is constant. But that's not true!, see this computation and Average cell area statistics.

Apparently, this distortion is caused by the Gnomonic projection which preserves shapes well but incurs significant distortions of areas (described in Comparing Geometrical Properties of Global Grids?)

This gis.stackexchange answer was very helpful in that regard:

H3 is based round an icosahedron that touches the earth sphere at a small number of places. This icosahedron has flat sides. These flat sides are divided into hexagons of equal size and so equal area. But when these hexagons are projected onto the sphere, they'll have different sizes and areas because the face of the icosahedron meets the sphere at different angles.

Not a strict hierarchy

Child hexagons are not strictly inside their parent hexagon, i. e. a certain set of areas is outside of that of the parent.

Pentagons / distortion vertices.

Some «hexagons» are pentagons.

Pentagons have a maximum number of 10 cell boundary vertices (MAX_CELL_BNDRY_VERTS).

Library API

Some interesting functions, structs and consts (defines) found in the H3 library:

H3Index

H3Index is a typedef for uint64_t (?? and identifies a H3 cell on the sphere ??).

A H3Index can be obtained from a latitude/longitude pair by calling latLngToCell.

All 64 bits of this type are used.

An invalid index is indicated with H3_NULL (analogous to NaN for floating points).

A h3Index stores the resolution in 4 bits (hence the possible 16 resolutions) in bits 63 through 60.

LatLng

A LatLng struct stores the latitude and longitude in (not so familiar) radians.

latLngToCell

H3Error latLngToCell(const LatLng *g, int res, H3Index *out) returns the H3 index of a given resulution in which the given coordinate is located.

latLngToCell is implemented in h3Index.c.

TODO: Compare to cellToLatLng.

h3ToString

h3Tostring(H3Index h, char *str, size_t sz) returns a zero terminated hexadecimal representation (i. e. sprintf(str, "%" PRIx64, h)) of the H3Index.

Because the index is 64 bit, the allocated size of buffer (str) needs to be at least 17 bytes (16 bytes for the representation and 1 byte for the terminating 0).

H3Error

H3Error is the uint32_t which is returned from a H3 function.

The following codes are available:

`E_SUCCESS`	0	Success (no error)
`E_FAILED`	1	The operation failed but a more specific error is not available
`E_DOMAIN`	2	Argument was outside of acceptable range (when a more specific error code is not available)
`E_LATLNG_DOMAIN`	3	Latitude or longitude arguments were outside of acceptable range
`E_RES_DOMAIN`	4	Resolution argument was outside of acceptable range
`E_CELL_INVALID`	5	`H3Index` cell argument was not valid
`E_DIR_EDGE_INVALID`	6	`H3Index` directed edge argument was not valid
`E_UNDIR_EDGE_INVALID`	7	`H3Index` undirected edge argument was not valid
`E_VERTEX_INVALID`	8	`H3Index` vertex argument was not valid
`E_PENTAGON`	9	Pentagon distortion was encountered which the algorithm could not handle it
`E_DUPLICATE_INPUT`	10	Duplicate input was encountered in the arguments and the algorithm could not handle it
`E_NOT_NEIGHBORS`	11	`H3Index` cell arguments were not neighbors
`E_RES_MISMATCH`	12	`H3Index` cell arguments had incompatible resolutions
`E_MEMORY_ALLOC`	13	Necessary memory allocation failed
`E_MEMORY_BOUNDS`	14	Bounds of provided memory were not large enough
`E_OPTION_INVALID`	15	Mode or flags argument was not valid.