Celestia/Rotation Models

Introduction

All information on this page is relevant only for Celestia 1.5.0 and later.

Prior to v1.5.0, separate rotation statements were used. See the chapter on SSC files for descriptions of those declarations.

UniformRotation

Usage:

UniformRotation
{
   Period <hours>
   Inclination <degrees>
   AscendingNode <degrees>
   MeridianAngle <degrees>
   Epoch <date>
}

Period is the sidereal rotation period of the object; that is, the rotation with respect to some fixed background. Thus the rotation period for the Earth would be 23.93 rather than 24 hours. If no Period is specified, the object will be tidally locked (i.e. always showing the same face to the parent body).

FixedRotation

Usage:

FixedRotation
{
   Inclination <degrees>
   AscendingNode <degrees>
   MeridianAngle <degrees>
}

An object with a FixedRotation will maintain a constant orientation within its reference frame. A fixed rotation has properties identical to UniformRotation except that a rotation period isn't required.

PrecessingRotation

Usage:

PrecessingRotation
{
   Period <hours>
   PrecessionPeriod <years>
   Inclination <degrees>
   AscendingNode <degrees>
   MeridianAngle <degrees>
   Epoch <date>
}

SampledOrientation

Usage:

SampledOrientation <filename>

Where the filename is the name of a Celestia orientation file, which by convention has the extension .q (for quaternion.) The orientation file is a text file containing a time tagged list of quaternions. Times are Julian dates specified in Barycentric Dynamical Time (TDB). Each record in the file has the form:

<double: Julian Date> <float: w> <float: x> <float: y> <float: z>

where w is the real part, and x, y, and z the imaginary parts of a quaternion. A rotation of angle theta about the axis V is given by the quaternion: $(\cos {\frac {\theta }{2}},\mathbf {V} \sin {\frac {\theta }{2}})$

ScriptedRotation

A ScriptedRotation is used create rotation model where the orientation is given by a function in Lua script file.

Usage:

ScriptedRotation
{
    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. Function is the name of a factory function that produces a table with the rotation model properties, including a function that returns the orientation at a particular time. All of the ScriptRotation properties other than Module and Function are passed on to the Lua function to create the rotation object. The function name is the only required parameter.

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

period - A number giving the period of the rotation in days. If not present, the rotation is assumed to be aperiodic.
beginDate, endDate - optional values that specify the time span over which the rotation model is valid. If not given, the rotation model is assumed to be usable at any time. A rotation model with end < begin is not allowed.
orientation(time) - The position function takes a time value as input (TDB Julian day) and returns four values which are the quaternion (w, x, y, z). This quaternion is related to the axis angle rotation (A, theta) by:

$w=\cos {\frac {\theta }{2}}$ , $x=A_{x}\sin {\frac {\theta }{2}}$ , $y=A_{y}\sin {\frac {\theta }{2}}$ , $z=A_{z}\sin {\frac {\theta }{2}}$

Here's an example of how to use a ScriptedRotation in an .ssc file:

"Scripted" "Sol/Earth"
{
    ScriptedRotation
    {
        Module "rotations"
        Function "wobble"
        Period 1
        Amplitude 180
    }
}

The above ssc fragment tells Celestia to load a file called rotations.lua and invoke the function named wobble to create a new rotation model object. The rest of the properties will all be passed to the wobble function as fields of a table. Next, the contents of rotations.lua:

-- prototype for the wobble scripted rotation has default values for
-- any parameters that are omitted in the ssc file.
wobbleproto =
{
   Amplitude = 0,
   Period    = 1,
}

-- constructor method
function wobbleproto:new(o)
   o = o or {}  -- create table if one not provided
   setmetatable(o, self)
   self.__index = self

   -- set the period to whatever value was specified in the ssc file;
   -- slightly confusing because Celestia is case sensitive--period must
   -- be lowercase, but the field from the ssc file is capitalized.
   o.period = o.Period

   return o
end

-- The orientation function. This implementation produces a back and forth
-- wobble of Amplitude degrees about the z axis.
function wobbleproto:orientation(tjd)
   local t = tjd - 2451545.0
   local theta = self.Amplitude * math.sin((t / self.Period + 0) * math.pi * 2);

   -- convert from degrees to radians
   theta = theta * math.pi / 180

   -- compute a quaternion representing the orientation
   return math.cos(theta / 2), 0, 0, math.sin(theta / 2)
end

function wobble(sscvals)
   -- create a new wobble rotation object
   return wobbleproto:new(sscvals)
end

ScriptedRotations 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 orientation function will always return the same orientation for identical time values.

SpiceRotation

1.6.0

Usage:

SpiceRotation
{
    Kernel <string|string array>   # optional
    Frame <string>
    BaseFrame <string>             # optional (defaults to ecliptic)
    Period <number>                # optional (units are hours)
    Beginning <number>             # optional
    Ending <number>                # optional
}

SpiceRotation is used to import a orientation information from NASA's SPICE system into Celestia. The orientation of a Celestia object will be locked to a SPICE frame.

Not all versions of Celestia are built with SPICE support. SpiceRotation is not support in versions of Celestia earlier than 1.6.0.

The Kernel property can be used to specify the name of one or more SPICE kernel (SPK) files to load. It can be omitted if all required kernel files were listed in the definition of a previously loaded object. Celestia expects the kernel file to reside in an add-on's data directory.

Frame and BaseFrame are strings that give SPICE names for the frames. The orientation of the SpiceRotation is the orientation of the frame relative to the base frame. If no base frame is specified, the default is eclipj2000. The base frame should be the SPICE equivalent of whatever the BodyFrame of the Celestia object is.

Beginning and Ending specify the valid time range of the SPICE rotation. If the Beginning and Ending are omitted, the rotation model is assumed to be valid at any time. It is an error to specify Beginning without Ending, and vice versa.

Period specifies the principal rotation period; it defaults to 0 indicating that the rotation is aperiodic. It is not essential to provide the rotation period; it is only used by Celestia for displaying object information such as sidereal day length.

Example:

# Use the frame IAU_EARTH as defined by the constants in the SPICE text kernel pck00008.tpc
SpiceRotation
{
    Kernel              "pck00008.tpc"
    Frame               "IAU_EARTH"
    BaseFrame           "eclipj2000"
    Period              23.9344694
}