.. _coordinate-providers: Coordinates and ephemerides *************************** Within the ``coordinates`` object (see the :ref:`Coordinates component `) one specifies how to get the positional data of the entity given a time. This object contains a reference to the implementation class (which must implement ``IBodyCoordinates`` `IBodyCoordinates `__) and the necessary parameters to initialize it. There are currently a few implementations that can be used with the ``"impl"`` attribute. They are described in the following sub-sections. Orbit coordinates ================= Using ``OrbitLintCoordinates``, the coordinates of the object are linearly interpolated using its orbit, which is defined in a separate entity. See the :ref:`orbits section ` for more info. The ``name`` of the orbit entity must be given. For instance, the Hygieia moon uses orbit coordinates. .. code:: json { "coordinates" : { "impl" : "gaiasky.util.coord.OrbitLintCoordinates", "orbitName" : "Hygieia orbit" } } There are many types of orbit coordinates providers. The next sections describe the most important of them. .. rubric:: Periodicity Some trajectories are not periodic, like those for spacecraft like the Voyagers. In this case, we can instruct the ``coordinates`` object to not extend beyond the time span in the orbit file by using the ``periodic`` attribute: .. code:: json { "coordinates" : { "impl" : "gaiasky.util.coord.OrbitLintCoordinates", "periodic": false, "orbitName" : "Artemis2 orbit" } } Heliotropic orbit coordinates ============================= This defines coordinates coming from a :ref:`heliotropic orbit `. These orbits rotate with the Solar longitude, $L_s$, which is the ecliptic longitude of the Sun. This only makes sense for objects attached or around the Earth. Combining orbit coordinates =========================== Sometimes, an object needs to combine coordinates from different orbits in different parts of its lifetime. For example, Gaia has its main Lissajous orbit around L2 during its operations phase, and then it was put in a heliocentric orbit around the Sun. Since this requires a reference system change (L2 vs the Sun), two different orbit objects must be used at different dates. To do so, there are a couple of special coordinates providers: - ``TimedOrbitCoordinates`` -- wraps around a regular orbit coordinates object and includes a time range delimited by start and end, during which the coordinates of this object are active. It can also include a parent object, in which case, the owner of the orbit will change its parent when the orbit becomes active. - ``ComposedTimedOrbitCoordinates`` -- contains a list of ``TimedOrbitCoordinates``, and selects and applies the right one depending on the current date. For example, this is a valid coordinates provider for the Gaia spacecraft: .. code:: json { "coordinates": { "impl": "gaiasky.util.coord.ComposedTimedOrbitCoordinates", "processOnlyActive": true, "sequence": [ { "impl": "gaiasky.util.coord.TimedOrbitCoordinates", "start": "2013-01-01T00:00:00.00Z", "end": "2025-06-15T13:42:00.00Z", "parent": "Earth", "coordinates": { "impl": "gaiasky.util.coord.HeliotropicOrbitCoordinates", "orbitName": "Gaia orbit" } }, { "impl": "gaiasky.util.coord.TimedOrbitCoordinates", "start": "2025-06-15T13:42:00.00Z", "end": "2050-03-25T18:30:00.00Z", "parent": "Sun", "coordinates": { "impl": "gaiasky.util.coord.OrbitLintCoordinates", "orbitName": "Gaia heliocentric orbit" } } ] } This ``ComposedTimedOrbitCoordinates`` contains a sequence with two ``TimedOrbitCoordinates`` objects. One references the orbit object called "Gaia orbit", and the other references "Gaia heliocentric orbit". Note that the first one has "Earth" as parent, while the second one has "Sun" as parent. This means that, whenever the provider changes the orbit selection, the Gaia object will be moved from one parent to the other. The orbit objects referenced by these providers could look like this: .. code:: json {"objects": [ { "name": "Gaia orbit", "color": [ 1.0, 1.0, 0.2, 0.35 ], "componentTypes": [ "Orbits", "Satellites" ], "parent": "Gaia", "archetype": "HeliotropicOrbit", "provider": "gaiasky.data.orbit.OrbitFileDataProvider", "trail": true, "orbit": { "source": "path/to/orbit-L2.txt" } }, { "name": "Gaia heliocentric orbit", "color": [ 1.0, 0.431, 0.161, 0.55 ], "componentTypes": [ "Orbits", "Satellites" ], "parent": "Sun", "archetype": "Orbit", "provider": "gaiasky.data.orbit.OrbitFileDataProvider", "trail": true, "trailMap": 0.9, "orbit": { "source": "path/to/orbit-heliocentric.txt" } } ]} Static coordinates ================== Use ``StaticCoordinates`` to specify a static position (or a position at epoch for entities with proper motion). This is equivalent to using the top-level ``pos`` attribute, which also specifies the position at epoch. Static coordinates can also be applied a transformation using the ``transformMatrix`` and ``transformName`` attributes. The position may be given in cartesian or spherical coordinates. - ``position`` (with variants: ``positionKm``, ``positionPc``) -- position in cartesian coordinates in the internal reference system. - ``positionEquatorial`` -- equatorial coordinates (:math:`\alpha` [deg], :math:`\delta` [deg], and distance [parsecs]). - ``positionEcliptic`` -- ecliptic coordinates (:math:`\lambda` [deg], :math:`\beta` [deg], and distance [parsecs]). - ``positionGalactic`` -- galactic coordinates (l [deg], b [deg], and distance [parsecs]). .. code:: json { "coordinates" : { "impl" : "gaiasky.util.coord.StaticCoordinates", "position" : [-2.169e17, -1.257e17, -1.898e16] } } VSOP87 ====== All classes that extend ``AbstractVSOP87`` provide ephemerides for the major planets. These implement the ``VSOP87`` analytical solution. Our implementation of VSOP87 contains a class for each body, with all the terms hard-coded. For instance, to set up VSOP87 ephemeris for the Earth use the following: .. code:: json { "coordinates" : { "impl" : "gaiasky.util.coord.vsop87.EarthVSOP87", "orbitName" : "Earth orbit" } } .. raw:: html
Since 3.5.0
VSOP2000 ======== Implementation of the `analytical planetary solution VSOP2000 `__. You just need to point to the file for the particular bodies. Data files are available for Mercury, Venus, Earth, Moon, the Earth-Moon barycentre, Mars, Jupiter, Saturn, Uranus, Neptune and Pluto in ftp://syrte.obspm.fr/francou/vsop2000/. In order to use those, use the VSOP2000 class with the desired data file. .. code:: json { "coordinates" : { "impl" : "gaiasky.util.coord.vsop2000.VSOP2000", "dataFile" : "/path/to/data/vsop2000-p03.dat", "orbitName" : "Earth orbit" } } .. raw:: html
Since 3.5.0
Chebyshev polynomials ===================== Implementation of Chebyshev polynomials using the coefficients to compute the Ephemeris. Just like VSOP2000, each body needs a different data file, containing the coefficients for the body. .. code:: json { "coordinates" : { "impl" : "gaiasky.util.coord.chebyshev.ChebyshevEphemeris", "dataFile" : "/path/to/data/EARTH.position.data", "orbitName" : "Earth orbit" } } Moon AA coordinates =================== ``MoonAACoordinates`` contains a special implementation of the algorithm described in the book Astronomical Algorithms by Jean Meeus that provides the position of the Moon. Pluto coordinates ================= ``PlutoCoordinates`` is a special implementation, described `ppcomp.html#14 `__, which provides very fast but not very accurate positions for Pluto. Python scripting coordinates ============================ ``PythonBodyCoordinates``, reserved for coordinate providers implemented in Python via scripting. This object uses ``IPythonCoordinatesProvider`` instances implemented in a Python script to source coordinates. For more information, see :ref:`this section `.