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, bisplrep/-ev and interp2d, functions elevations.elevation2 and elevations.geoidHeight2, Ellispoid vs Orthometric Elevations and 6.22.1 Avoiding Pitfalls Related to Ellipsoid Height and Height Above Mean Sea Level.

Version: 24.08.24

Classes
| GeoidError Geoid interpolator `Geoid...` or interpolation issue.
| _GeoidBase (INTERNAL) Base class for `Geoid...`s.
| 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, interp2d or bisplrep/-ev 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, bisplrep/-ev 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`.