vextreme v1.4.3

Vextreme

Type-safe functions for 3-dimensional vectors.

Get Started

npm install vextreme

Use the types and functions in your source code

import { type Vec3, add } from 'vextreme';

const a: Vec3 = [0, 1, 2];
const b: Vec3 = [3, 4, 5];
const c = add(a, b);

API

Table of Contents

• Vec2
• Vec3
• add
  • Parameters
  • Examples
• angle
  • Parameters
  • Examples
• createScale
  • Parameters
  • Examples
• cross
  • Parameters
  • Examples
• diff
  • Parameters
  • Examples
• dot
  • Parameters
  • Examples
• equal
  • Parameters
  • Examples
• mag
  • Parameters
  • Examples
• midpoint
  • Parameters
  • Examples
• multiply
  • Parameters
  • Examples
• negate
  • Examples
• normalize
  • Parameters
  • Examples
• rotateLeft
  • Parameters
  • Examples
• rotateRight
  • Parameters
  • Examples
• toVec2
  • Parameters
  • Examples

Vec2

Represents a two-dimensional vector.

Type: [number, number]

Vec3

Represents a three-dimensional vector.

Type: [...Vec2, number]

add

Component-wise addition of a and b.

Parameters

• a Vec3
• b Vec3

Examples

add([0, 1, 2], [5, 4, 3]) // [5, 5, 5]

Returns Vec3

angle

Calculates the angle in radians between a and b.

Note that the angle between any vector and the zero vector is NaN because the zero vector does not have a magnitude.

Parameters

• a Vec3
• b Vec3

Examples

angle([0, 1, 2], [0, 1, 2]) // 0
angle([1, 0, 0], [0, 1, 0]) // 1.57...
angle([0, 0, 0], [1, 0, 0]) // NaN

Returns number

createScale

Returns a function that takes v and scales it by s.

You can think of negation as a scaling of -1.

Parameters

• s number

Examples

createScale(2)([0, 1, 2]); // [0, 2, 4]

const negate = createScale(-1);
negate([0, 1, 2]); // [0, -1, -2]

cross

Calculates the cross product of a and b.

Parameters

• a Vec3
• b Vec3

Examples

cross([0, 1, 2], [3, 4, 5]); // [-3, 6, -3]
cross([0, 0, 0], [0, 1, 2]); // [0, 0, 0]
cross([1, 0, 0], [0, 1, 0]); // [0, 0, 1]

Returns Vec3

diff

Component-wise subtraction between a and b.

Note that diff(a, b) and diff(b, a) are not the same.

Parameters

• a Vec3
• b Vec3

Examples

diff([0, 1, 2], [0, 0, -1]); // [0, 1, 3]
diff([0, 0, -1], [0, 1, 2]); // [0, -1, -3]
diff([0, 1, 2], [0, 1, 2]); // [0, 0, 0]

Returns Vec3

dot

Returns the dot product of a and b.

Parameters

• a Vec3
• b Vec3

Examples

dot([1, 0, 0], [0, 1, 0]); // 0
dot([0, 0, 0], [1, 0, 0]); // 0
dot([1, 0, 0], [2, 0, 0]); // 2

Returns number

equal

Returns whether a and b are equal on a component-wise level.

In other words, a[i] === b[i] for i in the range 0 <= i < a.length.

Parameters

• a Vec3
• b Vec3

Examples

const a: Vec3 = [0, 1, 2];
const b: Vec3 = [0, 1, 2];
a === b; // false
equal(a, b); // true

Returns boolean

mag

Returns the magnitude of v.

Parameters

• v Vec3

Examples

mag([1, 0, 0]); // 1
mag([0, 1, 2]); // 2.23606797749979

Returns number

midpoint

Calculates the midpoint as a Vec3 of the addition of a and b.

It may help to think of a and b as offsets from the origin. First you move along a then move along b to get to the point p. If v is a vector from the origin to p, midpoint(a, b) is a scaling of v by 1 / 2;

Parameters

• a Vec3
• b Vec3

Examples

midpoint([1, 0, 0], [0, 1, 0]); // [0.5, 0.5, 0]

Returns Vec3

multiply

Component-wise multiplication of a and b.

You can think of multiply as a scaling of a by the vector b where b[0] is a scaling in the x-dimension, b[1] in the y-dimension, and b[2] in the z-dimension.

If you only want to scale in one or two dimensions, you can use the identity for multiplication, a * 1 = a.

Parameters

• a Vec3
• b Vec3

Examples

multiply([0, 1, 2], [3, 4, 5]); // [0, 4, 10]
multiply([0, 1, 2], [1, 1, 5]); // [0, 1, 10]
multiply([0, 1, 2], [0, 0, 0]); // [0, 0, 0]

Returns Vec3

negate

Negates each component of v.

Examples

negate([0, 0, 0]); // [0, 0, 0]
negate([0, 1, 2]); // [0, -1, -2]

normalize

Normalizes v.

Parameters

• v Vec3

Examples

normalize([0, 1, 2]); // [0, 0.4472135954999579, 0.8944271909999159]
normalize([1, 0, 0]); // [1, 0, 0]

Returns Vec3

rotateLeft

Rotates v by shifting every component one position to the left. Shifting the leftmost component moves it to the end.

Parameters

• v Vec3

Examples

rotateLeft([0, 1, 2]); // [1, 2, 0]

Returns Vec3

rotateRight

Rotates v by shifting every component one position to the right. Shifting the rightmost component moves it to the start.

Parameters

• v Vec3

Examples

rotateRight([0, 1, 2]); // [2, 0, 1]

Returns Vec3

toVec2

Returns a Vec2 which is just v without its z-component.

Useful for generating points in an SVG path or anytime you want to cast a Vec3 to a 2D space.

Parameters

• v Vec3

Examples

toVec2([0, 1, 2]) // [0, 1]

Returns Vec2