Vec3

Description

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

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

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 coordinates of a point from polar coordinate transformation of the unit z-axis vector.

fromPolar Vec3

Calculates the unit vector corresponding to polar coordinates elevation and azimuth 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( 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) 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) 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