Celestia/Trajectories

Introduction

The orbits and trajectories of objects in Celestia are predefined. Their definitions are loaded when Celestia starts.

Celestia does not calculate any gravitational effects. All gravitational effects must be included in the orbit and trajectory definitions. Gravitational effects are already incorporated in Celestia's VSOP87 CustomOrbits and in the JPL DE405 ephemeris files which can be used in CustomOrbits, in NASA's SPICE ephemeris files which can be used in SpiceOrbits, and in the SampledOrbits of the spacecraft which are included with Celestia.

In many cases, Celestia assumes that an object will always be at same place at the same time. Periodic orbits have an orbital path drawn for them.

CustomOrbit, EllipticalOrbit and SampledOrbit directives are recognized by all versions of Celestia. FixedPosition, SpiceOrbit and ScriptedOrbit are new directives which require Celestia v1.5.0 or later.

By default, if an SSC or STC object orbits a Star or STC Barycenter, then trajectories are defined relative to our Solar System's J2000 Ecliptic plane. If an SSC object orbits another SSC object, then its trajectory is defined relative to the parent body's J2000 equator. In Celestia v1.5.0 or newer, one also has the option of specifying any of a number of other Reference Frames in an SSC catalog. These new orbit and reference frame directives are not yet recognized in an STC file.

The following is a list of the orbit and trajectory directives which are recognized in SSC files. More information is available on the page Celestia/SSC File.

FixedPosition

Requires Celestia 1.5.0

The FixedPosition trajectory type makes the center of a body stationary within its Reference Frame.

Usage:

FixedPosition [ <x> <y> <z> ]

Units for the coordinates are AU for bodies orbiting Stars or Barycenters, and kilometers for all other objects.

Alternate Usage (Requires Celestia 1.6.0):

It can be convenient to specify a fixed position using spherical rather than rectangular coordinates, thus Celestia offers an alternate form of FixedPosition:

FixedPosition
{
    Planetographic [ <longitude> <latitude> <altitude> ]
}

Longitude and latitude are in degrees; altitude is the height in kilometers above the surface of the parent object.

EllipticalOrbit

An EllipticalOrbit can be used either in an SSC file or in an STC file.

Usage:

EllipticalOrbit
{
    Period <number>

    SemiMajorAxis <number>
    PericenterDistance <number>

    ArgOfPericenter <degrees> 
    LongOfPericenter <degrees> 

    MeanAnomaly <degrees> # default: 0
    MeanLongitude <degrees>

    Eccentricity <number> # default: 0

    Inclination <degrees> # default: 0.0

    AscendingNode <degrees> # default = 0.0 

    Epoch <date> # default: J2000.0
}

A valid EllipticalOrbit requires Period and SemiMajorAxis (or PericenterDistance) to be specified. All the other properties have default values and are optional.

Period

gives the orbital period in Earth years for bodies that orbit Stars or Barycenters, and Earth solar days for all other bodies.

Several of the orbital parameters may be specified in two different ways.

SemiMajorAxis

The size of the orbit can be given as the SemiMajorAxis or PericenterDistance. The latter is more intuitive for hyperbolic orbits. If both SemiMajorAxis and PericenterDistance are specified, SemiMajorAxis overrides PericenterDistance. The units of both SemiMajorAxis and PericenterDistance are AU for bodies that orbit Stars or Barycenters, and kilometers for all other bodies.

ArgOfPericenter

The pericenter angle is given by either ArgOfPericenter or LongOfPericenter. ArgOfPericenter is measured from the ascending node, whereas LongOfPericenter is measured from the fundametal direction. If both ArgOfPericenter and LongOfPericenter are specified, ArgOfPericenter overrides LongOfPericenter.

MeanAnomaly

The position of the body on its orbit at Epoch is given by either the MeanAnomaly or the MeanLongitude. MeanAnomaly is measured from the pericenter angle, whereas MeanLongitude is measured from the fundamental direction. If both MeanAnomaly and MeanLongitude are specified, MeanAnomaly overrides MeanLongitude.

Eccentricity

determines the shape of the orbit. In fact, the name EllipticalOrbit is a bit misleading because the orbit may be circular, elliptical, parabolic, or hyperbolic depending upon the eccentricity:

