Table of Contents

Overview

Core Library

API Reference

The **H3 Core Library** uses the following coordinate systems internally.

Discrete hexagon planar grid systems naturally have 3 coordinate axes spaced 120° apart. We refer to such a system as an *ijk coordinate system*, for the three coordinate axes *i*, *j*, and *k*. A single *ijk* coordinate triplet is represented in the **H3 Core Library** using the structure type `CoordIJK`

.

Using an *ijk* coordinate system to address hexagon grid cells provides multiple valid addresses for each cell. *Normalizing* an *ijk* address (function `_ijkNormalize`

) creates a unique address consisting of the minimal positive *ijk* components; this always results in at most two non-zero components.

The **H3 Core Library** centers an *ijk* coordinate system on each face of the icosahedron; the combination of a face number and *ijk* coordinates on that face's coordinate system is represented using the structure type `FaceIJK`

.

Each grid resolution is rotated ~19.1° relative to the next coarser resolution. The rotation alternates between counterclockwise and clockwise at each successive resolution, so that each resolution will have one of two possible orientations: *Class II* or *Class III* (using a terminology coined by R. Buckminster Fuller). The base cells, which make up resolution 0, are *Class II*.

A *Hex2d* coordinate system is a cartesian coordinate system associated with a specific *ijk* coordinate system, where:

- the origin of the
*Hex2d*system is centered on the origin cell of the*ijk*system, - the positive
*x*-axis of the*Hex2d*system is aligned with the*i*-axis of the*ijk*system, and - 1.0 unit distance in the
*Hex2d*system is the distance between adjacent cell centers in the*ijk*coordinate system.

*Hex2d* coordinates are represented using the structure type `Vec2d`

.

Algorithms working with hexagons may want to refer to grid coordinates that are not interrupted by base cells or faces. These coordinates have 2 coordinate axes spaced 120° apart, with the coordinates anchored by an *origin* H3 index.

- local coordinates are only comparable when they have the same
*origin*index. - local coordinates are only valid near the
*origin*. Pratically, this is within the same base cell or a neighboring base cell, except for pentagons. - the coordinate space may have deleted or warped regions due to pentagon distortion.
- there may be multiple coordinates for the same index, with the same
*origin*. - the
*origin*may not be at`(0, 0)`

in the local coordinate space.

*Local IJ* coordinates are represented using the structure type `CoordIJ`

and an associated *origin* `H3Index`

.