Orbits#

When we talk about orbits in this context we talk about trajectory lines. In Gaia Sky, trajectory lines may be created from two different sources. Each source is handled by a class implementing the IOrbitDataProvider (IOrbitDataProvider) interface, which is also specified in their orbit object. Parameters available for Orbit archetypes are documented in the Trajectory component.

  • An orbit data file. In this case, the orbit data provider is OrbitFileDataProvider. This file contains four columns:

    • Time – the time, either as a string in the form YYYY-MM-dd_HH:mm:ss, or as a plain Julian date number.

    • X, Y, and Z coordinates, in the internal reference system and Kilometers.

  • The orbital elements, where the orbit data provider is OrbitalParametersProvider.

A sampled orbit comes from an orbit data file. In Gaia Sky, the orbits of all major planets are sampled, as well as the orbit of Gaia. For instance, the orbit of Venus.

{
    "name" : "Venus orbit",
    "color" : [1.0, 1.0, 1.0, 0.55],
    "componentType" : "Orbits",

    "parent" : "Sol",
    "archetype" : "Orbit",
    "provider" : "gaiasky.data.orbit.OrbitFileDataProvider",

    "orbit" : {
        "source" : "$data/default-data/orb.VENUS.dat",
    }
}

If the orbit is defined with its orbital elements, the elements need to be specified in the orbit object. For example, the orbit of Phobos.

{
    "name" : "Phobos orbit",
    "color" : [0.7, 0.7, 1.0, 0.4],
    "componentType" : "Orbits",

    "parent" : "Mars",
    "archetype" : "Orbit",
    "provider" : "gaiasky.data.orbit.OrbitalParametersProvider",

    "orbit" : {
        "period" : 0.3187,
        "epoch" : 2451545.0,
        "reference" : "laplace",
        "referencePole" : [317.7, 52.9],
        "semiMajorAxis" : 9375.0,
        "eccentricity" : 0.015,
        "inclination" : 1.1,
        "ascendingNode" : 169.2,
        "argOfPericenter" : 216.3,
        "meanAnomaly" : 189.7,
        "mu" : 4.2828e13
    }
}

The “orbit” object contains the Keplerian orbital elements:

  • period – in days.

  • epoch – in Julian days.

  • semiMajorAxis – in km.

  • eccentricity – no units.

  • inclination – in degrees.

  • ascendingNode – in degrees.

  • argOfPericenter – in degrees.

  • meanAnomaly – in degrees.

  • newMethod – set to true to evaluate the orbit using the modern orbit-element algorithm, instead of the legacy one.

  • fadeIn – the fade-in distances of the orbit line, in parsecs.

  • fadeOut – the fade-out distances of the orbit line, in parsecs.

  • mu – \(G*M\) of the central body (gravitational constant). Defaults to the Sun’s. It is recomputed automatically from the period (\(T\)) and the semi-major axis (\(a\)) when both are set, as \(\mu=4 * \pi^{2} a^{3} / T^{2}\).

  • reference – the reference plane the elements are expressed in. One of inherited (default), parentEquator, parentOrbitalPlane, ecliptic or laplace. See reference planes.

  • referencePole – the pole of the reference plane, as [right ascension, declination] in degrees in the equatorial frame of J2000. Overrides the pole that reference derives, and is the only way to specify a laplace plane.

Reference planes

Since 3.10.0

The inclination is the angle between the orbital plane and an unnamed plane, and the longitude of the ascending node is measured from an unnamed direction within that plane. The same numbers therefore describe different orbits in different frames, which is fine while they are our own, and a problem as soon as they come from a published table. The reference attribute names the plane explicitly; elements that do not set it keep the historical behaviour:

  • inherited (default) – the plane is resolved implicitly, from the reference-plane transform of the trajectory (the referencePlane/refPlane or transformFunction attribute) if there is one, else from the orientation of the parent body, else it is the equator. This is exactly the behaviour prior to 3.10.0.

  • parentEquator (JPL EQ) – the equatorial plane of the parent, whose pole is taken from the parent’s own rotation model, so the orbit is flattened onto the same equator the parent is drawn with. This is the classical convention for natural satellites.

  • parentOrbitalPlane (JPL POP) – the plane in which the parent orbits its own parent, whose pole is sampled from the parent’s coordinates. For a planet of the solar system this is very nearly the ecliptic; the two differ by the planet’s own inclination.

  • ecliptic (JPL EC) – the ecliptic of J2000, with the reference direction at the vernal equinox. This is what the eclipticToEquatorial transform function produces, and what JPL uses for irregular satellites, whose planes are set by the capture geometry.

  • laplace (JPL LP) – the plane about which the orbital plane precesses, whose normal is the orbital precession pole. It coincides with the equator of the parent for a close satellite and with the orbital plane of the parent for a distant one, and for the satellites in between it is neither, so it cannot be derived from the parent. Give it in referencePole; without a pole it falls back to parentEquator and logs a warning.