• eccentricity = 0 – circle
• 0 < eccentricity < 1 – ellipse
• eccentricity = 1 – parabola
• eccentricity > 1 – hyperbola

If Eccentricity is not provided, a circle is assumed.

Inclination

is optionally used to specify how much the orbit is tilted with respect to its reference plane. By default, that plane is the Ecliptic for bodies that orbit Stars or Barycenters, and the equator of the parent object for all other bodies. Starting with Celestia v1.5.0, any of a number of different reference planes can be specified. See Reference Frames for details. If Inclination is not specified, a value of 0 degrees is assumed.

AscendingNode

optionally defines the longitude of the point in its orbit where the orbiting body crosses the reference plane going "upward" or "northward". It is measured in degrees from the fundamental direction. If AscendingNode is not specified, a value of 0 degrees is assumed.

Epoch

optionally specifies the date at which these parameters are valid. It can be provided either as a number or as a quoted string. A number is interpreted as a Julian date. A quoted string is interpreted as a Gregorian date in the format "<year> <month> <day> <hours>:<minutes:<seconds>" e.g. "2007 10 09 12:13:14". If Epoch is omitted, a date of January 1, 2000, is assumed.

Starting with Celestia v1.5.0, Epoch must be specified in TDB. See Celestia/Time Scales for more information about TDB and UTC.

CustomOrbit

A CustomOrbit is an orbit calculation that is built in to Celestia. Orbital theories for all the major planets and most of the larger satellites are available. The valid standard CustomOrbit names are listed below. Starting with Celestia v1.5.0, a JPL DE405 ephemeris can be provided. See JPL Ephemerides for details. A CustomOrbit takes priority over an EllipticalOrbit, but a CustomOrbit which specifies an unrecognized name is ignored.

Usage:

CustomOrbit <name>

Example:

CustomOrbit "vsop87-venus"

The following list gives all of the available CustomOrbits in Celestia 1.5.0:

VSOP87

VSOP87 (Variations Séculaires des Orbites Planétaires) is an orbital theory for the major planets by P. Bretagnon et al. Celestia does not use the full set of terms. For a higher accuracy alternative to VSOP87, JPL Ephemerides may be used for the orbits of the major planets, Pluto, the Moon, and the Sun.

• vsop87-mercury
• vsop87-venus
• vsop87-earth
• vsop87-mars
• vsop87-jupiter
• vsop87-saturn
• vsop87-uranus
• vsop87-neptune
• vsop87-sun (orbit of Sun about the Solar System Barycenter)

Pluto

Reference needed

• pluto

Galilean satellites

From J. H. Lieske's "E5" theory as given in Jean Meeus's Astronomical Algorithms, pp. 301-315:

• io
• europa
• ganymede
• callisto

Satellites of Saturn

From Gérard Dourneau (1987), "Observations et étude du mouvement des huit premiers satellites de Saturne"

• mimas
• enceladus
• tethys
• dione
• rhea
• titan
• hyperion
• iapetus

Satellites of Uranus

From Laskar and Jacobson (1978), "An Analytical Ephemeris of the Uranian Satellites"

• miranda
• ariel
• umbriel
• titania
• oberon

The Moon

Reference needed

• moon

SampledTrajectory

This is available only in Celestia v1.5.0 or later.

SampledTrajectory is used to import an ASCII file containing a list of time stamps and positions (or optionally, positions with velocities.) Typically, such files are generated by trajectory modeling and analysis software.

SampledTrajectory
{
    Source <filename>
    DoublePrecision <boolean>
    Interpolation <string>
} 

The Source property is required, while the others are optional. The contents of the Source file are the same as for a SampledOrbit file. Valid values for interpolation are currently "linear" and "cubic", with cubic the default. DoublePrecision defaults to true. The following two trajectories are equivalent:

SampledTrajectory
{
    Source "file.xyz"
    DoublePrecision false
    Interpolation "cubic"
}

SampledOrbit "file.xyz"

Whenever accuracy is important, SampledTrajectory should be used with DoublePrecision true. Single precision floating point numbers are only precise to about one part in eight million; for an interplanetary trajectory to the outer solar system, this means errors of hundreds of kilometers.

A sampled trajectory file is a list of time and position records. Here's an excerpt from a trajectory file for Galileo:

