Celestia/Celx Scripting/CELX Lua Methods/Celx phase

= Celx Scripting: Phase =

phase
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 object:getphase method, which returns the active phase at a specified time, or
 * Using the 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:
 * 1) Attached to Cassini:
 * 2) * body fixed frame of Cassini;
 * 3) * trajectory is just a fixed position.
 * 4) Free flight after separation:
 * 5) * Saturn-centered frame;
 * 6) * trajectory from an xyz file or SPICE
 * 7) On the surface of Titan (default not implemented yet in Celestia ):
 * 8) * Titan-fixed frame;
 * 9) * trajectory is a fixed position.

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

timespan
number, number

Return the start and end times for this timeline phase as two TDB (Barycentric Dynamical Time) Julian date numbers.

Notes:
 * 1) The start time of a phase will always be equal to the end time of the previous phase.
 * 2) 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.
 * 3) 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.
 * 4) To convert between UTC and TDB times, you can use the  celestia:utctotdb and  celestia:tdbtoutc methods.
 * 5) 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
frame

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
frame

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
position

Return the position in frame coordinates at the specified time, as a "position" object.

Notes:
 * 1) 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:
 * 2) * From millionths of a light year to km, use a constant uly_to_km = 9460730.4725808.
 * 3) * From millionths of a light year to miles, use a constant uly_to_mls = 5912956.5453630.
 * 4) Next you can convert millionths of a light year to km or miles as follows:
 * 5) * km = number:millionths_of_a_light_year * uly_to_km
 * 6) * miles = number:millionths_of_a_light_year * uly_to_mls
 * 7) 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.
 * 8) 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.
 * 9) To convert between UTC and TDB times, you can use the  celestia:utctotdb and  celestia:tdbtoutc methods.
 * 10) 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
rotation

Return the orientation in frame coordinates at the specified time, as a "rotation" object.

Notes:
 * 1) 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.
 * 2) 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.
 * 3) To convert between UTC and TDB times, you can use the  celestia:utctotdb and  celestia:tdbtoutc methods.
 * 4) 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.