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.

object = celestia:find("Sol/Cassini")
count = 0
for phase in object:phases() do
   count = count + 1
   begintime, endtime = phase:timespan()
   celestia:print("Phase [" .. count .. "] of " .. object:name() .. 
                  "\nStart: " .. begintime .. " End: " .. endtime, 5.0, -1, -1, 2, 4)
   wait(5.0)
end

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.

tdbtime = celestia:utctotdb(2005, 01, 01)
celestia:settime(tdbtime)
object = celestia:find("huygens")
celestia:select(object)
phase = object:getphase(tdbtime)
-- Orbit frame
obj_orbf = phase:orbitframe()
object2 = obj_orbf:getrefobject()
-- Goto object and print message
obs = celestia:getobserver()
obs:gotolonglat(object, math.rad(42), math.rad(14), 0.033, 2.0)
celestia:print("Orbit frame reference object during this phase of " ..
               object:name() .. " is: " .. object2:name(), 10.0, -1, -1, 2, 4)
wait(10.0)

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.

tdbtime = celestia:utctotdb(2004, 06, 01)
celestia:settime(tdbtime)
object = celestia:find("huygens")
celestia:select(object)
phase = object:getphase(tdbtime)
-- Body frame
obj_bodyf = phase:bodyframe()
object2 = obj_bodyf:getrefobject()
-- Goto object and print message
obs = celestia:getobserver()
obs:gotolonglat(object, math.rad(42), math.rad(14), 0.033, 2.0)
celestia:print("Body frame reference object during this phase of " ..
               object:name() .. " is: " .. object2:name(), 10.0, -1, -1, 2, 4)
wait(10.0)

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.

uly_to_km = 9460730.4725808
tdbtime = celestia:utctotdb(2004, 06, 01)
celestia:settime(tdbtime)
object = celestia:find("huygens")
celestia:select(object)
phase = object:getphase(tdbtime)
obj_posf = phase:getposition(tdbtime)
-- Goto object and print message
obs = celestia:getobserver()
obs:gotolonglat(object, math.rad(42), math.rad(14), 0.033, 2.0)
celestia:print(object:name() .. " frame coordinates at 2004, 06, 01, 00:00:00 hr are:\n" ..
               "X: " .. obj_posf.x*uly_to_km*1000 .. " meter\n" .. 
               "Y: " .. obj_posf.y*uly_to_km*1000 .. " meter\n" ..
               "Z: " .. obj_posf.z*uly_to_km*1000 .. " meter", 10.0, -1, -1, 2, 6)
wait(10.0)

Example-2:
Get position of Huygens at a specific time during second phase.

uly_to_km = 9460730.4725808
tdbtime = celestia:utctotdb(2005, 01, 01)
celestia:settime(tdbtime)
object = celestia:find("huygens")
celestia:select(object)
phase = object:getphase(tdbtime)
obj_posf = phase:getposition(tdbtime)
-- Goto object and print message
obs = celestia:getobserver()
obs:gotolonglat(object, math.rad(42), math.rad(14), 0.033, 2.0)
celestia:print(object:name() .. " frame coordinates at 2005, 01, 01, 00:00:00 hr are:\n" ..
               "X: " .. obj_posf.x*uly_to_km .. " km\n" .. 
               "Y: " .. obj_posf.y*uly_to_km .. " km\n" ..
               "Z: " .. obj_posf.z*uly_to_km .. " km", 10.0, -1, -1, 2, 6)
wait(10.0)

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:

tdbtime = celestia:utctotdb(2005, 01, 01)
celestia:settime(tdbtime)
object = celestia:find("huygens")
celestia:select(object)
phase = object:getphase(tdbtime)
obj_rotf = phase:getorientation(tdbtime)
...

Return to the phase method index.