Vector3¶

Overview¶

Basic 3-dimensional vector, represented as (x,y,z).

@author Jonathan Olson <jonathan.olson@colorado.edu>

Class Vector3¶

import { Vector3 } from 'scenerystack/dot';

Constructor¶

new Vector3( x : number, y : number, z : number )¶

Instance Methods¶

getMagnitude() : number¶

The magnitude (Euclidean/L2 Norm) of this vector, i.e. \(\sqrt{x^2+y^2+z^2}\).

getMagnitudeSquared() : number¶

T squared magnitude (square of the Euclidean/L2 Norm) of this vector, i.e. \(x^2+y^2+z^2\).

distance( point : Vector3 ) : number¶

The Euclidean distance between this vector (treated as a point) and another point.

distanceXYZ( x : number, y : number, z : number ) : number¶

The Euclidean distance between this vector (treated as a point) and another point (x,y,z).

distanceSquared( point : Vector3 ) : number¶

The squared Euclidean distance between this vector (treated as a point) and another point.

distanceSquaredXYZ( x : number, y : number, z : number ) : number¶

The squared Euclidean distance between this vector (treated as a point) and another point (x,y,z).

dot( v : Vector3 ) : number¶

The dot-product (Euclidean inner product) between this vector and another vector v.

dotXYZ( x : number, y : number, z : number ) : number¶

The dot-product (Euclidean inner product) between this vector and another vector (x,y,z).

angleBetween( v : Vector3 ) : number¶

The angle between this vector and another vector, in the range \(\theta\in[0, \pi]\).

Equal to \(\theta = \cos^{-1}( \hat{u} \cdot \hat{v} )\) where \(\hat{u}\) is this vector (normalized) and \(\hat{v}\) is the input vector (normalized).

equals( other : Vector3 ) : boolean¶

Exact equality comparison between this vector and another vector.

@returns - Whether the two vectors have equal components

equalsEpsilon( other : Vector3, epsilon : number ) : boolean¶

Approximate equality comparison between this vector and another vector.

@returns - Whether difference between the two vectors has no component with an absolute value greater than epsilon.

isFinite() : boolean¶

Returns false if any component is NaN, infinity, or -infinity. Otherwise returns true.

copy( vector? : Vector3 ) : Vector3¶

Creates a copy of this vector, or if a vector is passed in, set that vector's values to ours.

This is the immutable form of the function set(), if a vector is provided. This will return a new vector, and will not modify this vector.

@param [vector] - If not provided, creates a new Vector3 with filled in values. Otherwise, fills in the values of the provided vector so that it equals this vector.

cross( v : Vector3 ) : Vector3¶

The Euclidean 3-dimensional cross-product of this vector by the passed-in vector.

normalized() : Vector3¶

Normalized (re-scaled) copy of this vector such that its magnitude is 1. If its initial magnitude is zero, an error is thrown.

This is the immutable form of the function normalize(). This will return a new vector, and will not modify this vector.

roundedSymmetric() : Vector3¶

This is the immutable form of the function roundSymmetric(). This will return a new vector, and will not modify this vector.

withMagnitude( magnitude : number ) : Vector3¶

Re-scaled copy of this vector such that it has the desired magnitude. If its initial magnitude is zero, an error is thrown. If the passed-in magnitude is negative, the direction of the resulting vector will be reversed.

This is the immutable form of the function setMagnitude(). This will return a new vector, and will not modify this vector.

timesScalar( scalar : number ) : Vector3¶

Copy of this vector, scaled by the desired scalar value.

This is the immutable form of the function multiplyScalar(). This will return a new vector, and will not modify this vector.

times( scalar : number ) : Vector3¶

Same as timesScalar.

This is the immutable form of the function multiply(). This will return a new vector, and will not modify this vector.

componentTimes( v : Vector3 ) : Vector3¶

Copy of this vector, multiplied component-wise by the passed-in vector v.

This is the immutable form of the function componentMultiply(). This will return a new vector, and will not modify this vector.

plus( v : Vector3 ) : Vector3¶

Addition of this vector and another vector, returning a copy.

This is the immutable form of the function add(). This will return a new vector, and will not modify this vector.

plusXYZ( x : number, y : number, z : number ) : Vector3¶

Addition of this vector and another vector (x,y,z), returning a copy.

This is the immutable form of the function addXYZ(). This will return a new vector, and will not modify this vector.

plusScalar( scalar : number ) : Vector3¶

Addition of this vector with a scalar (adds the scalar to every component), returning a copy.

This is the immutable form of the function addScalar(). This will return a new vector, and will not modify this vector.

minus( v : Vector3 ) : Vector3¶

Subtraction of this vector by another vector v, returning a copy.

This is the immutable form of the function subtract(). This will return a new vector, and will not modify this vector.

minusXYZ( x : number, y : number, z : number ) : Vector3¶

Subtraction of this vector by another vector (x,y,z), returning a copy.

This is the immutable form of the function subtractXYZ(). This will return a new vector, and will not modify this vector.

minusScalar( scalar : number ) : Vector3¶

Subtraction of this vector by a scalar (subtracts the scalar from every component), returning a copy.

This is the immutable form of the function subtractScalar(). This will return a new vector, and will not modify this vector.

dividedScalar( scalar : number ) : Vector3¶

Division of this vector by a scalar (divides every component by the scalar), returning a copy.

This is the immutable form of the function divideScalar(). This will return a new vector, and will not modify this vector.

negated() : Vector3¶

Negated copy of this vector (multiplies every component by -1).

This is the immutable form of the function negate(). This will return a new vector, and will not modify this vector.

blend( vector : Vector3, ratio : number ) : Vector3¶

