Reference Frames

Frames

The preferred way to retrieve a frame is by using the get_frame() function.

beyond.frames.frames.get_frame(frame)

Frame factory

Parameters:: frame (str) – name of the desired frame
Returns:: the object representing the frame demanded
Return type:: Frame
Raises:: UnknownFrameError –

However, in some cases this is done for you. See StateVector.frame for example.

CIO Based Frames

beyond.frames.frames.GCRF = <Frame 'GCRF'>: Geocentric Celestial Reference Frame

beyond.frames.frames.CIRF = <Frame 'CIRF'>: Celestial Intermediate Reference Frame

beyond.frames.frames.TIRF = <Frame 'TIRF'>: Terrestrial intermediate Reference Frame

beyond.frames.frames.ITRF = <Frame 'ITRF'>: International Terrestrial Reference Frame

IAU1980 based Frames

beyond.frames.frames.EME2000 = <Frame 'EME2000'>: EME2000 inertial frame (also known a J2000)

beyond.frames.frames.MOD = <Frame 'MOD'>: Mean (Equator) of Date

beyond.frames.frames.TOD = <Frame 'TOD'>: True (Equator) of Date

beyond.frames.frames.PEF = <Frame 'PEF'>: Pseudo Earth Fixed

beyond.frames.frames.TEME = <Frame 'TEME'>: True Equator Mean Equinox

Others

beyond.frames.frames.G50 = <Frame 'G50'>: Gamma 50 Reference Frame

beyond.frames.frames.WGS84 = <Frame 'ITRF'>

World Geodetic System 1984

This is equivalent to ITRF, with an error below the centimeter

Local Orbital Reference Frame

It is possible to attach a frame to a moving object by calling the method Orbit.as_frame() or Ephem.as_frame(). Both are a simple shortcut to the orbit2frame() function.

beyond.frames.frames.orbit2frame(name, ref_orbit, orientation=None, parent=<Frame 'EME2000'>, exists_warning=True)

Create a frame based on a Orbit or Ephem object.

Parameters:

name (str) – Name to give the created frame
ref_orbit (Orbit or Ephem)
orientation (str) – Orientation of the created frame. If orientation is None, the new frame will keep the orientation of the reference frame of the Orbit and move along with the orbit. Other acceptable values are "QSW", "TNW" or "LVLH".
parent (Frame) – Inertial frame to which to attach the LOF
exists_warning (bool) – Disable the warning when creating a frame with an already taken name by setting this value to False

Return type:

Frame

See local for informations regarding orientations.

Local orbital reference frame

beyond.frames.local.to_local(frame, orbit, expanded=True)

Provide the transformation matrix to convert a vector from an inertial frame to a local orbital reference frame of choice

Parameters:

frame (str) – Name of the local orbital frame (‘QSW’ or ‘TNW’)
orbit (List[float]) – cartesian coordinates (length 6)
expanded (bool) – If True the returned matrix is 6x6, 3x3 otherwise

Returns:

Transformation matrix

Return type:

numpy.ndarray

>>> delta_tnw = [1, 0, 0]
>>> p = [-6142438.668, 3492467.560, -25767.25680]
>>> v = [505.8479685, 942.7809215, 7435.922231]
>>> pv = p + v
>>> mat = to_local("TNW", pv, expanded=False).T
>>> delta_inert = mat @ delta_tnw
>>> all(delta_inert == v / norm(v))
True

beyond.frames.local.to_lvlh(orbit)

In the LVLH Local Orbital Reference Frame, z is oriented opposite the position vector, y opposite the angular momentum, and x complete the frame.

Parameters:: orbit (list) – Array of length 6
Returns:: matrix to convert from inertial frame to LVLH
Return type:: numpy.ndarray

>>> delta_lvlh = [0, 0, -1]
>>> p = [-6142438.668, 3492467.560, -25767.25680]
>>> v = [505.8479685, 942.7809215, 7435.922231]
>>> pv = p + v
>>> mat = to_lvlh(pv).T
>>> delta_inert = mat @ delta_lvlh
>>> all(delta_inert == p / norm(p))
True

beyond.frames.local.to_qsw(orbit)

In the QSW Local Orbital Reference Frame, x is oriented along the position vector, z along the angular momentum, and y complete the frame.

The frame is sometimes also called RSW (where R stands for radial).

Parameters:: orbit (list) – Array of length 6
Returns:: matrix to convert from inertial frame to QSW
Return type:: numpy.ndarray

>>> delta_qsw = [1, 0, 0]
>>> p = [-6142438.668, 3492467.560, -25767.25680]
>>> v = [505.8479685, 942.7809215, 7435.922231]
>>> pv = p + v
>>> mat = to_qsw(pv).T
>>> delta_inert = mat @ delta_qsw
>>> all(delta_inert == p / norm(p))
True

beyond.frames.local.to_tnw(orbit)

In the TNW Local Orbital Reference Frame, x is oriented along the velocity vector, z along the angular momentum, and y complete the frame.

Parameters:: orbit (list) – Array of length 6
Returns:: matrix to convert from inertial frame to TNW.
Return type:: numpy.ndarray

>>> delta_tnw = [1, 0, 0]
>>> p = [-6142438.668, 3492467.560, -25767.25680]
>>> v = [505.8479685, 942.7809215, 7435.922231]
>>> pv = p + v
>>> mat = to_tnw(pv).T
>>> delta_inert = mat @ delta_tnw
>>> all(delta_inert == v / norm(v))
True

