# Celestia/Celx Scripting/CELX Lua Methods/Celx frame

$_{Tekstinsubscript}$= Celx Scripting: Frame =

## frame

A "frame" object 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.
Within a CELX script, the frame methods need to be prefixed with the obtained "frame" object, separated with a semicolon.
The following methods can be used to obtain a "frame" object:
* Using the celestia:newframe method.
* Using the observer:getframe method.
* Using the 1.6.0 object:bodyfixedframe method.
* Using the 1.6.0 object:equatorialframe method.
* Using the 1.6.0 object:orbitframe method.
* Using the 1.6.0 object:bodyframe method.
* Using the 1.6.0 phase:orbitframe method.
* Using the 1.6.0 phase:bodyframe method.

## Methods

This chapter contains a list of all available frame methods, which can be used on "frame" objects.

### to

position frame:to(position:univ)
Convert a position from universal coordinates to frame coordinates. The converted position will be returned as a "position" object.
Arguments:

#### univ

    The position in universal coordinates, which must be converted to frame coordinates. Must be a "position" object.
Notes:
* A CELX "position" object contains the exact coordinates of a point in space. A position is relative to a coordinate system and may need to be converted to or from universal coordinates before further use.
* The position methods can be used on a CELX "position" object. "Position" objects can also be used in other methods, requiring a "position" object as an argument.
Example: Goto location at twice the current distance to the Earth's center, being the origin of the "ecliptic" frame of reference (follow).
Return to the frame method index.

### to (rotation)

rotation frame:to(rotation:univ [, number:time ])
Convert a rotation from the universal frame of reference to this frame of reference, at the specified time. The converted rotation will be returned as a "rotation" object.
Arguments:

#### univ

    The rotation from the universal frame of reference, which must be converted to this frame of reference. Must be a "rotation" object.

#### time

    The TDB (Barycentric Dynamical Time) Julian date number for this conversion. Celestia versions prior to version 1.5.0 use the UTC (Coordinated Universal Time) Julian date number for this conversion. If time is omitted, the current simulation time is used.
Notes:
* A CELX "rotation" object is internally a Quaternion, which is one possibility to mathematically describe a rotation in 3 dimensions (i.e. it can be converted to a rotation matrix). A rotation can also be used to describe the orientation of objects or the observer (i.e. where the observer is looking to, and where "up" is).
* The rotation methods can be used on a CELX "rotation" object. "Rotation" objects can also be used in other methods, requiring a "rotation" object as an argument.
* Older Celestia versions use UTC (Coordinated Universal Time) to calculate times and positions. Starting with version 1.5.0, although Celestia still displays UTC on the screen, it uses the TDB time scale internally for everything else, so for CELX scripting !!!
* The TDB time scale is a bit different from the more familiar UTC. By using TDB, Celestia places objects much more accurately. As of January 1, 2008, the difference between the two is about 65 seconds. For more information, see Celestia/Time_Scales.
* To convert between UTC and TDB times, you can use the 1.5.0 celestia:utctotdb and 1.5.0 celestia:tdbtoutc methods.
* To convert between normal calender dates and julian days, you can use the celestia:tojulianday and celestia:fromjulianday methods.
Return to the frame method index.

### from

position frame:from(position:rfpos [, number:time])
Convert a position from frame coordinates to universal coordinates, at the specified time. The converted position will be returned as a "position" object.
Arguments:

#### rfpos

    The position in frame coordinates, which must be converted to universal coordinates. Must be a "position" object.

#### time

    The TDB (Barycentric Dynamical Time) Julian date number for this conversion. Celestia versions prior to version 1.5.0 use the UTC (Coordinated Universal Time) Julian date number for this conversion. If time is omitted, the current simulation time is used.
Notes:
* A CELX "position" object contains the exact coordinates of a point in space. A position is relative to a coordinate system and may need to be converted to or from universal coordinates before further use.
* The position methods can be used on a CELX "position" object. "Position" objects can also be used in other methods, requiring a "position" object as an argument.
* Older Celestia versions use UTC (Coordinated Universal Time) to calculate times and positions. Starting with version 1.5.0, although Celestia still displays UTC on the screen, it uses the TDB time scale internally for everything else, so for CELX scripting !!!
* The TDB time scale is a bit different from the more familiar UTC. By using TDB, Celestia places objects much more accurately. As of January 1, 2008, the difference between the two is about 65 seconds. For more information, see Celestia/Time_Scales.
* To convert between UTC and TDB times, you can use the 1.5.0 celestia:utctotdb and 1.5.0 celestia:tdbtoutc methods.
* To convert between normal calender dates and julian days, you can use the celestia:tojulianday and celestia:fromjulianday methods.
Return to the frame method index.

### from (rotation)

rotation frame:from(rotation:rfrot)
Convert a rotation from this frame of reference to the universal frame of reference. The converted rotation will be returned as a "rotation" object.
Arguments:

#### rfrot

    The rotation from this frame of reference, which must be converted to the universal frame of reference. Must be a "rotation" object.
Notes:
* A CELX "rotation" object is internally a Quaternion, which is one possibility to mathematically describe a rotation in 3 dimensions (i.e. it can be converted to a rotation matrix). A rotation can also be used to describe the orientation of objects or the observer (i.e. where the observer is looking to, and where "up" is).
* The rotation methods can be used on a CELX "rotation" object. "Rotation" objects can also be used in other methods, requiring a "rotation" object as an argument.
Return to the frame method index.

### getcoordinatesystem

string frame:getcoordinatesystem
Return a string describing the frame's coordinate system. String will be one of:
* universal
* ecliptic
* equatorial
* observer
* lock
* chase
* 1.6.0 bodyfixed
Notes:
* In Celestia version 1.6.0, the name bodyfixed has replaced planetographic.
Example:
Return to the frame method index.

### getrefobject

object frame:getrefobject
Get the reference object of this frame, being the frame center, as an "object" object.
Notes:
* For the universal frame of reference, a nil object will be returned.
* A CELX "object" object does refer to a celestial object like a planet or a star, but it can also be a location or spacecraft.
* The object methods can be used on a CELX "object" object. "Object" objects can also be used in other methods, requiring an "object" object as an argument.
Example:
Return to the frame method index.

### gettargetobject

object frame:gettargetobject
Get the target object for a phaselock frame, as an "object" object.
Notes:
* For a non phaselock frame, a nil object will be returned.
* A CELX "object" object does refer to a celestial object like a planet or a star, but it can also be a location or spacecraft.
* The object methods can be used on a CELX "object" object. "Object" objects can also be used in other methods, requiring an "object" object as an argument.
Example:
Return to the frame method index.