Celestia/Celx Scripting/CELX Lua Methods/Celx frame

Tekst in subscript= 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 object:bodyfixedframe method.
 * Using the object:equatorialframe method.
 * Using the object:orbitframe method.
 * Using the object:bodyframe method.
 * Using the phase:orbitframe method.
 * Using the phase:bodyframe method.

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

to
position

Convert a position from universal coordinates to frame coordinates. The converted position will be returned as a "position" object.

Notes:
 * 1) 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.
 * 2) 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).

-- Find, select, center and follow Earth first obs = celestia:getobserver earth = celestia:find("Sol/Earth") celestia:select(earth) obs:center(earth,0.0) wait(0.0) frame = celestia:newframe("ecliptic", earth) obs:setframe(frame) -- Get actual observer position and convert to frame coordinates obs_pos = obs:getposition obs_pos_f = frame:to(obs_pos) -- Goto location at twice the current distance to the Earth's center obs_pos_2f = celestia:newposition(2*obs_pos_f.x, 2*obs_pos_f.y, 2*obs_pos_f.z) obs:gotolocation(obs_pos_2f, 1.0) wait(1.0)

Return to the frame method index.

to (rotation)
rotation

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.

Notes:
 * 1) 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).
 * 2) 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.
 * 3) Older Celestia versions use UTC (Coordinated Universal Time) to calculate times and positions. Starting with version, although Celestia still displays UTC on the screen, it uses the TDB time scale internally for everything else, so for CELX scripting !!!
 * 4) 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.
 * 5) To convert between UTC and TDB times, you can use the  celestia:utctotdb and  celestia:tdbtoutc methods.
 * 6) 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

Convert a position from frame coordinates to universal coordinates, at the specified time. The converted position will be returned as a "position" object.

Notes:
 * 1) 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.
 * 2) 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.
 * 3) Older Celestia versions use UTC (Coordinated Universal Time) to calculate times and positions. Starting with version, although Celestia still displays UTC on the screen, it uses the TDB time scale internally for everything else, so for CELX scripting !!!
 * 4) 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.
 * 5) To convert between UTC and TDB times, you can use the  celestia:utctotdb and  celestia:tdbtoutc methods.
 * 6) 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

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

Notes:
 * 1) 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).
 * 2) 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

Return a string describing the frame's coordinate system. String will be one of:
 * universal
 * ecliptic
 * equatorial
 * observer
 * lock
 * chase
 * bodyfixed

Notes:
 * 1) In Celestia version, the name bodyfixed has replaced planetographic.

Example:

obs = celestia:getobserver actual_frame = obs:getframe actual_coordsys = actual_frame:getcoordinatesystem celestia:print("Current Coordinate System: " .. actual_coordsys, 5.0, -1, -1, 2, 4) wait(5.0)

Return to the frame method index.

getrefobject
object

Get the reference object of this frame, being the frame center, as an "object" object.

Notes:
 * 1) For the universal frame of reference, a nil object will be returned.
 * 2) 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.
 * 3) 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:

obs = celestia:getobserver actual_frame = obs:getframe refobj = actual_frame:getrefobject if not refobj then celestia:print("Currently NO Reference Object present.", 5.0, -1, -1, 2, 4) else refobj_name = refobj:name celestia:print("Current Reference Object: " .. refobj_name, 5.0, -1, -1, 2, 4) end wait(5.0)

Return to the frame method index.

gettargetobject
object

Get the target object for a phaselock frame, as an "object" object.

Notes:
 * 1) For a non phaselock frame, a nil object will be returned.
 * 2) 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.
 * 3) 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:

obs = celestia:getobserver actual_frame = obs:getframe tarobj = actual_frame:gettargetobject if not tarobj then celestia:print("Currently NO Target Object present.", 5.0, -1, -1, 2, 4) else tarobj_name = tarobj:name celestia:print("Current Target Object: " .. tarobj_name, 5.0, -1, -1, 2, 4) end wait(5.0)

Return to the frame method index.