h3Index.hpp File Reference

#include "QueryEngine/ExtensionFunctions/h3lib/include/h3Index.h"
#include "QueryEngine/ExtensionFunctions/h3lib/include/baseCells.h"

Include dependency graph for h3Index.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
EXTENSION_NOINLINE H3Index H3_EXPORT()	h3ToParent (H3Index h, int parentRes)
	returns the parent (or grandparent, etc) hexagon of the given hexagon More...
EXTENSION_INLINE int	_h3LeadingNonZeroDigit (H3Index h)
EXTENSION_NOINLINE H3Index	_h3RotatePent60ccw (H3Index h)
EXTENSION_NOINLINE H3Index	_h3RotatePent60cw (H3Index h)
EXTENSION_NOINLINE H3Index	_h3Rotate60ccw (H3Index h)
EXTENSION_NOINLINE H3Index	_h3Rotate60cw (H3Index h)
EXTENSION_NOINLINE H3Index	_faceIjkToH3 (const FaceIJK(fijk), int res)
EXTENSION_NOINLINE H3Index H3_EXPORT()	geoToH3 (const double lon, const double lat, int res)
	find the H3 index of the resolution res cell containing the lat/lng More...
EXTENSION_NOINLINE int	_h3ToFaceIjkWithInitializedFijk (H3Index h, FaceIJK(fijk))
EXTENSION_NOINLINE bool	_h3ToFaceIjk (H3Index h, FaceIJK(fijk))
EXTENSION_NOINLINE bool	_h3ToGeo (H3Index h3, GeoCoord(g))
EXTENSION_NOINLINE int64_t H3_EXPORT()	h3ToGeoPacked (H3Index h3)
	find the lat/lon center point g of the cell h3 More...
EXTENSION_NOINLINE double H3_EXPORT()	h3ToLon (H3Index h3)
EXTENSION_NOINLINE double H3_EXPORT()	h3ToLat (H3Index h3)

Function Documentation

EXTENSION_NOINLINE H3Index _faceIjkToH3	(	const	FaceIJKfijk,
		int	res
	)

Convert an FaceIJK address to the corresponding H3Index.

Parameters

fijk	The FaceIJK address.
res	The cell resolution.

Returns

The encoded H3Index (or H3_NULL on failure).

Definition at line 643 of file h3Index.hpp.

References _baseCellIsCwOffset(), _downAp7(), _downAp7r(), _faceIjkToBaseCell(), _faceIjkToBaseCellCCWrot60(), _h3LeadingNonZeroDigit(), _h3Rotate60ccw(), _h3Rotate60cw(), _h3RotatePent60ccw(), _ijkNormalize(), _ijkSub(), _isBaseCellPentagon(), _unitIjkToDigit(), _upAp7(), _upAp7r(), CoordIJK, CoordIJK_clone, CoordIJK_copy, CoordIJK_ptr, FACE_INDEX, FaceIJK, FaceIJK_clone, H3_HEXAGON_MODE, H3_INIT, H3_NULL, H3_SET_BASE_CELL, H3_SET_INDEX_DIGIT, H3_SET_MODE, H3_SET_RESOLUTION, H3Index, I_INDEX, isResClassIII(), J_INDEX, K_AXES_DIGIT, K_INDEX, and MAX_FACE_COORD.

Referenced by geoToH3().

                                                                      {
  // initialize the index
  H3Index h = H3_INIT;
  H3_SET_MODE(h, H3_HEXAGON_MODE);
  H3_SET_RESOLUTION(h, res);

  // check for res 0/base cell
  if (res == 0) {
    if (fijk[I_INDEX] > MAX_FACE_COORD || fijk[J_INDEX] > MAX_FACE_COORD ||
        fijk[K_INDEX] > MAX_FACE_COORD) {
      // out of range input
      return H3_NULL;
    }

    H3_SET_BASE_CELL(h, _faceIjkToBaseCell(fijk));
    return h;
  }

  // we need to find the correct base cell FaceIJK for this H3 index;
  // start with the passed in face and resolution res ijk coordinates
  // in that face's coordinate system
  FaceIJK(fijkBC) = FaceIJK_clone(fijk);

  // build the H3Index from finest res up
  // adjust r for the fact that the res 0 base cell offsets the indexing
  // digits
  CoordIJK_ptr(ijk) = fijkBC;
  for (int r = res - 1; r >= 0; r--) {
    CoordIJK(lastIJK) = CoordIJK_clone(ijk);
    CoordIJK(lastCenter);
    if (isResClassIII(r + 1)) {
      // rotate ccw
      _upAp7(ijk);
      CoordIJK_copy(lastCenter, ijk);
      _downAp7(lastCenter);
    } else {
      // rotate cw
      _upAp7r(ijk);
      CoordIJK_copy(lastCenter, ijk);
      _downAp7r(lastCenter);
    }

    CoordIJK(diff);
    _ijkSub(lastIJK, lastCenter, diff);
    _ijkNormalize(diff);

    H3_SET_INDEX_DIGIT(h, r + 1, _unitIjkToDigit(diff));
  }

  // fijkBC should now hold the IJK of the base cell in the
  // coordinate system of the current face

  if (fijkBC[I_INDEX] > MAX_FACE_COORD || fijkBC[J_INDEX] > MAX_FACE_COORD ||
      fijkBC[K_INDEX] > MAX_FACE_COORD) {
    // out of range input
    return H3_NULL;
  }

  // lookup the correct base cell
  int baseCell = _faceIjkToBaseCell(fijkBC);
  H3_SET_BASE_CELL(h, baseCell);

  // rotate if necessary to get canonical base cell orientation
  // for this base cell
  int numRots = _faceIjkToBaseCellCCWrot60(fijkBC);
  if (_isBaseCellPentagon(baseCell)) {
    // force rotation out of missing k-axes sub-sequence
    if (_h3LeadingNonZeroDigit(h) == K_AXES_DIGIT) {
      // check for a cw/ccw offset face; default is ccw
      if (_baseCellIsCwOffset(baseCell, fijkBC[FACE_INDEX])) {
        h = _h3Rotate60cw(h);
      } else {
        h = _h3Rotate60ccw(h);
      }
    }

    for (int i = 0; i < numRots; i++)
      h = _h3RotatePent60ccw(h);
  } else {
    for (int i = 0; i < numRots; i++) {
      h = _h3Rotate60ccw(h);
    }
  }

  return h;
}

Here is the call graph for this function:

Here is the caller graph for this function:

EXTENSION_INLINE int _h3LeadingNonZeroDigit

(

H3Index

h

)

Determines whether one resolution is a valid child resolution of another. Each resolution is considered a valid child resolution of itself.

Parameters

parentRes	int resolution of the parent
childRes	int resolution of the child

Returns

The validity of the child resolution maxH3ToChildrenSize returns the maximum number of children possible for a given child level.

Parameters

h	H3Index to find the number of children of
childRes	The resolution of the child level you're interested in

Returns

