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 <reference frame>

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>

Reference Frame object

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

Usage

{
    <J2000 ecliptic frame> | 
    <J2000 equator frame> |
    <body mean equator frame> |
    <body-fixed frame> |
    <two-vector frame>
}

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 <object name>
}

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 <object name>
}

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 name>
    Object <object name>
    Freeze <date>
}

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 <object name>
}

TwoVector property

Usage:

TwoVector
{
    Center <object name>
    Primary <axis>
    Secondary <axis>
}

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> | <RelativeVelocity> | <ConstantVector>
}

RelativePosition property

Usage:

RelativePosition
{
    Observer <object name>
    Target <object name>
}

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 <object name>
    Target <object name>
}

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 <vector>
    Frame <reference frame>
}

Examples:

Earth's north rotational pole:

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

Reference Frame Examples

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 <date>]
} }

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 [<Laplace plane ascending node>] Frame { EquatorJ2000 { Center "object" } } }
    }
    Secondary { Axis "z"
        ConstantVector { Vector [<Laplace plane pole>] Frame { EquatorJ2000 { Center "object" } } }
    }
} }

Additional Examples

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

# Place the Hale Telescope on the peak of Mount Palomar

 OrbitFrame { BodyFixed { Center "Sol/Earth" }}
 FixedPosition  [ -2407.99 -4753.86 3507.91 ]

# Orient it appropriately with respect to the surface
 
 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

}

External links

http://www.gps.caltech.edu/~marsdata/req/frames.html - SPICE Required Reading Documents: Reference Frames