Difference between revisions of "Oolite JavaScript Reference: Vector3D"

Revision as of 18:48, 16 October 2007

Prototype: Object
Subtypes: none

The Vector class is a geometrical vector in three-dimensional space, in cartesian representation. It is used to represent positions, headings and velocities. Explaining vector geometry is beyond the scope of this document, but there are numerous tutorials on the web.

Vector Expressions

All Oolite-provided functions which take a vector as an argument may instead be passed an Entity instead, in which case the entity’s position is used. In specifications, this is represented by arguments named vectorOrEntity.

Additionally, most Vector methods may be passed three numbers instead of a vector. In specifications, this is represented by arguments named vectorExpression. For example, if a and b are vectors whose values are (0, 1, 0) and (1, 0, 0) respectively, the following are equivalent:

var c = a.add(b);
var d = a.add(1, 0, 0);
// c and d are now both (1, 1, 0).

Properties

`x`

x : Number (read/write)

The x co-ordinate of the vector.

`y`

y : Number (read/write)

The y co-ordinate of the vector.

`z`

z : Number (read/write)

The z co-ordinate of the vector.

Methods

Constructor

new Vector([value : vectorExpression]) : Vector

Create a new vector with the specified value. If no value is provided, the vector is initialized to (0, 0, 0).

`add`

function add(v : vectorExpression) : Vector

Returns the vector sum of the target and v.

See Also: subtract()

`angleTo`

function angleTo(v : vectorExpression) : Number

Returns the angle (in radians) between the target and vectorExpression.

v.angleTo(u) is equivalent to acos(v.direction().dot(u.direction())).

`cross`

function cross(v : vectorExpression) : Vector

Returns the cross product of the target and vectorExpression.

See Also: dot()

`direction`

function direction() : Vector

Returns the unit vector with the same direction as the target.

v.direction() is equivalent to v.multiply(1 / v.magnitude()).

See Also: magnitude()

`distanceTo`

function distanceTo(v : vectorExpression) : Number

Returns the distance between the target and v.

u.distanceTo(v) is equivalent to u.subtract(v).magnitude().

See Also: squaredDistanceTo()

`dot`

function dot(v : vectorExpression) : Number

Returns the dot product of the target and v.

See Also: cross()

`magnitude`

function magnitude() : Number

Returns the magnitude (or length) of the vector.

See Also: squaredMagnitude(), direction()

`multiply`

function multiply(f : Number) : Vector

Returns the product of the target and f. This has the effect of scaling the vector by the factor f.

`rotateBy`

function rotateBy(q : quaternionExpression) : Vector

Apply the rotation specified by q to the target.

`rotationTo`

function rotationTo(v : vectorExpression [, maxArc : Number]) : Quaternion

Returns a quaternion corresponding to a rotation from the target to v. The optional parameter maxArc specifies a maximum rotation angle; if the angle between the target and v is greater than maxArc radians, a rotation of maxArc radians towards vectorExpression is generated instead.

`subtract`

function subtract(v : vectorExpression) : Vector

Returns the vector difference between the target and v.

See Also: add()

`squaredDistanceTo`

function squaredDistanceTo(v: vectorExpression) : Number

Returns the square of the distance between the target and v.

u.squaredDistanceTo(v) is equivalent to u.distanceTo(v) * u.distanceTo(v), or u.subtract(v).squaredMagnitude().

`squaredMagnitude`

function squaredMagnitude() : Number

Returns the square of the magnitude of the vector.

v.squaredMagnitude() is equivalent to v.magnitude() * v.magnitude().

`tripleProduct`

function tripleProduct(v : vectorExpression, w : vectorExpression) : Number

Returns the triple product of the target, v and w.

u.tripleProduct(v, w) is equivalent to u.dot(v.cross(w)).

@@ Line 7: / Line 7: @@
 All Oolite-provided functions which take a vector 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#position|position]]</code> is used. In specifications, this is represented by arguments named <code>vectorOrEntity</code>.
-Additionally, most <code>Vector</code> methods may be passed three numbers, or an array of three numbers, instead of a vector. In specifications, this is represented by arguments named <code>vectorExpression</code>. For example, if <code>a</code> and <code>b</code> are vectors whose values are (0, 1, 0) and (1, 0, 0) respectively, the following are equivalent:
+Additionally, most <code>Vector</code> methods may be passed three numbers instead of a vector. In specifications, this is represented by arguments named <code>vectorExpression</code>. For example, if <code>a</code> and <code>b</code> are vectors whose values are (0, 1, 0) and (1, 0, 0) respectively, the following are equivalent:
  var c = a.add(b);
  var d = a.add(1, 0, 0);
- var e = a.add([1, 0, 0]);
+ // c and d are now both (1, 1, 0).
- // c, d and e are now all (1, 1, 0).
 == Properties ==
@@ Line 102: / Line 102: @@
 === <code>squaredMagnitude</code> ===
- function '''squaredMagnitude'''() : Number
+ function '''squaredMagnitude() : Number
 Returns the square of the magnitude of the vector.
 <code>v.squaredMagnitude()</code> is equivalent to <code>v.[[#magnitude|magnitude]]() * v.[[#magnitude|magnitude]]()</code>.
-=== <code>toArray</code> ===
- function '''toArray'''() : Array
-Returns an array of the vector’s components, in the order <code>[x, y, z]</code>. <code>v.toArray()</code> is equivalent to <code>[v.x, v.y, v.z]</code>.
 === <code>tripleProduct</code> ===