beyond.frames.frames.Hill = <HillFrame 'HillQSW'>: Hill frame, for the Clohessy-Wiltshire propagator. This frame is curvilinear along it’s tangential axis and can’t be transformed into an other frame. It’s orientation (see beyond.frames.local) depends on the one used by the propagator.

Ground Stations

A ground station may be created using the create_station() function. This will ensure correct frames conversions.

beyond.frames.stations.create_station(name, latlonalt, parent_frame=<Frame 'ITRF'>, mask=None, equatorial=False)

Create a ground station instance

Parameters:

name (str) – Name of the station
latlonalt (tuple of float) –
coordinates of the station, as follow:
- Latitude in degrees
- Longitude in degrees
- Altitude to sea level in meters
parent_frame (Frame) – Planetocentric rotating frame of reference of coordinates.
orientation (str or float) – Heading of the station Acceptable values are ‘N’, ‘S’, ‘E’, ‘W’ or any angle in radians
mask – (2D array of float): First dimension is azimuth counterclockwise strictly increasing. Second dimension is elevation. Both in radians

Returns:

TopocentricFrame

class beyond.frames.stations.TopocentricFrame(name, orientation, center, mask=None)

Base class for ground station

get_mask(azim): Linear interpolation between two points of the mask

visibility(orb, **kwargs)

Visibility from a topocentric frame

see Propagator.iter() for description of arguments handling.

Parameters:

orb (Orbit) – Orbit to compute visibility from the station with

Keyword Arguments:

start (Date) – starting date of the visibility search
stop (Date or datetime.timedelta)
step (datetime.timedelta) – step of the computation
events (bool, Listener or list) – If evaluate to True, compute AOS, LOS and MAX elevation for each pass on this station. If ‘events’ is a Listener or an iterable of Listeners, they will be added to the computation

Any other keyword arguments are passed to the propagator.

Yields:

Orbit –

In-visibility point of the orbit. This Orbit is already: in the frame of the station and in spherical form.

Lagrange Points

beyond.frames.lagrange.lagrange(frame1, frame2, number, name=None, orientation=None)

Create a reference frame centred on Lagrange points

Parameters:

frame1 (Frame) – Most massive object frame
frame2 (Frame) – Less massive object frame
number (int) – Lagrange point number (1 for L1, 2 for L2, …)
name (str) – Name of the frame created.
orientation (Orientation) – If None, the created frame will be sinodic (i.e. oriented in QSW relative to frame2)

Returns:

Centred on the specified Lagrange point.

Return type:

Frame

Creating new frames

Creating new frames is done by creating Center and Orientation objects, and feeding them to Frame.

class beyond.frames.frames.Frame(name, orientation, center, exists_warning=True): Frame base class

class beyond.frames.center.Center(name, body=None)

Center of a reference frame.

This may represent a celestial body center, or the location of a ground station, or an arbitraty point in space

add_link(center, orientation, offset)

Attach the center to an already defined center.

For example when creating an earth ground station, the previously defined center should be Earth.

Parameters:

center (Center) – Parent center
orientation (Orientation) – orientation of the offset relative to the parent center
offset (list or Orbit) – offset relative to the parent center

If ‘offset’ has a ‘propagate’ attribute, it is called to provide a moving offset.

convert_to(date, new_center, orientation)

Compute the offset between to centers, in the given orientation.

Parameters:

date (Date)
new_center (Center or str)
orientation (Orientation)

Returns:

cartesian coordinates of the center relative: to the new_center.

Return type:

numpy.ndarray

class beyond.frames.orient.Orientation(name)

Rotation matrix generator for frame transformation handling

convert_to(date, new_orient)

Provide the rotation matrix to transform a vector in a given orientation (self) to another (new_orient)

Parameters:

date (Date)
new_orient (str or Orientation)

Returns:

6x6 rotation matrix

Return type:

numpy.ndarray

class beyond.frames.orient.LocalOrbitalOrientation(name, statevector, orient, parent): Local Orbital Orientation

class beyond.frames.orient.TopocentricOrientation(name, latlonalt, parent=<Orientation 'ITRF' at '0x79f5b38818b0'>): Orientation for handling topocentric frames i.e. ground stations

Earth Orientation Parameters

IAU1980

Implementation of the IAU 1980 Earth orientation model

beyond.frames.iau1980.earth_orientation(date): Earth Orientation as a rotation matrix

beyond.frames.iau1980.equinox(date, eop_correction=True, terms=106, kinematic=True): Equinox equation in degrees

beyond.frames.iau1980.nutation(date, eop_correction=True, terms=106): Nutation as a rotation matrix

beyond.frames.iau1980.precesion(date): Precession as a rotation matrix

beyond.frames.iau1980.rate(date)

Return the rotation rate vector of the earth for a given date

This rate is given in the pseudo-inertial frame (TOD)

beyond.frames.iau1980.sideral(date, longitude=0.0, model='mean', eop_correction=True, terms=106): Sideral time as a rotation matrix

IAU2000

Implementation of the IAU 2010 Earth orientation model

beyond.frames.iau2010.earth_orientation(date): Earth orientation as a rotating matrix

beyond.frames.iau2010.precesion_nutation(date): Precession/nutation joint rotation matrix for the IAU2010 model

beyond.frames.iau2010.rate(date)

Return the rotation rate vector of the earth for a given date

This rate is given in the pseudo-inertial frame (CIRF)

beyond.frames.iau2010.sideral(date): Sideral time as a rotation matrix