Oolite JavaScript Reference: Vector3D

This page documents a planned future Oolite scripting feature. It is presented as a basis for discussion or to help developers organize their thoughts. The functionality presented may end up taking a radically different form, or may not become available at all.

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 [read-write double]

The x co-ordinate of the vector.

`y`

y [read-write double]

The y co-ordinate of the vector.

`z`

z [read-write double]

The z co-ordinate of the vector.

Methods

Constructor

new Vector(vectorExpression);

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

`add`

Vector add(vectorExpression);

Returns the vector sum of the target and vectorExpression.

`subtract`

Vector subtract(vectorExpression);

Returns the vector difference between the target and vectorExpression.

`distanceTo`

double distanceTo(vectorExpression);

Returns the distance between the target and vectorExpression.

a.distanceTo(b) is equivalent to a.subtract(b).magnitude().

`squaredDistanceTo`

double squaredDistanceTo(vectorExpression);

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

a.squaredDistanceTo(b) is equivalent to a.distanceTo(b) * a.distanceTo(b).

`multiply`

Vector multiply(number);

Returns the product of the target and vectorExpression.

`dot`

double dot(vectorExpression);

Returns the dot product of the target and vectorExpression.

`angleTo`

double angleTo(vectorExpression);

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

a.angleTo(b) is equivalent to acos(a.direction().dot(b.direction())).

`cross`

double cross(vectorExpression);

Returns the cross product of the target and vectorExpression.

`tripleProduct`

double tripleProduct(vectorExpression1, vectorExpression2);

Returns the triple product of the target, vectorExpression1 and vectorExpression2.

a.tripleProduct(b, c) is equivalent to a.dot(b.cross(c)).

`direction`

Vector direction();

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

a.direction() is equivalent to a * (1 / a.magnitude()).

`magnitude`

double magnitude();

Returns the magnitude (or length) of the vector.

`squaredMagnitude`

double squaredMagnitude();

Returns the square of the magnitude of the vector.

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

`rotationTo`

Quaternion rotationTo(vectorExpression [, maxArc]);

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