Vec3

Available in: Interface Scripts Client Entity Scripts Server Entity Scripts Assignment Client Scripts

The Vec3 API 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
Methods

Properties:
Name Type Description
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

cross(v1, v2) → {Vec3}
Calculate the cross product of two vectors.
Parameters:
Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
Returns:
The cross product of v1 and v2.
Type: Vec3
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}
distance(p1, p2) → {number}
Calculate the distance between two points.
Parameters:
Name Type Description
p1 Vec3 The first point.
p2 Vec3 The second point.
Returns:
The distance between the two points.
Type: number
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
dot(v1, v2) → {number}
Calculate the dot product of two vectors.
Parameters:
Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
Returns:
The dot product of v1 and v2.
Type: number
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
equal(v1, v2) → {boolean}
Test 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.
Returns:
true if the two vectors are exactly equal, otherwise false.
Type: boolean
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
fromPolar(polar) → {Vec3}
Calculate 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 scale.
Returns:
The coordinates of the point.
Type: Vec3
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}
fromPolar(elevation, azimuth) → {Vec3}
Calculate 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.
Returns:
Unit vector for the direction specified by elevation and azimuth.
Type: Vec3
Example

Polar coordinates to Cartesian.

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}
getAngle(v1, v2) → {number}
Calculate the angle between two vectors.
Parameters:
Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
Returns:
The angle between the two vectors, in radians.
Type: number
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
length(v) → {number}
Calculate the length of a vector
Parameters:
Name Type Description
v Vec3 The vector.
Returns:
The length of the vector.
Type: number
mix(v1, v2, factor) → {Vec3}
Calculate 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 in the range 0.0 to 1.0.
Returns:
The linear interpolation between the two vectors: (1 - factor) * v1 + factor * v2.
Type: Vec3
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}
multiply(scale, v) → {Vec3}
Multiply a vector by a scale factor.
Parameters:
Name Type Description
scale number The scale factor.
v Vec3 The vector.
Returns:
The vector with each ordinate value multiplied by the scale.
Type: Vec3
multiply(v, scale) → {Vec3}
Multiply a vector by a scale factor.
Parameters:
Name Type Description
v Vec3 The vector.
scale number The scale factor.
Returns:
The vector with each ordinate value multiplied by the scale.
Type: Vec3
multiplyQbyV(q, v) → {Vec3}
Rotate a vector.
Parameters:
Name Type Description
q Quat The rotation to apply.
v Vec3 The vector to rotate.
Returns:
v rotated by q.
Type: Vec3
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}
multiplyVbyV(v1, v2) → {Vec3}
Multiply two vectors.
Parameters:
Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
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 }.
Type: Vec3
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}
normalize(v) → {Vec3}
Normalize a vector so that its length is 1.
Parameters:
Name Type Description
v Vec3 The vector to normalize.
Returns:
The vector normalized to have a length of 1.
Type: Vec3
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
orientedAngle(v1, v2, ref) → {number}
Calculate 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.
Returns:
The angle of rotation from the first vector to the second, in degrees, with a positive sign if the rotation axis aligns with the reference vector (has a positive dot product) otherwise a negative sign.
Type: number
Example

Compare Vec3.angle() 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
print(label, v)
Print to the program log a text label followed by a 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}
reflect(v, normal) → {Vec3}
Calculate 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.
Returns:
The vector reflected in the plane given by the normal.
Type: Vec3
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}
subtract(v1, v2) → {Vec3}
Calculate one vector subtracted from another.
Parameters:
Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
Returns:
The second vector subtracted from the first.
Type: Vec3
sum(v1, v2) → {Vec3}
Calculate the sum of two vectors.
Parameters:
Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
Returns:
The sum of the two vectors.
Type: Vec3
toPolar(p) → {Vec3}
Calculate 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.
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 scale.
Type: Vec3
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
withinEpsilon(v1, v2, epsilon) → {boolean}
Test 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.
Returns:
true if the distance between the points represented by the vectors is less than or equal to the epsilon, otherwise false.
Type: boolean
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