Celestia/Celx Scripting/CELX Lua Methods/Celx rotation
Celx Scripting: Rotation
editrotation
editA 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).
Within a CELX script, the rotation methods need to be prefixed with the obtained "rotation" object, separated with a colon.
The following methods can be used to obtain a "rotation" object:
- Using the celestia:newrotation(axis-angle) method.
- Using the celestia:newrotation() method.
- Using the observer:getorientation() method.
- Using the position:orientationto() method.
- Using the frame:to(rotation) method.
- Using the frame:from(rotation) method.
- Using the rotation:slerp() method.
- Using the 1.6.0 phase:getorientation() method.
Methods
editThis chapter contains a list of all available rotation methods, which can be used on "rotation" objects.
imag
editvector rotation:imag()
Return the X, Y and Z values of this rotation as a "vector" object.
Notes:
- A CELX "vector" object is a geometric object that has both a length and direction [X, Y, Z] in a 3 dimensional coordinate system.
- The vector methods can be used on a CELX "vector" object. "Vector" objects can also be used in other methods, requiring a "vector" object as an argument.
Example:
obs = celestia:getobserver() rot1 = obs:getorientation() vector = rot1:imag()
Return to the rotation method index.
real
editnumber rotation:real()
Return the W value of this rotation as a number.
Example:
obs = celestia:getobserver() rot1 = obs:getorientation() number = rot1:real()
Return to the rotation method index.
transform
editvector rotation:transform(vector:vec)
Transform a "vector" object by applying the rotation to that vector and return the result in a new "vector" object.
Arguments:
- vec
- The vector the rotation will be applied to. Must be a "vector" object.
Notes:
- A CELX "vector" object is a geometric object that has both a length and direction [X, Y, Z] in a 3 dimensional coordinate system.
- The vector methods can be used on a CELX "vector" object. "Vector" objects can also be used in other methods, requiring a "vector" object as an argument.
Example:
Goto a position at the actual dark side of Earth.
obs = celestia:getobserver() -- Set frame of reference to "universal". obs:setframe(celestia:newframe("universal")) -- Find the Sun and Earth and get their actual positions earth = celestia:find("Sol/Earth") sun = celestia:find("Sol") now = celestia:gettime() earthpos = earth:getposition(now) sunpos = sun:getposition(now) -- Get vector from Earth to the Sun vector1 = earthpos:vectorto(sunpos) -- Transform that vector over a rotation of 180 degrees = math.pi up_v = celestia:newvector(0,1,0) opposite = celestia:newrotation(up_v, math.pi) vector2 = opposite:transform(vector1) -- Adjust the length of the opposite vector vector2 = 0.0003 * vector2 -- Goto new position and center Earth. newpos = earthpos + vector2 obs:goto(newpos, 0.0) wait(0.0) obs:center(earth, 0.0) wait(0.0)
Return to the rotation method index.
setaxisangle
editrotation:setaxisangle(vector:vec, number:angle)
Set axis and angle, as defined in the vector and angle for this rotation.
Arguments:
- vec
- Vector describing the [X,Y,Z] axis for this rotation. Must be a "vector" object.
- angle
- The angle in radians for this rotation. Must be a number.
Notes:
- Angles in CELX are defined in radians instead of degrees. 180 degrees (half a circle) is the same as π radians = 3.14159265 radians = math.pi radians (LUA). You can convert degrees to radians and vice versa as follows:
- radians = math.rad( number:degrees ) = ( number:degrees / 180 * math.pi) = ( number:degrees / 180 * 3.14159265).
- degrees = math.deg( number:radians ) = ( number:radians * 180 / math.pi) = ( number:radians * 180 / 3.14159265).
- This method is equivalent to celestia:newrotation(axis-angle) method. Only by using this method, the "rotation" object needs to be present first, instead of being created by the method. To obtain such a "rotation" object, the celestia:newrotation() method can be used instead, or you can use an already existing "rotation" object, previously defined within your script.
Example:
Change the current observer view by 180 degrees (like a rear-view mirror).
obs = celestia:getobserver() -- Create a rotation object from all zero numbers. rot1 = celestia:newrotation(0, 0, 0, 0) -- Define the axis for the rotation as a vector up_vec = celestia:newvector(0, 1, 0) rot1:setaxisangle(up_vec, math.pi) obs:rotate(rot1) wait(0.0)
Return to the rotation method index.
slerp
editrotation:rot3 rotation:slerp(rotation:rot2, number:percent)
Return an interpolation of this rotation and another "rotation" object (rot2), using number to indicate how much of each rotation should be used. Return the result in a new "rotation" object (rot3).
Arguments:
- rot2
- Second rotation that will be used for the interpolation. Must be a "rotation" object.
- percent
- The percent number used to interpolate between the two rotations. Must be a number between 0 and 1.
- If percent is 0, this rotation is returned in rotation:rot3.
- If percent is 1, the second rotation (rot2) is returned in rotation:rot3.
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.
Example:
Goto a position in the Earth-Moon system and set the observer orientation to the middle of the Earth-Moon positions.
obs = celestia:getobserver() -- Set frame of reference to "universal". obs:setframe(celestia:newframe( "universal")) -- Find the actual position of the Earth. earth = celestia:find("Sol/Earth") earthpos = earth:getposition() -- Find the actual position of the Moon. moon = celestia:find("Sol/Earth/Moon") moonpos = moon:getposition() -- Calculate new position to goto newpos = earthpos + 0.5 * (moonpos - earthpos) newpos = newpos + celestia:newvector(0, 0, 0.075) obs:goto(newpos, 0.0) wait(0.0) -- Orientation from this position towards Earth orient_earth = newpos:orientationto(earthpos, celestia:newvector(0, 1, 0)) -- Orientation from this position towards Moon orient_moon = newpos:orientationto(moonpos, celestia:newvector(0, 1, 0)) -- Interpolate new observer orientation (middle) orientation = orient_earth:slerp(orient_moon, 0.5) obs:setorientation(orientation)