faceijk.h File Reference

FaceIJK functions including conversion to/from lat/lon. More...

#include "QueryEngine/ExtensionFunctions/h3lib/include/coordijk.h"
#include "QueryEngine/ExtensionFunctions/h3lib/include/h3api.h"
#include "QueryEngine/ExtensionFunctions/h3lib/include/vec2d.h"
#include "QueryEngine/ExtensionFunctions/h3lib/lib/faceijk.hpp"

Include dependency graph for faceijk.h:

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

Go to the source code of this file.

Macros
#define	FACE_INDEX   3
#define	FaceIJK(variable_name)   int variable_name[4]
#define	FaceIJK_clone(fijk)   { fijk[I_INDEX], fijk[J_INDEX], fijk[K_INDEX], fijk[FACE_INDEX] }
#define	FaceIJK_copy(dest_ijk, src_ijk)
#define	CCWROT_60_INDEX   4
#define	FaceOrientIJK(variable_name)   int variable_name[5]
#define	FaceOrientIJK2DArray(variable_name, size1, size2)   int variable_name[size1][size2][5]
#define	IJ   1
#define	KI   2
#define	JK   3

Enumerations
enum	Overage { NO_OVERAGE = 0, FACE_EDGE = 1, NEW_FACE = 2 }

Functions
EXTENSION_INLINE int	isResClassIII (int res)
EXTENSION_NOINLINE bool	_geoToFaceIjk (const GeoCoord(g), int res, FaceIJK(h))
EXTENSION_NOINLINE bool	_geoToHex2d (const GeoCoord(g), int res, int *face, Vec2d(v))
EXTENSION_NOINLINE bool	_faceIjkToGeo (const FaceIJK(h), int res, GeoCoord(g))
EXTENSION_NOINLINE bool	_hex2dToGeo (const Vec2d(v), int face, int res, int substrate, GeoCoord(g))
EXTENSION_NOINLINE int	_adjustOverageClassII (FaceIJK(fijk), int res, int pentLeading4, int substrate)

Detailed Description

FaceIJK functions including conversion to/from lat/lon.

References the Vec2d cartesian coordinate systems hex2d: local face-centered coordinate system scaled a specific H3 grid resolution unit length and with x-axes aligned with the local i-axes

Definition in file faceijk.h.

Macro Definition Documentation

#define CCWROT_60_INDEX   4

Definition at line 53 of file faceijk.h.

Referenced by _adjustOverageClassII().

#define FACE_INDEX   3

Definition at line 35 of file faceijk.h.

Referenced by _adjustOverageClassII(), _faceIjkToBaseCell(), _faceIjkToBaseCellCCWrot60(), _faceIjkToGeo(), _faceIjkToH3(), and _geoToFaceIjk().

#define FaceIJK

(

variable_name

)

int variable_name[4]

Definition at line 36 of file faceijk.h.

Referenced by _faceIjkToH3(), _h3ToGeo(), and geoToH3().

#define FaceIJK_clone

(

fijk

)

{ fijk[I_INDEX], fijk[J_INDEX], fijk[K_INDEX], fijk[FACE_INDEX] }

Definition at line 37 of file faceijk.h.

Referenced by _faceIjkToH3().

#define FaceIJK_copy	(		dest_ijk,
			src_ijk
	)

Value:

dest_ijk[I_INDEX] = src_ijk[I_INDEX]; \
  dest_ijk[J_INDEX] = src_ijk[J_INDEX]; \
  dest_ijk[K_INDEX] = src_ijk[K_INDEX]; \
  dest_ijk[FACE_INDEX] = src_ijk[FACE_INDEX];

Definition at line 39 of file faceijk.h.

Referenced by _h3ToFaceIjk().

#define FaceOrientIJK

(

variable_name

)

int variable_name[5]

Definition at line 54 of file faceijk.h.

#define FaceOrientIJK2DArray	(		variable_name,
			size1,
			size2
	)		int variable_name[size1][size2][5]

Definition at line 55 of file faceijk.h.

#define IJ   1

IJ quadrant faceNeighbors table direction

Definition at line 68 of file faceijk.h.

