Module geoid 

Geoid undulation (geoid height) lookup with bilinear interpolation.

The geoid undulation N is the height of the geoid (mean sea level equipotential surface) above the WGS84 reference ellipsoid, in metres. GNSS positioning yields the ellipsoidal height h; the orthometric height H (height above mean sea level) is

H = h - N

A geoid model is published as a regular latitude/longitude grid of N samples (EGM96, EGM2008, and the national models all ship this way). This module provides:

• GeoidGrid, a regular grid of undulation samples with bilinear interpolation (GeoidGrid::undulation_rad / GeoidGrid::undulation_deg);
• GeoidGrid::from_text, a data-loading hook that parses a simple, documented grid text format so a caller can supply a full EGM grid;
• GeoidGrid::from_egm96_dac, a loader for the authoritative NGA EGM96 15-arcminute binary grid (WW15MGH.DAC) for decimetre-class datum work;
• egm96_undulation / egm96_grid, a zero-setup lookup against an embedded genuine EGM96 1-degree global grid (a higher-accuracy alternative to the coarse built-in);
• geoid_undulation, a zero-setup lookup against a small COARSE built-in global grid, plus orthometric_height_m / ellipsoidal_height_m height conversion helpers.

Choosing a grid

Three accuracy tiers are available, in increasing fidelity:

1. geoid_undulation - the COARSE 30-degree built-in. It reproduces the large-scale character of the geoid (the Indian Ocean low, the North Atlantic / New Guinea highs, the polar offsets) and is fine for tests, sanity checks, and metre-scale fallback, but it is NOT survey-grade (decametre-level error).
2. egm96_undulation - an embedded GENUINE EGM96 1-degree global grid, decimated from the official NGA 15-arcminute model. Its bilinear lookup agrees with the full 15-arcminute EGM96 grid to ~0.4 m RMS (95th percentile ~0.7 m; up to a few metres over the steepest geoid gradients). This is the recommended zero-setup default for metre-class datum work.
3. GeoidGrid::from_egm96_dac with the official WW15MGH.DAC file (a ~2 MB download, not vendored here) - the full 15-arcminute resolution. Its bilinear lookup tracks the geoid to roughly decimetre RMS, but the worst-case bilinear interpolation error can still exceed 1 m over the steepest geoid gradients (see https://geographiclib.sourceforge.io/html/geoid.html for the egm96-15 error envelope), so this path supports decimetre-class typical datum work rather than guaranteed sub-metre accuracy everywhere. Embedding the full grid is impractical (the 15-arcminute grid is ~1 M samples and EGM2008 1-minute is ~2.3 GB), so the high-resolution path loads the file at runtime.

A caller with any other vendor grid can lower it to GeoidGrid::from_text or build a GeoidGrid via GeoidGrid::new and call GeoidGrid::undulation_rad directly.

Structs

GeoidGrid

A regular latitude/longitude grid of geoid undulation samples (metres) with bilinear interpolation.

Enums

GeoidError

Why a geoid grid could not be constructed or parsed.

Functions

egm96_ellipsoidal_height_m

Ellipsoidal height h = H + N (metres above the WGS84 ellipsoid) from an orthometric height and a geodetic position in radians, using the embedded GENUINE EGM96 1-degree model via egm96_undulation.

egm96_grid

The embedded genuine EGM96 1-degree global geoid, decoded once on first use.

egm96_orthometric_height_m

Orthometric height H = h - N (metres above mean sea level) from an ellipsoidal height and a geodetic position in radians, using the embedded GENUINE EGM96 1-degree model via egm96_undulation.

egm96_undulation

Geoid undulation N (metres above the WGS84 ellipsoid) at a geodetic position in radians, from the embedded GENUINE EGM96 1-degree global grid.

ellipsoidal_height_m

Ellipsoidal height h = H + N (metres above the WGS84 ellipsoid) from an orthometric height and a geodetic position in radians, using the COARSE 30-degree built-in model’s undulation (decametre-level error, NOT survey-grade). For metre-class conversion use egm96_ellipsoidal_height_m; for a real model, add GeoidGrid::undulation_rad directly.

geoid_undulation

Geoid undulation N (metres above the WGS84 ellipsoid) at a geodetic position in radians, from the COARSE built-in global grid.

orthometric_height_m

Orthometric height H = h - N (metres above mean sea level) from an ellipsoidal height and a geodetic position in radians, using the COARSE 30-degree built-in model’s undulation (decametre-level error, NOT survey-grade). For metre-class conversion use egm96_orthometric_height_m; for a real model, subtract GeoidGrid::undulation_rad directly.