How To

Class: Vec3

3-dimensional vector.

Constructors

new Vec3()

new Vec3(
   x?: number | number[],
   y?: number,
   z?: number): Vec3

Creates a new Vec3 object.

Parameters

x?

The x value. Defaults to 0. If x is an array of length 3, the array will be used to populate all components.

number | number[]

y?

number = 0

The y value. Defaults to 0.

z?

number = 0

The z value. Defaults to 0.

Example

const v = new Vec3(1, 2, 3)

Methods

add()

add(rhs: Vec3): Vec3

Adds a 3-dimensional vector to another in place.

Parameters

rhs

Vec3

The vector to add to the specified vector.

Example

const a = new Vec3(10, 10, 10)
const b = new Vec3(20, 20, 20)

a.add(b)

// Outputs [30, 30, 30]
console.log('The result of the addition is: ' + a.toString())

add2()

add2(lhs: Vec3, rhs: Vec3): Vec3

Adds two 3-dimensional vectors together and returns the result.

Parameters

lhs

Vec3

The first vector operand for the addition.

rhs

Vec3

The second vector operand for the addition.

Example

const a = new Vec3(10, 10, 10)
const b = new Vec3(20, 20, 20)
const r = new Vec3()

r.add2(a, b)
// Outputs [30, 30, 30]

console.log('The result of the addition is: ' + r.toString())

addScalar()

addScalar(scalar: number): Vec3

Adds a number to each element of a vector.

Example

const vec = new Vec3(3, 4, 5)

vec.addScalar(2)

// Outputs [5, 6, 7]
console.log('The result of the addition is: ' + vec.toString())

addScaled()

addScaled(rhs: Vec3, scalar: number): Vec3

Adds a 3-dimensional vector scaled by scalar value. Does not modify the vector being added.

Parameters

rhs

Vec3

The vector to add to the specified vector.

scalar

number

The number to multiply the added vector with.

Example

const vec = new Vec3(1, 2, 3)

vec.addScaled(Vec3.UP, 2)

// Outputs [1, 4, 3]
console.log('The result of the addition is: ' + vec.toString())

ceil()

ceil(src?: Vec3): Vec3

Each element is rounded up to the next largest integer.

Parameters

src?

Vec3 = ...

The vector to ceil. If not set, the operation is done in place.

clone()

clone(): Vec3

Returns an identical copy of the specified 3-dimensional vector.

Returns

Vec3

A 3-dimensional vector containing the result of the cloning.

Example

const v = new Vec3(10, 20, 30)
const vclone = v.clone()
console.log('The result of the cloning is: ' + vclone.toString())

copy()

copy(rhs: Vec3): Vec3

Copies the contents of a source 3-dimensional vector to a destination 3-dimensional vector.

Parameters

rhs

Vec3

A vector to copy to the specified vector.

Example

const src = new Vec3(10, 20, 30)
const dst = new Vec3()

dst.copy(src)

console.log('The two vectors are ' + (dst.equals(src) ? 'equal' : 'different'))

cross()

cross(lhs: Vec3, rhs: Vec3): Vec3

Returns the result of a cross product operation performed on the two specified 3-dimensional vectors.

Parameters

lhs

Vec3

The first 3-dimensional vector operand of the cross product.

rhs

Vec3

The second 3-dimensional vector operand of the cross product.

Example

const back = new Vec3().cross(Vec3.RIGHT, Vec3.UP)

// Prints the Z axis (i.e. [0, 0, 1])
console.log('The result of the cross product is: ' + back.toString())

distance()

distance(rhs: Vec3): number

Returns the distance between the two specified 3-dimensional vectors.

Parameters

rhs

Vec3

The second 3-dimensional vector to test.

Returns

number

The distance between the two vectors.

Example

const v1 = new Vec3(5, 10, 20)
const v2 = new Vec3(10, 20, 40)
const d = v1.distance(v2)
console.log('The distance between v1 and v2 is: ' + d)

div()

div(rhs: Vec3): Vec3

Divides a 3-dimensional vector by another in place.

Parameters

rhs

Vec3

The vector to divide the specified vector by.

Example

const a = new Vec3(4, 9, 16)
const b = new Vec3(2, 3, 4)

a.div(b)

// Outputs [2, 3, 4]
console.log('The result of the division is: ' + a.toString())

div2()

div2(lhs: Vec3, rhs: Vec3): Vec3