2447818.615972 134114700.2612462193 64912642.6984842718 39861.799941
2447819.615972 133153386.7785827518 66969511.3118158504 237125.784089
2447820.615972 132137795.3581911474 69024279.8844281882 418499.867572
2447821.615972 131079666.1268854141 71061806.8872888833 596914.157647

The first value on each line is a Julian date (TDB), and that last three values are positions in kilometers. The reference frame for the positions is given in the ssc file. By default, Celestia uses a technique called cubic Hermite interpolation for smooth motion between points.

Celestia 1.6.0 adds support for position and velocity trajectory files. These files have the extension xyzv, and can be used in exactly the same manner as xyz files in a SampledTrajectory:

SampledTrajectory { Source "trajectory.xyzv" }

The records in an xyzv file have the same layout as in an xyz file except that three velocity values are appended after each position. The units for velocity are kilometers per second. For a given file size, xyzv files give much more accurate positioning of objects. Thus, if it's possible to get velocities as well as positions for an object, an xyzv file should always be preferred over an xyz file.

The web interface for HORIZONS can be used to produce trajectories with velocities as well as positions. There's also a new tool for Celestia called spice2xyzv that will generate an xyzv file from one or more SPICE kernels.

SampledOrbit

SampledOrbit is deprecated; SampledTrajectory is more flexible and provides the same functionality.

SampledOrbit is used to import a file of times and associated coordinates.

Usage:

SampledOrbit <name>

Example:

SampledOrbit "galileo.xyz"

The file must be located in the directory named data which is associated with the object.

The file must contain sets of 4 numeric values which define positions along the object's trajectory. The individual values must be separated by spaces, tabs, or line terminators. Celestia reads 4 values for each set and doesn't care what "white space" is used to separate them. The file could contain one number per line or all of the numbers in the file could be on a single line.

Each set of numbers consists of a TDB Julian date followed by x, y and z positions measured in kilometers. They are positions within the coordinate system associated with the object. By default, for example, the SampledOrbit for a spaceprobe orbiting the Sun would contain heliocentric Ecliptic J2000 coordinates. In Celestia v1.5, any of a variety of Reference Frames could be specified. See Celestia/Reference_Frames for details.

Limitation:

Although the x, y and z coordinates may be provided with any precision, Celestia stores them internally as single precision (32 bit) floating point numbers. V1.5.0 of Celestia implements double precision as a separate option. See SampledTrajectory above.

SpiceOrbit

Requires Celestia 1.5.0

SpiceOrbit is used to import a trajectory from NASA's SPICE spacecraft information system into Celestia. Not all versions of Celestia are built with SPICE support.

Usage:

SpiceOrbit
{
    Kernel <filename>
    Target <ID string>
    Origin <ID string>
    Beginning <date>
    Ending <date>
    BoundingRadius <number>
    Period <number>
}

The Kernel property specifies the name of the SPICE kernel (SPK) file to load. Celestia expects the kernel file to reside in an add-on's data directory.

Target is the NAIF ID code for the object that you want to place in Celestia. A list of codes may be found here: http://www.gps.caltech.edu/~marsdata/req/naif_ids.html

Either the integer ID or name may be used. The SpiceOrbit will be ignored if the kernel file does not contain a trajectory for specified object ID. The trajectory coordinates are relative to the position of the Origin object, which is specified with another NAIF ID code. It must match the origin of the reference frame. The coordinate system of the SpiceOrbit is the mean ecliptic and equinox of J2000. This matches the default reference frame that Celestia uses for Sun-orbiting bodies, but not the reference frame for other bodies. For an object that does not orbit the Sun and has its trajectory defined by a SpiceOrbit, you must explicitly specify an ecliptic reference frame:

OrbitFrame
{
    EclipticJ2000 { Center <object name> }
}

Beginning and Ending delimit the time range over which the SPICE trajectory is valid. The values can be either numeric Julian dates or Gregorian date strings. These times must be within the bounding times specified inside the SPICE kernel.

The BoundingRadius of the orbit needs to be supplied in order for culling to work. Period is optional; it's used by Celestia only for orbit path rendering. If it's set to zero or not given at all, the orbit is assumed to be an aperiodic trajectory. The units for BoundingRadius and Period are AU and years for bodies that directly orbit a star, and kilometers and Earth solar days for other bodies. The use of two different units is for consistency with other Celestia trajectory types.

Example: Pluto

This example uses a SPICE kernel for the orbit of Pluto. Note that the origin "SUN" matches the reference frame center, given here by the parent object.

"Pluto" "Sol"
{
    SpiceOrbit
    {
         Kernel "de403_2000-2020.bsp"
         Target "Pluto Barycenter"
         Origin "SUN"
         Beginning "2000 1 1"
         Ending "2020 1 1"
         BoundingRadius 40
         Period 248.0
    }
}

ScriptedOrbit

Requires Celestia 1.5.0

A ScriptedOrbit is used to create custom trajectory functions with Lua scripts.

Usage:

ScriptedOrbit
{
    Module <string>
    Function <string>

    ...additional properties...
}

Module gives the name of a package that will be loaded via Lua's require method. It searches a standard lists of paths for a script file with the specified name. An Addon's ScriptedOrbit's Module file should be located in a directory named celxx in the Addon's main directory. Function is the name of a factory function that produces a table with the orbit properties, including a function that returns the position at a particular time. All of the ScriptedOrbit properties other than Module and Function are passed on to the Lua function to create the orbit object. The function name is the only required parameter.

To create your own ScriptedOrbit, you need to have some familiarity with the Lua scripting language used in Celestia's celx scripts. The Lua function specified in the ScriptedOrbit definition is a factory function that gets called immediately after the ScriptedOrbit is parsed. The factory function accepts a single table parameter containing all the properties from the ScriptedOrbit definition. The function must return a Lua orbit object, which is just a table with several standard fields. They are:

• boundingRadius - A number giving the maximum distance of the trajectory from the origin; must be present, and must be a positive value.
• period - A number giving the period of the orbit. If not present, the orbit is assumed to be aperiodic. The orbital period is only used for drawing the orbit path.
• beginDate, endDate - optional values that specify the time span over which the orbit is valid. If not given, the orbit is assumed to be usable at any time. The orbit is invalid if end < begin.
• position(time) - The position function receives a time value as input (TDB Julian day) and must return three values which are the x, y, and z coordinates. Units for the position are kilometers.

ScriptedOrbits have a few limitations. The only allowed parameters are simple types: strings, numbers, and booleans. Complex types such as arrays and property lists will not be passed on to the Lua factory function. This limitation may disappear in a future version of Celestia. Also, Celestia expects that the position function will always return the same position for identical time values.

Example ScriptedOrbit

Here's an example ScriptedOrbit usage in an .ssc file.

"Scripted" "Sol/Test Object"
{
    Radius 500

    ScriptedOrbit
    {
        Module "orbits"
        Function "lissajous"

        PeriodX 1
        PeriodY 3.1
        PeriodZ 2.4
        PhaseX 0.5
        PhaseY 0.2
        PhaseZ 0.0
        AmplitudeX 1000
        AmplitudeY 800
        AmplitudeZ 540
    }
}

The above ssc fragment tells Celestia to load a file called orbits.lua and invoke the function lissajous to create a new script orbit object. The rest of the properties will all be passed to the lissajous function as fields of a table. Next, the actual Lua function:

function lissajous(t)
   -- Create a new table
   local orbit = {};

   -- Save the parameter list 
   orbit.params = t;

   -- Set the required fields boundingRadius and position; note that position is actually a function

   -- Compute the bounding radius from the amplitudes
   orbit.boundingRadius =
       math.sqrt(t.AmplitudeX * t.AmplitudeX +
                 t.AmplitudeY * t.AmplitudeY +
                 t.AmplitudeZ * t.AmplitudeZ)

   -- The position function will be called whenever Celestia needs the position of the object
   function orbit:position(tjd)
       local t = tjd - 2451545.0
       local pi2 = math.pi * 2;
       local x = self.params.AmplitudeX * math.sin((t / self.params.PeriodX + self.params.PhaseX) * pi2)
       local y = self.params.AmplitudeY * math.sin((t / self.params.PeriodY + self.params.PhaseY) * pi2)
       local z = self.params.AmplitudeZ * math.sin((t / self.params.PeriodZ + self.params.PhaseZ) * pi2)

       return x, y, z
    end

    return orbit
end 

The Lissajous function may be used over and over with different ScriptedOrbit properties. As long as you know what parameters are expected, you can use an orbit script written by someone else without actually writing a line of code your self.