Package pygeodesy :: Module trf

Module trf

Veness' Terrestrial Reference Frames (TRF).

Classes RefFrame, registry RefFrames and TRFError.

Following is a copy of the comments in Veness' latlon-ellipsoidal-referenceframe.js.

Modern geodetic reference frames: a latitude/longitude point defines a geographic location on, above or below the earth’s surface, measured in degrees from the equator and the International Reference Meridian (IRM) and metres above the ellipsoid within a given Terrestrial Reference Frame at a given epoch.

This is scratching the surface of complexities involved in high precision geodesy, but may be of interest and/or value to those with less demanding requirements. More information here and here.

Note that ITRF solutions do not directly use an ellipsoid, but are specified by Cartesian coordinates. The GRS80 ellipsoid is recommended for transformations to geographical coordinates.

Note WGS84(G730/G873/G1150) are coincident with ITRF at 10-centimetre level, see also here. WGS84(G1674) and ITRF20014 / ITRF2008 "are likely to agree at the centimeter level", see also QPS/Qinsy.

Version: 24.03.12

Classes
	RefFrame Terrestrial Reference Frame (TRF) parameters.
	TransformXform Helmert transformation, extended with an `Xform` TRF converter.
	TRFXform7Tuple 7-Tuple `(tx, ty, tz, s, sx, sy, sz)` of conversion parameters with translations `tx`, `ty` and `tz` in `milli-meter`, scale `s` in `ppB` and rotations `sx`, `sy` and `sz` in `milli-arc-seconds`.
	TRFXform A Terrestrial Reference Frame (TRF) converter between two reference frames observed at an `epoch`.

Functions

date2epoch(year, month, day)
Return the epoch for a calendar day.

epoch2date(epoch)
Return the date for a reference frame epoch.

trfTransform0(reframe, reframe2, epoch=None, epoch2=None, indirect=True, inverse=True, exhaust=False)
Get a Helmert transform to convert one reframe observed at epoch to an other reframe2 at observed at epoch2 or epoch.

trfTransforms(reframe, reframe2, epoch=None, epoch2=None, indirect=True, inverse=True, exhaust=False)
Yield all Helmert transform to convert one reframe observed at epoch to an other reframe2 at observed at epoch2 or epoch.

trfXform(reframe1, reframe2, epoch=None, xform=None, rates=None, raiser=True)
Define a new Terrestrial Reference Frame (TRF) converter or get an existing one.

