Vec3

Description

The Vec3 API provides facilities for generating and manipulating 3-dimensional vectors. High Fidelity uses a right-handed Cartesian coordinate system where the y-axis is the "up" and the negative z-axis is the "front" direction. High Fidelity coordinate system

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts • Server Entity Scripts • Assignment Client Scripts

Properties

Name Type Summary
UNIT_X Vec3 { x: 1, y: 0, z: 0 } : Unit vector in the x-axis direction. Read-only.
UNIT_Y Vec3 { x: 0, y: 1, z: 0 } : Unit vector in the y-axis direction. Read-only.
UNIT_Z Vec3 { x: 0, y: 0, z: 1 } : Unit vector in the z-axis direction. Read-only.
UNIT_NEG_X Vec3 { x: -1, y: 0, z: 0 } : Unit vector in the negative x-axis direction. Read-only.
UNIT_NEG_Y Vec3 { x: 0, y: -1, z: 0 } : Unit vector in the negative y-axis direction. Read-only.
UNIT_NEG_Z Vec3 { x: 0, y: 0, z: -1 } : Unit vector in the negative z-axis direction. Read-only.
UNIT_XY Vec3 { x: 0.707107, y: 0.707107, z: 0 } : Unit vector in the direction of the diagonal between the x and y axes. Read-only.
UNIT_XZ Vec3 { x: 0.707107, y: 0, z: 0.707107 } : Unit vector in the direction of the diagonal between the x and z axes. Read-only.
UNIT_YZ Vec3 { x: 0, y: 0.707107, z: 0.707107 } : Unit vector in the direction of the diagonal between the y and z axes. Read-only.
UNIT_XYZ Vec3 { x: 0.577350, y: 0.577350, z: 0.577350 } : Unit vector in the direction of the diagonal between the x, y, and z axes. Read-only.
FLOAT_MAX Vec3 { x: 3.402823e+38, y: 3.402823e+38, z: 3.402823e+38 } : Vector with all axis values set to the maximum floating point value. Read-only.
FLOAT_MIN Vec3 { x: -3.402823e+38, y: -3.402823e+38, z: -3.402823e+38 } : Vector with all axis values set to the negative of the maximum floating point value. Read-only.
ZERO Vec3 { x: 0, y: 0, z: 0 } : Vector with all axis values set to 0. Read-only.
ONE Vec3 { x: 1, y: 1, z: 1 } : Vector with all axis values set to 1. Read-only.
TWO Vec3 { x: 2, y: 2, z: 2 } : Vector with all axis values set to 2. Read-only.
HALF Vec3 { x: 0.5, y: 0.5, z: 0.5 } : Vector with all axis values set to 0.5. Read-only.
RIGHT Vec3 { x: 1, y: 0, z: 0 } : Unit vector in the "right" direction. Synonym for UNIT_X. Read-only.
UP Vec3 { x: 0, y: 1, z: 0 } : Unit vector in the "up" direction. Synonym for UNIT_Y. Read-only.
FRONT Vec3 { x: 0, y: 0, z: -1 } : Unit vector in the "front" direction. Synonym for UNIT_NEG_Z. Read-only.

Methods

Name Return Value Summary
cross Vec3 Calculates the cross product of two vectors.
distance number Calculates the distance between two points.
dot number Calculates the dot product of two vectors.
equal boolean Tests whether two vectors are equal.

Note: The vectors must be exactly equal in order for true to be returned; it is often better to use withinEpsilon.

fromPolar Vec3 Calculates the unit vector corresponding to polar coordinates elevation and azimuth transformation of the unit z-axis vector.
fromPolar Vec3 Calculates the coordinates of a point from polar coordinate transformation of the unit z-axis vector.
getAngle number Calculates the angle between two vectors.
length number Calculates the length of a vector
mix Vec3 Calculates a linear interpolation between two vectors.
multiply Vec3 Multiplies a vector by a scale factor.
multiply Vec3 Multiplies a vector by a scale factor.
multiplyQbyV Vec3 Rotates a vector.
multiplyVbyV Vec3 Multiplies two vectors.
normalize Vec3 Normalizes a vector so that its length is 1.
orientedAngle number Calculates the angle of rotation from one vector onto another, with the sign depending on a reference vector.
print None Prints the vector to the program log, as a text label followed by the vector value.
reflect Vec3 Calculates the reflection of a vector in a plane.
subtract Vec3 Calculates one vector subtracted from another.
sum Vec3 Calculates the sum of two vectors.
toPolar Vec3 Calculates polar coordinates (elevation, azimuth, radius) that transform the unit z-axis vector onto a point.
withinEpsilon boolean Tests whether two vectors are equal within a tolerance.

Note: It is often better to use this function than equal.

Method Details

(static) cross( v1, v2 ) → {Vec3}
Returns: The cross product of v1 and v2.

Calculates the cross product of two vectors.

Parameters

Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
Example

The cross product of x and y unit vectors is the z unit vector.

