Difference between revisions of "Oolite JavaScript Reference: Quaternion"
m (Added category:Oolite.) |
(Cleaning up JavaScript pages with more idiomatic style (with JS 2-style type annotations). Also fixed a typo (normalize() doesn’t take a parameter).) |
||
| Line 1: | Line 1: | ||
| + | <small>'''Prototype:''' <code>[[Oolite JavaScript Reference: JavaScript basics#Object|Object]]</code></small><br /> | ||
| + | <small>'''Subtypes:''' none</small> | ||
| + | |||
The '''<code>Quaternion</code>''' class represents a [[quaternion]], a four-dimensional number, which is used to express rotations. Explaining quaternion mathematics is ''way'' beyond the scope of this document, but a quick overview is provided below. | The '''<code>Quaternion</code>''' class represents a [[quaternion]], a four-dimensional number, which is used to express rotations. Explaining quaternion mathematics is ''way'' beyond the scope of this document, but a quick overview is provided below. | ||
| Line 21: | Line 24: | ||
=== Quaternion Expressions === | === Quaternion Expressions === | ||
| − | All Oolite-provided functions which take a quaternion as an argument may instead be passed an [[Oolite/Development/Scripting/Class/Entity|Entity]] instead, in which case the entity’s <code>[[Oolite/Development/Scripting/Class/Entity#orientation|orientation]]</code> is used. In specifications, this is represented by arguments named <code>quaternionOrEntity</code>. (Is this actually useful? It seems less compellingly so than the [[Oolite/Development/Scripting/Class/Vector#Vector Expressions|vector equivalent. -- [[User:Ahruman]]) | + | All Oolite-provided functions which take a quaternion as an argument may instead be passed an [[Oolite/Development/Scripting/Class/Entity|Entity]] instead, in which case the entity’s <code>[[Oolite/Development/Scripting/Class/Entity#orientation|orientation]]</code> is used. In specifications, this is represented by arguments named <code>quaternionOrEntity</code>. (Is this actually useful? It seems less compellingly so than the [[Oolite/Development/Scripting/Class/Vector#Vector Expressions|vector equivalent]]. -- [[User:Ahruman]]) |
Additionally, most <code>Quaternion</code> methods may be passed four numbers instead of a vector. In specifications, this is represented by arguments named <code>quaternionExpression</code>. | Additionally, most <code>Quaternion</code> methods may be passed four numbers instead of a vector. In specifications, this is represented by arguments named <code>quaternionExpression</code>. | ||
| Line 27: | Line 30: | ||
== Properties == | == Properties == | ||
=== <code>w</code> === | === <code>w</code> === | ||
| − | w | + | '''w''' : Number (read/write) |
The ''w'' component of the quaternion. | The ''w'' component of the quaternion. | ||
=== <code>x</code> === | === <code>x</code> === | ||
| − | x | + | '''x''' : Number (read/write) |
The ''x'' component of the quaternion. | The ''x'' component of the quaternion. | ||
=== <code>y</code> === | === <code>y</code> === | ||
| − | y | + | '''y''' : Number (read/write) |
The ''y'' component of the quaternion. | The ''y'' component of the quaternion. | ||
=== <code>z</code> === | === <code>z</code> === | ||
| − | z | + | '''z''' : Number (read/write) |
The ''z'' component of the quaternion. | The ''z'' component of the quaternion. | ||
== Methods == | == Methods == | ||
=== Constructor === | === Constructor === | ||
| − | new Quaternion([ [[#Quaternion Expressions|quaternionExpression]]]) | + | '''new Quaternion'''([value : [[#Quaternion Expressions|quaternionExpression]]]) |
Create a new quaternion with the specified value. If no value is provided, the vector is initialized to the identity quaternion (1, 0, 0, 0). | Create a new quaternion with the specified value. If no value is provided, the vector is initialized to the identity quaternion (1, 0, 0, 0). | ||
=== <code>multiply</code> === | === <code>multiply</code> === | ||
| − | + | function '''multiply'''(q : [[#Quaternion Expressions|quaternionExpression]]) : Quaternion | |
Returns the standard quaternion product (Grassman product) of the target and <code>[[#Quaternion Expressions|quaternionExpression]]</code>. This is used to concatenate rotations together. | Returns the standard quaternion product (Grassman product) of the target and <code>[[#Quaternion Expressions|quaternionExpression]]</code>. This is used to concatenate rotations together. | ||
=== <code>dot</code> === | === <code>dot</code> === | ||
| − | + | function '''dot'''(q : [[#Quaternion Expressions|quaternionExpression]]) : Quaternion | |
Returns the quaternion dot product (inner product) of the target and <code>[[#Quaternion Expressions|quaternionExpression]]</code>. (This is not known to be useful – it’s not used anywhere in Oolite – but the functionality exists in Oolite’s maths library, so I’ve chosen to expose it. -- [[User:Ahruman|Ahruman]]) | Returns the quaternion dot product (inner product) of the target and <code>[[#Quaternion Expressions|quaternionExpression]]</code>. (This is not known to be useful – it’s not used anywhere in Oolite – but the functionality exists in Oolite’s maths library, so I’ve chosen to expose it. -- [[User:Ahruman|Ahruman]]) | ||
=== <code>rotate</code> === | === <code>rotate</code> === | ||
| − | + | function '''rotate'''(axis : [[Oolite/Development/Scripting/Class/Vector#Vector Expressions|vectorExpression]], angle : Number) : Quaternion | |
Returns a quaternion rotated <code>angle</code> radians about the axis of <code>[[Oolite/Development/Scripting/Class/Vector#Vector Expressions|vectorExpression]]</code>. (FIXME: clockwise or anticlockwise?) | Returns a quaternion rotated <code>angle</code> radians about the axis of <code>[[Oolite/Development/Scripting/Class/Vector#Vector Expressions|vectorExpression]]</code>. (FIXME: clockwise or anticlockwise?) | ||
=== <code>rotateX</code> === | === <code>rotateX</code> === | ||
| − | + | function '''rotateX'''(angle : Number) : Quaternion | |
Returns a quaternion rotated <code>angle</code> radians about the ''x'' axis. (FIXME: clockwise or anticlockwise?) | Returns a quaternion rotated <code>angle</code> radians about the ''x'' axis. (FIXME: clockwise or anticlockwise?) | ||
| Line 67: | Line 70: | ||
=== <code>rotateY</code> === | === <code>rotateY</code> === | ||
| − | + | function '''rotateY'''(angle : Number) : Quaternion | |
Returns a quaternion rotated <code>angle</code> radians about the ''y'' axis. (FIXME: clockwise or anticlockwise?) | Returns a quaternion rotated <code>angle</code> radians about the ''y'' axis. (FIXME: clockwise or anticlockwise?) | ||
| Line 73: | Line 76: | ||
=== <code>rotateZ</code> === | === <code>rotateZ</code> === | ||
| − | + | function '''rotateZ'''(angle : Number) : Quaternion | |
Returns a quaternion rotated <code>angle</code> radians about the ''z'' axis. (FIXME: clockwise or anticlockwise?) | Returns a quaternion rotated <code>angle</code> radians about the ''z'' axis. (FIXME: clockwise or anticlockwise?) | ||
| Line 79: | Line 82: | ||
=== <code>normalize</code> === | === <code>normalize</code> === | ||
| − | + | function '''normalize'''() : Quaternion | |
Returns the quaternion adjusted to fulfill the [[#Quaternions for Rotations|normal invariant]]. Specifically, this divides each component by the square root of (''w''² + ''x''² + ''y''² + ''z''²). | Returns the quaternion adjusted to fulfill the [[#Quaternions for Rotations|normal invariant]]. Specifically, this divides each component by the square root of (''w''² + ''x''² + ''y''² + ''z''²). | ||
=== <code>vectorForward</code> === | === <code>vectorForward</code> === | ||
| − | [[Oolite/Development/Scripting/Class/Vector|Vector]] | + | function '''vectorForward'''() : [[Oolite/Development/Scripting/Class/Vector|Vector]] |
Returns the forward vector from the quaternion. | Returns the forward vector from the quaternion. | ||
| Line 89: | Line 92: | ||
=== <code>vectorUp</code> === | === <code>vectorUp</code> === | ||
| − | [[Oolite/Development/Scripting/Class/Vector|Vector]] | + | function '''vectorUp'''() : [[Oolite/Development/Scripting/Class/Vector|Vector]] |
Returns the up vector from the quaternion. See <code>[[#vectorForward|vectorForward]]()</code> for a definition. | Returns the up vector from the quaternion. See <code>[[#vectorForward|vectorForward]]()</code> for a definition. | ||
=== <code>vectorRight</code> === | === <code>vectorRight</code> === | ||
| − | [[Oolite/Development/Scripting/Class/Vector|Vector]] | + | function '''vectorRight'''() : [[Oolite/Development/Scripting/Class/Vector|Vector]] |
Returns the right vector from the quaternion. See <code>[[#vectorForward|vectorForward]]()</code> for a definition. | Returns the right vector from the quaternion. See <code>[[#vectorForward|vectorForward]]()</code> for a definition. | ||
[[Category:Oolite scripting]] [[Category: Oolite]] | [[Category:Oolite scripting]] [[Category: Oolite]] | ||
Revision as of 22:55, 20 August 2007
Prototype: Object
Subtypes: none
The Quaternion class represents a quaternion, a four-dimensional number, which is used to express rotations. Explaining quaternion mathematics is way beyond the scope of this document, but a quick overview is provided below.
Contents
Quaternions for Rotations
This is a very quick, pragmatic discussion of quaternions as they apply to rotating things in Oolite. If you’re interested in the theory, see:
- Wikipedia: Quaternions and spatial rotation
- Wikipedia: Quaternion
- MathWorld: Quaternion
Consider a ship at point h oriented to face a station at point t. This can be expressed as the vector from the ship to the station, v = t − h. However, if the ship rolls, it is still heading along the same vector v, so additional information is required: a twist angle, α (FIXME: relative to what?). A rotation quaternion is a tuple Q = (w, x, y, z), such that
- Qw = cos α/2
- Qx = vx sin α/2
- Qy = vy sin α/2
- Qz = vz sin α/2
Additionally, a rotation quaternion must be normalized; that is, it must fulfill the normal invariant Qw² + Qx² + Qy² + Qz² = 1. Unlike with property list scripting and specifications, quaternions will not be automatically normalized for you except where specified, but a normalize() method is provided.
An identity rotation – that is, one which, when applied, has no effect – is represented by the identity quaternion (1, 0, 0, 0).
The Quaternion class provides several methods to make construction of rotations easier: rotate(), rotateX(), rotateY(), rotateZ().
Rotations can be combined by quaternion multiplication (see the multiply() method). Note that quaternion multiplication is not commutative; that is, PQ is not the same as QP. If this seems strange, take a box or book and assign it x, y and z axes. Rotate it about the x axis and then the y axis. Then, rotate it about the y axis followed by the x axis. If the results of the two rotations are the same, you’re doing it wrong.
Quaternion Expressions
All Oolite-provided functions which take a quaternion as an argument may instead be passed an Entity instead, in which case the entity’s orientation is used. In specifications, this is represented by arguments named quaternionOrEntity. (Is this actually useful? It seems less compellingly so than the vector equivalent. -- User:Ahruman)
Additionally, most Quaternion methods may be passed four numbers instead of a vector. In specifications, this is represented by arguments named quaternionExpression.
Properties
w
w : Number (read/write)
The w component of the quaternion.
x
x : Number (read/write)
The x component of the quaternion.
y
y : Number (read/write)
The y component of the quaternion.
z
z : Number (read/write)
The z component of the quaternion.
Methods
Constructor
new Quaternion([value : quaternionExpression])
Create a new quaternion with the specified value. If no value is provided, the vector is initialized to the identity quaternion (1, 0, 0, 0).
multiply
function multiply(q : quaternionExpression) : Quaternion
Returns the standard quaternion product (Grassman product) of the target and quaternionExpression. This is used to concatenate rotations together.
dot
function dot(q : quaternionExpression) : Quaternion
Returns the quaternion dot product (inner product) of the target and quaternionExpression. (This is not known to be useful – it’s not used anywhere in Oolite – but the functionality exists in Oolite’s maths library, so I’ve chosen to expose it. -- Ahruman)
rotate
function rotate(axis : vectorExpression, angle : Number) : Quaternion
Returns a quaternion rotated angle radians about the axis of vectorExpression. (FIXME: clockwise or anticlockwise?)
rotateX
function rotateX(angle : Number) : Quaternion
Returns a quaternion rotated angle radians about the x axis. (FIXME: clockwise or anticlockwise?)
q.rotateX(a) is equivalent to q.rotate(1, 0, 0, a).
rotateY
function rotateY(angle : Number) : Quaternion
Returns a quaternion rotated angle radians about the y axis. (FIXME: clockwise or anticlockwise?)
q.rotateY(a) is equivalent to q.rotate(0, 1, 0, a).
rotateZ
function rotateZ(angle : Number) : Quaternion
Returns a quaternion rotated angle radians about the z axis. (FIXME: clockwise or anticlockwise?)
q.rotateZ(a) is equivalent to q.rotate(0, 0, 1, a).
normalize
function normalize() : Quaternion
Returns the quaternion adjusted to fulfill the normal invariant. Specifically, this divides each component by the square root of (w² + x² + y² + z²).
vectorForward
function vectorForward() : Vector
Returns the forward vector from the quaternion.
To understand this, consider an entity which is aligned with the world co-ordinate system – that is, its orientation is the identity quaternion (1, 0, 0, 0), and thus its x axis is aligned with the world x axis, its y axis is aligned with the world y axis and its z axis is aligned with the world z axis. If it is rotated by a quaternion Q, Q.vectorForward() is the forward (z) axis after rotation. Similarly, Q.vectorUp() is the up (y) axis after rotation, and Q.vectorRight() is the right (x) axis after rotation.
vectorUp
function vectorUp() : Vector
Returns the up vector from the quaternion. See vectorForward() for a definition.
vectorRight
function vectorRight() : Vector
Returns the right vector from the quaternion. See vectorForward() for a definition.
