Added benchmarks vs S2, Boost.Geometry, GeographicLib

Author: gistrec

.gitignore

@@ -1,4 +1,5 @@
 build/
+build-*/
 
 # Compiled Object files
 *.slo

CMakeLists.txt

@@ -8,8 +8,9 @@ else()
 endif()
 
 include(CMakeDependentOption)
-option(GEO_UTILS_CPP_BUILD_TESTS    "Build geo-utils-cpp tests"    ${_geo_utils_cpp_is_top_level})
-option(GEO_UTILS_CPP_BUILD_EXAMPLES "Build geo-utils-cpp examples" ${_geo_utils_cpp_is_top_level})
+option(GEO_UTILS_CPP_BUILD_TESTS      "Build geo-utils-cpp tests"      ${_geo_utils_cpp_is_top_level})
+option(GEO_UTILS_CPP_BUILD_EXAMPLES   "Build geo-utils-cpp examples"   ${_geo_utils_cpp_is_top_level})
+option(GEO_UTILS_CPP_BUILD_BENCHMARKS "Build geo-utils-cpp benchmarks" OFF)
 cmake_dependent_option(GEO_UTILS_CPP_ENABLE_COVERAGE
     "Enable gcov coverage instrumentation (GCC/Clang only)" OFF
     "GEO_UTILS_CPP_BUILD_TESTS" OFF)
@@ -98,6 +99,11 @@ if(GEO_UTILS_CPP_BUILD_EXAMPLES)
     add_subdirectory(examples)
 endif()
 
+# Benchmarks (opt-in: pulls Google Benchmark and optionally S2/Boost/GeographicLib)
+if(GEO_UTILS_CPP_BUILD_BENCHMARKS)
+    add_subdirectory(benchmarks)
+endif()
+
 # Installation
 include(GNUInstallDirs)
 

README.md