Referenced by _adjustOverageClassII().

#define JK   3

JK quadrant faceNeighbors table direction

Definition at line 72 of file faceijk.h.

Referenced by _adjustOverageClassII().

#define KI   2

KI quadrant faceNeighbors table direction

Definition at line 70 of file faceijk.h.

Referenced by _adjustOverageClassII().

Enumeration Type Documentation

enum Overage

Invalid face index Digit representing overage type

Enumerator
NO_OVERAGE	No overage (on original face)
FACE_EDGE	On face edge (only occurs on substrate grids)
NEW_FACE	Overage on new face interior

Definition at line 78 of file faceijk.h.

             {
  NO_OVERAGE = 0,
  FACE_EDGE = 1,
  NEW_FACE = 2
} Overage;

Function Documentation

EXTENSION_NOINLINE int _adjustOverageClassII	(	FaceIJK(fijk)	,
		int	res,
		int	pentLeading4,
		int	substrate
	)

Generates the cell boundary in spherical coordinates for a pentagonal cell given by a FaceIJK address at a specified resolution.

Parameters

h	The FaceIJK address of the pentagonal cell.
res	The H3 resolution of the cell.
start	The first topological vertex to return.
length	The number of topological vertexes to return.
g	The spherical coordinates of the cell boundary. Get the vertices of a pentagon cell as substrate FaceIJK addresses
fijk	The FaceIJK address of the cell.
res	The H3 resolution of the cell. This may be adjusted if necessary for the substrate grid resolution.
fijkVerts	Output array for the vertices Generates the cell boundary in spherical coordinates for a cell given by a FaceIJK address at a specified resolution.
h	The FaceIJK address of the cell.
res	The H3 resolution of the cell.
start	The first topological vertex to return.
length	The number of topological vertexes to return.
g	The spherical coordinates of the cell boundary. Get the vertices of a cell as substrate FaceIJK addresses
fijk	The FaceIJK address of the cell.
res	The H3 resolution of the cell. This may be adjusted if necessary for the substrate grid resolution.
fijkVerts	Output array for the vertices Adjusts a FaceIJK address in place so that the resulting cell address is relative to the correct icosahedral face.
fijk	The FaceIJK address of the cell.
res	The H3 resolution of the cell.
pentLeading4	Whether or not the cell is a pentagon with a leading digit 4.
substrate	Whether or not the cell is in a substrate grid.

Returns

0 if on original face (no overage); 1 if on face edge (only occurs on substrate grids); 2 if overage on new face interior

Definition at line 864 of file faceijk.hpp.

References _ijkAdd(), _ijkNormalize(), _ijkRotate60ccw(), _ijkRotate60cw(), _ijkScale(), _ijkSub(), _setIJK(), CCWROT_60_INDEX, CoordIJK, CoordIJK_clone, CoordIJK_ptr, FACE_EDGE, FACE_INDEX, I_INDEX, IJ, J_INDEX, JK, K_INDEX, KI, maxDimByCIIres, NEW_FACE, NO_OVERAGE, run_benchmark_import::res, and unitScaleByCIIres.