Divides one 3-dimensional vector by another and writes the result to the specified vector.

Parameters

lhs

Vec3

The dividend vector (the vector being divided).

rhs

Vec3

The divisor vector (the vector dividing the dividend).

Example

const a = new Vec3(4, 9, 16)
const b = new Vec3(2, 3, 4)
const r = new Vec3()

r.div2(a, b)
// Outputs [2, 3, 4]

console.log('The result of the division is: ' + r.toString())

divScalar()

divScalar(scalar: number): Vec3

Divides each element of a vector by a number.

Example

const vec = new Vec3(3, 6, 9)

vec.divScalar(3)

// Outputs [1, 2, 3]
console.log('The result of the division is: ' + vec.toString())

dot()

dot(rhs: Vec3): number

Returns the result of a dot product operation performed on the two specified 3-dimensional vectors.

Parameters

rhs

Vec3

The second 3-dimensional vector operand of the dot product.

Returns

number

The result of the dot product operation.

Example

const v1 = new Vec3(5, 10, 20)
const v2 = new Vec3(10, 20, 40)
const v1dotv2 = v1.dot(v2)
console.log('The result of the dot product is: ' + v1dotv2)

equals()

equals(rhs: Vec3): boolean

Reports whether two vectors are equal.

Parameters

rhs

Vec3

The vector to compare to the specified vector.

Returns

boolean

True if the vectors are equal and false otherwise.

Example

const a = new Vec3(1, 2, 3)
const b = new Vec3(4, 5, 6)
console.log('The two vectors are ' + (a.equals(b) ? 'equal' : 'different'))

equalsApprox()

equalsApprox(rhs: Vec3, epsilon?: number): boolean

Reports whether two vectors are equal using an absolute error tolerance.

Parameters

rhs

Vec3

The vector to be compared against.

epsilon?

number = 1e-6

The maximum difference between each component of the two vectors. Defaults to 1e-6.

Returns

boolean

True if the vectors are equal and false otherwise.

Example

const a = new Vec3()
const b = new Vec3()
console.log(
  'The two vectors are approximately ' +
    (a.equalsApprox(b, 1e-9) ? 'equal' : 'different')
)

floor()

floor(src?: Vec3): Vec3

Each element is set to the largest integer less than or equal to its value.

Parameters

src?

Vec3 = ...

The vector to floor. If not set, the operation is done in place.

fromArray()

fromArray(arr: number[] | ArrayBufferView<ArrayBufferLike>, offset?: number): Vec3

Set the values of the vector from an array.

Parameters

arr

The array to set the vector values from.

number[] | ArrayBufferView<ArrayBufferLike>

offset?

number = 0

The zero-based index at which to start copying elements from the array. Default is 0.

Example

const v = new Vec3()
v.fromArray([
  20,
  10,
  5
])
// v is set to [20, 10, 5]

length()

length(): number

Returns the magnitude of the specified 3-dimensional vector.

Returns

number

The magnitude of the specified 3-dimensional vector.

Example

const vec = new Vec3(3, 4, 0)
const len = vec.length()
// Outputs 5
console.log('The length of the vector is: ' + len)

lengthSq()

lengthSq(): number

Returns the magnitude squared of the specified 3-dimensional vector.

Returns

number

The magnitude of the specified 3-dimensional vector.

Example

const vec = new Vec3(3, 4, 0)
const len = vec.lengthSq()
// Outputs 25
console.log('The length squared of the vector is: ' + len)

lerp()

lerp(
   lhs: Vec3,
   rhs: Vec3,
   alpha: number): Vec3

Returns the result of a linear interpolation between two specified 3-dimensional vectors.

Parameters

lhs

Vec3

The 3-dimensional to interpolate from.

rhs

Vec3

The 3-dimensional to interpolate to.

The value controlling the point of interpolation. Between 0 and 1, the linear interpolant will occur on a straight line between lhs and rhs. Outside of this range, the linear interpolant will occur on a ray extrapolated from this line.

Returns

Vec3

Self for chaining.

Example

const a = new Vec3(0, 0, 0)
const b = new Vec3(10, 10, 10)
const r = new Vec3()

r.lerp(a, b, 0) // r is equal to a
r.lerp(a, b, 0.5) // r is 5, 5, 5
r.lerp(a, b, 1) // r is equal to b

max()

max(rhs: Vec3): Vec3