@@ -121,6 +121,27 @@ int main() {
 }
 ```
 
+## Benchmarks
+
+`geo-utils-cpp` is a near-zero-overhead wrapper over the math itself, with a
+tiny disk footprint thanks to header-only + zero dependencies.
+
+| Library              | `distance_between` (M pairs/s) | `contains` (poly N=100, M qps) | Install size  |
+| -------------------- | -----------------------------: | -----------------------------: | ------------: |
+| **geo-utils-cpp**    |                       **36.7** |                       **2.17** |     **32 KB** |
+| naive haversine      |                           37.0 |                            —   |             0 |
+| S2 Geometry          |                           14.3 |                          18.0  |       32.8 MB |
+| Boost.Geometry       |                           40.0 |                           0.23 |       12.3 MB |
+| GeographicLib        |                            1.2 |                  no native PIP |        4.6 MB |
+
+Apple M1 · clang 17 · `-O2 -DNDEBUG`. We're tied with hand-written haversine
+on raw math, ~7× faster than Boost.Geometry on point-in-polygon, and have a
+**144–1000× smaller install footprint** than the alternatives. S2 wins on
+large-polygon containment thanks to spatial indexing.
+
+See [docs/benchmarks.md](docs/benchmarks.md) for the full methodology, all
+operations, and a discussion of when to reach for each library.
+
 ## API Reference
 
 See [docs/api.md](docs/api.md) for the full API reference.

benchmarks/CMakeLists.txt

@@ -0,0 +1,116 @@
+# Benchmarks for geo-utils-cpp.
+#
+# Build with:
+#     cmake -B build -DGEO_UTILS_CPP_BUILD_BENCHMARKS=ON
+#     cmake --build build --target bench_all
+#
+# Google Benchmark is fetched automatically. S2, Boost.Geometry, and
+# GeographicLib are looked up via find_package — missing competitors are
+# skipped with a status message instead of causing a hard error.
+
+include(FetchContent)
+
+# --- Google Benchmark -------------------------------------------------------
+
+set(BENCHMARK_ENABLE_TESTING  OFF CACHE BOOL "" FORCE)
+set(BENCHMARK_ENABLE_INSTALL  OFF CACHE BOOL "" FORCE)
+set(BENCHMARK_INSTALL_DOCS    OFF CACHE BOOL "" FORCE)
+set(BENCHMARK_ENABLE_GTEST_TESTS OFF CACHE BOOL "" FORCE)
+
+FetchContent_Declare(
+    google_benchmark
+    URL https://github.com/google/benchmark/archive/v1.8.4.tar.gz
+    DOWNLOAD_EXTRACT_TIMESTAMP ON
+)
+FetchContent_MakeAvailable(google_benchmark)
+
+# --- Shared infrastructure --------------------------------------------------
+
+add_library(geo_utils_cpp_bench_common INTERFACE)
+target_include_directories(geo_utils_cpp_bench_common INTERFACE
+    ${CMAKE_CURRENT_SOURCE_DIR}/common
+)
+target_compile_features(geo_utils_cpp_bench_common INTERFACE cxx_std_17)
+
+# Aggregator target: depend on every bench that ends up being built.
+add_custom_target(bench_all)
+
+function(_geo_utils_cpp_add_bench name source)
+    add_executable(bench_${name} ${source})
+    target_link_libraries(bench_${name} PRIVATE
+        geo::utils
+        geo_utils_cpp_bench_common
+        benchmark::benchmark_main
+        ${ARGN}
+    )
+    add_dependencies(bench_all bench_${name})
+endfunction()
+
+# --- geo-utils-cpp itself + naive haversine baseline ------------------------
+
+_geo_utils_cpp_add_bench(geo_utils speed/bench_geo_utils.cpp)
+_geo_utils_cpp_add_bench(naive     speed/bench_naive.cpp)
+
+# --- Optional: S2 Geometry --------------------------------------------------
+#
+# vcpkg port name: `s2geometry`. Homebrew formula: `s2geometry`. The CMake
+# package is conventionally exported as `s2`.
+find_package(s2 QUIET)
+if(s2_FOUND)
+    _geo_utils_cpp_add_bench(s2 speed/bench_s2.cpp s2::s2)
+    message(STATUS "geo-utils-cpp benchmarks: S2 found — bench_s2 enabled.")
+else()
+    message(STATUS "geo-utils-cpp benchmarks: S2 not found — bench_s2 skipped. "
+                   "Install via 'vcpkg install s2geometry' or 'brew install s2geometry'.")
+endif()
+
+# --- Optional: Boost.Geometry -----------------------------------------------
+#
+# Boost.Geometry is header-only. CMake 3.30 deprecates the FindBoost module in
+# favour of Boost's exported BoostConfig.cmake; we prefer CONFIG and fall back
+# to the legacy module so this works across CMake 3.14+.
+if(POLICY CMP0167)
+    cmake_policy(SET CMP0167 NEW)
+endif()
+
+find_package(Boost 1.70 QUIET CONFIG)
+if(NOT Boost_FOUND)
+    find_package(Boost 1.70 QUIET)
+endif()
+
+if(Boost_FOUND)
+    # Different Boost versions expose the header set as Boost::headers (>=1.71),
+    # Boost::boost (older), or only via Boost_INCLUDE_DIRS.
+    if(TARGET Boost::headers)
+        _geo_utils_cpp_add_bench(boost speed/bench_boost.cpp Boost::headers)
+    elseif(TARGET Boost::boost)
+        _geo_utils_cpp_add_bench(boost speed/bench_boost.cpp Boost::boost)
+    else()
+        _geo_utils_cpp_add_bench(boost speed/bench_boost.cpp)
+        target_include_directories(bench_boost PRIVATE ${Boost_INCLUDE_DIRS})
+    endif()
+    message(STATUS "geo-utils-cpp benchmarks: Boost.Geometry found — bench_boost enabled.")
+else()
+    message(STATUS "geo-utils-cpp benchmarks: Boost not found — bench_boost skipped. "
+                   "Install via 'vcpkg install boost-geometry' or 'brew install boost'.")
+endif()
+
+# --- Optional: GeographicLib ------------------------------------------------
+#
+# Recent GeographicLib versions export the target `GeographicLib::GeographicLib`.
+# Older versions exposed `${GeographicLib_LIBRARIES}` instead — we accept both.
+find_package(GeographicLib QUIET)
+if(GeographicLib_FOUND)
+    if(TARGET GeographicLib::GeographicLib)
+        _geo_utils_cpp_add_bench(geographiclib speed/bench_geographiclib.cpp
+            GeographicLib::GeographicLib)
+    else()
+        _geo_utils_cpp_add_bench(geographiclib speed/bench_geographiclib.cpp
+            ${GeographicLib_LIBRARIES})
+        target_include_directories(bench_geographiclib PRIVATE ${GeographicLib_INCLUDE_DIRS})
+    endif()
+    message(STATUS "geo-utils-cpp benchmarks: GeographicLib found — bench_geographiclib enabled.")
+else()
+    message(STATUS "geo-utils-cpp benchmarks: GeographicLib not found — bench_geographiclib skipped. "
+                   "Install via 'vcpkg install geographiclib' or 'brew install geographiclib'.")
+endif()

benchmarks/README.md

@@ -0,0 +1,107 @@
+# Benchmarks
+
+This directory measures `geo-utils-cpp` against three popular C++ geometry
+libraries on two axes:
+
+1. **Speed** — Google Benchmark micro-benchmarks for `distance`, `heading`,
+   `contains`, `area`, and `path_length`.
+2. **Disk footprint** — stripped binary size of a minimal consumer plus the
+   on-disk install size of each library.
+
+The benchmarks are **not built by default** and **not run in CI**. Set
+`-DGEO_UTILS_CPP_BUILD_BENCHMARKS=ON` to opt in.
+
+For a high-level summary of results and methodology see
+[`docs/benchmarks.md`](../docs/benchmarks.md).
+
+## Competitors
+
+| Library              | Model       | Notes                                             |
+| -------------------- | ----------- | ------------------------------------------------- |
+| **geo-utils-cpp**    | sphere      | This library — header-only, zero deps             |
+| **naive haversine**  | sphere      | ~30 lines of inline math, no library              |
+| **S2 Geometry**      | sphere      | Google's mapping library; depends on abseil       |
+| **Boost.Geometry**   | sphere\*    | `cs::spherical_equatorial<degree>` strategy       |
+| **GeographicLib**    | ellipsoid   | Karney's iterative geodesic — more accurate, slower; **no native point-in-polygon** |
+
+\* Boost.Geometry can also do ellipsoidal; we use the spherical strategy here
+to compare apples-to-apples on the algorithm we ourselves implement.
+
+## Installing competitors
+
+The CMake build looks each library up via `find_package` and *skips* the
+benchmark binary for any competitor it can't find — so you only need to
+install the libraries you want to compare against.
+
+### Homebrew (macOS / Linux)
+
+```sh
+brew install s2geometry boost geographiclib
+```
+
+### vcpkg
+
+```sh
+vcpkg install s2geometry boost-geometry geographiclib
+```
+
+(Then point CMake at the vcpkg toolchain file with
+`-DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake`.)
+
+### apt (Debian/Ubuntu)
+
+S2 is not in apt; install from source or vcpkg. The other two:
+
+```sh
+sudo apt install libboost-dev libgeographiclib-dev
+```
+
+## Building and running speed benchmarks
+
+```sh
+cmake -S . -B build-bench \
+    -DGEO_UTILS_CPP_BUILD_BENCHMARKS=ON \
+    -DCMAKE_BUILD_TYPE=Release
+cmake --build build-bench --target bench_all -j
+
+# Run any one binary:
+./build-bench/benchmarks/bench_geo_utils
+./build-bench/benchmarks/bench_naive
+./build-bench/benchmarks/bench_s2          # if S2 was found
+./build-bench/benchmarks/bench_boost       # if Boost was found
+./build-bench/benchmarks/bench_geographiclib  # if GeographicLib was found
+```
+
+Each binary supports the standard Google Benchmark flags. To produce a single
+combined JSON report:
+
+```sh
+for b in build-bench/benchmarks/bench_*; do
+    "$b" --benchmark_format=json --benchmark_out="$(basename $b).json"
+done
+```
+
+## Measuring disk footprint
+
+```sh
+./benchmarks/size/measure.sh
+```
+
+This builds a minimal "distance + point-in-polygon" consumer against every
+library it can find, strips the resulting binary, and reports both the
+binary size and the on-disk install size of each library. Override compiler
+or flags via `CXX=` and `CXXFLAGS=`.
+
+## Methodology notes
+
+- **Same inputs everywhere.** All benchmarks pull data from
+  `common/random_data.hpp`, which is seeded deterministically.
+- **Conversion costs are included** for libraries that don't accept lat/lng
+  natively (S2 takes `S2Point`; Boost takes its own point type). Pre-converting
+  outside the timing loop would understate the cost of "I have lat/lng, I want
+  a distance" — the actual usage pattern.
+- **Polygons are pre-built** outside the timing loop because in real code a
+  geofence is a one-time setup cost.
+- **Don't compare GeographicLib's distance/heading head-to-head as "speed".**
+  It computes a different (more accurate) thing on the WGS84 ellipsoid.
+  Treat it as a "trade-off" data point.

benchmarks/common/random_data.hpp

@@ -0,0 +1,67 @@
+// Copyright 2026 Aleksandr Kovalko
+// Licensed under the Apache License, Version 2.0
+//
+// Deterministic random data shared by every benchmark binary, so that all
+// libraries compete on identical inputs.
+
+#pragma once
+
+#include <cmath>
+#include <cstddef>
+#include <cstdint>
+#include <random>
+#include <vector>
+
+#include <geo/latlng.hpp>
+
+namespace geo::bench {
+
+inline constexpr std::uint64_t kSeed = 0xC0FFEEull;
+
+// Returns `n` random points uniformly distributed over the globe. Latitude is
+// clamped to [-80, 80] to keep all libraries on safe ground (S2 is fine near
+// the poles, but ellipsoidal Inverse can be numerically iffy for nearly
+// antipodal pairs).
+inline std::vector<LatLng> random_points(std::size_t n, std::uint64_t seed = kSeed) {
+    std::mt19937_64 rng(seed);
+    std::uniform_real_distribution<double> lat(-80.0, 80.0);
+    std::uniform_real_distribution<double> lng(-180.0, 180.0);
+    std::vector<LatLng> out;
+    out.reserve(n);
+    for (std::size_t i = 0; i < n; ++i) {
+        out.emplace_back(lat(rng), lng(rng));
+    }
+    return out;
+}
+
+// Returns a regular n-gon centered at (clat, clng) with the given radius
+// (degrees). Vertices are emitted counter-clockwise (positive signed area
+// in our convention).
+inline std::vector<LatLng> regular_polygon(std::size_t n, double clat, double clng, double radius_deg) {
+    constexpr double kPi = 3.14159265358979323846;
+    std::vector<LatLng> out;
+    out.reserve(n);
+    for (std::size_t i = 0; i < n; ++i) {
+        double a = 2.0 * kPi * static_cast<double>(i) / static_cast<double>(n);
+        out.emplace_back(clat + radius_deg * std::cos(a),
+                         clng + radius_deg * std::sin(a));
+    }
+    return out;
+}
+
+// Query points clustered around the polygon center. Roughly half land
+// inside, half outside — exercises both branches of contains().
+inline std::vector<LatLng> queries_around(double clat, double clng, double radius_deg,
+                                          std::size_t n, std::uint64_t seed = kSeed + 1) {
+    std::mt19937_64 rng(seed);
+    std::uniform_real_distribution<double> jitter(-2.0, 2.0);
+    std::vector<LatLng> out;
+    out.reserve(n);
+    for (std::size_t i = 0; i < n; ++i) {
+        out.emplace_back(clat + radius_deg * jitter(rng),
+                         clng + radius_deg * jitter(rng));
+    }
+    return out;
+}
+
+}  // namespace geo::bench

benchmarks/size/consumer_boost.cpp

@@ -0,0 +1,31 @@
+// Minimal consumer: distance + point-in-polygon, Boost.Geometry.
+
+#include <cstdio>
+#include <cstdlib>
+
+#include <boost/geometry.hpp>
+#include <boost/geometry/geometries/point.hpp>
+#include <boost/geometry/geometries/polygon.hpp>
+#include <boost/geometry/strategies/spherical/distance_haversine.hpp>
+
+namespace bg = boost::geometry;
+using Pt   = bg::model::point<double, 2, bg::cs::spherical_equatorial<bg::degree>>;
+using Poly = bg::model::polygon<Pt>;
+
+int main(int argc, char** argv) {
+    if (argc < 5) return 1;
+    Pt a(std::atof(argv[2]), std::atof(argv[1]));  // (lng, lat)
+    Pt b(std::atof(argv[4]), std::atof(argv[3]));
+    Poly poly;
+    bg::append(poly.outer(), Pt{-74.1, 40.7});
+    bg::append(poly.outer(), Pt{-74.1, 40.8});
+    bg::append(poly.outer(), Pt{-74.0, 40.8});
+    bg::append(poly.outer(), Pt{-74.0, 40.7});
+    bg::append(poly.outer(), Pt{-74.1, 40.7});
+    bg::correct(poly);
+
+    bg::strategy::distance::haversine<double> hav(6371009.0);
+    const double d = bg::distance(a, b, hav);
+    std::printf("%.1f %d\n", d, static_cast<int>(bg::within(a, poly)));
+    return 0;
+}