GeoPoint -> LatLng (#466)

* H3_EXPORT(pointToCell)

* find: pointToCell

* formatting

* find pointToCell in .md, .h.in, .txt

* filename change

* find: H3_EXPORT(cellToPoint)

* find: cellToPoint in .c

* find cellToPoint in *.txt, *.md

* filename changes

* cmake

* formatting

* rename files

* vertexToPoint

* LinkedGeoPoint

* formatting

* move `*`

* move `*` again

* eh, whatever, formatter

* find: GeoPoint in *.c,*.h,*.h.in

* formatting

* remaining GeoPoints

* filename changes

* lonDegs

* lonRads

* coslon and sinlon

* lat/lon -> lat/lng

* few more lat/lons

* E_LATLON_DOMAIN

* LatLon

* invalidLon

* a few stray `Lon `s

* minPosLon and maxNegLon

* minLon and maxLon

* `lon`s in polygonAlgos.h

* _LON

* stray `lon`s in latLngToCell.c

* posLatPosLon and negLatPosLon

* `lon=` and `lon;`

* some text locations

* in error-handling-rfc

* .lon

* ->lon

* `LatLng` struct in h3api.h.in

* let's not change the 3.x docs

* changelog

* updating the terminology rfc

* update copyright year

* update copyright year

* cite terminology RFC

* lat/lng in docs terminology page

* placeholder python names

* some dangling GeoCoord changes

* meh

* distanceRads

* pointDistKm

* pointDistM

* docs

* filter names

* latLngToCell in docs in a few more places

* docs filenames for latLngToCell

* h3ToGeoBoundary to cellToBoundary

* h3ToGeoDesc

* h3ToGeoDesc.md to cellToLatLngDesc.md

* formatting

* h3ToGeo in a few more places

* can't change the "js live" examples before the JS bindings update

* D -> d in version-3.x sidebards

* relative path seems to fix `Error: Docusaurus found broken links!`

* Revert "can't change the "js live" examples before the JS bindings update"

This reverts commit 25cb2c3.

* notes on cleaning up the website

* outputLngLatKML

* change weird LatLng variable name

* latLngToCellDesc

* remove website cleanup notes

Author: ajfriend

CHANGELOG.md

@@ -16,8 +16,14 @@ The public API of this library consists of the functions declared in file
 - closed-form implementation of `numHexagons`
 
 ### Breaking changes
-- rename `maxH3ToChildrenSize` to `cellToChildrenSize`
+- rename functions according to the terminology RFC (#403, #466)
 - `cellToChildrenSize` to output `int64_t` instead of `int`
+- `pointDistRads` to `distanceRads`
+- `pointDistKm` to `distanceKm`
+- `pointDistM` to `distanceM`
+
+### Other changes
+- generally use `lng` instead of `lon`
 
 ## [3.7.1] - 2020-10-05
 ### Fixed

CMakeLists.txt

@@ -106,7 +106,7 @@ set(LIB_SOURCE_FILES
     src/h3lib/include/polygonAlgos.h
     src/h3lib/include/h3Index.h
     src/h3lib/include/directedEdge.h
-    src/h3lib/include/geoPoint.h
+    src/h3lib/include/latLng.h
     src/h3lib/include/vec2d.h
     src/h3lib/include/vec3d.h
     src/h3lib/include/linkedGeo.h
@@ -129,7 +129,7 @@ set(LIB_SOURCE_FILES
     src/h3lib/lib/vertex.c
     src/h3lib/lib/linkedGeo.c
     src/h3lib/lib/localij.c
-    src/h3lib/lib/geoPoint.c
+    src/h3lib/lib/latLng.c
     src/h3lib/lib/directedEdge.c
     src/h3lib/lib/mathExtensions.c
     src/h3lib/lib/iterators.c
@@ -154,11 +154,11 @@ set(EXAMPLE_SOURCE_FILES
     examples/compactCells.c
     examples/edge.c)
 set(OTHER_SOURCE_FILES
-    src/apps/filters/cellToPoint.c
+    src/apps/filters/cellToLatLng.c
     src/apps/filters/h3ToLocalIj.c
     src/apps/filters/localIjToH3.c
     src/apps/filters/h3ToComponents.c
-    src/apps/filters/pointToCell.c
+    src/apps/filters/latLngToCell.c
     src/apps/filters/cellToBoundary.c
     src/apps/filters/gridDisk.c
     src/apps/filters/gridDiskUnsafe.c
@@ -172,15 +172,15 @@ set(OTHER_SOURCE_FILES
     src/apps/testapps/testCellToParent.c
     src/apps/testapps/testH3Index.c
     src/apps/testapps/mkRandGeoBoundary.c
-    src/apps/testapps/testPointToCell.c
+    src/apps/testapps/testLatLngToCell.c
     src/apps/testapps/testH3NeighborRotations.c
     src/apps/testapps/testCellToChildrenSize.c
     src/apps/testapps/testGridDisksUnsafe.c
-    src/apps/testapps/testCellToPoint.c
+    src/apps/testapps/testCellToLatLng.c
     src/apps/testapps/testCellToCenterChild.c
     src/apps/testapps/testCellToChildren.c
     src/apps/testapps/testGetIcosahedronFaces.c
-    src/apps/testapps/testGeoPoint.c
+    src/apps/testapps/testLatLng.c
     src/apps/testapps/testGridRingUnsafe.c
     src/apps/testapps/testH3SetToVertexGraph.c
     src/apps/testapps/testBBox.c
@@ -208,13 +208,13 @@ set(OTHER_SOURCE_FILES
     src/apps/testapps/testH3Memory.c
     src/apps/testapps/testH3Iterators.c
     src/apps/miscapps/cellToBoundaryHier.c
-    src/apps/miscapps/cellToPointHier.c
+    src/apps/miscapps/cellToLatLngHier.c
     src/apps/miscapps/generateBaseCellNeighbors.c
     src/apps/miscapps/generatePentagonDirectionFaces.c
     src/apps/miscapps/generateFaceCenterPoint.c
     src/apps/miscapps/h3ToHier.c
-    src/apps/fuzzers/fuzzerPointToCell.c
-    src/apps/fuzzers/fuzzerCellToPoint.c
+    src/apps/fuzzers/fuzzerLatLngToCell.c
+    src/apps/fuzzers/fuzzerCellToLatLng.c
     src/apps/fuzzers/fuzzerGridDisk.c
     src/apps/benchmarks/benchmarkPolygonToCells.c
     src/apps/benchmarks/benchmarkPolygon.c
@@ -378,16 +378,16 @@ if(BUILD_FILTERS)
         list(APPEND INSTALL_TARGETS ${name})
     endmacro()
 
-    add_h3_filter(pointToCell src/apps/filters/pointToCell.c ${APP_SOURCE_FILES})
+    add_h3_filter(latLngToCell src/apps/filters/latLngToCell.c ${APP_SOURCE_FILES})
     add_h3_filter(h3ToComponents src/apps/filters/h3ToComponents.c ${APP_SOURCE_FILES})
-    add_h3_filter(cellToPoint src/apps/filters/cellToPoint.c ${APP_SOURCE_FILES})
+    add_h3_filter(cellToLatLng src/apps/filters/cellToLatLng.c ${APP_SOURCE_FILES})
     add_h3_filter(h3ToLocalIj src/apps/filters/h3ToLocalIj.c ${APP_SOURCE_FILES})
     add_h3_filter(localIjToH3 src/apps/filters/localIjToH3.c ${APP_SOURCE_FILES})
     add_h3_filter(cellToBoundary src/apps/filters/cellToBoundary.c ${APP_SOURCE_FILES})
     add_h3_filter(gridDiskUnsafe src/apps/filters/gridDiskUnsafe.c ${APP_SOURCE_FILES})
     add_h3_filter(gridDisk src/apps/filters/gridDisk.c ${APP_SOURCE_FILES})
     add_h3_filter(cellToBoundaryHier src/apps/miscapps/cellToBoundaryHier.c ${APP_SOURCE_FILES})
-    add_h3_filter(cellToPointHier src/apps/miscapps/cellToPointHier.c ${APP_SOURCE_FILES})
+    add_h3_filter(cellToLatLngHier src/apps/miscapps/cellToLatLngHier.c ${APP_SOURCE_FILES})
     add_h3_filter(h3ToHier src/apps/miscapps/h3ToHier.c ${APP_SOURCE_FILES})
 
     # Generate KML files for visualizing the H3 grid
@@ -405,7 +405,7 @@ if(BUILD_FILTERS)
             VERBATIM
             DEPENDS create-kml-dir)
         add_custom_target(kml_centers_${resolution}
-            COMMAND ${SHELL} "$<TARGET_FILE:h3ToHier> -r ${resolution} | $<TARGET_FILE:cellToPoint> --kml --kml-name res${resolution}centers.kml --kml-description \"Res ${resolution} Centers\" > KML/res${resolution}centers.kml"
+            COMMAND ${SHELL} "$<TARGET_FILE:h3ToHier> -r ${resolution} | $<TARGET_FILE:cellToLatLng> --kml --kml-name res${resolution}centers.kml --kml-description \"Res ${resolution} Centers\" > KML/res${resolution}centers.kml"
             VERBATIM
             DEPENDS create-kml-dir)
         add_dependencies(kml
@@ -550,17 +550,17 @@ if(H3_IS_ROOT_PROJECT AND BUILD_TESTING)
     # Add each individual test
     file(GLOB all_centers tests/inputfiles/bc*centers.txt)
     foreach(file ${all_centers})
-        add_h3_test_with_file(testPointToCell src/apps/testapps/testPointToCell.c ${file})
+        add_h3_test_with_file(testLatLngToCell src/apps/testapps/testLatLngToCell.c ${file})
     endforeach()
 
     file(GLOB all_ic_files tests/inputfiles/res*ic.txt)
     foreach(file ${all_ic_files})
-        add_h3_test_with_file(testCellToPoint src/apps/testapps/testCellToPoint.c ${file})
+        add_h3_test_with_file(testCellToLatLng src/apps/testapps/testCellToLatLng.c ${file})
     endforeach()
 
     file(GLOB all_centers tests/inputfiles/rand*centers.txt)
     foreach(file ${all_centers})
-        add_h3_test_with_file(testPointToCell src/apps/testapps/testPointToCell.c ${file})
+        add_h3_test_with_file(testLatLngToCell src/apps/testapps/testLatLngToCell.c ${file})
     endforeach()
 
     file(GLOB all_cells tests/inputfiles/*cells.txt)
@@ -586,7 +586,7 @@ if(H3_IS_ROOT_PROJECT AND BUILD_TESTING)
     add_h3_test(testPolygonToCellsReported src/apps/testapps/testPolygonToCellsReported.c)
     add_h3_test(testVertexGraph src/apps/testapps/testVertexGraph.c)
     add_h3_test(testDirectedEdge src/apps/testapps/testDirectedEdge.c)
-    add_h3_test(testGeoPoint src/apps/testapps/testGeoPoint.c)
+    add_h3_test(testLatLng src/apps/testapps/testLatLng.c)
     add_h3_test(testBBox src/apps/testapps/testBBox.c)
     add_h3_test(testVertex src/apps/testapps/testVertex.c)
     add_h3_test(testPolygon src/apps/testapps/testPolygon.c)
@@ -632,8 +632,8 @@ if(BUILD_FUZZERS)
         add_dependencies(fuzzers ${name})
     endmacro()
 
-    add_h3_fuzzer(fuzzerPointToCell src/apps/fuzzers/fuzzerPointToCell.c)
-    add_h3_fuzzer(fuzzerCellToPoint src/apps/fuzzers/fuzzerCellToPoint.c)
+    add_h3_fuzzer(fuzzerLatLngToCell src/apps/fuzzers/fuzzerLatLngToCell.c)
+    add_h3_fuzzer(fuzzerCellToLatLng src/apps/fuzzers/fuzzerCellToLatLng.c)
     add_h3_fuzzer(fuzzerGridDisk src/apps/fuzzers/fuzzerGridDisk.c)
 endif()
 

README.md

@@ -152,15 +152,15 @@ To build the documentation website, see the [website/](./website/) directory.
 To get the H3 index for some location:
 
 ```
-./bin/geoToH3 --resolution 10 --latitude 40.689167 --longitude -74.044444
+./bin/latLngToCell --resolution 10 --latitude 40.689167 --longitude -74.044444
 ```
 
 10 is the H3 resolution, between 0 (coarsest) and 15 (finest). The coordinates entered are the latitude and longitude, in degrees, you want the index for (these coordinates are the Statue of Liberty).  You should get an H3 index as output, like `8a2a1072b59ffff`.
 
 You can then take this index and get some information about it, for example:
 
 ```
-./bin/h3ToGeoBoundary --index 8a2a1072b59ffff
+./bin/cellToBoundary --index 8a2a1072b59ffff
 ```
 
 This will produce the vertices of the hexagon at this location:
@@ -180,7 +180,7 @@ This will produce the vertices of the hexagon at this location:
 You can get the center coordinate of the hexagon like so:
 
 ```
-./bin/h3ToGeo --index 8a2a1072b59ffff
+./bin/cellToLatLng --index 8a2a1072b59ffff
 ```
 
 This will produce some coordinate:

dev-docs/RFCs/v4.0.0/error-handling-rfc.md

@@ -43,7 +43,7 @@ Sample:
 H3Error err;
 H3Index result;
 
-err = geoToH3(lat, lon, res, &result);
+err = latLngToCell(lat, lng, res, &result);
 if (err) {
     fprintf(stderr, "Error: %d", err);
 }
@@ -53,7 +53,7 @@ Sample with errors discarded:
 ```
 H3Index result;
 
-geoToH3(lat, lon, res, &result);
+latLngToCell(lat, lng, res, &result);
 ```
 
 Placing error information in the return of function calls requires that functions return two pieces of information - the error status, and the requested data. This approach does make it clear that a status code is returned and that may make it more usual that a consumer of the API does check the error status.
@@ -65,7 +65,7 @@ Sample:
 H3Error err;
 H3Index result;
 
-err = geoToH3(lat, lon, res, &result);
+err = latLngToCell(lat, lng, res, &result);
 if (err) {
     fprintf(stderr, "Error: %d", err);
 }
@@ -75,7 +75,7 @@ Sample with errors discarded:
 ```
 H3Index result;
 
-result = unsafe_geoToH3(lat, lon, res);
+result = unsafe_latLngToCell(lat, lng, res);
 ```
 
 This approach is the same as using return codes, but offers an "unsafe" version of some functions where there is less or no error information returned. This is intended to be used in performance critical cases where the inputs are known to be suitable ahead of time, or the caller would not do anything with the error information anyways.
@@ -87,7 +87,7 @@ Sample:
 H3Error err;
 H3Index result;
 
-err = geoToH3(lat, lon, res, &result);
+err = latLngToCell(lat, lng, res, &result);
 if (err) {
     const char* msg = h3GetError();
     fprintf(stderr, "Error: %d (%s)", err, msg);
@@ -105,7 +105,7 @@ Sample:
 H3Error err;
 H3Index result;
 
-result = geoToH3(lat, lon, res);
+result = latLngToCell(lat, lng, res);
 if (err = h3GetError()) {
     fprintf(stderr, "Error: %d", err);
 }
@@ -115,7 +115,7 @@ Sample with errors discarded:
 ```
 H3Index result;
 
-result = geoToH3(lat, lon, res);
+result = latLngToCell(lat, lng, res);
 ```
 
 In this approach, the data requested is returned from the function, and the consumer is responsible for knowing when to check for errors, and how to handle them. There are a few drawbacks:
@@ -131,7 +131,7 @@ Sample:
 H3Error err;
 H3Index result;
 
-result = geoToH3(lat, lon, res, &err);
+result = latLngToCell(lat, lng, res, &err);
 if (err) {
     fprintf(stderr, "Error: %d", err);    
 }
@@ -140,7 +140,7 @@ if (err) {
 Sample with errors discarded:
 ```
 H3Index result;
-result = geoToH3(lat, lon, res, NULL);
+result = latLngToCell(lat, lng, res, NULL);
 ```
 
 This is an inversion of the return code approach, where the error status is the reference parameter. This offers an advantage that a caller could choose to disregard the error status (for example by passing NULL)
@@ -156,7 +156,7 @@ int err;
 if (err = setjmp(env)) {
     fprintf(stderr, "Error: %d", err);
 } else {
-    result = geoToH3(lat, lon, res, env);
+    result = latLngToCell(lat, lng, res, env);
 }
 ```
 
@@ -176,9 +176,9 @@ It would be good to use a single pattern for error handling, so that callers do
 It is proposed that errors will be indicated by the return code of the function. Any public function that can return an
 error (for example, due to domain issues in its input) will return an error code.
 
-The signature for `geoToH3` will look like:
+The signature for `latLngToCell` will look like:
 ```
-H3Error geoToH3(double lat, double lon, int res, H3Index *result);
+H3Error latLngToCell(double lat, double lng, int res, H3Index *result);
 ```
 
 ### Is Valid Functions
@@ -243,7 +243,7 @@ SQLite's approach to this is to define broad error categories (in 8 bits), and t
 | 0     | E_SUCCESS            | Success (no error)
 | 1     | E_FAILED             | The operation failed but a more specific error is not available
 | 2     | E_DOMAIN             | Argument was outside of acceptable range (when a more specific error code is not available)
-| 3     | E_LATLON_DOMAIN      | Latitude or longitude arguments were outside of acceptable range
+| 3     | E_LATLNG_DOMAIN      | Latitude or longitude arguments were outside of acceptable range
 | 4     | E_RES_DOMAIN         | Resolution argument was outside of acceptable range
 | 5     | E_CELL_INVALID       | `H3Index` cell argument was not valid
 | 6     | E_DIR_EDGE_INVALID   | `H3Index` directed edge argument was not valid
@@ -261,9 +261,9 @@ The H3 library may always add additional error messages. Error messages not reco
 #### Example error code results
 
 ```
-geoToH3(lat=Infinity, lon=0, res=0, &out) => E_LATLON_DOMAIN
-geoToH3(lat=0, lat=0, res=-1, &out) => E_RES_DOMAIN
-h3ToGeo(index=0, &out) => E_CELL_INVALID
+latLngToCell(lat=Infinity, lng=0, res=0, &out) => E_LATLNG_DOMAIN
+latLngToCell(lat=0, lat=0, res=-1, &out) => E_RES_DOMAIN
+cellToLatLng(index=0, &out) => E_CELL_INVALID
 h3IsResClassIII(index=RES_0_INDEX, &out) => E_SUCCESS
 h3IsResClassIII(index=RES_1_INDEX, &out) => E_SUCCESS
 h3IsResClassIII(index=0, &out) => E_CELL_INVALID
@@ -273,7 +273,7 @@ hexRange(origin=AN_INDEX, k=-1, &out) => E_DOMAIN
 hexRange(origin=PENTAGON_INDEX, k=1, &out) => E_PENTAGON
 # Failed to allocate internal buffer:
 kRing(origin=AN_INDEX, k=1, &out) => E_MEMORY
-pointDistRads({Infinity, Infinity}, {0, 0}, &out) => E_LATLON_DOMAIN
+distanceRads({Infinity, Infinity}, {0, 0}, &out) => E_LATLNG_DOMAIN
 hexAreaKm2(res=-1) => E_RES_DOMAIN
 # Cannot parse:
 stringToH3(str="zzzz", &out) => E_FAILED

dev-docs/RFCs/v4.0.0/names_for_concepts_types_functions.md

@@ -52,7 +52,7 @@ The following technical terms should be used in the documentation, the H3 codeba
 - **grid**:
     - the graph with nodes corresponding to H3 cells, and edges given by pairs of adjacent cells
     - for example, `gridDistance` is the minimal number of edges in a graph path connecting two cells
-- **point**:
+- **lat/lng point**:
     - a representation of a geographic point in terms of a latitude/longitude pair
 - **topological**:
     - H3 cells are **topological** pentagons or hexagons, in the sense that they have 5 or 6 neighbors, respectively, in the H3 **grid**
@@ -66,7 +66,7 @@ The following technical terms should be used in the documentation, the H3 codeba
     - there is a one-to-one correspondence between the "base cell number" and the `H3Index` representation of resolution `0` cells
         + e.g., base cell 0 has `H3Index` hexadecimal representation `'8001fffffffffff'`
 - **boundary**:
-    - all or part of the list of geometric points that enclose an H3 cell
+    - all or part of the list of lat/lng points that enclose an H3 cell
     - may include more than 6 points in the case that a cell is not a geometric hexagon, such as when a hexagon crosses an icosahedron boundary
     - may also be used to describe the boundary between two geometric cells, as in the case of an edge
     - represented in the H3 codebase with the `CellBoundary` struct (previously `GeoBoundary` before v4.0)
@@ -100,7 +100,7 @@ The proposed prefix is `h3_`.
     + object properties (`getResolution`, `getBaseCellNumber`)
 - use `to` to denote transforms
     + different representations of the same object
-    + when doing a lossy transformation to a new object (`cellToParent`, `pointToCell`, `polygonToCells`)
+    + when doing a lossy transformation to a new object (`cellToParent`, `latLngToCell`, `polygonToCells`)
 - do not use `get` or `to` for *computations*
     + e.g., `compactCells`, `cellAreaKm2`
 
@@ -139,8 +139,8 @@ There is some ambiguity between property, transform, and computation, so use you
 | `h3GetResolution`             | `getResolution`       |
 | *DNE*                         | `getMode`             |
 | `h3GetFaces`                  | `getIcosahedronFaces` |
-| `geoToH3`                     | `pointToCell`         |
-| `h3ToGeo`                     | `cellToPoint`         |
+| `geoToH3`                     | `latLngToCell`        |
+| `h3ToGeo`                     | `cellToLatLng`        |
 | `compact`                     | `compactCells`        |
 | `uncompact`                   | `uncompactCells`      |
 | `polyfill`                    | `polygonToCells`      |
@@ -260,13 +260,13 @@ discussion requiring benchmarking, so we will defer that to a
 
 - rename `GeoBoundary` to `CellBoundary` to indicate it is space-limited to describing the geometry of cells
 
-|    Current name   |   Proposed name   |               Notes               |
-|-------------------|-------------------|-----------------------------------|
-| `GeoBoundary`     | `CellBoundary`    | <= 10 stack-allocated `GeoPoint`s |
-| `GeoCoord`        | `GeoPoint`        |                                   |
-| `Geofence`        | `GeoLoop`         | heap-allocated `GeoPoint`s        |
-| `GeoPolygon`      | `GeoPolygon`      |                                   |
-| `GeoMultiPolygon` | `GeoMultiPolygon` | currently not used                |
+|    Current name   |   Proposed name   |              Notes              |
+|-------------------|-------------------|---------------------------------|
+| `GeoCoord`        | `LatLng`          |                                 |
+| `GeoBoundary`     | `CellBoundary`    | <= 10 stack-allocated `LatLng`s |
+| `Geofence`        | `GeoLoop`         | heap-allocated `LatLng`s        |
+| `GeoPolygon`      | `GeoPolygon`      |                                 |
+| `GeoMultiPolygon` | `GeoMultiPolygon` | currently not used              |
 
 
 ### Functions

dev-docs/RFCs/v4.0.0/vertex-mode-rfc.md

@@ -13,8 +13,8 @@ This proposal would add a new H3 index mode, Vertex Mode, to provide a canonical
 The advantages of this approach:
 
 * Shared vertices can be compared between hexagons with a strict equality check
-* Vertices can be represented and stored without the trig calls required to produce a lat/lon point
-* Vertex to lat/lon can be guaranteed to return the same result across different cells that share the vertex
+* Vertices can be represented and stored without the trig calls required to produce a lat/lng point
+* Vertex to lat/lng can be guaranteed to return the same result across different cells that share the vertex
 
 At a minimum, this should open up significant performance and correctness gains in `h3SetToLinkedGeo` and `directedEdgeToBoundary`, and there are likely other uses as well.
 
@@ -47,4 +47,4 @@ Proposed simple algorithm for determining ownership:
 
 * `void getCellVertexes(H3Index cell, H3Vertex *vertices)`
 * `H3Vertex getCellVertex(H3Index cell, int vertIndex)`
-* `GeoCoord vertexToGeoPoint(H3Vertex vertex)`
+* `LatLng vertexToLatLng(H3Vertex vertex)`