pyegt.height

class pyegt.height.HeightModel(lat: float, lon: float, region: str | Literal[None] | None = None, from_model: str | Literal[None] | None = None, from_vrs: CRS | Literal[None] | None = None, from_wkt: str | Literal[None] | None = None, from_epsg: str | int | Literal[None] | None = None)

Look up the geoid, tidal, or geopotential model height above the ellipsoid in order to convert model-referenced heights to ellipsoid height (i.e. compatible with Cesium) and vice-versa.

The following figure demonstrates the difference between geoid, ellipsoid, and topographic ground surface:

Diagram showing conceptual model of ellipsoid height h, geoid height H, and height of geoid relative to ellipsoid N along with topographic surface (grey).

Ellipsoidal height (h) is generally used in global projections such as Cesium due to its small digital footprint and ease of calculation relative to systems based on gravity or geopotential height. However, gravity and tides are influenced by local differences in Earth’s density and other factors. Therefore some projects prefer reference systems that use height referenced to a geoid or tidal model (H) which provides a much easier framework to understand height relative to, for example, modeled mean sea level or sea level potential. Converting from H to h requires knowing the height difference between the geoid and the ellipsoid (N). Conversion is then a simple addition of these values (H + N = h).

The lookup performed by this pyegt.height.HeightModel class will use either the NGS or VDatum API to look up model height relative to the ellipsoid (N).

Parameters:

• lat (float) – Decimal latitude

• lon (float) – Decimal longitude

• region (str or None) – Region (for list see pyegt.height.HeightModel.from_model())

• from_model (str or None) – Model (for list see pyegt.height.HeightModel.available_regions())

• from_vrs (pyproj.CRS or None) – The vertical reference system to convert from (CRS.is_vertical must be true for the main CRS or a sub-CRS)

• from_wkt (str or None) – Use well-known text to get a VRS to convert from

• from_epsg (str or None) – Use an EPSG code to get a VRS to convert from

Raises:

AttributeError – if more than one of [from_model, from_vrs, from_wkt, from_epsg] is set

__eq__(_HeightModel__value: object) → bool

Use math.isclose() to compare as floating point numbers are not always directly comparable.

Returns:

Boolean equality of two floats

Return type:

bool

Raises:

ValueError – if no self.height value exists

__float__() → float

Convert to float.

Returns:

Height value (if exists)

Return type:

float

Raises:

ValueError – if no self.height value exists

__repr__() → str

Convert to printable representation, for example:

>>> from pyegt.height import HeightModel
>>> h = HeightModel(lat=64.506181, lon=-165.399282, from_model='EGM2008', region='ak')
>>> repr(h)
HeightModel(lat=64.506181, lon=-165.399282, from_model='EGM2008', region='ak') -> 6.998 meters

Returns:

repr() value

Return type:

str

__str__() → str

Convert to string.

Returns:

String representation of height or "n/a"

Return type:

str

as_dict() → dict

Return JSON object as dict using __dict__.

Returns:

JSON object

Return type:

dict

as_float() → float

Convert to float using __float__.

Returns:

Height value (if exists)

Return type:

float

as_string() → str

Convert to string using __str__.

Returns:

The height value in meters represented in string format

Return type:

str

available_models() → list

Return a list of available geoid and tidal models.

Returns:

List of models

Return type:

list

available_regions() → list

Return a list of regions usable with VDatum models. See VDatum regions in the docs.

Regions:

['contiguous', 'ak', 'seak', 'as', 'chesapeak_delaware',
'westcoast', 'gcnmi', 'hi', 'prvi', 'sgi', 'spi', 'sli']

Returns:

List of regions

Return type:

list

from_epsg(epsg: str | int | Literal[None])

Compute the height above the ellipsoid for the given EPSG code.

Parameters:

epsg (str or int or None) – EPSG code indicating a vertical reference system

Returns:

The modeled geoid height above the ellipsoid

Return type:

float

from_model(model: str | Literal[None] | None = None)

Compute the height above the ellipsoid for the given model name. Will set self.model if the model variable is supplied. Finally, it will call self.get_height().

Valid model values are:

# using NGS API
['GEOID99', 'G99SSS', 'GEOID03', 'USGG2003', 'GEOID06', 'USGG2009',
'GEOID09', 'XUSHG', 'USGG2012', 'GEOID12A', 'GEOID12B', 'GEOID18',]

# using VDatum API
['NAVD88', 'NGVD29', 'ASVD02', 'W0_USGG2012', 'GUVD04', 'NMVD03',
'PRVD02', 'VIVD09', 'CRD', 'EGM2008', 'EGM1996', 'EGM1984',
'XGEOID16B', 'XGEOID17B', 'XGEOID18B', 'XGEOID19B', 'XGEOID20B',
'IGLD85', 'LWD_IGLD85', 'OHWM_IGLD85', 'CRD', 'LMSL', 'MLLW',
'MLW', 'MTL', 'DTL', 'MHW', 'MHHW', 'LWD', 'NAD27', 'NAD83_1986',
'NAD83_2011', 'NAD83_NSRS2007', 'NAD83_MARP00', 'NAD83_PACP00',
'WGS84_G1674', 'ITRF2014', 'IGS14', 'ITRF2008', 'IGS08',
'ITRF2005', 'IGS2005', 'WGS84_G1150', 'ITRF2000', 'IGS00', 'IGb00',
'ITRF96', 'WGS84_G873', 'ITRF94', 'ITRF93', 'ITRF92', 'SIOMIT92',
'WGS84_G730', 'ITRF91', 'ITRF90', 'ITRF89', 'ITRF88',
'WGS84_TRANSIT', 'WGS84_G1762', 'WGS84_G2139']

Documentation can be found here for the NGS and VDatum APIs.

Parameters:

model (str or None) – Model to use for lookup

Returns:

The height of the given model in the given location

Return type:

float

Raises:

AttributeError – if no model has been set

from_vrs(vrs: CRS | Literal[None])

Compute the height above the ellipsoid for the given vertical reference system.

Parameters:

vrs (pyproj.crs.CRS or None) – Vertical reference system

Returns:

The modeled geoid height above the ellipsoid

Return type:

float

Raises:

AttributeError – if no VRS has been set

from_wkt(wkt: str | Literal[None])

Compute the height above the ellipsoid for the given well-known text VRS.

Parameters:

wkt (str or None) – Well-known text describing a vertical reference system

Returns:

The modeled geoid height above the ellipsoid

Return type:

float

get_height() → float

Get the height in meters of the given self.model above the ellipsoid.

Returns:

The modeled geoid height above the ellipsoid

Return type:

float

Raises:

ValueError – if no model is found matching self.model

in_cm() → float

Convert to centimeters (self.height * 100).

Returns:

Height value in cm (if it exists)

Return type:

float

in_feet() → float

Convert to imperial foot (for US survey feet use in_feet_us_survey()). 1 imperial foot = 0.999998 US survey feet

Returns:

Height value in ft (if it exists)

Return type:

float

in_feet_us_survey() → float

Convert to US survey foot (for imperial feet use in_feet()). 1 imperial foot = 0.999998 US survey feet

Returns:

Height value in usft (if it exists)

Return type:

float

verify_model() → bool

Search for a model in the list of known models.

Parameters:

vrs (str) – The search term, potentially a phrase containing the model name; ex: EGM2008 height will return EGM2008

Returns:

Returns the correctly formatted model name to use in the API query

Return type:

str

---

• Index

• Search Page

Back to top ↑