latLngToCell(g::LatLng, res::Int)::H3Index

find the H3 index of the resolution res cell containing the lat/lng

cellToLatLng(h::H3Index)::LatLng

find the lat/lng center point g of the cell h3

cellToBoundary(h::H3Index)::Vector{LatLng}

Determines the cell boundary in spherical coordinates for an H3 index.

@param h3 The H3 index. @param cb The boundary of the H3 cell in spherical coordinates.

getResolution(h::H3Index)::Cint

returns the resolution of the provided H3 index Works on both cells and directed edges.

getBaseCellNumber(h::H3Index)::Cint

returns the base cell "number" (0 to 121) of the provided H3 cell

Note: Technically works on H3 edges, but will return base cell of the origin cell.

stringToH3(str::String)::H3Index

Converts the string representation to H3Index (UInt64) representation.

h3ToString(h::H3Index)::String

Converts the H3Index representation of the index to the string representation.

isValidCell(h::H3Index)::Bool

confirms if an H3Index is a valid cell (hexagon or pentagon) In particular, returns 0 (False) for H3 directed edges or invalid data

isResClassIII(h::H3Index)::Bool

determines if a hexagon is Class III (or Class II)

isPentagon(h::H3Index)::Bool

determines if an H3 cell is a pentagon

gridDisk(origin::H3Index, k::Int)::Vector{H3Index}

Produce cells within grid distance k of the origin cell.

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

Output is placed in the provided array in no particular order. Elements of the output array may be left zero, as can happen when crossing a pentagon.

@param origin origin cell @param k k >= 0 @param out zero-filled array which must be of size maxGridDiskSize(k)

maxGridDiskSize(k::Int)::Int64

Maximum number of cells that result from the gridDisk algorithm with the given k. Formula source and proof: https://oeis.org/A003215

@param k k value, k >= 0. @param out size in indexes

gridDiskDistances(origin::H3Index, k::Int)::NamedTuple{(:out, :distances)}

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

gridDiskUnsafe(origin::H3Index, k::Int)::Vector{H3Index}

gridDiskUnsafe produces indexes within k distance of the origin index. Output behavior is undefined when one of the indexes returned by this function is a pentagon or is in the pentagon distortion area.

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

Output is placed in the provided array in order of increasing distance from the origin.

@param origin Origin location. @param k k >= 0 @param out Array which must be of size maxGridDiskSize(k). @return 0 if no pentagon or pentagonal distortion area was encountered.

gridDiskDistancesUnsafe(origin::H3Index, k::Int)::NamedTuple{(:out, :distances)}

hexRange produces indexes within k distance of the origin index.

gridDisksUnsafe(h3Set::Vector{H3Index}, k::Int)::Vector{H3Index}

gridDisksUnsafe takes an array of input hex IDs and a max k-ring and returns an array of hexagon IDs sorted first by the original hex IDs and then by the k-ring (0 to max), with no guaranteed sorting within each k-ring group.

@param h3Set A pointer to an array of H3Indexes @param length The total number of H3Indexes in h3Set @param k The number of rings to generate @param out A pointer to the output memory to dump the new set of H3Indexes to The memory block should be equal to maxGridDiskSize(k) * length @return 0 if no pentagon is encountered. Cannot trust output otherwise

gridRingUnsafe(origin::H3Index, k::Int)::Vector{H3Index}

Returns the "hollow" ring of hexagons at exactly grid distance k from the origin hexagon. In particular, k=0 returns just the origin hexagon.

A nonzero failure code may be returned in some cases, for example, if a pentagon is encountered. Failure cases may be fixed in future versions.

@param origin Origin location. @param k k >= 0 @param out Array which must be of size 6 * k (or 1 if k == 0) @return 0 if successful; nonzero otherwise.

gridPathCells(origin::H3Index, destination::H3Index)::Vector{H3Index}

Given two H3 indexes, return the line of indexes between them (inclusive).

This function may fail to find the line between two indexes, for example if they are very far apart. It may also fail when finding distances for indexes on opposite sides of a pentagon.

Notes:

• The specific output of this function should not be considered stable across library versions. The only guarantees the library provides are that the line length will be gridDistance(start, end) + 1 and that every index in the line will be a neighbor of the preceding index.
• Lines are drawn in grid space, and may not correspond exactly to either Cartesian lines or great arcs.

@param start Start index of the line @param end End index of the line @param out Output array, which must be of size gridPathCellsSize(start, end) @return 0 on success, or another value on failure.

gridPathCellsSize(origin::H3Index, destination::H3Index)::Int64

Number of indexes in a line from the start index to the end index, to be used for allocating memory. Returns a negative number if the line cannot be computed.

@param start Start index of the line @param end End index of the line @param size Size of the line @returns 0 on success, or another value on error

gridDistance(origin::H3Index, h::H3Index)::Int64

Produces the grid distance between the two indexes.

This function may fail to find the distance between two indexes, for example if they are very far apart. It may also fail when finding distances for indexes on opposite sides of a pentagon.

@param origin Index to find the distance from. @param index Index to find the distance to. @return The distance, or a negative number if the library could not compute the distance.

cellToLocalIj(origin::H3Index, h::H3Index)::CoordIJ

Produces ij coordinates for an index anchored by an origin.

The coordinate space used by this function may have deleted regions or warping due to pentagonal distortion.

Coordinates are only comparable if they come from the same origin index.

Failure may occur if the index is too far away from the origin or if the index is on the other side of a pentagon.

This function's output is not guaranteed to be compatible across different versions of H3.

@param origin An anchoring index for the ij coordinate system. @param index Index to find the coordinates of @param mode Mode, must be 0 @param out ij coordinates of the index will be placed here on success @return 0 on success, or another value on failure.

localIjToCell(origin::H3Index, ij::CoordIJ)::H3Index

Produces an index for ij coordinates anchored by an origin.

The coordinate space used by this function may have deleted regions or warping due to pentagonal distortion.

Failure may occur if the index is too far away from the origin or if the index is on the other side of a pentagon.

This function's output is not guaranteed to be compatible across different versions of H3.

@param origin An anchoring index for the ij coordinate system. @param out ij coordinates to index. @param mode Mode, must be 0 @param index Index will be placed here on success. @return 0 on success, or another value on failure.

cellToParent(h::H3Index, parentRes::Int)::H3Index

cellToParent produces the parent index for a given H3 index

@param h H3Index to find parent of @param parentRes The resolution to switch to (parent, grandparent, etc)

@return H3Index of the parent, or H3_NULL if you actually asked for a child

cellToChildren(h::H3Index, childRes::Int)::Vector{H3Index}

provides the children (or grandchildren, etc) of the given cell

cellToChildrenSize(h::H3Index, childRes::Int)::Int

determines the exact number of children (or grandchildren, etc) that would be returned for the given cell

compactCells(h3Set::Vector{H3Index})::Vector{H3Index}

compacts the given set of hexagons as best as possible

uncompactCells(compactedSet::Vector{H3Index}, res::Int)::Vector{H3Index}

uncompacts the compacted hexagon set

uncompactCellsSize(compactedSet::Vector{H3Index}, res::Int)::Int64

determines the exact number of hexagons that will be uncompacted from the compacted set

areNeighborCells(origin::H3Index, destination::H3Index)::Bool

Returns whether or not the provided H3Indexes are neighbors. @param origin The origin H3 index. @param destination The destination H3 index. @param out Set to 1 if the indexes are neighbors, 0 otherwise @return Error code if the origin or destination are invalid or incomparable.

cellsToDirectedEdge(origin::H3Index, destination::H3Index)::H3Index

Returns a directed edge H3 index based on the provided origin and destination @param origin The origin H3 hexagon index @param destination The destination H3 hexagon index @return The directed edge H3Index, or H3_NULL on failure.

isValidDirectedEdge(edge::H3Index)::Bool

returns whether the H3Index is a valid directed edge

getDirectedEdgeOrigin(edge::H3Index)::H3Index

Returns the origin hexagon from the directed edge H3Index @param edge The edge H3 index @return The origin H3 hexagon index, or H3_NULL on failure

getDirectedEdgeDestination(edge::H3Index)::H3Index

Returns the destination hexagon from the directed edge H3Index @param edge The edge H3 index @return The destination H3 hexagon index, or H3_NULL on failure

directedEdgeToCells(edge::H3Index)::Tuple{H3Index, H3Index}

Returns the origin, destination pair of hexagon IDs for the given edge ID @param edge The directed edge H3Index @param originDestination Pointer to memory to store origin and destination IDs

originToDirectedEdges(origin::H3Index)::Vector{H3Index}

