uber · nrabinowitz · Jul 14, 2022 · Jul 5, 2022 · Jul 5, 2022 · Jul 5, 2022
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,8 @@ The public API of this library consists of the functions declared in file
 [h3api.h.in](./src/h3lib/include/h3api.h.in).
 
 ## [Unreleased]
+### Breaking changes
+- `distance*` functions (`distanceKm`, etc) renamed to `greatCircleDistance*`. (#622)
 
 ## [4.0.0-rc3] - 2022-06-03
 ### Fixed

diff --git a/src/apps/fuzzers/fuzzerDistances.c b/src/apps/fuzzers/fuzzerDistances.c
@@ -32,9 +32,9 @@ int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
     }
     const inputArgs *args = (const inputArgs *)data;
 
-    H3_EXPORT(distanceRads)(&args->a, &args->b);
-    H3_EXPORT(distanceKm)(&args->a, &args->b);
-    H3_EXPORT(distanceM)(&args->a, &args->b);
+    H3_EXPORT(greatCircleDistanceRads)(&args->a, &args->b);
+    H3_EXPORT(greatCircleDistanceKm)(&args->a, &args->b);
+    H3_EXPORT(greatCircleDistanceM)(&args->a, &args->b);
 
     return 0;
 }

diff --git a/src/apps/testapps/testH3CellAreaExhaustive.c b/src/apps/testapps/testH3CellAreaExhaustive.c
@@ -34,9 +34,9 @@
  * neighboring cells. Tests positivity and commutativity.
  *
  * Tests the functions:
- *     distanceRads
- *     distanceKm
- *     distanceM
+ *     greatCircleDistanceRads
+ *     greatCircleDistanceKm
+ *     greatCircleDistanceM
  *
  * @param  edge  H3 directed edge denoting neighboring cells
  */
