From 6c258eb92f6e1206e212efe660d3e2e93bd16563 Mon Sep 17 00:00:00 2001 From: Nick Rabinowitz Date: Tue, 5 Jul 2022 15:27:00 -0700 Subject: [PATCH 1/5] Rename distance* functions to latLngDistance* --- src/apps/fuzzers/fuzzerDistances.c | 6 +++--- src/apps/testapps/testH3CellAreaExhaustive.c | 18 ++++++++++-------- src/apps/testapps/testLatLng.c | 14 +++++++------- src/h3lib/include/h3api.h.in | 6 +++--- src/h3lib/lib/bbox.c | 6 +++--- src/h3lib/lib/latLng.c | 19 ++++++++++--------- 6 files changed, 36 insertions(+), 33 deletions(-) diff --git a/src/apps/fuzzers/fuzzerDistances.c b/src/apps/fuzzers/fuzzerDistances.c index fe5f1ec68..1d9065415 100644 --- 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(latLngDistanceRads)(&args->a, &args->b); + H3_EXPORT(latLngDistanceKm)(&args->a, &args->b); + H3_EXPORT(latLngDistanceM)(&args->a, &args->b); return 0; } diff --git a/src/apps/testapps/testH3CellAreaExhaustive.c b/src/apps/testapps/testH3CellAreaExhaustive.c index 25d79bcf0..e4e408c7e 100644 --- a/src/apps/testapps/testH3CellAreaExhaustive.c +++ b/src/apps/testapps/testH3CellAreaExhaustive.c @@ -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(latLngDistanceRads)(&a, &b); + ba = H3_EXPORT(latLngDistanceRads)(&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(latLngDistanceKm)(&a, &b); + ba = H3_EXPORT(latLngDistanceKm)(&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(latLngDistanceM)(&a, &b); + ba = H3_EXPORT(latLngDistanceM)(&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(latLngDistanceKm)(&a, &b) > + H3_EXPORT(latLngDistanceRads)(&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(latLngDistanceM)(&a, &b) > + H3_EXPORT(latLngDistanceKm)(&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 index 6e0a92bff..07d0f1c64 100644 --- a/src/apps/testapps/testLatLng.c +++ b/src/apps/testapps/testLatLng.c @@ -62,9 +62,9 @@ SUITE(latLng) { setGeoDegs(&p2, 0, 10); // TODO: Epsilon is relatively large - t_assert(H3_EXPORT(distanceRads)(&p1, &p1) < EPSILON_RAD * 1000, + t_assert(H3_EXPORT(latLngDistanceRads)(&p1, &p1) < EPSILON_RAD * 1000, "0 distance as expected"); - t_assert(fabs(H3_EXPORT(distanceRads)(&p1, &p2) - + t_assert(fabs(H3_EXPORT(latLngDistanceRads)(&p1, &p2) - H3_EXPORT(degsToRads)(10)) < EPSILON_RAD * 1000, "distance along longitude as expected"); } @@ -184,14 +184,14 @@ SUITE(latLng) { double distance = H3_EXPORT(degsToRads)(15); _geoAzDistanceRads(&start, azimuth, distance, &out); - t_assert(fabs(H3_EXPORT(distanceRads)(&start, &out) - distance) < + t_assert(fabs(H3_EXPORT(latLngDistanceRads)(&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(latLngDistanceRads)(&start, &out) < 0.01, "moved back to origin"); } @@ -199,10 +199,10 @@ SUITE(latLng) { 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(latLngDistanceRads)( + &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(latLngDistanceRads)( &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 index 20d135c3e..e59ee31b0 100644 --- a/src/h3lib/include/h3api.h.in +++ b/src/h3lib/include/h3api.h.in @@ -319,14 +319,14 @@ DECLSPEC double H3_EXPORT(radsToDegs)(double radians); * @{ */ /** @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(latLngDistanceRads)(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(latLngDistanceKm)(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(latLngDistanceM)(const LatLng *a, const LatLng *b); /** @} */ /** @defgroup getHexagonAreaAvg getHexagonAreaAvg diff --git a/src/h3lib/lib/bbox.c b/src/h3lib/lib/bbox.c index de46bc5d8..cdc4df21b 100644 --- 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(latLngDistanceKm)(&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(latLngDistanceKm)(&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(latLngDistanceKm)(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 index 739bc1fee..e4d4f0a24 100644 --- 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(latLngDistanceRads)(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(latLngDistanceKm)(const LatLng *a, const LatLng *b) { + return H3_EXPORT(latLngDistanceRads)(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(latLngDistanceM)(const LatLng *a, const LatLng *b) { + return H3_EXPORT(latLngDistanceKm)(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(latLngDistanceRads)(a, b), + H3_EXPORT(latLngDistanceRads)(b, c), + H3_EXPORT(latLngDistanceRads)(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(latLngDistanceRads)(&cb.verts[i], &cb.verts[i + 1]); } return E_SUCCESS; From ba5665fed4665f6dde9e01bf5590d17ead493415 Mon Sep 17 00:00:00 2001 From: Nick Rabinowitz Date: Tue, 5 Jul 2022 16:46:40 -0700 Subject: [PATCH 2/5] Add to CHANGELOG, update docs, update upgrade instructions --- CHANGELOG.md | 2 ++ src/apps/testapps/testH3CellAreaExhaustive.c | 6 ++-- website/docs/api/misc.mdx | 36 +++++++++---------- .../docs/library/migration-3.x/functions.md | 33 +++++++++-------- 4 files changed, 41 insertions(+), 36 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 00fdab658..9669b600d 100644 --- 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 `latLngDistance*`. (#622) ## [4.0.0-rc3] - 2022-06-03 ### Fixed diff --git a/src/apps/testapps/testH3CellAreaExhaustive.c b/src/apps/testapps/testH3CellAreaExhaustive.c index e4e408c7e..92f205c2e 100644 --- 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 + * latLngDistanceRads + * latLngDistanceKm + * latLngDistanceM * * @param edge H3 directed edge denoting neighboring cells */ diff --git a/website/docs/api/misc.mdx b/website/docs/api/misc.mdx index 61eb5142f..12bba9e2e 100644 --- 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 +## latLngDistanceKm ```c -double distanceKm(const LatLng *a, const LatLng *b); +double latLngDistanceKm(const LatLng *a, const LatLng *b); ``` ```py -h3.distance(point1, point2, unit='km') +h3.lat_lng_distance(point1, point2, unit='km') ``` ```java -double distance(LatLng point1, LatLng point2, LengthUnit unit); +double latLngDistance(LatLng point1, LatLng point2, LengthUnit unit); ``` ```js -h3.distance(point1, point2, h3.UNITS.km) +h3.latLngDistance(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.latLngDistance(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 +## latLngDistanceM ```c -double distanceM(const LatLng *a, const LatLng *b); +double latLngDistanceM(const LatLng *a, const LatLng *b); ``` ```py -h3.distance(point1, point2, unit='m') +h3.lat_lng_distance(point1, point2, unit='m') ``` ```java -double distance(LatLng point1, LatLng point2, LengthUnit unit); +double latLngDistance(LatLng point1, LatLng point2, LengthUnit unit); ``` ```js -h3.distance(point1, point2, h3.UNITS.m) +h3.latLngDistance(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.latLngDistance(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 +## latLngDistanceRads ```c -double distanceRads(const LatLng *a, const LatLng *b); +double latLngDistanceRads(const LatLng *a, const LatLng *b); ``` ```py -h3.distance(point1, point2, unit='rads') +h3.lat_lng_distance(point1, point2, unit='rads') ``` ```java -double distance(LatLng point1, LatLng point2, LengthUnit unit); +double latLngDistance(LatLng point1, LatLng point2, LengthUnit unit); ``` ```js -h3.distance(point1, point2, h3.UNITS.rads) +h3.latLngDistance(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.latLngDistance(point1, point2, h3.UNITS.rads) } ``` diff --git a/website/docs/library/migration-3.x/functions.md b/website/docs/library/migration-3.x/functions.md index c7f684eb4..b2ae17de4 100644 --- a/website/docs/library/migration-3.x/functions.md +++ b/website/docs/library/migration-3.x/functions.md @@ -27,8 +27,8 @@ The following function and structure names changed from 3.x to 4.0.0: | `h3GetResolution` | `getResolution` | | *DNE* | `getMode` | | `h3GetFaces` | `getIcosahedronFaces` | -| `geoToH3` | `latLngToCell` | -| `h3ToGeo` | `cellToLatLng` | +| `geoToH3` | `latLngToCell` | +| `h3ToGeo` | `cellToLatLng` | | `compact` | `compactCells` | | `uncompact` | `uncompactCells` | | `polyfill` | `polygonToCells` | @@ -123,16 +123,19 @@ For a future undirected edge mode, use the term `Edge`. ### Area/Length Functions -| 3.x name. | 4.0.0 name | -|----------------|-----------------------------| -| `hexAreaKm2` | `getHexagonAreaAvgKm2` | -| `hexAreaM2` | `getHexagonAreaAvgM2` | -| `edgeLengthKm` | `getHexagonEdgeLengthAvgKm` | -| `edgeLengthM` | `getHexagonEdgeLengthAvgM` | -| *DNE* | `getPentagonAreaAvg*` | -| *DNE* | `getPentagonEdgeLengthAvg*` | -| *DNE* | `cellAreaKm2` | -| *DNE* | `cellAreaM2` | +| 3.x name. | 4.0.0 name | +|-----------------|-----------------------------| +| `hexAreaKm2` | `getHexagonAreaAvgKm2` | +| `hexAreaM2` | `getHexagonAreaAvgM2` | +| `edgeLengthKm` | `getHexagonEdgeLengthAvgKm` | +| `edgeLengthM` | `getHexagonEdgeLengthAvgM` | +| *DNE* | `getPentagonAreaAvg*` | +| *DNE* | `getPentagonEdgeLengthAvg*` | +| *DNE* | `cellAreaKm2` | +| *DNE* | `cellAreaM2` | +| `pointDistKm` | `latLngDistanceKm` | +| `pointDistM` | `latLngDistanceM` | +| `pointDistRads` | `latLngDistanceRads` | **Note**: `cellAreaKm2` and `cellAreaM2` would return the actual area of the passed-in cell. @@ -145,9 +148,9 @@ the passed-in cell. | 3.x name | 4.0.0 name | Notes | |-------------------|-------------------|-----------------------------------| -| `GeoBoundary` | `CellBoundary` | <= 10 stack-allocated `LatLng`s | -| `GeoCoord` | `LatLng` | | -| `Geofence` | `GeoLoop` | heap-allocated `LatLng`s | +| `GeoBoundary` | `CellBoundary` | <= 10 stack-allocated `LatLng`s | +| `GeoCoord` | `LatLng` | | +| `Geofence` | `GeoLoop` | heap-allocated `LatLng`s | | `GeoPolygon` | `GeoPolygon` | | | `GeoMultiPolygon` | `GeoMultiPolygon` | currently not used | From 127b92eb27db2fb5c423e7488bec412e63698093 Mon Sep 17 00:00:00 2001 From: Nick Rabinowitz Date: Tue, 5 Jul 2022 16:48:33 -0700 Subject: [PATCH 3/5] Update Python lat_lng -> latlng --- website/docs/api/misc.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/api/misc.mdx b/website/docs/api/misc.mdx index 12bba9e2e..1d38a6b31 100644 --- a/website/docs/api/misc.mdx +++ b/website/docs/api/misc.mdx @@ -920,7 +920,7 @@ double latLngDistanceKm(const LatLng *a, const LatLng *b); ```py -h3.lat_lng_distance(point1, point2, unit='km') +h3.latlng_distance(point1, point2, unit='km') ``` @@ -973,7 +973,7 @@ double latLngDistanceM(const LatLng *a, const LatLng *b); ```py -h3.lat_lng_distance(point1, point2, unit='m') +h3.latlng_distance(point1, point2, unit='m') ``` @@ -1026,7 +1026,7 @@ double latLngDistanceRads(const LatLng *a, const LatLng *b); ```py -h3.lat_lng_distance(point1, point2, unit='rads') +h3.latlng_distance(point1, point2, unit='rads') ``` From 85dbfe5a7005ebd5a6bf27c16edc409f77ae71e9 Mon Sep 17 00:00:00 2001 From: Nick Rabinowitz Date: Tue, 5 Jul 2022 17:16:03 -0700 Subject: [PATCH 4/5] Update @defgroup name --- src/h3lib/include/h3api.h.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/h3lib/include/h3api.h.in b/src/h3lib/include/h3api.h.in index e59ee31b0..9afd5d31f 100644 --- a/src/h3lib/include/h3api.h.in +++ b/src/h3lib/include/h3api.h.in @@ -314,7 +314,7 @@ DECLSPEC double H3_EXPORT(degsToRads)(double degrees); DECLSPEC double H3_EXPORT(radsToDegs)(double radians); /** @} */ -/** @defgroup distance distance +/** @defgroup latLngDistance latLngDistance * Functions for distance * @{ */ From 57ac6c7f6b14a526caaa4b9c26000b4997f244d5 Mon Sep 17 00:00:00 2001 From: Nick Rabinowitz Date: Wed, 13 Jul 2022 13:52:19 -0700 Subject: [PATCH 5/5] Change latLngDistance to greatCircleDistance --- CHANGELOG.md | 2 +- src/apps/fuzzers/fuzzerDistances.c | 6 ++-- src/apps/testapps/testH3CellAreaExhaustive.c | 26 +++++++-------- src/apps/testapps/testLatLng.c | 17 +++++----- src/h3lib/include/h3api.h.in | 11 ++++--- src/h3lib/lib/bbox.c | 6 ++-- src/h3lib/lib/latLng.c | 18 +++++------ website/docs/api/misc.mdx | 32 +++++++++---------- .../docs/library/migration-3.x/functions.md | 6 ++-- 9 files changed, 64 insertions(+), 60 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9669b600d..7ca382074 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,7 @@ The public API of this library consists of the functions declared in file ## [Unreleased] ### Breaking changes -- `distance*` functions (`distanceKm`, etc) renamed to `latLngDistance*`. (#622) +- `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 index 1d9065415..16b41566a 100644 --- 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(latLngDistanceRads)(&args->a, &args->b); - H3_EXPORT(latLngDistanceKm)(&args->a, &args->b); - H3_EXPORT(latLngDistanceM)(&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 index 92f205c2e..d0e5c1e6d 100644 --- 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: - * latLngDistanceRads - * latLngDistanceKm - * latLngDistanceM + * greatCircleDistanceRads + * greatCircleDistanceKm + * greatCircleDistanceM * * @param edge H3 directed edge denoting neighboring cells */ @@ -55,26 +55,26 @@ static void haversine_assert(H3Index edge) { double ab, ba; - ab = H3_EXPORT(latLngDistanceRads)(&a, &b); - ba = H3_EXPORT(latLngDistanceRads)(&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(latLngDistanceKm)(&a, &b); - ba = H3_EXPORT(latLngDistanceKm)(&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(latLngDistanceM)(&a, &b); - ba = H3_EXPORT(latLngDistanceM)(&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(latLngDistanceKm)(&a, &b) > - H3_EXPORT(latLngDistanceRads)(&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(latLngDistanceM)(&a, &b) > - H3_EXPORT(latLngDistanceKm)(&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 index 07d0f1c64..e500a26b4 100644 --- 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(latLngDistanceRads)(&p1, &p1) < EPSILON_RAD * 1000, - "0 distance as expected"); - t_assert(fabs(H3_EXPORT(latLngDistanceRads)(&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,14 +185,14 @@ SUITE(latLng) { double distance = H3_EXPORT(degsToRads)(15); _geoAzDistanceRads(&start, azimuth, distance, &out); - t_assert(fabs(H3_EXPORT(latLngDistanceRads)(&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(latLngDistanceRads)(&start, &out) < 0.01, + t_assert(H3_EXPORT(greatCircleDistanceRads)(&start, &out) < 0.01, "moved back to origin"); } @@ -199,10 +200,10 @@ SUITE(latLng) { 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(latLngDistanceRads)( + 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(latLngDistanceRads)( + 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 index 9afd5d31f..a55d84755 100644 --- 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 latLngDistance latLngDistance +/** @defgroup greatCircleDistance greatCircleDistance * Functions for distance * @{ */ /** @brief "great circle distance" between pairs of LatLng points in radians*/ -DECLSPEC double H3_EXPORT(latLngDistanceRads)(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(latLngDistanceKm)(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(latLngDistanceM)(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 index cdc4df21b..8576c4948 100644 --- 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(latLngDistanceKm)(&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(latLngDistanceKm)(&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(latLngDistanceKm)(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 index e4d4f0a24..923ef28b7 100644 --- 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(latLngDistanceRads)(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(latLngDistanceRads)(const LatLng *a, const LatLng *b) { /** * The great circle distance in kilometers between two spherical coordinates. */ -double H3_EXPORT(latLngDistanceKm)(const LatLng *a, const LatLng *b) { - return H3_EXPORT(latLngDistanceRads)(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(latLngDistanceM)(const LatLng *a, const LatLng *b) { - return H3_EXPORT(latLngDistanceKm)(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(latLngDistanceRads)(a, b), - H3_EXPORT(latLngDistanceRads)(b, c), - H3_EXPORT(latLngDistanceRads)(c, a)); + return triangleEdgeLengthsToArea(H3_EXPORT(greatCircleDistanceRads)(a, b), + H3_EXPORT(greatCircleDistanceRads)(b, c), + H3_EXPORT(greatCircleDistanceRads)(c, a)); } /** @@ -438,7 +438,7 @@ H3Error H3_EXPORT(exactEdgeLengthRads)(H3Index edge, double *length) { *length = 0.0; for (int i = 0; i < cb.numVerts - 1; i++) { *length += - H3_EXPORT(latLngDistanceRads)(&cb.verts[i], &cb.verts[i + 1]); + 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 index 1d38a6b31..cbf6f45d2 100644 --- 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. -## latLngDistanceKm +## greatCircleDistanceKm ```c -double latLngDistanceKm(const LatLng *a, const LatLng *b); +double greatCircleDistanceKm(const LatLng *a, const LatLng *b); ``` ```py -h3.latlng_distance(point1, point2, unit='km') +h3.great_circle_distance(point1, point2, unit='km') ``` ```java -double latLngDistance(LatLng point1, LatLng point2, LengthUnit unit); +double greatCircleDistance(LatLng point1, LatLng point2, LengthUnit unit); ``` ```js -h3.latLngDistance(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.latLngDistance(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. -## latLngDistanceM +## greatCircleDistanceM ```c -double latLngDistanceM(const LatLng *a, const LatLng *b); +double greatCircleDistanceM(const LatLng *a, const LatLng *b); ``` @@ -980,21 +980,21 @@ h3.latlng_distance(point1, point2, unit='m') ```java -double latLngDistance(LatLng point1, LatLng point2, LengthUnit unit); +double greatCircleDistance(LatLng point1, LatLng point2, LengthUnit unit); ``` ```js -h3.latLngDistance(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.latLngDistance(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. -## latLngDistanceRads +## greatCircleDistanceRads ```c -double latLngDistanceRads(const LatLng *a, const LatLng *b); +double greatCircleDistanceRads(const LatLng *a, const LatLng *b); ``` @@ -1033,21 +1033,21 @@ h3.latlng_distance(point1, point2, unit='rads') ```java -double latLngDistance(LatLng point1, LatLng point2, LengthUnit unit); +double greatCircleDistance(LatLng point1, LatLng point2, LengthUnit unit); ``` ```js -h3.latLngDistance(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.latLngDistance(point1, point2, h3.UNITS.rads) + return h3.greatCircleDistance(point1, point2, h3.UNITS.rads) } ``` diff --git a/website/docs/library/migration-3.x/functions.md b/website/docs/library/migration-3.x/functions.md index b2ae17de4..9231647c2 100644 --- a/website/docs/library/migration-3.x/functions.md +++ b/website/docs/library/migration-3.x/functions.md @@ -133,9 +133,9 @@ For a future undirected edge mode, use the term `Edge`. | *DNE* | `getPentagonEdgeLengthAvg*` | | *DNE* | `cellAreaKm2` | | *DNE* | `cellAreaM2` | -| `pointDistKm` | `latLngDistanceKm` | -| `pointDistM` | `latLngDistanceM` | -| `pointDistRads` | `latLngDistanceRads` | +| `pointDistKm` | `greatCircleDistanceKm` | +| `pointDistM` | `greatCircleDistanceM` | +| `pointDistRads` | `greatCircleDistanceRads` | **Note**: `cellAreaKm2` and `cellAreaM2` would return the actual area of the passed-in cell.