mdi-backburger

# 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. Overte uses a right-handed Cartesian coordinate system where the y-axis is the "up" and the negative z-axis is the "front" direction. ### 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

`azimuth` number

##### 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.0``1.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``````