Variables
	__all__ = `_ALL_LAZY.trf`
	RefFrames = `RefFrames.ETRF89: RefFrame(name='ETRF89', epoch=19...` Some pre-defined RefFrames, all lazily instantiated.
	RefFrames.ETRF2000 RefFrame(name='ETRF2000', epoch=2005, datum=Datums.GRS80) .Xforms=(0, -14)
	RefFrames.ETRF2005 RefFrame(name='ETRF2005', epoch=2005, datum=Datums.GRS80) .Xforms=(0, -1)
	RefFrames.ETRF2008 RefFrame(name='ETRF2008', epoch=2008, datum=Datums.GRS80) .Xforms=(0, 0)
	RefFrames.ETRF2014 RefFrame(name='ETRF2014', epoch=2014, datum=Datums.GRS80) .Xforms=(0, -14)
	RefFrames.ETRF2020 RefFrame(name='ETRF2020', epoch=2020, datum=Datums.GRS80) .Xforms=(0, -14)
	RefFrames.ETRF88 RefFrame(name='ETRF88', epoch=1988, datum=Datums.GRS80) .Xforms=(0, 0)
	RefFrames.ETRF89 RefFrame(name='ETRF89', epoch=1989, datum=Datums.GRS80) .Xforms=(0, -1)
	RefFrames.ETRF90 RefFrame(name='ETRF90', epoch=1990, datum=Datums.GRS80) .Xforms=(0, -1)
	RefFrames.ETRF91 RefFrame(name='ETRF91', epoch=1991, datum=Datums.GRS80) .Xforms=(0, -1)
	RefFrames.ETRF92 RefFrame(name='ETRF92', epoch=1992, datum=Datums.GRS80) .Xforms=(0, -1)
	RefFrames.ETRF93 RefFrame(name='ETRF93', epoch=1993, datum=Datums.GRS80) .Xforms=(0, -1)
	RefFrames.ETRF94 RefFrame(name='ETRF94', epoch=1994, datum=Datums.GRS80) .Xforms=(0, -1)
	RefFrames.ETRF96 RefFrame(name='ETRF96', epoch=1996, datum=Datums.GRS80) .Xforms=(0, -1)
	RefFrames.ETRF97 RefFrame(name='ETRF97', epoch=1997, datum=Datums.GRS80) .Xforms=(0, -1)
	RefFrames.GDA2020 RefFrame(name='GDA2020', epoch=2020, datum=Datums.GRS80) .Xforms=(0, -4)
	RefFrames.GDA94 RefFrame(name='GDA94', epoch=1994, datum=Datums.GRS80) .Xforms=(0, -3)
	RefFrames.ITRF2000 RefFrame(name='ITRF2000', epoch=1997, datum=Datums.GRS80) .Xforms=(15, -5)
	RefFrames.ITRF2005 RefFrame(name='ITRF2005', epoch=2000, datum=Datums.GRS80) .Xforms=(8, -3)
	RefFrames.ITRF2008 RefFrame(name='ITRF2008', epoch=2005, datum=Datums.GRS80) .Xforms=(17, -2)
	RefFrames.ITRF2014 RefFrame(name='ITRF2014', epoch=2010, datum=Datums.GRS80) .Xforms=(16, -1)
	RefFrames.ITRF2020 RefFrame(name='ITRF2020', epoch=2015, datum=Datums.GRS80) .Xforms=(16, 0)
	RefFrames.ITRF88 RefFrame(name='ITRF88', epoch=1988, datum=Datums.GRS80) .Xforms=(3, -4)
	RefFrames.ITRF89 RefFrame(name='ITRF89', epoch=1989, datum=Datums.GRS80) .Xforms=(4, -4)
	RefFrames.ITRF90 RefFrame(name='ITRF90', epoch=1988, datum=Datums.GRS80) .Xforms=(6, -4)
	RefFrames.ITRF91 RefFrame(name='ITRF91', epoch=1988, datum=Datums.GRS80) .Xforms=(4, -4)
	RefFrames.ITRF92 RefFrame(name='ITRF92', epoch=1988, datum=Datums.GRS80) .Xforms=(4, -4)
	RefFrames.ITRF93 RefFrame(name='ITRF93', epoch=1988, datum=Datums.GRS80) .Xforms=(4, -4)
	RefFrames.ITRF94 RefFrame(name='ITRF94', epoch=1993, datum=Datums.GRS80) .Xforms=(4, -4)
	RefFrames.ITRF96 RefFrame(name='ITRF96', epoch=1997, datum=Datums.GRS80) .Xforms=(5, -5)
	RefFrames.ITRF97 RefFrame(name='ITRF97', epoch=1997, datum=Datums.GRS80) .Xforms=(5, -4)
	RefFrames.NAD83 RefFrame(name='NAD83', epoch=1997, datum=Datums.GRS80) .Xforms=(0, -6)
	RefFrames.NAD83cors96 RefFrame(name='NAD83cors96', epoch=1997, datum=Datums.GRS80) .Xforms=(1, 0)
	RefFrames.WGS84 RefFrame(name='WGS84', epoch=1984, datum=Datums.GRS80) .Xforms=(0, -1)
	RefFrames.WGS84g1150 RefFrame(name='WGS84g1150', epoch=2001, datum=Datums.GRS80) .Xforms=(1, 0)
	RefFrames.WGS84g1674 RefFrame(name='WGS84g1674', epoch=2005, datum=Datums.GRS80) .Xforms=(0, 0)
	RefFrames.WGS84g1762 RefFrame(name='WGS84g1762', epoch=2005, datum=Datums.GRS80) .Xforms=(0, 0)

