faceijk.hpp File Reference

#include "QueryEngine/ExtensionFunctions/h3lib/include/faceijk.h"
#include "QueryEngine/ExtensionFunctions/h3lib/include/geoCoord.h"
#include "QueryEngine/ExtensionFunctions/h3lib/include/h3Index.h"
#include "QueryEngine/ExtensionFunctions/h3lib/include/vec3d.h"

Include dependency graph for faceijk.hpp:

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

Go to the source code of this file.

Macros
#define	M_SQRT7   2.6457513110645905905016157536392604257102

Functions
DEVICE const	GeoCoordArray (faceCenterGeo, NUM_ICOSA_FACES)
	icosahedron face centers in lat/lon radians More...
static DEVICE const	Vec3dArray (faceCenterPoint, NUM_ICOSA_FACES)
	icosahedron face centers in x/y/z on the unit sphere More...
static DEVICE const	FaceOrientIJK2DArray (faceNeighbors, NUM_ICOSA_FACES, 4)
	Definition of which faces neighbor each other. More...
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	_hex2dToGeo (const Vec2d(v), int face, int res, int substrate, GeoCoord(g))
EXTENSION_NOINLINE bool	_faceIjkToGeo (const FaceIJK(h), int res, GeoCoord(g))
EXTENSION_NOINLINE int	_adjustOverageClassII (FaceIJK(fijk), int res, int pentLeading4, int substrate)

Variables
static DEVICE const double	faceAxesAzRadsCII [NUM_ICOSA_FACES][3]
	icosahedron face ijk axes as azimuth in radians from face center to vertex 0/1/2 respectively More...
static DEVICE const int	maxDimByCIIres []
	direction from the origin face to the destination face, relative to the origin face's coordinate system, or -1 if not adjacent. More...
static DEVICE const int	unitScaleByCIIres []
	unit scale distance table More...

Macro Definition Documentation

#define M_SQRT7   2.6457513110645905905016157536392604257102

square root of 7

Definition at line 36 of file faceijk.hpp.

Referenced by _geoToHex2d(), and _hex2dToGeo().

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:

static DEVICE const FaceOrientIJK2DArray ( faceNeighbors  , NUM_ICOSA_FACES  , 4    )

static

Definition of which faces neighbor each other.

DEVICE const GeoCoordArray	(	faceCenterGeo	,
		NUM_ICOSA_FACES
	)

icosahedron face centers in lat/lon radians

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:

static DEVICE const Vec3dArray ( faceCenterPoint  , NUM_ICOSA_FACES    )

static

icosahedron face centers in x/y/z on the unit sphere

Variable Documentation

DEVICE const double faceAxesAzRadsCII[NUM_ICOSA_FACES][3]

static

Initial value:

= {
    {5.619958268523939882, 3.525563166130744542, 1.431168063737548730},  
    {5.760339081714187279, 3.665943979320991689, 1.571548876927796127},  
    {0.780213654393430055, 4.969003859179821079, 2.874608756786625655},  
    {0.430469363979999913, 4.619259568766391033, 2.524864466373195467},  
    {6.130269123335111400, 4.035874020941915804, 1.941478918548720291},  
    {2.692877706530642877, 0.598482604137447119, 4.787272808923838195},  
    {2.982963003477243874, 0.888567901084048369, 5.077358105870439581},  
    {3.532912002790141181, 1.438516900396945656, 5.627307105183336758},  
    {3.494305004259568154, 1.399909901866372864, 5.588700106652763840},  
    {3.003214169499538391, 0.908819067106342928, 5.097609271892733906},  
    {5.930472956509811562, 3.836077854116615875, 1.741682751723420374},  
    {0.138378484090254847, 4.327168688876645809, 2.232773586483450311},  
    {0.448714947059150361, 4.637505151845541521, 2.543110049452346120},  
    {0.158629650112549365, 4.347419854898940135, 2.253024752505744869},  
    {5.891865957979238535, 3.797470855586042958, 1.703075753192847583},  
    {2.711123289609793325, 0.616728187216597771, 4.805518392002988683},  
    {3.294508837434268316, 1.200113735041072948, 5.388903939827463911},  
    {3.804819692245439833, 1.710424589852244509, 5.899214794638635174},  
    {3.664438879055192436, 1.570043776661997111, 5.758833981448388027},  
    {2.361378999196363184, 0.266983896803167583, 4.455774101589558636},  
}

icosahedron face ijk axes as azimuth in radians from face center to vertex 0/1/2 respectively

Definition at line 89 of file faceijk.hpp.

Referenced by _geoToHex2d(), and _hex2dToGeo().

DEVICE const int maxDimByCIIres[]

static

Initial value:

= {
    2,        
    -1,       
    14,       
    -1,       
    98,       
    -1,       
    686,      
    -1,       
    4802,     
    -1,       
    33614,    
    -1,       
    235298,   
    -1,       
    1647086,  
    -1,       
    11529602  
}

direction from the origin face to the destination face, relative to the origin face's coordinate system, or -1 if not adjacent.

overage distance table

Definition at line 302 of file faceijk.hpp.

Referenced by _adjustOverageClassII().

DEVICE const int unitScaleByCIIres[]

static

Initial value:

= {
    1,       
    -1,      
    7,       
    -1,      
    49,      
    -1,      
    343,     
    -1,      
    2401,    
    -1,      
    16807,   
    -1,      
    117649,  
    -1,      
    823543,  
    -1,      
    5764801  
}

unit scale distance table

Definition at line 323 of file faceijk.hpp.

Referenced by _adjustOverageClassII().