h3 3.5.0 → 3.7.1

data/ext/h3/src/src/h3lib/lib/baseCells.c

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 Uber Technologies, Inc.
+ * Copyright 2016-2020 Uber Technologies, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,16 +18,17 @@
  */
 
 #include "baseCells.h"
+
 #include "h3Index.h"
 
-/** @struct BaseCellOrient
+/** @struct BaseCellRotation
  *  @brief base cell at a given ijk and required rotations into its system
  */
 typedef struct {
     int baseCell;  ///< base cell number
     int ccwRot60;  ///< number of ccw 60 degree rotations relative to current
                    /// face
-} BaseCellOrient;
+} BaseCellRotation;
 
 /** @brief Neighboring base cell ID in each IJK direction.
  *
@@ -304,7 +305,7 @@ const int baseCellNeighbor60CCWRots[NUM_BASE_CELLS][7] = {
  * This table can be accessed using the functions `_faceIjkToBaseCell` and
  * `_faceIjkToBaseCellCCWrot60`
  */
-static const BaseCellOrient faceIjkBaseCells[NUM_ICOSA_FACES][3][3][3] = {
+static const BaseCellRotation faceIjkBaseCells[NUM_ICOSA_FACES][3][3][3] = {
     {// face 0
      {
          // i 0
@@ -862,6 +863,27 @@ void _baseCellToFaceIjk(int baseCell, FaceIJK* h) {
     *h = baseCellData[baseCell].homeFijk;
 }
 
+/**
+ * @brief Given a base cell and the face it appears on, return
+ *        the number of 60' ccw rotations for that base cell's
+ *        coordinate system.
+ * @returns The number of rotations, or INVALID_ROTATIONS if the base
+ *          cell is not found on the given face
+ */
+int _baseCellToCCWrot60(int baseCell, int face) {
+    if (face < 0 || face > NUM_ICOSA_FACES) return INVALID_ROTATIONS;
+    for (int i = 0; i < 3; i++) {
+        for (int j = 0; j < 3; j++) {
+            for (int k = 0; k < 3; k++) {
+                if (faceIjkBaseCells[face][i][j][k].baseCell == baseCell) {
+                    return faceIjkBaseCells[face][i][j][k].ccwRot60;
+                }
+            }
+        }
+    }
+    return INVALID_ROTATIONS;
+}
+
 /** @brief Return whether or not the tested face is a cw offset face.
  */
 bool _baseCellIsCwOffset(int baseCell, int testFace) {

data/ext/h3/src/src/h3lib/lib/bbox.c

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2017 Uber Technologies, Inc.
+ * Copyright 2016-2020 Uber Technologies, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,9 +18,11 @@
  */
 
 #include "bbox.h"
+
 #include <float.h>
 #include <math.h>
 #include <stdbool.h>
+
 #include "constants.h"
 #include "geoCoord.h"
 #include "h3Index.h"
@@ -84,38 +86,65 @@ double _hexRadiusKm(H3Index h3Index) {
     GeoBoundary h3Boundary;
     H3_EXPORT(h3ToGeo)(h3Index, &h3Center);
     H3_EXPORT(h3ToGeoBoundary)(h3Index, &h3Boundary);
-    return _geoDistKm(&h3Center, h3Boundary.verts);
+    return H3_EXPORT(pointDistKm)(&h3Center, h3Boundary.verts);
 }
 
 /**
- * Get the radius of the bbox in hexagons - i.e. the radius of a k-ring centered
- * on the bbox center and covering the entire bbox.
- * @param  bbox Bounding box to measure
- * @param  res  Resolution of hexagons to use in measurement
- * @return      Radius in hexagons
+ * bboxHexEstimate returns an estimated number of hexagons that fit
+ *                 within the cartesian-projected bounding box
+ *
+ * @param bbox the bounding box to estimate the hexagon fill level
+ * @param res the resolution of the H3 hexagons to fill the bounding box
+ * @return the estimated number of hexagons to fill the bounding box
  */
-int bboxHexRadius(const BBox* bbox, int res) {
-    // Determine the center of the bounding box
-    GeoCoord center;
-    bboxCenter(bbox, &center);
+int bboxHexEstimate(const BBox* bbox, int res) {
+    // Get the area of the pentagon as the maximally-distorted area possible
+    H3Index pentagons[12] = {0};
+    H3_EXPORT(getPentagonIndexes)(res, pentagons);
+    double pentagonRadiusKm = _hexRadiusKm(pentagons[0]);
+    // Area of a regular hexagon is 3/2*sqrt(3) * r * r
+    // The pentagon has the most distortion (smallest edges) and shares its
+    // edges with hexagons, so the most-distorted hexagons have this area,
+    // shrunk by 20% off chance that the bounding box perfectly bounds a
+    // pentagon.
+    double pentagonAreaKm2 =
+        0.8 * (2.59807621135 * pentagonRadiusKm * pentagonRadiusKm);
 
-    // Use a vertex on the side closest to the equator, to ensure the longest
-    // radius in cases with significant distortion. East/west is arbitrary.
-    double lat =
-        fabs(bbox->north) > fabs(bbox->south) ? bbox->south : bbox->north;
-    GeoCoord vertex = {lat, bbox->east};
+    // Then get the area of the bounding box of the geofence in question
+    GeoCoord p1, p2;
+    p1.lat = bbox->north;
+    p1.lon = bbox->east;
+    p2.lat = bbox->south;
+    p2.lon = bbox->west;
+    double d = H3_EXPORT(pointDistKm)(&p1, &p2);
+    // Derived constant based on: https://math.stackexchange.com/a/1921940
+    // Clamped to 3 as higher values tend to rapidly drag the estimate to zero.
+    double a = d * d / fmin(3.0, fabs((p1.lon - p2.lon) / (p1.lat - p2.lat)));
 
-    // Determine the length of the bounding box "radius" to then use
-    // as a circle on the earth that the k-rings must be greater than
-    double bboxRadiusKm = _geoDistKm(&center, &vertex);
+    // Divide the two to get an estimate of the number of hexagons needed
+    int estimate = (int)ceil(a / pentagonAreaKm2);
+    if (estimate == 0) estimate = 1;
+    return estimate;
+}
 
-    // Determine the radius of the center hexagon
-    double centerHexRadiusKm = _hexRadiusKm(H3_EXPORT(geoToH3)(&center, res));
+/**
+ * lineHexEstimate returns an estimated number of hexagons that trace
+ *                 the cartesian-projected line
+ *
+ *  @param origin the origin coordinates
+ *  @param destination the destination coordinates
+ *  @param res the resolution of the H3 hexagons to trace the line
+ *  @return the estimated number of hexagons required to trace the line
+ */
+int lineHexEstimate(const GeoCoord* origin, const GeoCoord* destination,
+                    int res) {
+    // Get the area of the pentagon as the maximally-distorted area possible
+    H3Index pentagons[12] = {0};
+    H3_EXPORT(getPentagonIndexes)(res, pentagons);
+    double pentagonRadiusKm = _hexRadiusKm(pentagons[0]);
 
-    // The closest point along a hexagon drawn through the center points
-    // of a k-ring aggregation is exactly 1.5 radii of the hexagon. For
-    // any orientation of the GeoJSON encased in a circle defined by the
-    // bounding box radius and center, it is guaranteed to fit in this k-ring
-    // Rounded *up* to guarantee containment
-    return (int)ceil(bboxRadiusKm / (1.5 * centerHexRadiusKm));
+    double dist = H3_EXPORT(pointDistKm)(origin, destination);
+    int estimate = (int)ceil(dist / (2 * pentagonRadiusKm));
+    if (estimate == 0) estimate = 1;
+    return estimate;
 }

data/ext/h3/src/src/h3lib/lib/coordijk.c

@@ -19,10 +19,12 @@
  */
 
 #include "coordijk.h"
+
 #include <math.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+
 #include "constants.h"
 #include "geoCoord.h"
 #include "mathExtensions.h"

data/ext/h3/src/src/h3lib/lib/faceijk.c

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2019 Uber Technologies, Inc.
+ * Copyright 2016-2020 Uber Technologies, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,11 +19,13 @@
  */
 
 #include "faceijk.h"
+
 #include <assert.h>
 #include <math.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+
 #include "constants.h"
 #include "coordijk.h"
 #include "geoCoord.h"
@@ -499,20 +501,28 @@ void _faceIjkToGeo(const FaceIJK* h, int res, GeoCoord* g) {
  *
  * @param h The FaceIJK address of the pentagonal cell.
  * @param res The H3 resolution of the cell.
+ * @param start The first topological vertex to return.
+ * @param length The number of topological vertexes to return.
  * @param g The spherical coordinates of the cell boundary.
  */
-void _faceIjkPentToGeoBoundary(const FaceIJK* h, int res, GeoBoundary* g) {
+void _faceIjkPentToGeoBoundary(const FaceIJK* h, int res, int start, int length,
+                               GeoBoundary* g) {
     int adjRes = res;
     FaceIJK centerIJK = *h;
     FaceIJK fijkVerts[NUM_PENT_VERTS];
     _faceIjkPentToVerts(&centerIJK, &adjRes, fijkVerts);
 
+    // If we're returning the entire loop, we need one more iteration in case
+    // of a distortion vertex on the last edge
+    int additionalIteration = length == NUM_PENT_VERTS ? 1 : 0;
+
     // convert each vertex to lat/lon
     // adjust the face of each vertex as appropriate and introduce
     // edge-crossing vertices as needed
     g->numVerts = 0;
     FaceIJK lastFijk;
-    for (int vert = 0; vert < NUM_PENT_VERTS + 1; vert++) {
+    for (int vert = start; vert < start + length + additionalIteration;
+         vert++) {
         int v = vert % NUM_PENT_VERTS;
 
         FaceIJK fijk = fijkVerts[v];
@@ -522,7 +532,7 @@ void _faceIjkPentToGeoBoundary(const FaceIJK* h, int res, GeoBoundary* g) {
         // all Class III pentagon edges cross icosa edges
         // note that Class II pentagons have vertices on the edge,
         // not edge intersections
-        if (isResClassIII(res) && vert > 0) {
+        if (isResClassIII(res) && vert > start) {
             // find hex2d of the two vertexes on the last face
 
             FaceIJK tmpFijk = fijk;
@@ -583,9 +593,9 @@ void _faceIjkPentToGeoBoundary(const FaceIJK* h, int res, GeoBoundary* g) {
         }
 
         // convert vertex to lat/lon and add to the result
-        // vert == NUM_PENT_VERTS is only used to test for possible intersection
-        // on last edge
-        if (vert < NUM_PENT_VERTS) {
+        // vert == start + NUM_PENT_VERTS is only used to test for possible
+        // intersection on last edge
+        if (vert < start + NUM_PENT_VERTS) {
             Vec2d vec;
             _ijkToHex2d(&fijk.coord, &vec);
             _hex2dToGeo(&vec, fijk.face, adjRes, 1, &g->verts[g->numVerts]);
@@ -664,34 +674,35 @@ void _faceIjkPentToVerts(FaceIJK* fijk, int* res, FaceIJK* fijkVerts) {
  *
  * @param h The FaceIJK address of the cell.
  * @param res The H3 resolution of the cell.
- * @param isPentagon Whether or not the cell is a pentagon.
+ * @param start The first topological vertex to return.
+ * @param length The number of topological vertexes to return.
  * @param g The spherical coordinates of the cell boundary.
  */
-void _faceIjkToGeoBoundary(const FaceIJK* h, int res, int isPentagon,
+void _faceIjkToGeoBoundary(const FaceIJK* h, int res, int start, int length,
                            GeoBoundary* g) {
-    if (isPentagon) {
-        _faceIjkPentToGeoBoundary(h, res, g);
-        return;
-    }
-
     int adjRes = res;
     FaceIJK centerIJK = *h;
     FaceIJK fijkVerts[NUM_HEX_VERTS];
     _faceIjkToVerts(&centerIJK, &adjRes, fijkVerts);
 
+    // If we're returning the entire loop, we need one more iteration in case
+    // of a distortion vertex on the last edge
+    int additionalIteration = length == NUM_HEX_VERTS ? 1 : 0;
+
     // convert each vertex to lat/lon
     // adjust the face of each vertex as appropriate and introduce
     // edge-crossing vertices as needed
     g->numVerts = 0;
     int lastFace = -1;
-    int lastOverage = 0;  // 0: none; 1: edge; 2: overage
-    for (int vert = 0; vert < NUM_HEX_VERTS + 1; vert++) {
+    Overage lastOverage = NO_OVERAGE;
+    for (int vert = start; vert < start + length + additionalIteration;
+         vert++) {
         int v = vert % NUM_HEX_VERTS;
 
         FaceIJK fijk = fijkVerts[v];
 
-        int pentLeading4 = 0;
-        int overage = _adjustOverageClassII(&fijk, adjRes, pentLeading4, 1);
+        const int pentLeading4 = 0;
+        Overage overage = _adjustOverageClassII(&fijk, adjRes, pentLeading4, 1);
 
         /*
         Check for edge-crossing. Each face of the underlying icosahedron is a
@@ -702,8 +713,8 @@ void _faceIjkToGeoBoundary(const FaceIJK* h, int res, int isPentagon,
         projection. Note that Class II cell edges have vertices on the face
         edge, with no edge line intersections.
         */
-        if (isResClassIII(res) && vert > 0 && fijk.face != lastFace &&
-            lastOverage != 1) {
+        if (isResClassIII(res) && vert > start && fijk.face != lastFace &&
+            lastOverage != FACE_EDGE) {
             // find hex2d of the two vertexes on original face
             int lastV = (v + 5) % NUM_HEX_VERTS;
             Vec2d orig2d0;
@@ -730,7 +741,7 @@ void _faceIjkToGeoBoundary(const FaceIJK* h, int res, int isPentagon,
                     edge0 = &v1;
                     edge1 = &v2;
                     break;
-                case KI:
+                // case KI:
                 default:
                     assert(adjacentFaceDir[centerIJK.face][face2] == KI);
                     edge0 = &v2;
@@ -756,9 +767,9 @@ void _faceIjkToGeoBoundary(const FaceIJK* h, int res, int isPentagon,
         }
 
         // convert vertex to lat/lon and add to the result
-        // vert == NUM_HEX_VERTS is only used to test for possible intersection
-        // on last edge
-        if (vert < NUM_HEX_VERTS) {
+        // vert == start + NUM_HEX_VERTS is only used to test for possible
+        // intersection on last edge
+        if (vert < start + NUM_HEX_VERTS) {
             Vec2d vec;
             _ijkToHex2d(&fijk.coord, &vec);
             _hex2dToGeo(&vec, fijk.face, adjRes, 1, &g->verts[g->numVerts]);

data/ext/h3/src/src/h3lib/lib/geoCoord.c

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2017 Uber Technologies, Inc.
+ * Copyright 2016-2020 Uber Technologies, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,8 +18,10 @@
  */
 
 #include "geoCoord.h"
+
 #include <math.h>
 #include <stdbool.h>
+
 #include "constants.h"
 #include "h3api.h"
 
@@ -45,7 +47,7 @@ double _posAngleRads(double rads) {
  * @return Whether or not the two coordinates are within the threshold distance
  *         of each other.
  */
-bool geoAlmostEqualThreshold(const GeoCoord* p1, const GeoCoord* p2,
+bool geoAlmostEqualThreshold(const GeoCoord *p1, const GeoCoord *p2,
                              double threshold) {
     return fabs(p1->lat - p2->lat) < threshold &&
            fabs(p1->lon - p2->lon) < threshold;
@@ -60,18 +62,18 @@ bool geoAlmostEqualThreshold(const GeoCoord* p1, const GeoCoord* p2,
  * @return Whether or not the two coordinates are within the epsilon distance
  *         of each other.
  */
-bool geoAlmostEqual(const GeoCoord* p1, const GeoCoord* p2) {
+bool geoAlmostEqual(const GeoCoord *p1, const GeoCoord *p2) {
     return geoAlmostEqualThreshold(p1, p2, EPSILON_RAD);
 }
 
 /**
  * Set the components of spherical coordinates in decimal degrees.
  *
- * @param p The spherical coodinates.
- * @param latDegs The desired latitidue in decimal degrees.
+ * @param p The spherical coordinates.
+ * @param latDegs The desired latitude in decimal degrees.
  * @param lonDegs The desired longitude in decimal degrees.
  */
-void setGeoDegs(GeoCoord* p, double latDegs, double lonDegs) {
+void setGeoDegs(GeoCoord *p, double latDegs, double lonDegs) {
     _setGeoRads(p, H3_EXPORT(degsToRads)(latDegs),
                 H3_EXPORT(degsToRads)(lonDegs));
 }
@@ -79,11 +81,11 @@ void setGeoDegs(GeoCoord* p, double latDegs, double lonDegs) {
 /**
  * Set the components of spherical coordinates in radians.
  *
- * @param p The spherical coodinates.
- * @param latRads The desired latitidue in decimal radians.
+ * @param p The spherical coordinates.
+ * @param latRads The desired latitude in decimal radians.
  * @param lonRads The desired longitude in decimal radians.
  */
-void _setGeoRads(GeoCoord* p, double latRads, double lonRads) {
+void _setGeoRads(GeoCoord *p, double latRads, double lonRads) {
     p->lat = latRads;
     p->lon = lonRads;
 }
@@ -134,47 +136,39 @@ double constrainLng(double lng) {
 }
 
 /**
- * Find the great circle distance in radians between two spherical coordinates.
+ * The great circle distance in radians between two spherical coordinates.
  *
- * @param p1 The first spherical coordinates.
- * @param p2 The second spherical coordinates.
- * @return The great circle distance in radians between p1 and p2.
+ * This function uses the Haversine formula.
+ * For math details, see:
+ *     https://en.wikipedia.org/wiki/Haversine_formula
+ *     https://www.movable-type.co.uk/scripts/latlong.html
+ *
+ * @param  a  the first lat/lng pair (in radians)
+ * @param  b  the second lat/lng pair (in radians)
+ *
+ * @return    the great circle distance in radians between a and b
  */
-double _geoDistRads(const GeoCoord* p1, const GeoCoord* p2) {
-    // use spherical triangle with p1 at A, p2 at B, and north pole at C
-    double bigC = fabs(p2->lon - p1->lon);
-    if (bigC > M_PI)  // assume we want the complement
-    {
-        // note that in this case they can't both be negative
-        double lon1 = p1->lon;
-        if (lon1 < 0.0L) lon1 += 2.0L * M_PI;
-        double lon2 = p2->lon;
-        if (lon2 < 0.0L) lon2 += 2.0L * M_PI;
-
-        bigC = fabs(lon2 - lon1);
-    }
+double H3_EXPORT(pointDistRads)(const GeoCoord *a, const GeoCoord *b) {
+    double sinLat = sin((b->lat - a->lat) / 2.0);
+    double sinLng = sin((b->lon - a->lon) / 2.0);
 
-    double b = M_PI_2 - p1->lat;
-    double a = M_PI_2 - p2->lat;
+    double A = sinLat * sinLat + cos(a->lat) * cos(b->lat) * sinLng * sinLng;
 
-    // use law of cosines to find c
-    double cosc = cos(a) * cos(b) + sin(a) * sin(b) * cos(bigC);
-    if (cosc > 1.0L) cosc = 1.0L;
-    if (cosc < -1.0L) cosc = -1.0L;
+    return 2 * atan2(sqrt(A), sqrt(1 - A));
+}
 
-    return acos(cosc);
+/**
+ * The great circle distance in kilometers between two spherical coordinates.
+ */
+double H3_EXPORT(pointDistKm)(const GeoCoord *a, const GeoCoord *b) {
+    return H3_EXPORT(pointDistRads)(a, b) * EARTH_RADIUS_KM;
 }
 
 /**
- * Find the great circle distance in kilometers between two spherical
- * coordinates.
- *
- * @param p1 The first spherical coordinates.
- * @param p2 The second spherical coordinates.
- * @return The distance in kilometers between p1 and p2.
+ * The great circle distance in meters between two spherical coordinates.
  */
-double _geoDistKm(const GeoCoord* p1, const GeoCoord* p2) {
-    return EARTH_RADIUS_KM * _geoDistRads(p1, p2);
+double H3_EXPORT(pointDistM)(const GeoCoord *a, const GeoCoord *b) {
+    return H3_EXPORT(pointDistKm)(a, b) * 1000;
 }
 
 /**
@@ -184,7 +178,7 @@ double _geoDistKm(const GeoCoord* p1, const GeoCoord* p2) {
  * @param p2 The second spherical coordinates.
  * @return The azimuth in radians from p1 to p2.
  */
-double _geoAzimuthRads(const GeoCoord* p1, const GeoCoord* p2) {
+double _geoAzimuthRads(const GeoCoord *p1, const GeoCoord *p2) {
     return atan2(cos(p2->lat) * sin(p2->lon - p1->lon),
                  cos(p1->lat) * sin(p2->lat) -
                      sin(p1->lat) * cos(p2->lat) * cos(p2->lon - p1->lon));
@@ -200,8 +194,8 @@ double _geoAzimuthRads(const GeoCoord* p1, const GeoCoord* p2) {
  * @param p2 The spherical coordinates at the desired azimuth and distance from
  * p1.
  */
-void _geoAzDistanceRads(const GeoCoord* p1, double az, double distance,
-                        GeoCoord* p2) {
+void _geoAzDistanceRads(const GeoCoord *p1, double az, double distance,
+                        GeoCoord *p2) {
     if (distance < EPSILON) {
         *p2 = *p1;
         return;
@@ -302,6 +296,16 @@ double H3_EXPORT(edgeLengthM)(int res) {
 
 /** @brief Number of unique valid H3Indexes at given resolution. */
 int64_t H3_EXPORT(numHexagons)(int res) {
+    /**
+     * Note: this *actually* returns the number of *cells*
+     * (which includes the 12 pentagons) at each resolution.
+     *
+     * This table comes from the recurrence:
+     *
+     *  num_cells(0) = 122
+     *  num_cells(i+1) = (num_cells(i)-12)*7 + 12*6
+     *
+     */
     static const int64_t nums[] = {122L,
                                    842L,
                                    5882L,
@@ -320,3 +324,117 @@ int64_t H3_EXPORT(numHexagons)(int res) {
                                    569707381193162L};
     return nums[res];
 }
+
+/**
+ * Surface area in radians^2 of spherical triangle on unit sphere.
+ *
+ * For the math, see:
+ * https://en.wikipedia.org/wiki/Spherical_trigonometry#Area_and_spherical_excess
+ *
+ * @param   a  length of triangle side A in radians
+ * @param   b  length of triangle side B in radians
+ * @param   c  length of triangle side C in radians
+ *
+ * @return     area in radians^2 of triangle on unit sphere
+ */
+double triangleEdgeLengthsToArea(double a, double b, double c) {
+    double s = (a + b + c) / 2;
+
+    a = (s - a) / 2;
+    b = (s - b) / 2;
+    c = (s - c) / 2;
+    s = s / 2;
+
+    return 4 * atan(sqrt(tan(s) * tan(a) * tan(b) * tan(c)));
+}
+
+/**
+ * Compute area in radians^2 of a spherical triangle, given its vertices.
+ *
+ * @param   a  vertex lat/lng in radians
+ * @param   b  vertex lat/lng in radians
+ * @param   c  vertex lat/lng in radians
+ *
+ * @return     area of triangle on unit sphere, in radians^2
+ */
+double triangleArea(const GeoCoord *a, const GeoCoord *b, const GeoCoord *c) {
+    return triangleEdgeLengthsToArea(H3_EXPORT(pointDistRads)(a, b),
+                                     H3_EXPORT(pointDistRads)(b, c),
+                                     H3_EXPORT(pointDistRads)(c, a));
+}
+
+/**
+ * Area of H3 cell in radians^2.
+ *
+ * The area is calculated by breaking the cell into spherical triangles and
+ * summing up their areas. Note that some H3 cells (hexagons and pentagons)
+ * are irregular, and have more than 6 or 5 sides.
+ *
+ * todo: optimize the computation by re-using the edges shared between triangles
+ *
+ * @param   cell  H3 cell
+ *
+ * @return        cell area in radians^2
+ */
+double H3_EXPORT(cellAreaRads2)(H3Index cell) {
+    GeoCoord c;
+    GeoBoundary gb;
+    H3_EXPORT(h3ToGeo)(cell, &c);
+    H3_EXPORT(h3ToGeoBoundary)(cell, &gb);
+
+    double area = 0.0;
+    for (int i = 0; i < gb.numVerts; i++) {
+        int j = (i + 1) % gb.numVerts;
+        area += triangleArea(&gb.verts[i], &gb.verts[j], &c);
+    }
+
+    return area;
+}
+
+/**
+ * Area of H3 cell in kilometers^2.
+ */
+double H3_EXPORT(cellAreaKm2)(H3Index h) {
+    return H3_EXPORT(cellAreaRads2)(h) * EARTH_RADIUS_KM * EARTH_RADIUS_KM;
+}
+
+/**
+ * Area of H3 cell in meters^2.
+ */
+double H3_EXPORT(cellAreaM2)(H3Index h) {
+    return H3_EXPORT(cellAreaKm2)(h) * 1000 * 1000;
+}
+
+/**
+ * Length of a unidirectional edge in radians.
+ *
+ * @param   edge  H3 unidirectional edge
+ *
+ * @return        length in radians
+ */
+double H3_EXPORT(exactEdgeLengthRads)(H3Index edge) {
+    GeoBoundary gb;
+
+    H3_EXPORT(getH3UnidirectionalEdgeBoundary)(edge, &gb);
+
+    double length = 0.0;
+    for (int i = 0; i < gb.numVerts - 1; i++) {
+        length += H3_EXPORT(pointDistRads)(&gb.verts[i], &gb.verts[i + 1]);
+    }
+
+    return length;
+}
+
+/**
+ * Length of a unidirectional edge in kilometers.
+ */
+double H3_EXPORT(exactEdgeLengthKm)(H3Index edge) {
+    return H3_EXPORT(exactEdgeLengthRads)(edge) * EARTH_RADIUS_KM;
+}
+
+/**
+ * Length of a unidirectional edge in meters.
+ */
+double H3_EXPORT(exactEdgeLengthM)(H3Index edge) {
+    return H3_EXPORT(exactEdgeLengthKm)(edge) * 1000;
+}