Function Details

date2epoch (year, month, day)

Return the epoch for a calendar day.

Arguments:

year - Year of the date (scalar).
month - Month in the year (scalar, 1..12).
day - Day in the month (scalar, 1..31).

Returns:

Epoch, the fractional year (float).

Raises:

TRFError - Invalid year, month or day.

Note: Any year is considered a leap year, i.e. having 29 days in February.

epoch2date (epoch)

Return the date for a reference frame epoch.

Arguments:

epoch - Fractional year (scalar).

Returns:

3-Tuple (year, month, day).

Raises:

TRFError - Invalid epoch.

Note: Any year is considered a leap year, i.e. having 29 days in February.

trfTransform0 (reframe, reframe2, epoch=None, epoch2=None, indirect=True, inverse=True, exhaust=False)

Get a Helmert transform to convert one reframe observed at epoch to an other reframe2 at observed at epoch2 or epoch.

Returns:: A TransformXform instance, a 0-tuple for unity, identity or None if no conversion exists.

See Also: Function trfTransforms for futher details.

trfTransforms (reframe, reframe2, epoch=None, epoch2=None, indirect=True, inverse=True, exhaust=False)

Yield all Helmert transform to convert one reframe observed at epoch to an other reframe2 at observed at epoch2 or epoch.

Arguments:

reframe - The frame to convert from (RefFrame or str).
reframe2 - The frame to convert to (RefFrame or str).
epoch - Epoch to observe from (Epoch, scalar or str), otherwise reframe's epoch.
epoch2 - Optional epoch to observe to (Epoch, scalar or str), otherwise epoch.
indirect - If True, include transforms via one intermediate reframe, otherwise only direct reframe to reframe2 transforms (bool).
inverse - If True, include inverse, otherwise only forward transforms (bool).
exhaust - If True, exhaustively generate all transforms, forward and inverse and via any number of intermediate reframes (bool).

Returns:

A TransformXform instance for each available conversion, without duplicates.

Raises:

TRFError - Invalid reframe, reframe2, epoch or epoch2.
TypeError - Invalid reframe or reframe2.

trfXform (reframe1, reframe2, epoch=None, xform=None, rates=None, raiser=True)

Define a new Terrestrial Reference Frame (TRF) converter or get an existing one.

Arguments:

reframe1 - Source frame (RefFrame or str), converting from.
reframe2 - Destination frame (RefFrame or str), converting to.
epoch - Epoch, a fractional year (Epoch, scalar or str) or None for reframe2's epoch.
xform - Transform parameters (TRFXform7Tuple).
rates - Rate parameters (TRFXform7Tuple), as xform, but in units-per-year.
raiser - If False, do not raise an error if the converter exists, replace it (bool).

Returns:

The new TRF converter (TRFXform) or if no epoch, xform and rates are given, return the existing one (TRFXform) or None if not available.

Raises:

TRFError - Invalid reframe1, reframe2, epoch, xform or rates or the TRF converter already exists.

Variables Details

RefFrames

Some pre-defined RefFrames, all lazily instantiated.

Value:

RefFrames.ETRF89: RefFrame(name='ETRF89', epoch=1989, datum=Datums.GRS
80),
RefFrames.NAD83cors96: RefFrame(name='NAD83cors96', epoch=1997, datum=
Datums.GRS80),
RefFrames.GDA2020: RefFrame(name='GDA2020', epoch=2020, datum=Datums.G
RS80),
RefFrames.ETRF92: RefFrame(name='ETRF92', epoch=1992, datum=Datums.GRS
80),
...