Package pygeodesy :: Module geoids |
[frames] | no frames]

# Module geoids

Geoid models and geoid height interpolations.

Classes GeoidG2012B, GeoidKarney and GeoidPGM to interpolate the height of various geoids at `LatLon` locations or separate lat-/longitudes using different interpolation methods and `geoid` model files.

GeoidKarney is a transcoding of Charles Karney's C++ class Geoid to pure Python. The GeoidG2012B and GeoidPGM interpolators both depend on scipy and numpy and require those packages to be installed.

In addition, each geoid interpolator needs `grid knots` (down)loaded from a `geoid` model file, specific to the interpolator, more details below and in the documentation of the interpolator class. For each interpolator, there are several interpolation choices, like linear, cubic, etc.

# Typical usage

1. Choose one of the interpolator classes GeoidG2012B, GeoidKarney or GeoidPGM and download a `geoid` model file, containing locations with known heights also referred to as the `grid knots`. See the documentation of the interpolator class for references to available `grid` models.

   `>>> from pygeodesy import GeoidG2012B # or -Karney or -PGM as GeoidXyz`

2. Instantiate an interpolator with the `geoid` model file and use keyword arguments to select different interpolation options

   `>>> ginterpolator = GeoidXyz(geoid_model_file, **options)`

3. Get the interpolated geoid height of other `LatLon` location(s) with

   `>>> ll = LatLon(1, 2, ...)`

   `>>> h = ginterpolator(ll)`

   or

   `>>> h0, h1, h2, ... = ginterpolator(ll0, ll1, ll2, ...)`

   or a list, tuple, generator, etc. of `LatLon`s

   `>>> hs = ginterpolator(lls)`

4. For separate lat- and longitudes invoke the `.height` method as

   `>>> h = ginterpolator.height(lat, lon)`

   or as 2 lists, 2 tuples, etc.

   `>>> hs = ginterpolator.height(lats, lons)`

5. An example is in issue #64, courtesy of SBFRF.

Notes:

- Classes GeoidG2012B and GeoidPGM require both numpy and scipy to be installed.
- Errors from `scipy` are raised as SciPyErrors. Warnings issued by `scipy` can be thrown as SciPyWarning exceptions, provided Python `warnings` are filtered accordingly, see SciPyWarning.

See Also: Karney's GeographicLib, Geoid height and Installing the Geoid datasets, SciPy interpolation RectBivariateSpline and interp2d, functions elevations.elevation2 and elevations.geoidHeight2, Ellispoid vs Orthometric Elevations and Pitfalls Related to Ellipsoid Height and Height Above Mean Sea Level (AMSL).

Version: 24.07.25

Classes
| _GeoidBase (INTERNAL) Base class for `Geoid...`s.
| GeoidError Geoid interpolator `Geoid...` or interpolation issue.
| GeoidG2012B Geoid height interpolator for GEOID12B Model grids CONUS, Alaska, Hawaii, Guam and Northern Mariana Islands, Puerto Rico and U.S. Virgin Islands and American Samoa based on `SciPy` RectBivariateSpline or interp2d interpolation.
| GeoidHeight5Tuple 5-Tuple `(lat, lon, egm84, egm96, egm2008)` for GeoidHeights.dat tests with the heights for 3 different EGM grids at `degrees90` and `degrees180` degrees (after converting `lon` from original `0 <= EasterLon <= 360`).
| GeoidKarney Geoid height interpolator for Karney's GeographicLib Earth Gravitational Model (EGM) geoid egm*.pgm datasets using bilinear or cubic interpolation and caching in pure Python, transcoded from Karney's C++ class Geoid.
| GeoidPGM Geoid height interpolator for Karney's GeographicLib Earth Gravitational Model (EGM) geoid egm*.pgm datasets but based on `SciPy` RectBivariateSpline or interp2d interpolation.
| PGMError Issue parsing or cropping an `egm*.pgm` geoid dataset.

Functions
egmGeoidHeights(GeoidHeights_dat) Generate geoid egm*.pgm height tests from GeoidHeights.dat Test data for Geoids. |

Variables
| __all__ = `_ALL_LAZY.geoids`

Function Details

### egmGeoidHeights (GeoidHeights_dat) |
Generate geoid egm*.pgm height tests from GeoidHeights.dat Test data for Geoids. Arguments: `GeoidHeights_dat` - The un-gz-ed `GeoidHeights.dat` file (`str` or `file` handle). Returns: For each test, yield a GeoidHeight5Tuple`(lat, lon, egm84, egm96, egm2008)`. Raises: `GeoidError` - Invalid `GeoidHeights_dat`. Note: Function egmGeoidHeights is used to test the geoids GeoidKarney and GeoidPGM, see PyGeodesy module `test/testGeoids.py`.