pygeodesy.geoids

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

# Module geoids

Geoid models and geoid height interpolations.

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

GeoidKarney is a transcoding of Charles Karney's C++ class Geoid to pure Python.

The GeoidEGM96, 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 an interpolator class GeoidEGM96, 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 GeoidEGM96 as GeoidXyz # or GeoidG2012B, -Karney or -PGM`

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 `LatLon` location(s) with

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

   `>>> h = ginterpolator(ll)`

   or

   `>>> h1, h2, h3, ... = ginterpolator(ll1, ll2, ll3, ...)`

   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)`

   or for several positionals use the `height_` method

   `>>> h1, h2, ... = ginterpolator.height_(lat1, lon1, lat2, lon2, ...)`

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

Notes:

- Classes GeoidEGM96, 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, World Geodetic System 1984 (WG84) and Earth Gravitational Model 96 (EGM96) Data and Apps, 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: 26.02.02

Classes
| GeoidError Geoid interpolator `Geoid...` or interpolation issue.
| _GeoidBase (INTERNAL) Base class for `Geoid...`s.
| GeoidEGM96 Geoid height interpolator for the EGM96 15 Minute Interpolation Grid based on `SciPy` interpolation RectBivariateSpline, interp2d or bisplrep/-ev.
| 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` interpolation RectBivariateSpline, interp2d or bisplrep/-ev.
| 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 An issue while 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`
| geoids = `_sys.argv [1:]`

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`.