Referenced by _h3ToFaceIjk().

                                                            {
  Overage overage = NO_OVERAGE;

  CoordIJK_ptr(ijk) = fijk;

  // get the maximum dimension value; scale if a substrate grid
  int maxDim = maxDimByCIIres[res];
  if (substrate)
    maxDim *= 3;

  // check for overage
  if (substrate && ijk[I_INDEX] + ijk[J_INDEX] + ijk[K_INDEX] == maxDim)  // on edge
    overage = FACE_EDGE;
  else if (ijk[I_INDEX] + ijk[J_INDEX] + ijk[K_INDEX] > maxDim)  // overage
  {
    overage = NEW_FACE;

    const int* fijkOrient;
    if (ijk[K_INDEX] > 0) {
      if (ijk[J_INDEX] > 0)  // jk "quadrant"
        fijkOrient = faceNeighbors[fijk[FACE_INDEX]][JK];
      else  // ik "quadrant"
      {
        fijkOrient = faceNeighbors[fijk[FACE_INDEX]][KI];

        // adjust for the pentagonal missing sequence
        if (pentLeading4) {
          // translate origin to center of pentagon
          CoordIJK(origin);
          _setIJK(origin, maxDim, 0, 0);
          CoordIJK(tmp);
          _ijkSub(ijk, origin, tmp);
          // rotate to adjust for the missing sequence
          _ijkRotate60cw(tmp);
          // translate the origin back to the center of the triangle
          _ijkAdd(tmp, origin, ijk);
        }
      }
    } else  // ij "quadrant"
      fijkOrient = faceNeighbors[fijk[FACE_INDEX]][IJ];

    fijk[FACE_INDEX] = fijkOrient[FACE_INDEX];

    // rotate and translate for adjacent face
    for (int i = 0; i < fijkOrient[CCWROT_60_INDEX]; i++)
      _ijkRotate60ccw(ijk);

    CoordIJK(transVec) = CoordIJK_clone(fijkOrient);
    int unitScale = unitScaleByCIIres[res];
    if (substrate)
      unitScale *= 3;
    _ijkScale(transVec, unitScale);
    _ijkAdd(ijk, transVec, ijk);
    _ijkNormalize(ijk);

    // overage points on pentagon boundaries can end up on edges
    if (substrate && ijk[I_INDEX] + ijk[J_INDEX] + ijk[K_INDEX] == maxDim)  // on edge
      overage = FACE_EDGE;
  }

  return overage;
}

Here is the call graph for this function:

Here is the caller graph for this function:

EXTENSION_NOINLINE bool _faceIjkToGeo	(	const	FaceIJKh,
		int	res,
		GeoCoord(g)
	)

Determines the center point in spherical coordinates of a cell given by a FaceIJK address at a specified resolution.

Parameters

h	The FaceIJK address of the cell.
res	The H3 resolution of the cell.
g	The spherical coordinates of the cell center point.

Definition at line 495 of file faceijk.hpp.

References _hex2dToGeo(), _ijkToHex2d(), FACE_INDEX, and Vec2d.