Provides all of the directed edges from the current H3Index. @param origin The origin hexagon H3Index to find edges for. @param edges The memory to store all of the edges inside.

directedEdgeToBoundary(edge::H3Index)::Vector{LatLng}

Provides the coordinates defining the directed edge. @param edge The directed edge H3Index @param cb The cellboundary object to store the edge coordinates.

hexAreaKm2(res::Int)::Cdouble

Average hexagon area in square kilometers at the given resolution.

hexAreaM2(res::Int)::Cdouble

Average hexagon area in square meters at the given resolution.

edgeLengthKm(res::Int)::Cdouble

Average hexagon edge length in kilometers at the given resolution.

edgeLengthM(res::Int)::Cdouble

Average hexagon edge length in meters at the given resolution.

getNumCells(res::Int)::Int64

number of cells (hexagons and pentagons) for a given resolution

It works out to be 2 + 120*7^r for resolution r.

Mathematical notes

Let h(n) be the number of children n levels below a single hexagon.

Then h(n) = 7^n.

Let p(n) be the number of children n levels below a single pentagon.

Then p(0) = 1, and p(1) = 6, since each pentagon has 5 hexagonal immediate children and 1 pentagonal immediate child.

In general, we have the recurrence relation

p(n) = 5h(n-1) + p(n-1) = 57^(n-1) + p(n-1).

Working through the recurrence, we get that

p(n) = 1 + 5\sum_{k=1}^n 7^{k-1} = 1 + 5(7^n - 1)/6,

using the closed form for a geometric series.

Using the closed forms for h(n) and p(n), we can get a closed form for the total number of cells at resolution r:

c(r) = 12p(r) + 110h(r) = 2 + 120*7^r.

@param res H3 cell resolution

@return number of cells at resolution res

getRes0Cells()::Vector{H3Index}

All the resolution 0 H3 indexes.

res0CellCount()::Cint

returns the number of resolution 0 cells (hexagons and pentagons)

ijToIjk(c::CoordIJ)::CoordIJK

Transforms coordinates from the IJ coordinate system to the IJK+ coordinate system.

ijkToHex2d(c::CoordIJK)::Vec2d

Find the center point in 2D cartesian coordinates of a hex.

ijkToIj(c::CoordIJK)::CoordIJ

Transforms coordinates from the IJK+ coordinate system to the IJ coordinate system.

ijkDistance(c1::CoordIJK, c2::CoordIJK)::Int

Finds the distance between the two coordinates. Returns result.

ijkNormalize(c::CoordIJK)::CoordIJK

Normalizes ijk coordinates by setting the components to the smallest possible values. Works in place.

cellToLocalIjk(origin::H3Index, h3::H3Index)::CoordIJK

Produces ijk+ coordinates for an index anchored by an origin.

The coordinate space used by this function may have deleted regions or warping due to pentagonal distortion.

Coordinates are only comparable if they come from the same origin index.

Failure may occur if the index is too far away from the origin or if the index is on the other side of a pentagon.

@param origin An anchoring index for the ijk+ coordinate system. @param index Index to find the coordinates of @param out ijk+ coordinates of the index will be placed here on success @return 0 on success, or another value on failure.

h3ToFaceIjk(h::H3Index)::FaceIJK

Convert an H3Index to a FaceIJK address.

localIjkToCell(origin::H3Index, ijk::CoordIJK)::H3Index

Produces an index for ijk+ coordinates anchored by an origin.

The coordinate space used by this function may have deleted regions or warping due to pentagonal distortion.

Failure may occur if the coordinates are too far away from the origin or if the index is on the other side of a pentagon.

@param origin An anchoring index for the ijk+ coordinate system. @param ijk IJK+ Coordinates to find the index of @param out The index will be placed here on success @return 0 on success, or another value on failure.

faceIjkToH3(faceijk::FaceIJK, res::Int)::H3Index

Convert an FaceIJK address to the corresponding H3Index.

hex2dToCoordIJK(v::Vec2d)::CoordIJK

Determine the containing hex in ijk+ coordinates for a 2D cartesian coordinate vector (from DGGRID).

geoToVec3d(geo::LatLng)::Vec3d

Calculate the 3D coordinate on unit sphere from the latitude and longitude.

geoToFaceIjk(geo::LatLng, res::Int)::FaceIJK

Encodes a coordinate on the sphere to the FaceIJK address of the containing cell at the specified resolution.