A linear interpolation between this vector (ratio=0) and another vector (ratio=1).

@param vector @param ratio - Not necessarily constrained in [0, 1]

average( vector : Vector3 ) : Vector3¶

The average (midpoint) between this vector and another vector.

toString() : string¶

Debugging string for the vector.

toVector2() : Vector2¶

Converts this to a 2-dimensional vector, discarding the z-component.

toVector4() : Vector4¶

Converts this to a 4-dimensional vector, with the w-component equal to 1 (useful for homogeneous coordinates).

toVector4Zero() : Vector4¶

Converts this to a 4-dimensional vector, with the w-component equal to 0

setXYZ( x : number, y : number, z : number ) : Vector3¶

Sets all of the components of this vector, returning this.

setX( x : number ) : Vector3¶

Sets the x-component of this vector, returning this.

setY( y : number ) : Vector3¶

Sets the y-component of this vector, returning this.

setZ( z : number ) : Vector3¶

Sets the z-component of this vector, returning this.

set( v : Vector3 ) : Vector3¶

Sets this vector to be a copy of another vector.

This is the mutable form of the function copy(). This will mutate (change) this vector, in addition to returning this vector itself.

setMagnitude( magnitude : number ) : Vector3¶

Sets the magnitude of this vector. If the passed-in magnitude is negative, this flips the vector and sets its magnitude to abs( magnitude ).

This is the mutable form of the function withMagnitude(). This will mutate (change) this vector, in addition to returning this vector itself.

add( v : Vector3 ) : Vector3¶

Adds another vector to this vector, changing this vector.

This is the mutable form of the function plus(). This will mutate (change) this vector, in addition to returning this vector itself.

addXYZ( x : number, y : number, z : number ) : Vector3¶

Adds another vector (x,y,z) to this vector, changing this vector.

This is the mutable form of the function plusXYZ(). This will mutate (change) this vector, in addition to returning this vector itself.

addScalar( scalar : number ) : Vector3¶

Adds a scalar to this vector (added to every component), changing this vector.

This is the mutable form of the function plusScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

subtract( v : Vector3 ) : Vector3¶

Subtracts this vector by another vector, changing this vector.

This is the mutable form of the function minus(). This will mutate (change) this vector, in addition to returning this vector itself.

subtractXYZ( x : number, y : number, z : number ) : Vector3¶

Subtracts this vector by another vector (x,y,z), changing this vector.

This is the mutable form of the function minusXYZ(). This will mutate (change) this vector, in addition to returning this vector itself.

subtractScalar( scalar : number ) : Vector3¶

Subtracts this vector by a scalar (subtracts each component by the scalar), changing this vector.

This is the mutable form of the function minusScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

multiplyScalar( scalar : number ) : Vector3¶

Multiplies this vector by a scalar (multiplies each component by the scalar), changing this vector.

This is the mutable form of the function timesScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

multiply( scalar : number ) : Vector3¶

Multiplies this vector by a scalar (multiplies each component by the scalar), changing this vector. Same as multiplyScalar.

This is the mutable form of the function times(). This will mutate (change) this vector, in addition to returning this vector itself.

componentMultiply( v : Vector3 ) : Vector3¶

Multiplies this vector by another vector component-wise, changing this vector.

This is the mutable form of the function componentTimes(). This will mutate (change) this vector, in addition to returning this vector itself.

divideScalar( scalar : number ) : Vector3¶

Divides this vector by a scalar (divides each component by the scalar), changing this vector.

This is the mutable form of the function dividedScalar(). This will mutate (change) this vector, in addition to returning this vector itself.

negate() : Vector3¶

Negates this vector (multiplies each component by -1), changing this vector.

This is the mutable form of the function negated(). This will mutate (change) this vector, in addition to returning this vector itself.

setCross( v : Vector3 ) : Vector3¶

Sets our value to the Euclidean 3-dimensional cross-product of this vector by the passed-in vector.

normalize() : Vector3¶

Normalizes this vector (rescales to where the magnitude is 1), changing this vector.

This is the mutable form of the function normalized(). This will mutate (change) this vector, in addition to returning this vector itself.

roundSymmetric() : Vector3¶

Rounds each component of this vector with Utils.roundSymmetric.

This is the mutable form of the function roundedSymmetric(). This will mutate (change) this vector, in addition to returning the vector itself.

toStateObject() : Vector3StateObject¶

Returns a duck-typed object meant for use with tandem/phet-io serialization.

freeToPool()¶

Instance Properties¶

x : number¶

The X coordinate of the vector.

y : number¶

The Y coordinate of the vector.

z : number¶

The Z coordinate of the vector.

isVector3 : boolean¶

dimension : number¶

Static Methods¶

average( vectors : Vector3[] ) : Vector3¶

Take a component-based mean of all vectors provided.

slerp( start : Vector3, end : Vector3, ratio : number ) : Vector3¶

Spherical linear interpolation between two unit vectors.

@param start - Start unit vector @param end - End unit vector @param ratio - Between 0 (at start vector) and 1 (at end vector) @returns Spherical linear interpolation between the start and end

fromStateObject( stateObject : Vector3StateObject ) : Vector3¶

Constructs a Vector3 from a duck-typed object, for use with tandem/phet-io deserialization.

Static Properties¶

pool : Pool¶

(readonly)

ZERO : Vector3¶

X_UNIT : Vector3¶

Y_UNIT : Vector3¶

Z_UNIT : Vector3¶

Vector3IO : IOType¶

Type Vector3StateObject¶

import type { Vector3StateObject } from 'scenerystack/dot';

• x: number
• y: number
• z: number

Source Code¶

See the source for Vector3.ts in the dot repository.