Each element is assigned a value from rhs parameter if it is larger.

Parameters

rhs

Vec3

The 3-dimensional vector used as the source of elements to compare to.

Returns

Vec3

Self for chaining.

min()

min(rhs: Vec3): Vec3

Each element is assigned a value from rhs parameter if it is smaller.

Parameters

rhs

Vec3

The 3-dimensional vector used as the source of elements to compare to.

Returns

Vec3

Self for chaining.

mul()

mul(rhs: Vec3): Vec3

Multiplies a 3-dimensional vector to another in place.

Parameters

rhs

Vec3

The 3-dimensional vector used as the second multiplicand of the operation.

Returns

Vec3

Self for chaining.

Example

const a = new Vec3(2, 3, 4)
const b = new Vec3(4, 5, 6)

a.mul(b)

// Outputs [8, 15, 24]
console.log('The result of the multiplication is: ' + a.toString())

mul2()

mul2(lhs: Vec3, rhs: Vec3): Vec3

Returns the result of multiplying the specified 3-dimensional vectors together.

Parameters

lhs

Vec3

The 3-dimensional vector used as the first multiplicand of the operation.

rhs

Vec3

The 3-dimensional vector used as the second multiplicand of the operation.

Returns

Vec3

Self for chaining.

Example

const a = new Vec3(2, 3, 4)
const b = new Vec3(4, 5, 6)
const r = new Vec3()

r.mul2(a, b)

// Outputs [8, 15, 24]
console.log('The result of the multiplication is: ' + r.toString())

mulScalar()

mulScalar(scalar: number): Vec3

Multiplies each element of a vector by a number.

Parameters

scalar

number

The number to multiply by.

Returns

Vec3

Self for chaining.

Example

const vec = new Vec3(3, 6, 9)

vec.mulScalar(3)

// Outputs [9, 18, 27]
console.log('The result of the multiplication is: ' + vec.toString())

normalize()

normalize(src?: Vec3): Vec3

Returns this 3-dimensional vector converted to a unit vector in place. If the vector has a length of zero, the vector's elements will be set to zero.

const v = new Vec3(25, 0, 0)

v.normalize()

// Outputs [1, 0, 0]
console.log('The result of the vector normalization is: ' + v.toString())

project()

project(rhs: Vec3): Vec3

Projects this 3-dimensional vector onto the specified vector.

const v = new Vec3(5, 5, 5)
const normal = new Vec3(1, 0, 0)

v.project(normal)

// Outputs [5, 0, 0]
console.log('The result of the vector projection is: ' + v.toString())

round()

round(src?: Vec3): Vec3

Each element is rounded up or down to the nearest integer.

set(
   x: number,
   y: number,
   z: number): Vec3

Sets the specified 3-dimensional vector to the supplied numerical values.

const v = new Vec3()
v.set(5, 10, 20)

// Outputs [5, 10, 20]
console.log('The result of the vector set is: ' + v.toString())

sub()

sub(rhs: Vec3): Vec3

Subtracts a 3-dimensional vector from another in place.

const a = new Vec3(10, 10, 10)
const b = new Vec3(20, 20, 20)

a.sub(b)

// Outputs [-10, -10, -10]
console.log('The result of the subtraction is: ' + a.toString())

sub2()

sub2(lhs: Vec3, rhs: Vec3): Vec3

Subtracts two 3-dimensional vectors from one another and returns the result.

const a = new Vec3(10, 10, 10)
const b = new Vec3(20, 20, 20)
const r = new Vec3()

r.sub2(a, b)

// Outputs [-10, -10, -10]
console.log('The result of the subtraction is: ' + r.toString())

subScalar()

subScalar(scalar: number): Vec3

Subtracts a number from each element of a vector.

const vec = new Vec3(3, 4, 5)

vec.subScalar(2)

// Outputs [1, 2, 3]
console.log('The result of the subtraction is: ' + vec.toString())

toArray()

toArray(arr?: number[] | ArrayBufferView<ArrayBufferLike>, offset?: number): number[] | ArrayBufferView<ArrayBufferLike>

Converts the vector to an array.

const v = new Vec3(20, 10, 5)
// Outputs [20, 10, 5]
console.log(v.toArray())

toString()

toString(): string

Converts the vector to string form.

Returns

string

The vector in string form.

Example

const v = new Vec3(20, 10, 5)
// Outputs [20, 10, 5]
console.log(v.toString())