@@ -55,24 +55,26 @@ static void haversine_assert(H3Index edge) {
 
     double ab, ba;
 
-    ab = H3_EXPORT(distanceRads)(&a, &b);
-    ba = H3_EXPORT(distanceRads)(&b, &a);
+    ab = H3_EXPORT(greatCircleDistanceRads)(&a, &b);
+    ba = H3_EXPORT(greatCircleDistanceRads)(&b, &a);
     t_assert(ab > 0, pos);
     t_assert(ab == ba, comm);
 
-    ab = H3_EXPORT(distanceKm)(&a, &b);
-    ba = H3_EXPORT(distanceKm)(&b, &a);
+    ab = H3_EXPORT(greatCircleDistanceKm)(&a, &b);
+    ba = H3_EXPORT(greatCircleDistanceKm)(&b, &a);
     t_assert(ab > 0, pos);
     t_assert(ab == ba, comm);
 
-    ab = H3_EXPORT(distanceM)(&a, &b);
-    ba = H3_EXPORT(distanceM)(&b, &a);
+    ab = H3_EXPORT(greatCircleDistanceM)(&a, &b);
+    ba = H3_EXPORT(greatCircleDistanceM)(&b, &a);
     t_assert(ab > 0, pos);
     t_assert(ab == ba, comm);
 
-    t_assert(H3_EXPORT(distanceKm)(&a, &b) > H3_EXPORT(distanceRads)(&a, &b),
+    t_assert(H3_EXPORT(greatCircleDistanceKm)(&a, &b) >
+                 H3_EXPORT(greatCircleDistanceRads)(&a, &b),
              "measurement in kilometers should be greater than in radians");
-    t_assert(H3_EXPORT(distanceM)(&a, &b) > H3_EXPORT(distanceKm)(&a, &b),
+    t_assert(H3_EXPORT(greatCircleDistanceM)(&a, &b) >
+                 H3_EXPORT(greatCircleDistanceKm)(&a, &b),
              "measurement in meters should be greater than in kilometers");
 }
 

diff --git a/src/apps/testapps/testLatLng.c b/src/apps/testapps/testLatLng.c
@@ -62,9 +62,10 @@ SUITE(latLng) {
         setGeoDegs(&p2, 0, 10);
 
         // TODO: Epsilon is relatively large
-        t_assert(H3_EXPORT(distanceRads)(&p1, &p1) < EPSILON_RAD * 1000,
-                 "0 distance as expected");
-        t_assert(fabs(H3_EXPORT(distanceRads)(&p1, &p2) -
+        t_assert(
+            H3_EXPORT(greatCircleDistanceRads)(&p1, &p1) < EPSILON_RAD * 1000,
+            "0 distance as expected");
+        t_assert(fabs(H3_EXPORT(greatCircleDistanceRads)(&p1, &p2) -
                       H3_EXPORT(degsToRads)(10)) < EPSILON_RAD * 1000,
                  "distance along longitude as expected");
     }
@@ -184,25 +185,25 @@ SUITE(latLng) {
         double distance = H3_EXPORT(degsToRads)(15);
 
         _geoAzDistanceRads(&start, azimuth, distance, &out);
-        t_assert(fabs(H3_EXPORT(distanceRads)(&start, &out) - distance) <
-                     EPSILON_RAD,
+        t_assert(fabs(H3_EXPORT(greatCircleDistanceRads)(&start, &out) -
+                      distance) < EPSILON_RAD,
                  "moved distance is as expected");
 
         LatLng start2 = out;
         _geoAzDistanceRads(&start2, azimuth + degrees180, distance, &out);
         // TODO: Epsilon is relatively large
-        t_assert(H3_EXPORT(distanceRads)(&start, &out) < 0.01,
+        t_assert(H3_EXPORT(greatCircleDistanceRads)(&start, &out) < 0.01,
                  "moved back to origin");
     }
 
     TEST(distanceRads_wrappedLongitude) {
         const LatLng negativeLongitude = {.lat = 0, .lng = -(M_PI + M_PI_2)};
         const LatLng zero = {.lat = 0, .lng = 0};
 
-        t_assert(fabs(M_PI_2 - H3_EXPORT(distanceRads)(&negativeLongitude,
-                                                       &zero)) < EPSILON_RAD,
+        t_assert(fabs(M_PI_2 - H3_EXPORT(greatCircleDistanceRads)(
+                                   &negativeLongitude, &zero)) < EPSILON_RAD,
                  "Distance with wrapped longitude");
-        t_assert(fabs(M_PI_2 - H3_EXPORT(distanceRads)(
+        t_assert(fabs(M_PI_2 - H3_EXPORT(greatCircleDistanceRads)(
                                    &zero, &negativeLongitude)) < EPSILON_RAD,
                  "Distance with wrapped longitude and swapped arguments");
     }

diff --git a/src/h3lib/include/h3api.h.in b/src/h3lib/include/h3api.h.in
@@ -314,19 +314,22 @@ DECLSPEC double H3_EXPORT(degsToRads)(double degrees);
 DECLSPEC double H3_EXPORT(radsToDegs)(double radians);
 /** @} */
 
-/** @defgroup distance distance
+/** @defgroup greatCircleDistance greatCircleDistance
  * Functions for distance
  * @{
  */
 /** @brief "great circle distance" between pairs of LatLng points in radians*/
-DECLSPEC double H3_EXPORT(distanceRads)(const LatLng *a, const LatLng *b);
+DECLSPEC double H3_EXPORT(greatCircleDistanceRads)(const LatLng *a,
+                                                   const LatLng *b);
 
 /** @brief "great circle distance" between pairs of LatLng points in
  * kilometers*/
-DECLSPEC double H3_EXPORT(distanceKm)(const LatLng *a, const LatLng *b);
+DECLSPEC double H3_EXPORT(greatCircleDistanceKm)(const LatLng *a,
+                                                 const LatLng *b);
 
 /** @brief "great circle distance" between pairs of LatLng points in meters*/
-DECLSPEC double H3_EXPORT(distanceM)(const LatLng *a, const LatLng *b);
+DECLSPEC double H3_EXPORT(greatCircleDistanceM)(const LatLng *a,
+                                                const LatLng *b);
 /** @} */
 
 /** @defgroup getHexagonAreaAvg getHexagonAreaAvg

diff --git a/src/h3lib/lib/bbox.c b/src/h3lib/lib/bbox.c
@@ -86,7 +86,7 @@ double _hexRadiusKm(H3Index h3Index) {
     CellBoundary h3Boundary;
     H3_EXPORT(cellToLatLng)(h3Index, &h3Center);
     H3_EXPORT(cellToBoundary)(h3Index, &h3Boundary);
-    return H3_EXPORT(distanceKm)(&h3Center, h3Boundary.verts);
+    return H3_EXPORT(greatCircleDistanceKm)(&h3Center, h3Boundary.verts);
 }
 
 /**
@@ -117,7 +117,7 @@ int64_t bboxHexEstimate(const BBox *bbox, int res) {
     p1.lng = bbox->east;
     p2.lat = bbox->south;
     p2.lng = bbox->west;
-    double d = H3_EXPORT(distanceKm)(&p1, &p2);
+    double d = H3_EXPORT(greatCircleDistanceKm)(&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.lng - p2.lng) / (p1.lat - p2.lat)));
@@ -145,7 +145,7 @@ int64_t lineHexEstimate(const LatLng *origin, const LatLng *destination,
     H3_EXPORT(getPentagons)(res, pentagons);
     double pentagonRadiusKm = _hexRadiusKm(pentagons[0]);
 
-    double dist = H3_EXPORT(distanceKm)(origin, destination);
+    double dist = H3_EXPORT(greatCircleDistanceKm)(origin, destination);
     int64_t estimate = (int64_t)ceil(dist / (2 * pentagonRadiusKm));
     if (estimate == 0) estimate = 1;
     return estimate;

diff --git a/src/h3lib/lib/latLng.c b/src/h3lib/lib/latLng.c
@@ -149,7 +149,7 @@ double constrainLng(double lng) {
  *
  * @return    the great circle distance in radians between a and b
  */
-double H3_EXPORT(distanceRads)(const LatLng *a, const LatLng *b) {
+double H3_EXPORT(greatCircleDistanceRads)(const LatLng *a, const LatLng *b) {
     double sinLat = sin((b->lat - a->lat) / 2.0);
     double sinLng = sin((b->lng - a->lng) / 2.0);
 
@@ -161,15 +161,15 @@ double H3_EXPORT(distanceRads)(const LatLng *a, const LatLng *b) {
 /**
  * The great circle distance in kilometers between two spherical coordinates.
  */
-double H3_EXPORT(distanceKm)(const LatLng *a, const LatLng *b) {
-    return H3_EXPORT(distanceRads)(a, b) * EARTH_RADIUS_KM;
+double H3_EXPORT(greatCircleDistanceKm)(const LatLng *a, const LatLng *b) {
+    return H3_EXPORT(greatCircleDistanceRads)(a, b) * EARTH_RADIUS_KM;
 }
 
 /**
  * The great circle distance in meters between two spherical coordinates.
  */
-double H3_EXPORT(distanceM)(const LatLng *a, const LatLng *b) {
-    return H3_EXPORT(distanceKm)(a, b) * 1000;
+double H3_EXPORT(greatCircleDistanceM)(const LatLng *a, const LatLng *b) {
+    return H3_EXPORT(greatCircleDistanceKm)(a, b) * 1000;
 }
 
 /**
@@ -356,9 +356,9 @@ double triangleEdgeLengthsToArea(double a, double b, double c) {
  * @return     area of triangle on unit sphere, in radians^2
  */
 double triangleArea(const LatLng *a, const LatLng *b, const LatLng *c) {
-    return triangleEdgeLengthsToArea(H3_EXPORT(distanceRads)(a, b),
-                                     H3_EXPORT(distanceRads)(b, c),
-                                     H3_EXPORT(distanceRads)(c, a));
+    return triangleEdgeLengthsToArea(H3_EXPORT(greatCircleDistanceRads)(a, b),
+                                     H3_EXPORT(greatCircleDistanceRads)(b, c),
+                                     H3_EXPORT(greatCircleDistanceRads)(c, a));
 }
 
 /**
@@ -437,7 +437,8 @@ H3Error H3_EXPORT(exactEdgeLengthRads)(H3Index edge, double *length) {
 
     *length = 0.0;
     for (int i = 0; i < cb.numVerts - 1; i++) {
-        *length += H3_EXPORT(distanceRads)(&cb.verts[i], &cb.verts[i + 1]);
+        *length +=
+            H3_EXPORT(greatCircleDistanceRads)(&cb.verts[i], &cb.verts[i + 1]);
     }
 
     return E_SUCCESS;

diff --git a/website/docs/api/misc.mdx b/website/docs/api/misc.mdx
@@ -898,7 +898,7 @@ This function exists for memory management and is not exposed.
 
 Number of pentagon H3 indexes per resolution. This is always 12, but provided as a convenience.
 
-## distanceKm
+## greatCircleDistanceKm
 
 <Tabs
   groupId="language"
@@ -913,35 +913,35 @@ Number of pentagon H3 indexes per resolution. This is always 12, but provided as
 <TabItem value="c">
 
 ```c
-double distanceKm(const LatLng *a, const LatLng *b);
+double greatCircleDistanceKm(const LatLng *a, const LatLng *b);
 ```
 
 </TabItem>
 <TabItem value="python">
 
 ```py
-h3.distance(point1, point2, unit='km')
+h3.great_circle_distance(point1, point2, unit='km')
 ```
 
 </TabItem>
 <TabItem value="java">
 
 ```java
-double distance(LatLng point1, LatLng point2, LengthUnit unit);
+double greatCircleDistance(LatLng point1, LatLng point2, LengthUnit unit);
 ```
 
 </TabItem>
 <TabItem value="javascript">
 
 ```js
-h3.distance(point1, point2, h3.UNITS.km)
+h3.greatCircleDistance(point1, point2, h3.UNITS.km)
 ```
 
 ```js live
 function example() {
   const point1 = [-10, 0];
   const point2 = [10, 0];
-  return h3.distance(point1, point2, h3.UNITS.km)
+  return h3.greatCircleDistance(point1, point2, h3.UNITS.km)
 }
 ```
 
@@ -951,7 +951,7 @@ function example() {
 Gives the "great circle" or "haversine" distance between pairs of
 LatLng points (lat/lng pairs) in kilometers.
 
-## distanceM
+## greatCircleDistanceM
 
 <Tabs
   groupId="language"
@@ -966,35 +966,35 @@ LatLng points (lat/lng pairs) in kilometers.
 <TabItem value="c">
 
 ```c
-double distanceM(const LatLng *a, const LatLng *b);
+double greatCircleDistanceM(const LatLng *a, const LatLng *b);
 ```
 
 </TabItem>
 <TabItem value="python">
 
 ```py
-h3.distance(point1, point2, unit='m')
+h3.latlng_distance(point1, point2, unit='m')
 ```
 
 </TabItem>
 <TabItem value="java">
 
 ```java
-double distance(LatLng point1, LatLng point2, LengthUnit unit);
+double greatCircleDistance(LatLng point1, LatLng point2, LengthUnit unit);
 ```
 
 </TabItem>
 <TabItem value="javascript">
 
 ```js
-h3.distance(point1, point2, h3.UNITS.m)
+h3.greatCircleDistance(point1, point2, h3.UNITS.m);
 ```
 
 ```js live
 function example() {
   const point1 = [-10, 0];
   const point2 = [10, 0];
-  return h3.distance(point1, point2, h3.UNITS.m)
+  return h3.greatCircleDistance(point1, point2, h3.UNITS.m);
 }
 ```
 
@@ -1004,7 +1004,7 @@ function example() {
 Gives the "great circle" or "haversine" distance between pairs of
 LatLng points (lat/lng pairs) in meters.
 
-## distanceRads
+## greatCircleDistanceRads
 
 <Tabs
   groupId="language"
@@ -1019,35 +1019,35 @@ LatLng points (lat/lng pairs) in meters.
 <TabItem value="c">
 
 ```c
-double distanceRads(const LatLng *a, const LatLng *b);
+double greatCircleDistanceRads(const LatLng *a, const LatLng *b);
 ```
 
 </TabItem>
 <TabItem value="python">
 
 ```py
-h3.distance(point1, point2, unit='rads')
+h3.latlng_distance(point1, point2, unit='rads')
 ```
 
 </TabItem>
 <TabItem value="java">
 
 ```java
-double distance(LatLng point1, LatLng point2, LengthUnit unit);
+double greatCircleDistance(LatLng point1, LatLng point2, LengthUnit unit);
 ```
 
 </TabItem>
 <TabItem value="javascript">
 
 ```js
-h3.distance(point1, point2, h3.UNITS.rads)
+h3.greatCircleDistance(point1, point2, h3.UNITS.rads)
 ```
 
 ```js live
 function example() {
   const point1 = [-10, 0];
   const point2 = [10, 0];
-  return h3.distance(point1, point2, h3.UNITS.rads)
+  return h3.greatCircleDistance(point1, point2, h3.UNITS.rads)
 }
 ```