# Celx Scripting: Phase
## phase

1.6.0 The phase class is NOT available until Celestia version 1.6.0.
The timeline of an object is subdivided into one or more phases. Each phase has its own:
* trajectory;
* rotation model;
* orbit frame;
* body frame.
An object's phase(s) can be obtained in one of two ways:
* Using the 1.6.0 object:getphase method, which returns the active phase at a specified time, or
* Using the 1.6.0 object:phases method, which returns an iterator over all of the phases in an object's timeline.
Example: The timeline for the Huygens probe might have three phases:
* Attached to Cassini:
** body fixed frame of Cassini;
** trajectory is just a fixed position.
* Free flight after separation:
** Saturn-centered frame;
** trajectory from an xyz file or SPICE
* On the surface of Titan (default not implemented yet in Celestia 1.6.0):
** Titan-fixed frame;
** trajectory is a fixed position.

## Methods

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

### timespan

1.6.0 number, number phase:timespan
Return the start and end times for this timeline phase as two TDB (Barycentric Dynamical Time) Julian date numbers.
Notes:
* The start time of a phase will always be equal to the end time of the previous phase.
* For a phase valid at any time, the start time and end time will be equal to the special floating point values -infinity and +infinity.
* 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.
Example: Retrieve the start and end times of the phases of Cassini's timeline.
Return to the phase method index.

### orbitframe

1.6.0 frame phase:orbitframe
Return the orbit frame for this timeline phase, as a "frame" object.
Example: Display orbit frame reference object of Huygens during Free flight after separation from Cassini.
Return to the phase method index.

### bodyframe

1.6.0 frame phase:bodyframe
Return the body frame for this timeline phase, as a "frame" object.
Example: Display body frame reference object of Huygens during it flight on Cassini to Saturn.
Return to the phase method index.

### getposition

1.6.0 position phase:getposition(number:time)
Return the position in frame coordinates at the specified time, as a "position" object.
Arguments:

#### time

    The time used to determine the position, as a TDB (Barycentric Dynamical Time) Julian date number. A time outside the span covered by the phase are automatically clamped to either the beginning or ending of the span.
Notes:
* Position components (X,Y,Z) in Celestia are stored in millionths of a light year. So when you want your positions defined in km or miles, you have to convert these positions. Therefore, you can use a constant, which must be initialized first within your script:
** From millionths of a light year to km, use a constant uly_to_km = 9460730.4725808.
** From millionths of a light year to miles, use a constant uly_to_mls = 5912956.5453630.
* Next you can convert millionths of a light year to km or miles as follows:
** km = number:millionths_of_a_light_year * uly_to_km
** miles = number:millionths_of_a_light_year * uly_to_mls
* 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.
* 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.
Example-1: Get position of Huygens at a specific time during first phase.
Example-2: Get position of Huygens at a specific time during second phase.
Return to the phase method index.

### getorientation

1.6.0 rotation phase:getorientation(number:time)
Return the orientation in frame coordinates at the specified time, as a "rotation" object.
Arguments:

#### time

    The time used to determine the orientation, as a TDB (Barycentric Dynamical Time) Julian date number. A time outside the span covered by the phase are automatically clamped to either the beginning or ending of the span.
Notes:
* 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.
* 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.
Example:
Return to the phase method index.