int count of maximum number of children (equal for hexagons, less for pentagons makeDirectChild takes an index and immediately returns the immediate child index based on the specified cell number. Bit operations only, could generate invalid indexes if not careful (deleted cell under a pentagon).

Parameters

h	H3Index to find the direct child of
cellNumber	int id of the direct child (0-6)

Returns

The new H3Index for the child h3ToChildren takes the given hexagon id and generates all of the children at the specified resolution storing them into the provided memory pointer. It's assumed that maxH3ToChildrenSize was used to determine the allocation.

Parameters

h	H3Index to find the children of
childRes	int the child level to produce
children	H3Index* the memory to store the resulting addresses in h3ToCenterChild produces the center child index for a given H3 index at the specified resolution
h	H3Index to find center child of
childRes	The resolution to switch to

Returns

H3Index of the center child, or H3_NULL if you actually asked for a parent compact takes a set of hexagons all at the same resolution and compresses them by pruning full child branches to the parent level. This is also done for all parents recursively to get the minimum number of hex addresses that perfectly cover the defined space.

Parameters

h3Set	Set of hexagons
compactedSet	The output array of compressed hexagons (preallocated)
numHexes	The size of the input and output arrays (possible that no contiguous regions exist in the set at all and no compression possible)

Returns

an error code on bad input data uncompact takes a compressed set of hexagons and expands back to the original set of hexagons.

Parameters

compactedSet	Set of hexagons
numHexes	The number of hexes in the input set
h3Set	Output array of decompressed hexagons (preallocated)
maxHexes	The size of the output array to bound check against
res	The hexagon resolution to decompress to

Returns

An error code if output array is too small or any hexagon is smaller than the output resolution. maxUncompactSize takes a compacted set of hexagons are provides an upper-bound estimate of the size of the uncompacted set of hexagons.

Parameters

compactedSet	Set of hexagons
numHexes	The number of hexes in the input set
res	The hexagon resolution to decompress to

Returns

The number of hexagons to allocate memory for, or a negative number if an error occurs. h3IsResClassIII takes a hexagon ID and determines if it is in a Class III resolution (rotated versus the icosahedron and subject to shape distortion adding extra points on icosahedron edges, making them not true hexagons).

Parameters

h	The H3Index to check.

Returns

Returns 1 if the hexagon is class III, otherwise 0. h3IsPentagon takes an H3Index and determines if it is actually a pentagon.

Parameters

h	The H3Index to check.

Returns

Returns 1 if it is a pentagon, otherwise 0. Returns the highest resolution non-zero digit in an H3Index.

Parameters

h	The H3Index.

Returns

The highest resolution non-zero digit in the H3Index.

Definition at line 551 of file h3Index.hpp.

References CENTER_DIGIT, H3_GET_INDEX_DIGIT, and H3_GET_RESOLUTION.

Referenced by _faceIjkToH3(), _h3RotatePent60ccw(), _h3RotatePent60cw(), and _h3ToFaceIjk().

                                                       {
  for (int r = 1; r <= H3_GET_RESOLUTION(h); r++)
    if (H3_GET_INDEX_DIGIT(h, r))
      return H3_GET_INDEX_DIGIT(h, r);

  // if we're here it's all 0's
  return CENTER_DIGIT;
}

Here is the caller graph for this function:

EXTENSION_NOINLINE H3Index _h3Rotate60ccw

(

H3Index

h

)

Rotate an H3Index 60 degrees counter-clockwise.

Parameters

h	The H3Index.

Definition at line 616 of file h3Index.hpp.

References _rotate60ccw(), H3_GET_INDEX_DIGIT, H3_GET_RESOLUTION, H3_SET_INDEX_DIGIT, and run_benchmark_import::res.

Referenced by _faceIjkToH3(), and _h3RotatePent60ccw().

                                                     {
  for (int r = 1, res = H3_GET_RESOLUTION(h); r <= res; r++) {
    Direction oldDigit = H3_GET_INDEX_DIGIT(h, r);
    H3_SET_INDEX_DIGIT(h, r, _rotate60ccw(oldDigit));
  }

  return h;
}

Here is the call graph for this function:

Here is the caller graph for this function:

EXTENSION_NOINLINE H3Index _h3Rotate60cw

(

H3Index

h

)

Rotate an H3Index 60 degrees clockwise.

Parameters

h	The H3Index.

Definition at line 629 of file h3Index.hpp.

References _rotate60cw(), H3_GET_INDEX_DIGIT, H3_GET_RESOLUTION, H3_SET_INDEX_DIGIT, and run_benchmark_import::res.

Referenced by _faceIjkToH3(), _h3RotatePent60cw(), and _h3ToFaceIjk().

                                                    {
  for (int r = 1, res = H3_GET_RESOLUTION(h); r <= res; r++) {
    H3_SET_INDEX_DIGIT(h, r, _rotate60cw(H3_GET_INDEX_DIGIT(h, r)));
  }

  return h;
}

Here is the call graph for this function:

Here is the caller graph for this function:

EXTENSION_NOINLINE H3Index _h3RotatePent60ccw

(

H3Index

h

)

Rotate an H3Index 60 degrees counter-clockwise about a pentagonal center.

Parameters

h	The H3Index.

Definition at line 564 of file h3Index.hpp.

References _h3LeadingNonZeroDigit(), _h3Rotate60ccw(), _rotate60ccw(), H3_GET_INDEX_DIGIT, H3_GET_RESOLUTION, H3_SET_INDEX_DIGIT, K_AXES_DIGIT, and run_benchmark_import::res.

Referenced by _faceIjkToH3().

                                                         {
  // rotate in place; skips any leading 1 digits (k-axis)

  int foundFirstNonZeroDigit = 0;
  for (int r = 1, res = H3_GET_RESOLUTION(h); r <= res; r++) {
    // rotate this digit
    H3_SET_INDEX_DIGIT(h, r, _rotate60ccw(H3_GET_INDEX_DIGIT(h, r)));

    // look for the first non-zero digit so we
    // can adjust for deleted k-axes sequence
    // if necessary
    if (!foundFirstNonZeroDigit && H3_GET_INDEX_DIGIT(h, r) != 0) {
      foundFirstNonZeroDigit = 1;

      // adjust for deleted k-axes sequence
      if (_h3LeadingNonZeroDigit(h) == K_AXES_DIGIT)
        h = _h3Rotate60ccw(h);
    }
  }
  return h;
}

Here is the call graph for this function:

Here is the caller graph for this function:

EXTENSION_NOINLINE H3Index _h3RotatePent60cw

(

H3Index

h

)

Rotate an H3Index 60 degrees clockwise about a pentagonal center.

Parameters

h	The H3Index.

Definition at line 590 of file h3Index.hpp.

References _h3LeadingNonZeroDigit(), _h3Rotate60cw(), _rotate60cw(), H3_GET_INDEX_DIGIT, H3_GET_RESOLUTION, H3_SET_INDEX_DIGIT, K_AXES_DIGIT, and run_benchmark_import::res.

                                                        {
  // rotate in place; skips any leading 1 digits (k-axis)

  int foundFirstNonZeroDigit = 0;
  for (int r = 1, res = H3_GET_RESOLUTION(h); r <= res; r++) {
    // rotate this digit
    H3_SET_INDEX_DIGIT(h, r, _rotate60cw(H3_GET_INDEX_DIGIT(h, r)));

    // look for the first non-zero digit so we
    // can adjust for deleted k-axes sequence
    // if necessary
    if (!foundFirstNonZeroDigit && H3_GET_INDEX_DIGIT(h, r) != 0) {
      foundFirstNonZeroDigit = 1;

      // adjust for deleted k-axes sequence
      if (_h3LeadingNonZeroDigit(h) == K_AXES_DIGIT)
        h = _h3Rotate60cw(h);
    }
  }
  return h;
}

Here is the call graph for this function:

EXTENSION_NOINLINE bool _h3ToFaceIjk	(	H3Index	h,
		FaceIJK(fijk)
	)

Convert an H3Index to a FaceIJK address.

Parameters

h	The H3Index.
fijk	The corresponding FaceIJK address.

Definition at line 783 of file h3Index.hpp.

References _adjustOverageClassII(), _downAp7r(), _h3LeadingNonZeroDigit(), _h3Rotate60cw(), _h3ToFaceIjkWithInitializedFijk(), _isBaseCellPentagon(), _upAp7r(), baseCellData, CoordIJK, CoordIJK_clone, CoordIJK_copy, FaceIJK_copy, H3_GET_BASE_CELL, H3_GET_RESOLUTION, isResClassIII(), NO_OVERAGE, and run_benchmark_import::res.

Referenced by _h3ToGeo().

                                                               {
  int baseCell = H3_GET_BASE_CELL(h);
  // adjust for the pentagonal missing sequence; all of sub-sequence 5 needs
  // to be adjusted (and some of sub-sequence 4 below)
  if (_isBaseCellPentagon(baseCell) && _h3LeadingNonZeroDigit(h) == 5)
    h = _h3Rotate60cw(h);

  // start with the "home" face and ijk+ coordinates for the base cell of c
  FaceIJK_copy(fijk, baseCellData[baseCell].homeFijk);
  if (!_h3ToFaceIjkWithInitializedFijk(h, fijk))
    return true;  // no overage is possible; h lies on this face

  // if we're here we have the potential for an "overage"; i.e., it is
  // possible that c lies on an adjacent face

  CoordIJK(origIJK) = CoordIJK_clone(fijk);

  // if we're in Class III, drop into the next finer Class II grid
  int res = H3_GET_RESOLUTION(h);
  if (isResClassIII(res)) {
    // Class III
    _downAp7r(fijk);
    res++;
  }

  // adjust for overage if needed
  // a pentagon base cell with a leading 4 digit requires special handling
  int pentLeading4 = (_isBaseCellPentagon(baseCell) && _h3LeadingNonZeroDigit(h) == 4);
  if (_adjustOverageClassII(fijk, res, pentLeading4, 0) != NO_OVERAGE) {
    // if the base cell is a pentagon we have the potential for secondary
    // overages
    if (_isBaseCellPentagon(baseCell)) {
      while (_adjustOverageClassII(fijk, res, 0, 0) != NO_OVERAGE)
        continue;
    }

    if (res != H3_GET_RESOLUTION(h))
      _upAp7r(fijk);
  } else if (res != H3_GET_RESOLUTION(h)) {
    CoordIJK_copy(fijk, origIJK);
  }
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

EXTENSION_NOINLINE int _h3ToFaceIjkWithInitializedFijk	(	H3Index	h,
		FaceIJK(fijk)
	)

Convert an H3Index to the FaceIJK address on a specified icosahedral face.

Parameters

h	The H3Index.
fijk	The FaceIJK address, initialized with the desired face and normalized base cell coordinates.

Returns

Returns 1 if the possibility of overage exists, otherwise 0.

Definition at line 753 of file h3Index.hpp.

References _downAp7(), _downAp7r(), _isBaseCellPentagon(), _neighbor(), H3_GET_BASE_CELL, H3_GET_INDEX_DIGIT, H3_GET_RESOLUTION, I_INDEX, isResClassIII(), J_INDEX, K_INDEX, and run_benchmark_import::res.

Referenced by _h3ToFaceIjk().

                                                                                 {
  int* ijk = fijk;
  int res = H3_GET_RESOLUTION(h);

  // center base cell hierarchy is entirely on this face
  int possibleOverage = 1;
  if (!_isBaseCellPentagon(H3_GET_BASE_CELL(h)) &&
      (res == 0 || (fijk[I_INDEX] == 0 && fijk[J_INDEX] == 0 && fijk[K_INDEX] == 0)))
    possibleOverage = 0;

  for (int r = 1; r <= res; r++) {
    if (isResClassIII(r)) {
      // Class III == rotate ccw
      _downAp7(ijk);
    } else {
      // Class II == rotate cw
      _downAp7r(ijk);
    }

    _neighbor(ijk, H3_GET_INDEX_DIGIT(h, r));
  }

  return possibleOverage;
}

Here is the call graph for this function:

Here is the caller graph for this function:

EXTENSION_NOINLINE bool _h3ToGeo	(	H3Index	h3,
		GeoCoord(g)
	)

Determines the spherical coordinates of the center point of an H3 index.

Parameters

h3	The H3 index.
g	The spherical coordinates of the H3 cell center. Note: spherical coordinates are in radians.

Definition at line 834 of file h3Index.hpp.

References _faceIjkToGeo(), _h3ToFaceIjk(), FaceIJK, and H3_GET_RESOLUTION.

Referenced by h3ToGeoPacked(), h3ToLat(), and h3ToLon().

                                                          {
  FaceIJK(fijk);
  _h3ToFaceIjk(h3, fijk);
  _faceIjkToGeo(fijk, H3_GET_RESOLUTION(h3), g);
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function: