Reference Frames



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


Frame factory


frame (str) – name of the desired frame


the object representing the frame demanded

Return type




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


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.

  • 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" or "TNW".

  • 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


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

  • 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


Transformation matrix

Return type


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

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) or LVLH (Local Vertical Local Horizontal).


orbit (list) – Array of length 6


matrix to convert from inertial frame to QSW

Return type


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

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


orbit (list) – Array of length 6


matrix to convert from inertial frame to TNW.

Return type


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

  • 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



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

Base class for ground station


Linear interpolation between two points of the mask

visibility(orb, **kwargs)

Visibility from a topocentric frame

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


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.



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

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


Centred on the specified Lagrange point.

Return type


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, 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

Attach the center to an already defined center.

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

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


cartesian coordinates of the center relative

to the new_center.

Return type


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)


6x6 rotation matrix

Return type


class beyond.frames.orient.LocalOrbitalOrientation(name, statevector, orient, parent)

Local Orbital Orientation

class beyond.frames.orient.TopocentricOrientation(name, latlonalt, parent=<Orientation 'ITRF' at '0x7f0787b059d0'>)

Orientation for handling topocentric frames i.e. ground stations

Earth Orientation Parameters


Implementation of the IAU 1980 Earth orientation model


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


Precession as a rotation matrix


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


Implementation of the IAU 2010 Earth orientation model


Earth orientation as a rotating matrix


Precession/nutation joint rotation matrix for the IAU2010 model


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

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


Sideral time as a rotation matrix