h3 3.5.0 → 3.7.1

data/ext/h3/src/CHANGELOG.md

@@ -7,6 +7,66 @@ The public API of this library consists of the functions declared in file
 
 ## [Unreleased]
 
+## [3.7.1] - 2020-10-05
+### Fixed
+- Finding invalid edge boundaries should not crash. (#399)
+- Build fixes for FreeBSD. (#397)
+
+## [3.7.0] - 2020-09-28
+### Added
+- Area and haversine distance functions (#377):
+    - `cellAreaRads2`
+    - `cellAreaKm2`
+    - `cellAreaM2`
+    - `pointDistRads`
+    - `pointDistKm`
+    - `pointDistM`
+    - `exactEdgeLengthRads`
+    - `exactEdgeLengthKm`
+    - `exactEdgeLengthM`
+- Refactor `getH3UnidirectionalEdgeBoundary` for accuracy at small resolutions. (#391)
+    - Speeds up `getH3UnidirectionalEdgeBoundary` by about 3x.
+    - Implement core logic for future vertex mode.
+### Fixed
+- Fixed building the library with custom memory allocation functions on Mac OSX. (#362)
+- The installed H3 CMake target should have include directories specified. (#381)
+### Changed
+- Tests now use `bash` on Windows. (#381)
+
+## [3.6.4] - 2020-06-19
+### Added
+- `H3_MEMORY_PREFIX` CMake option for replacing the memory management functions used in H3. (#317)
+- Support for building Debian packages of H3. (#352)
+### Fixed
+- Removed duplicate include statements. (#333)
+- Fixed macro `H3_DIGIT_MASK_NEGATIVE`. (#329)
+## Changed
+- Again implement new `polyfill` algorithm. (#313)
+
+## [3.6.3] - 2020-01-21
+### Fixed
+- `compact` detects and fails on cases with duplicated input indexes. (#299)
+### Changed
+- `h3IsValid` returns false for indexes that have non-zero reserved bits. (#300)
+- `h3IsValid` and `h3UnidirectionalEdgeIsValid` return false for indexes with the high bit set. (#300)
+
+## [3.6.2] - 2019-12-9
+- Revert new `polyfill` algorithm until reported issues are fixed. (#293)
+
+## [3.6.1] - 2019-11-11
+### Fixed
+- `compact` handles zero length input correctly. (#278)
+- `bboxHexRadius` scaling factor adjusted to guarantee containment for `polyfill`. (#279)
+- `polyfill` new algorithm for up to 3x perf boost. (#282)
+- Fix CMake targets for KML generation. (#285)
+
+## [3.6.0] - 2019-08-12
+### Added
+- `h3ToCenterChild` function to find center child at given resolution (#267)
+- `getPentagonIndexes` (and `pentagonIndexCount`) function to find pentagons at given resolution (#267)
+### Fixed
+- Fix bounds check for local IJ coordinates (#271)
+
 ## [3.5.0] - 2019-07-22
 ### Added
 - CMake options for excluding filter applications or benchmarks from the build. (#247)

data/ext/h3/src/CMakeLists.txt

@@ -1,4 +1,4 @@
-# Copyright 2017-2019 Uber Technologies, Inc.
+# Copyright 2017-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.
@@ -15,6 +15,7 @@
 cmake_minimum_required(VERSION 3.1)
 
 set(H3_PREFIX "" CACHE STRING "Prefix for exported symbols")
+set(H3_ALLOC_PREFIX "" CACHE STRING "Prefix for allocation functions")
 
 # Needed due to CMP0042
 set(CMAKE_MACOSX_RPATH 1)
@@ -34,7 +35,8 @@ option(BUILD_FILTERS "Build filter applications." ON)
 option(BUILD_GENERATORS "Build code generation applications." ON)
 
 if(WIN32)
-    set(SHELL PowerShell -Command)
+    # Use bash (usually from Git for Windows) for piping results
+    set(SHELL bash -c)
 
     set(EXECUTABLE_OUTPUT_PATH bin)
     set(LIBRARY_OUTPUT_PATH bin)
@@ -107,6 +109,7 @@ set(LIB_SOURCE_FILES
     src/h3lib/lib/h3Index.c
     src/h3lib/lib/vec2d.c
     src/h3lib/lib/vec3d.c
+    src/h3lib/lib/vertex.c
     src/h3lib/lib/linkedGeo.c
     src/h3lib/lib/localij.c
     src/h3lib/lib/geoCoord.c
@@ -143,6 +146,8 @@ set(OTHER_SOURCE_FILES
     src/apps/testapps/testVertexGraph.c
     src/apps/testapps/testCompact.c
     src/apps/testapps/testPolyfill.c
+    src/apps/testapps/testPolyfillReported.c
+    src/apps/testapps/testPentagonIndexes.c
     src/apps/testapps/testKRing.c
     src/apps/testapps/testH3ToGeoBoundary.c
     src/apps/testapps/testH3ToParent.c
@@ -153,28 +158,38 @@ set(OTHER_SOURCE_FILES
     src/apps/testapps/testMaxH3ToChildrenSize.c
     src/apps/testapps/testHexRanges.c
     src/apps/testapps/testH3ToGeo.c
+    src/apps/testapps/testH3ToCenterChild.c
     src/apps/testapps/testH3ToChildren.c
     src/apps/testapps/testH3GetFaces.c
     src/apps/testapps/testGeoCoord.c
     src/apps/testapps/testHexRing.c
     src/apps/testapps/testH3SetToVertexGraph.c
     src/apps/testapps/testBBox.c
+    src/apps/testapps/testVertex.c
     src/apps/testapps/testPolygon.c
     src/apps/testapps/testVec2d.c
     src/apps/testapps/testVec3d.c
     src/apps/testapps/testH3UniEdge.c
+    src/apps/testapps/testH3UniEdgeExhaustive.c
     src/apps/testapps/testLinkedGeo.c
     src/apps/testapps/mkRandGeo.c
     src/apps/testapps/testH3Api.c
     src/apps/testapps/testH3SetToLinkedGeo.c
     src/apps/testapps/testH3ToLocalIj.c
+    src/apps/testapps/testH3ToLocalIjExhaustive.c
     src/apps/testapps/testH3Distance.c
+    src/apps/testapps/testH3DistanceExhaustive.c
     src/apps/testapps/testH3Line.c
+    src/apps/testapps/testH3LineExhaustive.c
+    src/apps/testapps/testH3CellArea.c
+    src/apps/testapps/testH3CellAreaExhaustive.c
     src/apps/testapps/testCoordIj.c
     src/apps/testapps/testCoordIjk.c
+    src/apps/testapps/testH3Memory.c
     src/apps/miscapps/h3ToGeoBoundaryHier.c
     src/apps/miscapps/h3ToGeoHier.c
     src/apps/miscapps/generateBaseCellNeighbors.c
+    src/apps/miscapps/generatePentagonDirectionFaces.c
     src/apps/miscapps/generateNumHexagons.c
     src/apps/miscapps/generateFaceCenterPoint.c
     src/apps/miscapps/h3ToHier.c
@@ -183,6 +198,7 @@ set(OTHER_SOURCE_FILES
     src/apps/benchmarks/benchmarkH3SetToLinkedGeo.c
     src/apps/benchmarks/benchmarkKRing.c
     src/apps/benchmarks/benchmarkH3Line.c
+    src/apps/benchmarks/benchmarkH3UniEdge.c
     src/apps/benchmarks/benchmarkH3Api.c)
 
 set(ALL_SOURCE_FILES
@@ -192,36 +208,55 @@ set(UNCONFIGURED_API_HEADER src/h3lib/include/h3api.h.in)
 set(CONFIGURED_API_HEADER src/h3lib/include/h3api.h)
 configure_file(${UNCONFIGURED_API_HEADER} ${CONFIGURED_API_HEADER})
 
-set(INSTALL_TARGETS h3)
+set(INSTALL_TARGETS)
 
-# Build the H3 library
-add_library(h3 ${LIB_SOURCE_FILES} ${CONFIGURED_API_HEADER})
+function(add_h3_library name h3_alloc_prefix_override)
+    add_library(${name} ${LIB_SOURCE_FILES} ${CONFIGURED_API_HEADER})
 
-target_compile_options(h3 PRIVATE ${H3_COMPILE_FLAGS})
-target_link_libraries(h3 PRIVATE ${H3_LINK_FLAGS})
+    target_compile_options(${name} PRIVATE ${H3_COMPILE_FLAGS})
+    target_link_libraries(${name} PRIVATE ${H3_LINK_FLAGS})
 
-find_library(M_LIB m)
-if(M_LIB)
-    target_link_libraries(h3 PUBLIC ${M_LIB})
-endif()
+    find_library(M_LIB m)
+    if(M_LIB)
+        target_link_libraries(${name} PUBLIC ${M_LIB})
+    endif()
 
-if(BUILD_SHARED_LIBS)
-    set_target_properties(h3 PROPERTIES SOVERSION ${H3_SOVERSION})
-endif()
+    if(BUILD_SHARED_LIBS)
+        set_target_properties(${name} PROPERTIES SOVERSION ${H3_SOVERSION})
+    endif()
 
-target_compile_definitions(h3 PUBLIC H3_PREFIX=${H3_PREFIX})
-if(have_alloca)
-    target_compile_definitions(h3 PUBLIC H3_HAVE_ALLOCA)
-endif()
-if(have_vla)
-    target_compile_definitions(h3 PUBLIC H3_HAVE_VLA)
-endif()
-target_include_directories(h3 PUBLIC
-    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src/h3lib/include>
-    $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/src/h3lib/include>)
+    target_compile_definitions(${name} PUBLIC H3_PREFIX=${H3_PREFIX})
+    set(has_alloc_prefix NO)
+    if(h3_alloc_prefix_override)
+        set(has_alloc_prefix YES)
+        target_compile_definitions(${name} PUBLIC H3_ALLOC_PREFIX=${h3_alloc_prefix_override})
+    elseif(H3_ALLOC_PREFIX)
+        set(has_alloc_prefix YES)
+        target_compile_definitions(${name} PUBLIC H3_ALLOC_PREFIX=${H3_ALLOC_PREFIX})
+    endif()
+    # Mac OSX defaults to not looking up undefined symbols dynamically,
+    # so enable that explicitly.
+    if(has_alloc_prefix AND APPLE)
+        target_link_libraries(${name} PRIVATE "-undefined dynamic_lookup")
+    endif()
+
+    if(have_alloca)
+        target_compile_definitions(${name} PUBLIC H3_HAVE_ALLOCA)
+    endif()
+    if(have_vla)
+        target_compile_definitions(${name} PUBLIC H3_HAVE_VLA)
+    endif()
+    target_include_directories(${name} PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src/h3lib/include>
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/src/h3lib/include>)
+endfunction()
+
+# Build the H3 library
+add_h3_library(h3 "")
 
 # Automatic code formatting
-find_program(CLANG_FORMAT_PATH clang-format)
+# Give preference to clang-format-9
+find_program(CLANG_FORMAT_PATH NAMES clang-format-9 clang-format)
 cmake_dependent_option(
     ENABLE_FORMAT "Enable running clang-format before compiling" ON
     "CLANG_FORMAT_PATH" OFF)
@@ -344,11 +379,11 @@ if(BUILD_FILTERS)
         set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "KML/res${resolution}cells.kml")
         set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "KML/res${resolution}centers.kml")
         add_custom_target(kml_cells_${resolution}
-            COMMAND ${SHELL} "$<TARGET_FILE:h3ToHier> ${resolution} | $<TARGET_FILE:h3ToGeoBoundary> 1 res${resolution}cells.kml \"Res ${resolution} Cells\" > KML/res${resolution}cells.kml"
+            COMMAND ${SHELL} "$<TARGET_FILE:h3ToHier> -r ${resolution} | $<TARGET_FILE:h3ToGeoBoundary> --kml --kml-name res${resolution}cells.kml --kml-description \"Res ${resolution} Cells\" > KML/res${resolution}cells.kml"
             VERBATIM
             DEPENDS create-kml-dir)
         add_custom_target(kml_centers_${resolution}
-            COMMAND ${SHELL} "$<TARGET_FILE:h3ToHier> ${resolution} | $<TARGET_FILE:h3ToGeo> 1 res${resolution}centers.kml \"Res ${resolution} Centers\" > KML/res${resolution}centers.kml"
+            COMMAND ${SHELL} "$<TARGET_FILE:h3ToHier> -r ${resolution} | $<TARGET_FILE:h3ToGeo> --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
@@ -360,6 +395,7 @@ endif()
 if(BUILD_GENERATORS)
     # Code generation
     add_h3_executable(generateBaseCellNeighbors src/apps/miscapps/generateBaseCellNeighbors.c ${APP_SOURCE_FILES})
+    add_h3_executable(generatePentagonDirectionFaces src/apps/miscapps/generatePentagonDirectionFaces.c ${APP_SOURCE_FILES})
     add_h3_executable(generateNumHexagons src/apps/miscapps/generateNumHexagons.c ${APP_SOURCE_FILES})
     add_h3_executable(generateFaceCenterPoint src/apps/miscapps/generateFaceCenterPoint.c ${APP_SOURCE_FILES})
 
@@ -393,6 +429,37 @@ if(BUILD_TESTING)
             )
     endif()
 
+    add_h3_library(h3WithTestAllocators test_prefix_)
+
+    macro(add_h3_memory_test name srcfile)
+        # Like other test code, but these need to be linked against
+        # a different copy of the H3 library which has known intercepted
+        # allocator functions.
+        add_executable(${ARGV} ${APP_SOURCE_FILES})
+
+        if(TARGET ${name})
+            target_link_libraries(${name} PUBLIC h3WithTestAllocators)
+            target_include_directories(${name} PUBLIC
+            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src/apps/applib/include>)
+            target_compile_options(${name} PRIVATE ${H3_COMPILE_FLAGS})
+            target_link_libraries(${name} PRIVATE ${H3_LINK_FLAGS})
+        endif()
+
+        math(EXPR test_number "${test_number}+1")
+
+        add_test(NAME ${name}_test${test_number} COMMAND ${TEST_WRAPPER} "$<TARGET_FILE:${name}>")
+
+        if(ENABLE_COVERAGE)
+            add_custom_target(${name}_coverage${test_number}
+                COMMAND ${name} > /dev/null
+                COMMENT "Running ${name}_coverage${test_number}"
+                )
+
+            add_dependencies(coverage ${name}_coverage${test_number})
+            add_dependencies(${name}_coverage${test_number} clean-coverage)
+        endif()
+    endmacro()
+
     macro(add_h3_test_common name srcfile)
         # need to actually make the test target
         if(NOT TARGET ${name})
@@ -420,11 +487,7 @@ if(BUILD_TESTING)
     macro(add_h3_test_with_file name srcfile argfile)
         add_h3_test_common(${name} ${srcfile})
         # add a special command (so we don't need to read the test file from the test program)
-        if(WIN32)
-            set(dump_command "Get-Content")
-        else()
-            set(dump_command "cat")
-        endif()
+        set(dump_command "cat")
 
         add_test(NAME ${name}_test${test_number}
                  COMMAND ${SHELL} "${dump_command} ${argfile} | ${TEST_WRAPPER_STR} $<TARGET_FILE:${name}>")
@@ -465,7 +528,6 @@ if(BUILD_TESTING)
     endmacro()
 
     # Add each individual test
-
     file(GLOB all_centers tests/inputfiles/bc*centers.txt)
     foreach(file ${all_centers})
         add_h3_test_with_file(testH3ToGeo src/apps/testapps/testH3ToGeo.c ${file})
@@ -491,6 +553,7 @@ if(BUILD_TESTING)
     add_h3_test(testHexRing src/apps/testapps/testHexRing.c)
     add_h3_test(testHexRanges src/apps/testapps/testHexRanges.c)
     add_h3_test(testH3ToParent src/apps/testapps/testH3ToParent.c)
+    add_h3_test(testH3ToCenterChild src/apps/testapps/testH3ToCenterChild.c)
     add_h3_test(testH3ToChildren src/apps/testapps/testH3ToChildren.c)
     add_h3_test(testH3GetFaces src/apps/testapps/testH3GetFaces.c)
     add_h3_test(testMaxH3ToChildrenSize src/apps/testapps/testMaxH3ToChildrenSize.c)
@@ -500,23 +563,39 @@ if(BUILD_TESTING)
     add_h3_test(testH3SetToVertexGraph src/apps/testapps/testH3SetToVertexGraph.c)
     add_h3_test(testLinkedGeo src/apps/testapps/testLinkedGeo.c)
     add_h3_test(testPolyfill src/apps/testapps/testPolyfill.c)
+    add_h3_test(testPolyfillReported src/apps/testapps/testPolyfillReported.c)
     add_h3_test(testVertexGraph src/apps/testapps/testVertexGraph.c)
     add_h3_test(testH3UniEdge src/apps/testapps/testH3UniEdge.c)
     add_h3_test(testGeoCoord src/apps/testapps/testGeoCoord.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)
     add_h3_test(testVec2d src/apps/testapps/testVec2d.c)
     add_h3_test(testVec3d src/apps/testapps/testVec3d.c)
     add_h3_test(testH3ToLocalIj src/apps/testapps/testH3ToLocalIj.c)
     add_h3_test(testH3Distance src/apps/testapps/testH3Distance.c)
     add_h3_test(testH3Line src/apps/testapps/testH3Line.c)
+    add_h3_test(testH3CellArea src/apps/testapps/testH3CellArea.c)
     add_h3_test(testCoordIj src/apps/testapps/testCoordIj.c)
     add_h3_test(testCoordIjk src/apps/testapps/testCoordIjk.c)
     add_h3_test(testBaseCells src/apps/testapps/testBaseCells.c)
+    add_h3_test(testPentagonIndexes src/apps/testapps/testPentagonIndexes.c)
 
     add_h3_test_with_arg(testH3NeighborRotations src/apps/testapps/testH3NeighborRotations.c 0)
     add_h3_test_with_arg(testH3NeighborRotations src/apps/testapps/testH3NeighborRotations.c 1)
     add_h3_test_with_arg(testH3NeighborRotations src/apps/testapps/testH3NeighborRotations.c 2)
+
+    # The "Exhaustive" part of the test name is used by the test-fast to exclude these files.
+    # test-fast exists so that Travis CI can run Valgrind on tests without taking a very long time.
+    add_h3_test(testH3UniEdgeExhaustive src/apps/testapps/testH3UniEdgeExhaustive.c)
+    add_h3_test(testH3ToLocalIjExhaustive src/apps/testapps/testH3ToLocalIjExhaustive.c)
+    add_h3_test(testH3LineExhaustive src/apps/testapps/testH3LineExhaustive.c)
+    add_h3_test(testH3DistanceExhaustive src/apps/testapps/testH3DistanceExhaustive.c)
+    add_h3_test(testH3CellAreaExhaustive src/apps/testapps/testH3CellAreaExhaustive.c)
+
+    add_h3_memory_test(testH3Memory src/apps/testapps/testH3Memory.c)
+
+    add_custom_target(test-fast COMMAND ctest -E Exhaustive)
 endif()
 
 if(BUILD_BENCHMARKS)
@@ -532,6 +611,7 @@ if(BUILD_BENCHMARKS)
     add_h3_benchmark(benchmarkH3Api src/apps/benchmarks/benchmarkH3Api.c)
     add_h3_benchmark(benchmarkKRing src/apps/benchmarks/benchmarkKRing.c)
     add_h3_benchmark(benchmarkH3Line src/apps/benchmarks/benchmarkH3Line.c)
+    add_h3_benchmark(benchmarkH3UniEdge src/apps/benchmarks/benchmarkH3UniEdge.c)
     add_h3_benchmark(benchmarkH3SetToLinkedGeo src/apps/benchmarks/benchmarkH3SetToLinkedGeo.c)
     add_h3_benchmark(benchmarkPolyfill src/apps/benchmarks/benchmarkPolyfill.c)
     add_h3_benchmark(benchmarkPolygon src/apps/benchmarks/benchmarkPolygon.c)
@@ -554,6 +634,10 @@ set(project_config "${generated_dir}/${PROJECT_NAME}Config.cmake")
 set(TARGETS_EXPORT_NAME "${PROJECT_NAME}Targets")
 set(namespace "${PROJECT_NAME}::")
 
+# TODO: Unclear why this is needed to get the libh3 Debian package to build correctly
+# with shared libraries.
+set(CMAKE_INSTALL_DEFAULT_COMPONENT_NAME "libh3")
+
 # Include module with fuction 'write_basic_package_version_file'
 include(CMakePackageConfigHelpers)
 
@@ -582,6 +666,14 @@ configure_package_config_file(
 install(
     TARGETS ${INSTALL_TARGETS}
     EXPORT "${TARGETS_EXPORT_NAME}"
+    RUNTIME DESTINATION "bin"
+    COMPONENT h3
+)
+
+install(
+    TARGETS h3
+    EXPORT "${TARGETS_EXPORT_NAME}"
+    COMPONENT libh3
     LIBRARY DESTINATION "lib"
     ARCHIVE DESTINATION "lib"
     RUNTIME DESTINATION "bin"
@@ -594,6 +686,7 @@ install(
 install(
     FILES "${CMAKE_CURRENT_BINARY_DIR}/src/h3lib/include/h3api.h"
     DESTINATION "${include_install_dir}/h3"
+    COMPONENT libh3-dev
 )
 
 # Config
@@ -602,6 +695,7 @@ install(
 install(
     FILES "${project_config}" "${version_config}"
     DESTINATION "${config_install_dir}"
+    COMPONENT libh3-dev
 )
 
 # Config
@@ -610,4 +704,27 @@ install(
     EXPORT "${TARGETS_EXPORT_NAME}"
     NAMESPACE "${namespace}"
     DESTINATION "${config_install_dir}"
+    COMPONENT libh3-dev
 )
+
+# Debian package build
+set(CPACK_DEB_COMPONENT_INSTALL 1)
+set(CPACK_GENERATOR "DEB")
+set(CPACK_DEBIAN_FILE_NAME "DEB-DEFAULT")
+# set(CPACK_DEBIAN_PACKAGE_MAINTAINER "TEST PACKAGE") # Required
+set(CPACK_PACKAGE_HOMEPAGE_URL "https://www.h3geo.org")
+set(CPACK_RESOURCE_FILE_LICENSE "${PROJECT_SOURCE_DIR}/LICENSE")
+set(CPACK_DEBIAN_LIBH3_PACKAGE_DEPENDS "libc6 (>= 2.27)")
+set(CPACK_DEBIAN_LIBH3-DEV_PACKAGE_DEPENDS "libh3 (= ${H3_VERSION})")
+set(CPACK_DEBIAN_H3_PACKAGE_DEPENDS "libc6 (>= 2.27), libh3 (= ${H3_VERSION})")
+set(CPACK_DEBIAN_LIBH3_DESCRIPTION "Library files for the H3 hexagonal discrete global grid system.")
+set(CPACK_DEBIAN_LIBH3-DEV_DESCRIPTION "Development files and headers for the H3 hexagonal discrete global grid system.")
+set(CPACK_DEBIAN_H3_DESCRIPTION "UNIX style filter (command line) tools for the H3 hexagonal discrete global grid system.")
+set(CPACK_DEBIAN_LIBH3_PACKAGE_NAME "libh3")
+set(CPACK_DEBIAN_LIBH3-DEV_PACKAGE_NAME "libh3-dev")
+set(CPACK_DEBIAN_H3_PACKAGE_NAME "h3")
+set(CPACK_DEBIAN_LIBH3_PACKAGE_SECTION "libs")
+set(CPACK_DEBIAN_LIBH3-DEV_PACKAGE_SECTION "libdevel")
+set(CPACK_DEBIAN_H3_PACKAGE_SECTION "science")
+
+include(CPack)

data/ext/h3/src/CONTRIBUTING.md

@@ -9,7 +9,7 @@ Planned improvements and changes are listed on the [H3 Roadmap](https://github.c
 * Please include tests that show the bug is fixed or feature works as intended.
 * Please add a description of your change to the Unreleased section of the [changelog](./CHANGELOG.md).
 * Please open issues to discuss large features or changes which would break compatibility, before submitting pull requests.
-* Please keep H3 compatible with major C compilers, such as GCC, Clang, and MSVC.
+* Please keep H3 compatible with major C compilers, such as GCC, Clang, and MSVC. We use clang-format-9 for source code formatting, if you have another version the CI job may error on formatting differences.
 * Please keep code coverage of the core H3 library at 100%.
 
 Before we can merge your changes, you must agree to the [Uber Contributor License Agreement](https://cla-assistant.io/uber/h3).

data/ext/h3/src/README.md

@@ -1,22 +1,27 @@
+<img align="right" src="https://uber.github.io/img/h3Logo-color.svg" alt="H3 Logo" width="200">
+
 # H3: A Hexagonal Hierarchical Geospatial Indexing System
 
-[![Build Status](https://travis-ci.com/uber/h3.svg?branch=master)](https://travis-ci.com/uber/h3)
-[![Build status](https://ci.appveyor.com/api/projects/status/61431y4sc5w0tsuk/branch/master?svg=true)](https://ci.appveyor.com/project/Uber/h3/branch/master)
+[![test-linux](https://github.com/uber/h3/workflows/test-linux/badge.svg)](https://github.com/uber/h3/actions)
+[![test-macos](https://github.com/uber/h3/workflows/test-macos/badge.svg)](https://github.com/uber/h3/actions)
+[![test-windows](https://github.com/uber/h3/workflows/test-windows/badge.svg)](https://github.com/uber/h3/actions)
+[![test-website](https://github.com/uber/h3/workflows/test-website/badge.svg)](https://github.com/uber/h3/actions)
 [![Coverage Status](https://coveralls.io/repos/github/uber/h3/badge.svg?branch=master)](https://coveralls.io/github/uber/h3?branch=master)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 
 H3 is a geospatial indexing system using a hexagonal grid that can be (approximately) subdivided into finer and finer hexagonal grids, combining the benefits of a hexagonal grid with [S2](https://code.google.com/archive/p/s2-geometry-library/)'s hierarchical subdivisions.
 
-Documentation is available at [https://uber.github.io/h3/](https://uber.github.io/h3/). Developer documentation in Markdown format is available under the [dev-docs](./dev-docs/) directory.
+Documentation is available at [https://h3geo.org/](https://h3geo.org/). Developer documentation in Markdown format is available under the [dev-docs](./dev-docs/) directory.
 
  * Post **bug reports or feature requests** to the [GitHub Issues page](https://github.com/uber/h3/issues)
  * Ask **questions** by posting to the [H3 tag on StackOverflow](https://stackoverflow.com/questions/tagged/h3)
+ * There is also an [H3 Slack workspace](https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg)
 
 ## Installing
 
-We recommend using prebuilt bindings if they are available for your programming language. Bindings for [Go](https://github.com/uber/h3-go), [Java](https://github.com/uber/h3-java), [JavaScript](https://github.com/uber/h3-js), [Python](https://github.com/uber/h3-py), and [others](https://uber.github.io/h3/#/documentation/community/bindings) are available.
+We recommend using prebuilt bindings if they are available for your programming language. Bindings for [Go](https://github.com/uber/h3-go), [Java](https://github.com/uber/h3-java), [JavaScript](https://github.com/uber/h3-js), [Python](https://github.com/uber/h3-py), and [others](https://h3geo.org/docs/community/bindings) are available.
 
-On macOS, you can install H3 using brew:
+On macOS, you can install H3 using `brew`:
 ```
 brew install h3
 ```
@@ -28,7 +33,7 @@ Still here? To build the H3 C library, you'll need a C compiler (tested with `gc
 
 #### Install build-time dependencies
 
-* Alpine 
+* Alpine
 ```
 # Installing the bare build requirements
 apk add cmake make gcc libtool musl-dev
@@ -43,7 +48,7 @@ sudo apt install cmake make gcc libtool
 sudo apt install clang-format cmake-curses-gui lcov doxygen
 ```
 
-* macOS (using brew)
+* macOS (using `brew`)
 
 First make sure you [have the developer tools installed](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/) and then
 
@@ -58,24 +63,71 @@ brew install clang-format lcov doxygen
 
 You will need to install CMake and Visual Studio, including the Visual C++ compiler. For building on Windows, please follow the [Windows build instructions](dev-docs/build_windows.md).
 
+* FreeBSD
+
+ ```
+# Installing the build requirements
+sudo pkg install bash cmake gmake doxygen lcov
+```
+
 #### Compilation
 
-From the repository you would then compile like so:
+From the repository root, you can compile H3 with:
 
 ```
-cmake .
+mkdir build
+cd build
+cmake ..
 make
 ```
 
+All subsequent `make` commands should be run from within the `build` directory.
+
+**Note**: There are several ways to build H3 with CMake; the method above is just one example that restricts all build artifacts to the `build` directory.
+
 You can install system-wide with:
 
 ```
 sudo make install
 ```
 
+If using the method above, from the repository root, you can clean all build artifacts with:
+
+```
+rm -rf build
+```
+
 #### Testing
 
-After making the project, you can test with `make test`, and if `lcov` is installed you can `make coverage` to generate a code coverage report.
+After making the project, you can test with `make test`.
+You can run a faster test suite that excludes the most expensive tests with `make test-fast`.
+
+#### Coverage
+
+You can generate a code coverage report if `lcov` is installed, and if the project was built with the `CMAKE_BUILD_TYPE=Debug` option.
+For example, from a clean repository, you could run:
+
+```
+mkdir build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Debug ..
+make
+make coverage
+```
+
+You can then view a detailed HTML coverage report by opening `coverage/index.html` in your browser.
+
+#### Benchmarks
+
+You can run timing benchmarks by building with the `CMAKE_BUILD_TYPE=Release`, and running `make benchmarks`:
+
+```
+mkdir build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Release ..
+make
+make benchmarks
+```
 
 #### Documentation
 
@@ -92,8 +144,7 @@ To build the documentation website, see the [website/](./website/) directory.
 To get the H3 index for some location:
 
 ```
-./bin/geoToH3 10
-40.689167 -74.044444
+./bin/geoToH3 --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`.
@@ -101,8 +152,7 @@ To get the H3 index for some location:
 You can then take this index and get some information about it, for example:
 
 ```
-./bin/h3ToGeoBoundary
-8a2a1072b59ffff
+./bin/h3ToGeoBoundary --index 8a2a1072b59ffff
 ```
 
 This will produce the vertices of the hexagon at this location:
@@ -122,8 +172,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
-8a2a1072b59ffff
+./bin/h3ToGeo --index 8a2a1072b59ffff
 ```
 
 This will produce some coordinate: