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.

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},𝐕\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 useable 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.