Referenced by _h3ToGeo().

                                                                              {
  Vec2d(v);
  _ijkToHex2d(h, v);
  _hex2dToGeo(v, h[FACE_INDEX], res, 0, g);
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

EXTENSION_NOINLINE bool _geoToFaceIjk	(	const	GeoCoordg,
		int	res,
		FaceIJK(h)
	)

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

Parameters

g	The spherical coordinates to encode.
res	The desired H3 resolution for the encoding.
h	The FaceIJK address of the containing cell at resolution res.

Definition at line 362 of file faceijk.hpp.

References _geoToHex2d(), _hex2dToCoordIJK(), FACE_INDEX, and Vec2d.

Referenced by geoToH3().

                                                                              {
  // first convert to hex2d
  Vec2d(v);
  _geoToHex2d(g, res, &h[FACE_INDEX], v);

  // then convert to ijk+
  _hex2dToCoordIJK(v, h);

  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

EXTENSION_NOINLINE bool _geoToHex2d	(	const	GeoCoordg,
		int	res,
		int *	face,
		Vec2d(v)
	)

Encodes a coordinate on the sphere to the corresponding icosahedral face and containing 2D hex coordinates relative to that face center.

Parameters

g	The spherical coordinates to encode.
res	The desired H3 resolution for the encoding.
face	The icosahedral face containing the spherical coordinates.
v	The 2D hex coordinates of the cell containing the point.

Definition at line 382 of file faceijk.hpp.

References _geoAzimuthRads(), _geoToVec3d(), _pointSquareDist(), _posAngleRads(), EPSILON, f(), faceAxesAzRadsCII, isResClassIII(), M_AP7_ROT_RADS, M_SQRT7, NUM_ICOSA_FACES, run_benchmark_import::res, RES0_U_GNOMONIC, Vec3d, X_INDEX, and Y_INDEX.

Referenced by _geoToFaceIjk().

                                                                                     {
  Vec3d(v3d);
  _geoToVec3d(g, v3d);

  // determine the icosahedron face
  *face = 0;
  double sqd = _pointSquareDist(faceCenterPoint[0], v3d);
  for (int f = 1; f < NUM_ICOSA_FACES; f++) {
    double sqdT = _pointSquareDist(faceCenterPoint[f], v3d);
    if (sqdT < sqd) {
      *face = f;
      sqd = sqdT;
    }
  }

  // cos(r) = 1 - 2 * sin^2(r/2) = 1 - 2 * (sqd / 4) = 1 - sqd/2
  double r = acos(1 - sqd / 2);

  if (r < EPSILON) {
    v[X_INDEX] = v[Y_INDEX] = 0.0;
    return true;
  }

  // now have face and r, now find CCW theta from CII i-axis
  double theta = _posAngleRads(faceAxesAzRadsCII[*face][0] -
                               _posAngleRads(_geoAzimuthRads(faceCenterGeo[*face], g)));

  // adjust theta for Class III (odd resolutions)
  if (isResClassIII(res))
    theta = _posAngleRads(theta - M_AP7_ROT_RADS);

  // perform gnomonic scaling of r
  r = tan(r);

  // scale for current resolution length u
  r /= RES0_U_GNOMONIC;
  for (int i = 0; i < res; i++)
    r *= M_SQRT7;

  // we now have (r, theta) in hex2d with theta ccw from x-axes

  // convert to local x,y
  v[X_INDEX] = r * cos(theta);
  v[Y_INDEX] = r * sin(theta);

  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

EXTENSION_NOINLINE bool _hex2dToGeo	(	const	Vec2dv,
		int	face,
		int	res,
		int	substrate,
		GeoCoord(g)
	)

Determines the center point in spherical coordinates of a cell given by 2D hex coordinates on a particular icosahedral face.

Parameters

v	The 2D hex coordinates of the cell.
face	The icosahedral face upon which the 2D hex coordinate system is centered.
res	The H3 resolution of the cell.
substrate	Indicates whether or not this grid is actually a substrate grid relative to the specified resolution.
g	The spherical coordinates of the cell center point.

Definition at line 442 of file faceijk.hpp.

References _geoAzDistanceRads(), _posAngleRads(), _v2dMag(), EPSILON, faceAxesAzRadsCII, GeoCoordCopy, isResClassIII(), M_AP7_ROT_RADS, M_SQRT7, run_benchmark_import::res, RES0_U_GNOMONIC, X_INDEX, and Y_INDEX.

Referenced by _faceIjkToGeo().

                                                 {
  // calculate (r, theta) in hex2d
  double r = _v2dMag(v);

  if (r < EPSILON) {
    GeoCoordCopy(g, faceCenterGeo[face]);
    return true;
  }

  double theta = atan2(v[Y_INDEX], v[X_INDEX]);

  // scale for current resolution length u
  for (int i = 0; i < res; i++)
    r /= M_SQRT7;

  // scale accordingly if this is a substrate grid
  if (substrate) {
    r /= 3.0;
    if (isResClassIII(res))
      r /= M_SQRT7;
  }

  r *= RES0_U_GNOMONIC;

  // perform inverse gnomonic scaling of r
  r = atan(r);

  // adjust theta for Class III
  // if a substrate grid, then it's already been adjusted for Class III
  if (!substrate && isResClassIII(res))
    theta = _posAngleRads(theta + M_AP7_ROT_RADS);

  // find theta as an azimuth
  theta = _posAngleRads(faceAxesAzRadsCII[face][0] - theta);

  // now find the point at (r,theta) from the face center
  _geoAzDistanceRads(faceCenterGeo[face], theta, r, g);

  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

EXTENSION_INLINE int isResClassIII

(

int

res

)

Returns whether or not a resolution is a Class III grid. Note that odd resolutions are Class III and even resolutions are Class II.

Parameters

res	The H3 resolution.

Returns

1 if the resolution is a Class III grid, and 0 if the resolution is a Class II grid.

Definition at line 350 of file faceijk.hpp.

Referenced by _faceIjkToH3(), _geoToHex2d(), _h3ToFaceIjk(), _h3ToFaceIjkWithInitializedFijk(), and _hex2dToGeo().

                                            {
  return res % 2;
}

Here is the caller graph for this function: