Add initial implementation

.github/workflows/cargo_test.yml

@@ -0,0 +1,23 @@
+name: Cargo Build & Test
+
+on:
+  push:
+  pull_request:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build_and_test:
+    name: Rust project - latest
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        toolchain:
+          - stable
+          - beta
+    steps:
+      - uses: actions/checkout@v3
+      - run: rustup update ${{ matrix.toolchain }} && rustup default ${{ matrix.toolchain }}
+      - run: cargo build --verbose
+      - run: cargo test --verbose

.gitignore

@@ -1 +1,3 @@
 target/
+Cargo.lock
+egm.zip

Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "egm2008"
+version = "0.1.0"
+edition = "2021"
+authors = ["FlightAware", "Ben Burwell <[email protected]>"]
+description = "Earth Gravitational Model (EGM2008)"
+keywords = ["egm", "geoid", "gis"]
+license = "BSD-3-Clause"
+homepage = "https://github.com/flightaware/egm2008"
+repository = "https://github.com/flightaware/egm2008"
+categories = ["science::geo"]
+readme = "README.md"
+include = [
+  "src/*.rs",
+  "Cargo.toml"
+]
+
+[dependencies]
+thiserror = "1.0.50"

LICENSE.txt

@@ -0,0 +1,26 @@
+Copyright 2023 FlightAware
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1 +1,24 @@
-# Earth Gravitational Model
+# Earth Gravitational Model (EGM2008)
+
+The coordinate system used by GPS is [WGS 84](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS_84), which expresses altitudes as a "height above ellipsoid".
+Because this ellipsoid is a mathematical simplification, the height given by GPS does not necessarily reflect the height above the actual ground beneath.
+
+The [Earth Gravitational Models](https://en.wikipedia.org/wiki/Earth_Gravitational_Model) published by the National Geospatial Intelligence Agency are a way to approximate how high an altitude given in WGS 84 coordinates truly is above the ground.
+
+This library includes data derived from [EGM 2008](https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84) along with an interpolation function. Together, these allow for an approximate offset to be obtained for arbitrary points on the globe.
+
+The `geoid.rs` file containing terrain data is [generated using the Fortran program](./tools/README.md) provided by NGA.
+
+## Updating `geoid.rs`
+
+The `src/geoid.rs` file is generated by a Python script (`generate.py`) that
+runs NGA's Fortran interpolation program. In order to run the script, you'll
+need to download the EGM model data from the NGA's website.
+
+You will also need to install `gfortran`. There are a few ways to do this:
+- On macOS, through [Homebrew](https://brew.sh) with `brew install gfortran`.
+- Use the included [Nix](https://nix.dev) dev shell with `nix develop`.
+
+For convenience, you can run `generate_geoid.sh` which will download and verify
+the model data from NGA, compile the interpolation program, and update
+`src/geoid.rs`.

egm.zip.sha256

@@ -0,0 +1 @@
+0f65f16e6fd3f89a6b8022d7a89375d0c29fb275a551927175669bb610904cd0  egm.zip

flake.nix

@@ -0,0 +1,24 @@
+{
+  inputs = {
+    nixpkgs.url = "nixpkgs";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = { self, nixpkgs, flake-utils, ... }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        pkgs = nixpkgs.legacyPackages.${system};
+      in {
+        devShells = {
+          default = pkgs.mkShell {
+            nativeBuildInputs = with pkgs; [
+              rustc
+              cargo
+              rustfmt
+              gfortran
+              python3
+            ];
+          };
+      };
+    });
+}

generate.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+
+import sys
+import os
+import re
+import math
+from contextlib import closing
+
+scale = 3.0
+splitter = re.compile(r'\s+')
+
+if math.fmod(360.0, scale) != 0:
+    raise RuntimeError('non-exact scale')
+if math.fmod(180.0, scale) != 0:
+    raise RuntimeError('non-exact scale')
+
+bandsize = int(360.0 / scale + 1)
+bandcount = int(180.0 / scale + 1)
+tablesize = bandsize * bandcount
+table = [None] * tablesize
+
+print('{} degree grid, {} table entries'.format(scale, tablesize), file=sys.stderr)
+print('Generating INPUT.DAT', file=sys.stderr)
+with closing(open('INPUT.DAT', 'w')) as f:
+    for lat in range(bandcount):
+        for lon in range(bandsize):
+            print(lat * scale - 90.0, lon * scale - 180.0, file=f)
+
+print('Generating OUTPUT.DAT', file=sys.stderr)
+os.system('./interpolate')
+
+with closing(open('OUTPUT.DAT', 'r')) as f:
+    for line in f:
+        line = line.strip()
+        lat, lon, geoid = splitter.split(line.rstrip('\r\n'))
+        lat, lon, geoid = float(lat), float(lon), float(geoid)
+
+        lat_i = int((lat + 90) / scale)
+        lon_i = int((lon + 180) / scale)
+        index = (lat_i * bandsize) + lon_i
+        table[index] = geoid
+
+for i in range(tablesize):
+    if table[i] is None:
+        raise RuntimeError('missing values at index {}'.format(i))
+
+print('Generating geoid.rs', file=sys.stderr)
+with closing(open('geoid.rs', 'w')) as f:
+    prog = '''
+// Generated by generate.py, DO NOT EDIT!
+
+/// Grid size in degrees.
+pub(crate) const SCALE: f32 = {scale};
+
+/// How many entries each band has.
+pub(crate) const BAND_SIZE: usize = {bandsize};
+
+/// How many bands there are in total.
+pub(crate) const BAND_COUNT: usize = {bandcount};
+
+/// An array of geoid undulation data with BAND_SIZE * BAND_COUNT entries.
+///
+/// Data is expressed in meters.
+#[allow(clippy::approx_constant)]
+pub(crate) const DATA: &[f32] = &{table};
+'''.format(scale=scale,
+           bandsize=bandsize,
+           bandcount=bandcount,
+           table=table)
+    print(prog, file=f)
+
+print('Formatting geoid.rs', file=sys.stderr)
+os.system('rustfmt geoid.rs')

generate_geoid.sh

@@ -0,0 +1,36 @@
+#!/bin/sh
+
+project_dir=$(pwd)
+
+if [ ! -f egm.zip ]; then
+  echo "===> Downloading egm.zip from earth-info.nga.mil..."
+  curl -o egm.zip 'https://earth-info.nga.mil/php/download.php?file=egm-08interpolation'
+else
+  echo "===> Using existing egm.zip"
+fi
+
+echo "===> Verifying downloaded archive..."
+if ! shasum -a 256 -c egm.zip.sha256; then
+  echo "     Bailing due to bad checksum!"
+  exit 1
+fi
+
+build_dir=$(mktemp -d)
+echo "===> Unzipping egm.zip into $build_dir..."
+unzip egm.zip -d "$build_dir"
+
+echo "===> Installing generate.py..."
+cp generate.py "$build_dir/generate.py"
+
+echo "===> Entering $build_dir..."
+cd "$build_dir" || exit 1
+
+echo "===> Compiling Fortran interpolater..."
+gfortran -o interpolate interp_2p5min.f
+
+echo "===> Generating geoid.rs..."
+python3 generate.py
+mv geoid.rs "$project_dir/src/geoid.rs"
+
+echo "===> Cleaning up $build_dir..."
+rm -rf "$build_dir"