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 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).

-- 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 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:

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 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:

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 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:

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.