Celestia/Reference Frames

Reference Frames
A reference frame is an origin and set of axes which define the coordinate system used for a body's trajectory and orientation. The origin is some other body defined in a catalog file. There are a number of ways to set the coordinate system axes.

The reference frames used for a body's trajectory and its orientation do not have to be the same. This is useful in some situations. For example, the orbit of a satellite may be given in a geocentric equatorial coordinate system, while the attitude is given in a local vertical-local horizontal system.

All of the Reference Frames keywords require Celestia 1.5. They are ignored by earlier versions.

OrbitFrame property
Set the reference frame for the trajectory

Default: For bodies which have a star as the parent, the default reference frame for the orbit is centered on the star. The fundamental plane is the J2000 Earth ecliptic, and the preferred direction (x-axis) is the J2000 equinox. For all other bodies, the default reference frame is the equatorial frame of the parent body.

Usage OrbitFrame  

BodyFrame property
Set the reference frame for the orientation

Default: For bodies which have a star as the parent, the default reference frame for the orientation is the J2000 ecliptic and equinox. For all other bodies, the default reference frame is the equatorial frame of the parent body (which can in turn default to the J2000 ecliptic and so on).

Usage BodyFrame  

Reference Frame object
A reference frame is a list containing a single property that is one of the specific reference frame types.

Usage {     |  |   |     |  }

EclipticJ2000 property
EclipticJ2000 is a reference frame with the Earth ecliptic at epoch J2000 as the fundamental plane. The x-axis points along the J2000 vernal equinox, the z-axis points northward perpendicular to the ecliptic, and the y-axis completes the right-handed system.

Usage: EclipticJ2000 {    Center   }

EquatorJ2000 property
EquatorJ2000 is a reference frame with the Earth equator at epoch J2000 as the fundamental plane. The x-axis points along the J2000 vernal equinox, the z-axis is the mean north pole, and the y-axis completes the right-handed system.

Usage: EquatorJ2000 {    Center   }

MeanEquator property
MeanEquator defines a reference frame in which the body's equator of date is the xy-plane. The z-axis is perpendicular to the xy-plane, pointing in a direction such that the body rotates counterclockwise about it. The x-axis is the ascending node of the equatorial plane on the J2000 ecliptic plane.

Usage: MeanEquator {    Center   Object   Freeze   }

Properties:
 * Object: the fundamental plane is the equatorial plane of this body
 * Freeze: if set, the equator of the freeze epoch is used instead of the equator of date

BodyFixed property
A BodyFixed reference frame rotates with the specified body.

Usage: BodyFixed {    Center   }

TwoVector property
Usage: TwoVector {    Center   Primary   Secondary   }

Axis object
An axis object is a list containing a single direction property along with an axis label.

Usage:

{    Axis "x" | "y" | "z" | "-x" | "-y" | "-z"  |  |  }

RelativePosition property
Usage:

RelativePosition {    Observer   Target   }

The default observer object is the coordinate frame center. The target object has no default and must always be specified.

RelativeVelocity property
Usage:

RelativeVelocity {    Observer   Target   }

The default observer object is the coordinate frame center. The target object has no default and must always be specified.

ConstantVector property
Usage:

ConstantVector {    Vector   Frame   }

Examples:

Earth's north rotational pole:

ConstantVector {    Vector [ 0 0 1 ] Frame { EquatorJ2000 { Center "Sol/Earth" } } }

Heliocentric Earth Equatorial
OrbitFrame { EquatorJ2000 { Center "Sol" } }

Geocentric Solar Ecliptic
This reference frame is based on an example from the SPICE Frames Required Reading document. The origin is the Earth, the xy-plane is the Earth's orbital plane, and the x-axis points from Earth toward the Sun.

OrbitFrame { TwoVector { Center "Sol/Earth" Primary { Axis "x" RelativePosition { Target "Sol" } }        Secondary { Axis "y" RelativeVelocity { Target "Sol" } }    } }

Sun-locked
This reference frame for a Sun-orbiting object called 'Test' has its z-axis pointing toward the Sun, and the x axis pointing in the direction of travel. An object with a fixed orientation in this reference frame will always have the same side facing the Sun:

BodyFrame { TwoVector { Center "Sol/Test" Primary { Axis "z" RelativePosition { Target "Sol" } }        Secondary { Axis "x" RelativeVelocity { Target "Sol" } }    } }

JPL Solar System Dynamics pages
The JPL Solar System Dynamics pages provide mean orbital parameters of planetary satellites using a variety of reference frames. Entering these in solarsys.ssc can be challenging.


 * When mean ecliptic elements are given (for a satellite of "object"):

EllipticalOrbit { ... } OrbitFrame { EclipticJ2000 { Center "object" } }


 * When the elements are referred to the primary's equator:

EllipticalOrbit { ... } OrbitFrame { BodyMeanEquator { Center "object" Object "object" [Freeze ] } }


 * When the elements are referred to the ICRF (which is very nearly identical to the Earth equatorial frame):

EllipticalOrbit { ... } OrbitFrame { EquatorJ2000 { Center "object" } }


 * When the elements are referred to the local Laplace planes:

This is the worst case. The Laplace plane for each satellite is defined by its polar right ascension and declination (in the EquatorJ2000 frame); this defines the local Laplace plane's ascending node longitude (90° plus the pole's RA) and inclination (the co-declination, i.e. 90° minus the dec).

EllipticalOrbit { ... } OrbitFrame { TwoVector { Center "object" Primary { Axis "x" ConstantVector { Vector [] Frame { EquatorJ2000 { Center "object" } } } }    Secondary { Axis "z" ConstantVector { Vector [] Frame { EquatorJ2000 { Center "object" } } } } } }

Placing Several Objects Identically on the Earth's Surface
Here's an example of defining a position and orientation relative to the Earth. One can then reference this definition while placing several models instead of replicating the same definition for each of them: corrections to the position only have to be made in one place instead of several.

Note that some of the declarations which are included in this example could be omitted since their default values would place the objects appropriately.

"Hale_position" "Sol/Earth" { Class "invisible" Radius 0.0001 OrbitFrame { BodyFixed { Center "Sol/Earth" }} FixedPosition [ -2407.99 -4753.86 3507.91 ] BodyFrame { BodyFixed { Center "Sol/Earth" }} FixedRotation { MeridianAngle -116.86 AscendingNode 90 } } "Hale_model" "Sol/Earth/Hale_position" {  Mesh "telescope.3ds" Radius 0.3 OrbitFrame { BodyFixed { Center "Sol/Earth/Hale_position" }} FixedPosition [ 0 0 0 ] BodyFrame { BodyFixed { Center "Sol/Earth/Hale_position" }} FixedRotation { } Albedo 0.1 } "Dome_model" "Sol/Earth/Hale_position" {  Mesh "dome.3ds" Radius 0.3 OrbitFrame { BodyFixed { Center "Sol/Earth/Hale_position" }} FixedPosition [ 0 0 0 ] BodyFrame { BodyFixed { Center "Sol/Earth/Hale_position" }} FixedRotation { } Albedo 0.1 }
 * 1) Place the Hale Telescope on the peak of Mount Palomar
 * 1) Orient it appropriately with respect to the surface