In every explicit mode the reference direction is the ascending node of the reference plane on the equatorial plane of J2000, which is where the JPL satellite tables measure their longitudes of the ascending node from, so their inclinations and nodes can be transcribed without arithmetic. The plane is constant, so it is resolved once and cached. When the reference is explicit, neither the reference-plane transform of the trajectory nor the orientation of the parent play any part in the frame. The names are case-insensitive, and the JPL two-letter codes and the hyphenated and underscore-free variants are accepted as well.

The elements of Phobos in the example above are the JPL values for the orbit of the satellite, and JPL expresses them on its Laplace plane, which is what the reference and referencePole attributes carry. The pole of that plane sits very close to the one of Mars, as it must for a satellite this close to its planet. The elements of a satellite that has no Laplace plane of its own, an irregular one, would use ecliptic instead.

The orbital elements of extrasolar systems are typically given in a special reference system. In this reference system, the reference plane is the plane whose normal is the line of sight vector from the Sun to the planet or star for which the orbit is defined. The reference direction is the direction from the object to the north celestial pole projected on the reference plane. In order to apply such a transformation automatically, Gaia Sky provides an additional attribute "model" to objects of the archetype Orbit. When this attribute has the value "extrasolar_system", the transformation described above is applied automatically. The default value of "model" is "default". Below is an example:

{
   "name": "J0805+4812 star orbit",
   "color": [
     1.0,
     0.0,
     1.0,
     1.0
   ],
   "componentType": [
     "Orbits",
     "Stars"
   ],
   "parent": "J0805+4812 Center",
   "archetype": "Orbit",
   "provider": "gaiasky.data.orbit.OrbitalParametersProvider",
   "model": "extrasolar_system",
   "newMethod": true,

   "trail" : true,
   "trailMap" : 0.5,

   "fadeIn" : [ 50.0e3, 100.0e3 ],
   "fadeOut" : [ 100.0e3, 200.0e3 ],

   "orbit": {
     "period": 735.9078666506588,
     "epoch": 2457397.4170103897,
     "semiMajorAxis": 48464416.969729796,
     "eccentricity": 0.4203524474493615,
     "inclination": 107.89617887219426,
     "ascendingNode": 175.09066812003118,
     "argOfPericenter": 326.7130552945523,
     "meanAnomaly": 0.0,
     "mu": 9.9998e+21
   }
 }
Since 3.5.0

Attributes available to Orbit archetypes are defined in the Trajectory component documentation.

TLE Orbits#

Some satellite orbits need to update the orbital elements quite often to stay up to date. Gaia Sky provides the functionality of automatically updating orbital elements of satellites by reading them in TLE (Two-Line Element set) format from the internet. To use this, your object must use the OrbitTLE archetype. This has three additional attribute:

  • urlTLE – URL to read the TLE data from.

  • nameTLE – name in the TLE file for this particular craft. Typically, a TLE file contains the data for multiple objects. This name matches the name line in the file to select the object.

  • updateIntervalTLE – the update interval, in days. Elements read from TLE are cached in special files in the data directory. These files are used unless they are older than the time specified here. This is the number of days (integer plus day fraction) that need to elapse until a new update of the TLE data is attempted. Set negative to update every time.

Heliotropic orbits#

Provides coordinates of objects in heliotropic orbits using those orbits’ data, like Gaia or JWST. The implementation is in HeliotropicOrbitCoordinates. Heliotropic orbits use the archetype HeliotropicOrbit, and their parent is typically the object they orbit. These orbits only make sense when attached to objects around the Earth, as they get rotated by the sun longitude angle.

On this page

This Page