Flocc

Agent-based modeling in JavaScript in the browser or on the server. [v0.4.8]

Vector

Overview

A vector is a container for multi-dimensional numerical data. For example, an agent’s direction (velocity) or acceleration in 2 or 3 dimensions can be stored as a vector. This can make the process of modeling change over time easier and more dynamic.

A new vector can be instantiated like this:

const vec1 = new Vector();

// vectors can be created with or without coordinate values
const vec2 = new Vector(0, 1);

// vectors can be created in many-dimensional spaces
const vec3 = new Vector(1.5, 2, -3.1, 1, 0, 0, 5);

Properties

.x, .y, .z, .w
.r, .g, .b, .a

The above two rows correspond to the zero-based indices 0, 1, 2, and 3 of a given vector. The top row of properties is (generally) used for spatial vectors, while the bottom row is (generally) used for color spaces.

const coord = new Vector(3, 4, 5);
coord.x; // 3
coord.y; // 4
coord.z; // 5

const red = new Vector(255, 0, 0);
red.r; // 255
red.g; // 0
red.b; // 0

.xy, .xz, .yz, .xyz
.rgb, .rgba

These values return arrays of length 2 to 4 corresponding to the indices that are suggested by the letters used.

coord.xy; // [3, 4]
coord.xyz; // [3, 4, 5]

red.rgb; // [255, 0, 0]

Methods

.index(n)

Get the value of the vector at (zero-based) index n. If n is greater than the vector’s dimension, this will default to zero.

const a = new Vector(3, 5);
a.index(0); // 3
a.index(1); // 5
a.index(2); // 0

.set(n, value) or .set(key, value)

Set the value at a given index of this vector. If the first parameter is a number, used the zero-based index. If the first parameter is one of x, y, z, w, r, g, b, or a, uses the index of the property as indicated above.

const b = new Vector();
b.set(0, 5);
b.x === 5; // true
b.set('y', 2);
b.index(1) === 2; // true

.add(vec)

Adds the values of vec to the each of current vector’s values, index by index. If the vectors have different dimensions (number of indices), uses the dimension of the larger vector, filling in missing indices of the smaller with zero.

const c = new Vector(10, 2);
const d = new Vector( 2, 5, 7);
c.add(d);
// now c has values 12, 7, 7

.dot(vec)

Compute the dot value of this vector with another. If the vectors have different dimensions (number of indices), it fills in missing indices of the smaller with zero.

const a = new Vector(1, 3, -5);
const b = new Vector(4, -2, -1);
a.dot(b); // returns 3

.multiplyScalar(n)

Multiply each of the values of the current vector by n.

const e = new Vector(1, 3, 5);
e.multiplyScalar(4);
// now e has values 4, 12, 20

.addScalar(n)

Add n to each of the values of the current vector.

const f = new Vector(7, 6);
f.addScalar(10);
// now f has values 17, 16

.length()

Finds the Euclidean length of this vector (the distance from the vector to the origin).

.normalize()

Turn the current vector into a unit vector (length = 1). Has no effect on zero-length vectors.

.clone()

Return a new vector with the same values as the current one.

.rotateZ(angle)

Rotate the vector about the z-axis by angle radians. For two-dimensional vectors, this method rotates them about the origin (in three dimensions, it does the same thing, simply leaving the vector’s z value unchanged).

.lerp(vec, t)

Linearly interpolate between this vector and another. This function returns a new vector whose dimensional values are linear interpolations between the dimensional values of both vectors by t.

const a = new Vector(1, 3, -5);
const b = new Vector(4, -2);
const c = a.lerp(b, 0.5);
c.xyz; // returns [2.5, 0.5, -2.5]