var v1 = { x: 1, y: 0, z: 0 };
var v2 = { x: 0, y: 1, z: 0 };
var crossProduct = Vec3.cross(v1, v2);
print(JSON.stringify(crossProduct)); // {"x":0,"y":0,"z":1}
(static) distance( p1, p2 ) → {number}
Returns: The distance between the two points.

Calculates the distance between two points.

Parameters

Name Type Description
p1 Vec3 The first point.
p2 Vec3 The second point.
Example

The distance between two points is aways positive.

var p1 = { x: 0, y: 0, z: 0 };
var p2 = { x: 0, y: 0, z: 10 };
var distance = Vec3.distance(p1, p2);
print(distance); // 10

p2 = { x: 0, y: 0, z: -10 };
distance = Vec3.distance(p1, p2);
print(distance); // 10
(static) dot( v1, v2 ) → {number}
Returns: The dot product of v1 and v2.

Calculates the dot product of two vectors.

Parameters

Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
Example

The dot product of vectors at right angles is 0.

var v1 = { x: 1, y: 0, z: 0 };
var v2 = { x: 0, y: 1, z: 0 };
var dotProduct = Vec3.dot(v1, v2);
print(dotProduct); // 0
(static) equal( v1, v2 ) → {boolean}
Returns: true if the two vectors are exactly equal, otherwise false.

Tests whether two vectors are equal.

Note: The vectors must be exactly equal in order for true to be returned; it is often better to use withinEpsilon.

Parameters

Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
Example

Vectors are only equal if exactly the same.

var v1 = { x: 10, y: 10, z: 10 };
var v2 = { x: 10, y: 10, z: 10 };

var equal = Vec3.equal(v1, v2);
print(equal);  // true

v2 = { x: 10, y: 10, z: 10.0005 };
equal = Vec3.equal(v1, v2);
print(equal);  // false
(static) fromPolar( elevation, azimuth ) → {Vec3}
Returns: Unit vector for the direction specified by elevation and azimuth.

Calculates the unit vector corresponding to polar coordinates elevation and azimuth transformation of the unit z-axis vector.

Parameters

Name Type Description
elevation number Rotation about the x-axis, in radians.
azimuth number Rotation about the y-axis, in radians.
Example

Polar coordinates to Cartesian coordinates.

var elevation = -19.471 * Math.PI / 180;
var rotation = 45 * Math.PI / 180;
var p = Vec3.fromPolar(elevation, rotation);
print(JSON.stringify(p));  // {"x":0.667,"y":0.333,"z":0.667}
p = Vec3.multiply(7.5, p);
print(JSON.stringify(p));  // {"x":5,"y":2.5,"z":5}
(static) fromPolar( polar ) → {Vec3}
Returns: The coordinates of the point.

Calculates the coordinates of a point from polar coordinate transformation of the unit z-axis vector.

Parameters

Name Type Description
polar Vec3 The polar coordinates of a point: x elevation rotation about the x-axis in radians, y azimuth rotation about the y-axis in radians, and z radius.
Example

Polar coordinates to Cartesian.

var polar = { x: -19.471 * Math.PI / 180, y: 45 * Math.PI / 180, z: 7.5 };
var p = Vec3.fromPolar(polar);
print(JSON.stringify(p));  // {"x":5,"y":2.5,"z":5}
(static) getAngle( v1, v2 ) → {number}
Returns: The angle between the two vectors, in radians.

Calculates the angle between two vectors.

Parameters

Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
Example

Calculate the angle between two vectors.

var v1 = { x: 10, y: 0, z: 0 };
var v2 = { x: 0, y: 0, z: 10 };
var angle = Vec3.getAngle(v1, v2);
print(angle * 180 / Math.PI);  // 90
     
(static) length( v ) → {number}
Returns: The length of the vector.

Calculates the length of a vector

Parameters

Name Type Description
v Vec3 The vector.
(static) mix( v1, v2, factor ) → {Vec3}
Returns: The linear interpolation between the two vectors: (1 - factor) * v1 + factor * v2.

Calculates a linear interpolation between two vectors.

Parameters

Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
factor number The interpolation factor, range 0.01.0.
Example

Linear interpolation between two vectors.

var v1 = { x: 10, y: 0, z: 0 };
var v2 = { x: 0, y: 10, z: 0 };
var interpolated = Vec3.mix(v1, v2, 0.75);  // 1/4 of v1 and 3/4 of v2.
print(JSON.stringify(interpolated));  // {"x":2.5,"y":7.5","z":0}
(static) multiply( v, scale ) → {Vec3}
Returns: The vector with each ordinate value multiplied by the scale.

Multiplies a vector by a scale factor.

Parameters

Name Type Description
v Vec3 The vector.
scale number The scale factor.
(static) multiply( scale, v ) → {Vec3}
Returns: The vector with each ordinate value multiplied by the scale.

Multiplies a vector by a scale factor.

Parameters

Name Type Description
scale number The scale factor.
v Vec3 The vector.
(static) multiplyQbyV( q, v ) → {Vec3}
Returns: v rotated by q.

Rotates a vector.

Parameters

Name Type Description
q Quat The rotation to apply.
v Vec3 The vector to rotate.
Example

Rotate the negative z-axis by 90 degrees about the x-axis.

var v = Vec3.UNIT_NEG_Z;
var q = Quat.fromPitchYawRollDegrees(90, 0, 0);
var result = Vec3.multiplyQbyV(q, v);
print(JSON.stringify(result));  // {"x":0,"y":1.000,"z":1.19e-7}
(static) multiplyVbyV( v1, v2 ) → {Vec3}
Returns: A vector formed by multiplying the ordinates of two vectors: { x: v1.x * v2.x, y: v1.y * v2.y, z: v1.z * v2.z }.

Multiplies two vectors.

Parameters

Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
Example

Multiply two vectors.

var v1 = { x: 1, y: 2, z: 3 };
var v2 = { x: 1, y: 2, z: 3 };
var multiplied = Vec3.multiplyVbyV(v1, v2);
print(JSON.stringify(multiplied));  // {"x":1,"y":4,"z":9}
(static) normalize( v ) → {Vec3}
Returns: The vector normalized to have a length of 1.

Normalizes a vector so that its length is 1.

Parameters

Name Type Description
v Vec3 The vector to normalize.
Example

Normalize a vector.

var v = { x: 10, y: 10, z: 0 };
var normalized = Vec3.normalize(v);
print(JSON.stringify(normalized));  // {"x":0.7071,"y":0.7071,"z":0}
print(Vec3.length(normalized));  // 1
(static) orientedAngle( v1, v2, ref ) → {number}
Returns: The angle of rotation from the first vector to the second, in degrees. The value is positive if the rotation axis aligns with the reference vector (has a positive dot product), otherwise the value is negative.

Calculates the angle of rotation from one vector onto another, with the sign depending on a reference vector.

Parameters

Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
ref Vec3 Reference vector.
Example

Compare Vec3.getAngle() and Vec3.orientedAngle().

var v1 = { x: 5, y: 0, z: 0 };
var v2 = { x: 5, y: 0, z: 5 };

var angle = Vec3.getAngle(v1, v2);
print(angle * 180 / Math.PI);  // 45

print(Vec3.orientedAngle(v1, v2, Vec3.UNIT_Y));  // -45
print(Vec3.orientedAngle(v1, v2, Vec3.UNIT_NEG_Y));  // 45
print(Vec3.orientedAngle(v1, v2, { x: 1, y: 2, z: -1 }));  // -45
print(Vec3.orientedAngle(v1, v2, { x: 1, y: -2, z: -1 }));  // 45
(static) print( label, v )

Prints the vector to the program log, as a text label followed by the vector value.

Parameters

Name Type Description
label string The label to print.
v Vec3 The vector value to print.
Example

Two ways of printing a label and vector value.

var v = { x: 1, y: 2, z: 3 };
Vec3.print("Vector: ", v);  // dvec3(1.000000, 2.000000, 3.000000)
print("Vector: " + JSON.stringify(v));  // {"x":1,"y":2,"z":3}
(static) reflect( v, normal ) → {Vec3}
Returns: The vector reflected in the plane given by the normal.

Calculates the reflection of a vector in a plane.

Parameters

Name Type Description
v Vec3 The vector to reflect.
normal Vec3 The normal of the plane.
Example

Reflect a vector in the x-z plane.

var v = { x: 1, y: 2, z: 3 };
var normal = Vec3.UNIT_Y;
var reflected = Vec3.reflect(v, normal);
print(JSON.stringify(reflected));  // {"x":1,"y":-2,"z":3}
(static) subtract( v1, v2 ) → {Vec3}
Returns: The second vector subtracted from the first.

Calculates one vector subtracted from another.

Parameters

Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
(static) sum( v1, v2 ) → {Vec3}
Returns: The sum of the two vectors.

Calculates the sum of two vectors.

Parameters

Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
(static) toPolar( p ) → {Vec3}
Returns: Vector of polar coordinates for the point: x elevation rotation about the x-axis in radians, y azimuth rotation about the y-axis in radians, and z radius.

Calculates polar coordinates (elevation, azimuth, radius) that transform the unit z-axis vector onto a point.

Parameters

Name Type Description
p Vec3 The point to calculate the polar coordinates for.
Example

Polar coordinates for a point.

var v = { x: 5, y: 2.5, z: 5 };
var polar = Vec3.toPolar(v);
print("Elevation: " + polar.x * 180 / Math.PI);  // -19.471
print("Azimuth: " + polar.y * 180 / Math.PI);  // 45
print("Radius: " + polar.z);  // 7.5
(static) withinEpsilon( v1, v2, epsilon ) → {boolean}
Returns: true if the distance between the points represented by the vectors is less than or equal to epsilon, otherwise false.

Tests whether two vectors are equal within a tolerance.

Note: It is often better to use this function than equal.

Parameters

Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
epsilon number The maximum distance between the two vectors.
Example

Testing vectors for near equality.

var v1 = { x: 10, y: 10, z: 10 };
var v2 = { x: 10, y: 10, z: 10.0005 };

var equal = Vec3.equal(v1, v2);
print(equal);  // false

equal = Vec3.withinEpsilon(v1, v2, 0.001);
print(equal);  // true