Three.js Vector3 Guide and Common Math Operations

This article explores the Vector3 class in Three.js, explaining its role as a fundamental building block for representing 3D points and directions. We will examine what a Vector3 object is and detail the common, native mathematical operations you can perform with it—including addition, multiplication, normalization, dot products, and cross products—to manipulate 3D coordinates efficiently in your web graphics applications.

What is a Vector3 Object?

In Three.js, a Vector3 is a class that represents a 3D vector. It holds three numeric properties: x, y, and z. This object serves two primary purposes in a 3D scene:

1. Position: Representing a specific point in 3D space (e.g., the location of a mesh, light, or camera).
2. Direction: Representing a direction and a magnitude (length), such as the velocity of a moving object or the direction a light is shining.

By default, instantiating a new Vector3 without arguments initializes its coordinates to (0, 0, 0):

const position = new THREE.Vector3(1, 2, 3);

Native Mathematical Operations in Three.js

The Vector3 class includes a robust set of built-in methods to perform mathematical operations without requiring manual coordinate calculations.

1. Addition and Subtraction

You can add or subtract vectors directly. This is commonly used for moving objects or calculating offsets.

• .add(v): Adds vector v to the current vector.
• .addVectors(a, b): Sets the current vector to the sum of vector a and vector b.
• .sub(v): Subtracts vector v from the current vector.
• .subVectors(a, b): Sets the current vector to a - b.

const vecA = new THREE.Vector3(1, 2, 3);
const vecB = new THREE.Vector3(4, 5, 6);

vecA.add(vecB); // vecA becomes (5, 7, 9)

2. Scaling (Scalar Multiplication and Division)

Scaling multiplies or divides all three components (\(x, y, z\)) by a single number (a scalar). This changes the vector’s length without changing its direction.

• .multiplyScalar(s): Multiplies the vector by the number s.
• .divideScalar(s): Divides the vector by the number s.

const velocity = new THREE.Vector3(1, 2, 3);
velocity.multiplyScalar(2); // velocity becomes (2, 4, 6)

3. Normalization

Normalization scales a vector so that its total length (magnitude) becomes exactly 1, turning it into a “unit vector.” Unit vectors are crucial for representing pure directions.

• .normalize(): Rescales the vector to length 1.

const direction = new THREE.Vector3(3, 0, 0);
direction.normalize(); // direction becomes (1, 0, 0)

4. Length and Distance

Three.js provides native methods to calculate spatial distances and vector magnitudes.

• .length(): Calculates the Euclidean length (magnitude) of the vector from \((0,0,0)\).
• .distanceTo(v): Calculates the straight-line distance between the current vector and vector v.

const pointA = new THREE.Vector3(0, 0, 0);
const pointB = new THREE.Vector3(0, 3, 0);

const distance = pointA.distanceTo(pointB); // Returns 3

5. Dot Product

The dot product multiplies two vectors to return a single scalar number. It is used to determine the angle between two vectors or to project one vector onto another. If the dot product is 0, the vectors are perpendicular.

• .dot(v): Returns the dot product of the current vector and vector v.

const vec1 = new THREE.Vector3(1, 0, 0);
const vec2 = new THREE.Vector3(0, 1, 0);

const dotProduct = vec1.dot(vec2); // Returns 0 (perpendicular)

6. Cross Product

The cross product of two vectors returns a third vector that is perpendicular to both of the original vectors. This is highly useful for calculating surface normals or creating perpendicular camera angles.

• .cross(v): Sets the current vector to the cross product of itself and v.
• .crossVectors(a, b): Sets the current vector to the cross product of a and b.

const axisX = new THREE.Vector3(1, 0, 0);
const axisY = new THREE.Vector3(0, 1, 0);
const axisZ = new THREE.Vector3();

axisZ.crossVectors(axisX, axisY); // axisZ becomes (0, 0, 1)

7. Linear Interpolation (Lerp)

Interpolation smoothly transitions a vector toward another target vector. This is widely used for smooth animations, camera movement, and physics damping.

• .lerp(v, alpha): Linearly interpolates the current vector toward vector v, where alpha is the percent of the distance (expressed as a fraction between 0 and 1).

const currentPosition = new THREE.Vector3(0, 0, 0);
const targetPosition = new THREE.Vector3(10, 10, 10);

// Move 10% of the way toward the target
currentPosition.lerp(targetPosition, 0.1); // currentPosition becomes (1, 1, 1)