@inglorious/utils 1.0.0 → 1.2.0

package/src/math/linear-algebra/quaternion.js

@@ -0,0 +1,22 @@
+/**
+ * @typedef {import('../../../types').Vector3} Vector3
+ * @typedef {import('../../../types').Quaternion} Quaternion
+ */
+
+import { cos, sin } from "../trigonometry.js"
+
+const DEFAULT_ANGLE = 0
+const HALF = 2 // Constant representing the divisor for halving an angle.
+// eslint-disable-next-line no-magic-numbers
+const Y_AXIS = [0, 1, 0] // Default axis of rotation (Y-axis).
+
+/**
+ * Computes a quaternion representing a rotation around a given axis.
+ *
+ * @param {number} [angle=0] - The angle of rotation in radians. Defaults to 0.
+ * @param {Vector3} [axis=Y_AXIS] - The axis of rotation as a 3D vector Defaults to the Y-axis.
+ * @returns {Quaternion} The quaternion as an array [w, x, y, z].
+ */
+export function quaternion(angle = DEFAULT_ANGLE, axis = Y_AXIS) {
+  return [cos(angle / HALF), ...axis.map((coord) => coord * sin(angle / HALF))]
+}

package/src/math/linear-algebra/quaternion.test.js

@@ -0,0 +1,25 @@
+import { expect, test } from "vitest"
+
+import { cos, pi, sin } from "../trigonometry.js"
+import { quaternion } from "./quaternion.js"
+
+test("it should return the quaternion for no rotation", () => {
+  const angle = 0
+  const expectedResult = [1, 0, 0, 0]
+
+  expect(quaternion(angle)).toStrictEqual(expectedResult)
+})
+
+test("it should return the quaternion for a rotation of pi/2", () => {
+  const angle = pi() / 2
+  const expectedResult = [cos(pi() / 4), 0, sin(pi() / 4), 0]
+
+  expect(quaternion(angle)).toStrictEqual(expectedResult)
+})
+
+test("it should return the quaternion for a rotation of negative pi/2", () => {
+  const angle = -pi() / 2
+  const expectedResult = [cos(-pi() / 4), -0, sin(-pi() / 4), -0]
+
+  expect(quaternion(angle)).toStrictEqual(expectedResult)
+})

package/src/math/linear-algebra/quaternions.js

@@ -0,0 +1,20 @@
+/**
+ * @typedef {import('./types').Quaternion} Quaternion
+ */
+
+import { times } from "./vector.js"
+import { cross, dot, sum } from "./vectors.js"
+
+/**
+ * Combines two quaternions using the Hamilton product.
+ *
+ * @param {Quaternion} q1 - The first quaternion.
+ * @param {Quaternion} q2 - The second quaternion.
+ * @returns {Quaternion} - The resulting quaternion after combining q1 and q2.
+ */
+export function combine(q1, q2) {
+  const [s, ...v] = q1
+  const [t, ...w] = q2
+
+  return [s * t - dot(v, w), ...sum(times(w, s), times(v, t), cross(v, w))]
+}

package/src/math/linear-algebra/quaternions.test.js

@@ -0,0 +1,29 @@
+import { expect, test } from "vitest"
+
+import { cos, pi, sin } from "../trigonometry.js"
+import { quaternion } from "./quaternion.js"
+import { combine } from "./quaternions.js"
+
+test("it should combine two zero-angle quaternions by giving the same 0-angle quaternion", () => {
+  const q1 = quaternion(0)
+  const q2 = quaternion(0)
+  const expectedResult = [1, 0, 0, 0]
+
+  expect(combine(q1, q2)).toStrictEqual(expectedResult)
+})
+
+test("it should combine a zero-angle quaternion with a nonzero-angle quaternion", () => {
+  const q1 = quaternion(0)
+  const q2 = quaternion(pi() / 2)
+  const expectedResult = [cos(pi() / 4), 0, sin(pi() / 4), 0]
+
+  expect(combine(q1, q2)).toStrictEqual(expectedResult)
+})
+
+test("it should combine two nonzero-angle quaternions", () => {
+  const q1 = quaternion(pi() / 2)
+  const q2 = quaternion(pi() / 2)
+  const expectedResult = [2.220446049250313e-16, 0, 1, 0] // close to [0, 0, 1, 0]
+
+  expect(combine(q1, q2)).toStrictEqual(expectedResult)
+})

package/src/math/linear-algebra/types.d.ts

@@ -0,0 +1,4 @@
+export type Vector2 = [number, number]
+export type Vector3 = [number, number, number]
+export type Quaternion = [number, number, number, number]
+export type Vector7 = [number, number, number, number, number, number, number]

package/src/math/linear-algebra/vector.js

@@ -0,0 +1,337 @@
+/**
+ * @typedef {import('./types').Vector2} Vector2
+ * @typedef {import('./types').Vector3} Vector3
+ */
+
+import { hypothenuse } from "../geometry/triangle.js"
+import {
+  abs as nAbs,
+  clamp as nClamp,
+  mod as nMod,
+  snap as nSnap,
+} from "../numbers.js"
+import { atan2, cos, sin } from "../trigonometry.js"
+import { from2D, to2D } from "./2d.js"
+import { quaternion } from "./quaternion.js"
+import { cross, sum } from "./vectors.js"
+
+const ZERO_VECTOR = [0, 0, 0] // eslint-disable-line no-magic-numbers
+const UNIT_VECTOR = [1, 0, 0] // eslint-disable-line no-magic-numbers
+
+const X = 0
+const Y = 1
+const Z = 2
+const LAST_COORDINATE = 1
+const TWO_COORDINATES = 2
+const NO_Y = 0
+const DEFAULT_PRECISION = 1
+const DEFAULT_DECIMALS = 0
+
+/**
+ * Returns the absolute value of each component in the vector.
+ * @param {Vector3} vector - The input vector.
+ * @returns {Vector3} The vector with absolute values.
+ */
+export function abs(vector) {
+  return vector.map(nAbs)
+}
+
+/**
+ * Calculates the angle of the vector in radians.
+ * @param {Vector3} vector - The input vector.
+ * @returns {number} The angle in radians.
+ */
+export function angle(vector) {
+  return atan2(vector[vector.length - LAST_COORDINATE], vector[X])
+}
+
+/**
+ * Clamps the magnitude of the vector between the given min and max values.
+ * @param {Vector3} vector - The input vector.
+ * @param {number} min - The minimum magnitude.
+ * @param {number} max - The maximum magnitude.
+ * @returns {Vector3} The clamped vector.
+ */
+export function clamp(vector, min, max) {
+  const length = magnitude(vector)
+
+  if (typeof min === "number" && length < min) {
+    return setMagnitude(vector, min)
+  }
+
+  if (typeof max === "number" && length > max) {
+    return setMagnitude(vector, max)
+  }
+
+  if (typeof min !== "number" && typeof max !== "number") {
+    return vector.map((coordinate, index) =>
+      nClamp(coordinate, min[index], max[index]),
+    )
+  }
+
+  return vector
+}
+
+/**
+ * Returns the conjugate of the vector.
+ * @param {Vector3} vector - The input vector.
+ * @returns {Vector3} The conjugated vector.
+ */
+export function conjugate(vector) {
+  return vector.map((coordinate, index) => (index ? -coordinate : coordinate))
+}
+
+/**
+ * Creates a vector with the given magnitude and angle.
+ * @param {number} magnitude - The magnitude of the vector.
+ * @param {number} angle - The angle of the vector in radians.
+ * @returns {Vector3} The created vector.
+ */
+export function createVector(magnitude, angle) {
+  return multiply(fromAngle(angle), magnitude)
+}
+
+/**
+ * Divides each component of the vector by the given scalar.
+ * @param {Vector3} vector - The input vector.
+ * @param {number} scalar - The scalar value.
+ * @returns {Vector3} The resulting vector.
+ */
+export function divide(vector, scalar) {
+  return vector.map((coordinate) => coordinate / scalar)
+}
+
+/**
+ * Creates a unit vector from the given angle.
+ * @param {number} angle - The angle in radians.
+ * @returns {Vector3} The unit vector.
+ */
+export function fromAngle(angle) {
+  return rotate(UNIT_VECTOR, angle)
+}
+
+export const length = magnitude
+
+/**
+ * Calculates the magnitude of the vector.
+ * @param {Vector3} vector - The input vector.
+ * @returns {number} The magnitude of the vector.
+ */
+export function magnitude(vector) {
+  return hypothenuse(...vector)
+}
+
+/**
+ * Calculates the modulus of each component in the vector with the given divisor.
+ * @param {Vector3} vector - The input vector.
+ * @param {number} divisor - The divisor value.
+ * @returns {Vector3} The resulting vector.
+ */
+export function mod(vector, divisor) {
+  return vector.map((coordinate) => nMod(coordinate, divisor))
+}
+
+/**
+ * Multiplies each component of the vector by the given scalar.
+ * @param {Vector3} vector - The input vector.
+ * @param {number} scalar - The scalar value.
+ * @returns {Vector3} The resulting vector.
+ */
+export function multiply(vector, scalar) {
+  return vector.map((coordinate) => coordinate * scalar)
+}
+
+/**
+ * Normalizes the vector to have a magnitude of 1.
+ * @param {Vector3} vector - The input vector.
+ * @returns {Vector3} The normalized vector.
+ */
+export function normalize(vector) {
+  const length = magnitude(vector)
+  return vector.map((coordinate) => coordinate / length)
+}
+
+export const remainder = mod
+
+/**
+ * Rotates the vector by the given angle.
+ * @param {Vector3} vector - The input vector.
+ * @param {number} angle - The angle in radians.
+ * @returns {Vector3} The rotated vector.
+ */
+export function rotate(vector, angle) {
+  const is2D = vector.length === TWO_COORDINATES
+
+  let v = is2D ? from2D(vector) : vector
+
+  let result = rotateWithQuaternion(v, angle)
+
+  return is2D ? to2D(result) : result
+}
+
+/**
+ * Scales the vector by the given scalar. Alias of `multiply`.
+ * @param {Vector3} vector - The input vector.
+ * @param {number} scalar - The scalar value.
+ * @returns {Vector3} The resulting vector.
+ */
+export const scale = multiply
+
+/**
+ * Sets the angle of the vector while maintaining its magnitude.
+ * @param {Vector3} vector - The input vector.
+ * @param {number} angle - The new angle in radians.
+ * @returns {Vector3} The vector with the updated angle.
+ */
+export function setAngle(vector, angle) {
+  const length = magnitude(vector)
+  const [x, z] = toCartesian([length, angle])
+  return [x, NO_Y, z]
+}
+
+/**
+ * Sets the length of the vector while maintaining its direction. Alias of `setMagnitude`.
+ */
+export const setLength = setMagnitude
+
+/**
+ * Sets the magnitude of the vector while maintaining its direction.
+ * @param {Vector3} vector - The input vector.
+ * @param {number} length - The new magnitude.
+ * @returns {Vector3} The vector with the updated magnitude.
+ */
+export function setMagnitude(vector, length) {
+  const normalized = normalize(vector)
+  return multiply(normalized, length)
+}
+
+/**
+ * Shifts the components of the vector by the given index.
+ * @param {Vector3} vector - The input vector.
+ * @param {number} index - The index to shift by.
+ * @returns {Vector3} The shifted vector.
+ */
+export function shift(vector, index) {
+  return [...vector.slice(index), ...vector.slice(X, index)]
+}
+
+/**
+ * Snaps each component of the vector to the nearest multiple of the given precision.
+ * @param {Vector3} vector - The input vector.
+ * @param {number} [precision=DEFAULT_PRECISION] - The precision value.
+ * @returns {Vector3} The snapped vector.
+ */
+export function snap(vector, precision = DEFAULT_PRECISION) {
+  return vector.map((coordinate) => nSnap(coordinate, -precision, precision))
+}
+
+export const times = multiply
+
+/**
+ * Converts polar coordinates to Cartesian coordinates.
+ * @param {Vector2} vector - The polar coordinates [magnitude, angle].
+ * @returns {Vector2} The Cartesian coordinates [x, y].
+ */
+export function toCartesian([magnitude, angle]) {
+  return [magnitude * cos(angle), magnitude * sin(angle)]
+}
+
+/**
+ * Converts a vector to cylindrical coordinates.
+ * @param {Vector2} vector - The input vector.
+ * @returns {Vector2} The cylindrical coordinates [radius, theta, z].
+ */
+export function toCylindrical(vector) {
+  const radius = magnitude(vector)
+  const theta = angle(vector)
+  return [radius * cos(theta), radius * sin(theta), vector[Z]]
+}
+
+/**
+ * Converts a vector to polar coordinates.
+ * @param {Vector2} vector - The input vector.
+ * @returns {Vector2} The polar coordinates [magnitude, angle].
+ */
+export function toPolar(vector) {
+  return [magnitude(vector), angle(vector)]
+}
+
+/**
+ * Converts a vector to a string representation.
+ * @param {Vector3} vector - The input vector.
+ * @param {number} [decimals=DEFAULT_DECIMALS] - The number of decimal places.
+ * @returns {string} The string representation of the vector.
+ */
+export function toString(vector, decimals = DEFAULT_DECIMALS) {
+  return `[${vector
+    .map((coordinate) => coordinate.toFixed(decimals))
+    .join(", ")}]`
+}
+
+// TODO: add toSpherical(vector),
+
+/**
+ * Converts a 3D cartesian vector to spherical coordinates [radius, inclination, azimuth].
+ * - radius (r): distance from the origin.
+ * - inclination (θ): angle from the Y-axis (0 to PI).
+ * - azimuth (φ): angle from the X-axis in the XZ-plane (-PI to PI).
+ *
+ * @param {Vector3} vector The cartesian vector [x, y, z].
+ * @returns {Vector3} The spherical coordinates [r, θ, φ].
+ */
+export function toSpherical(vector) {
+  const r = magnitude(vector)
+
+  if (!r) {
+    return zero()
+  }
+
+  // In a Y-up system, inclination is the angle with the Y axis.
+  const inclination = Math.acos(vector[Y] / r)
+  // Azimuth is the angle in the XZ plane, which `angle()` calculates.
+  const azimuth = angle(vector)
+
+  return [r, inclination, azimuth]
+}
+
+/**
+ * Creates a unit vector with the given angle.
+ * @param {number} angle - The angle in radians.
+ * @returns {Vector3} The unit vector.
+ */
+export function unit(angle) {
+  if (!angle) {
+    return [...UNIT_VECTOR]
+  }
+
+  return setAngle(UNIT_VECTOR, angle)
+}
+
+/**
+ * Creates a zero vector.
+ * @returns {Vector3} The zero vector.
+ */
+export function zero() {
+  return [...ZERO_VECTOR]
+}
+
+/**
+ * Rotates the vector using a quaternion.
+ * @param {Vector3} vector - The input vector.
+ * @param {number} angle - The angle in radians.
+ * @returns {Vector3} The rotated vector.
+ */
+function rotateWithQuaternion(vector, angle) {
+  if (!angle) {
+    return vector
+  }
+
+  // @see https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation#Performance_comparisons
+  const [w, ...r] = quaternion(angle)
+  const result = sum(
+    vector,
+    cross(multiply(r, 2), sum(cross(r, vector), multiply(vector, w))), // eslint-disable-line no-magic-numbers
+  )
+
+  return conjugate(result) // HACK: not really sure why I should invert the result, it just works this way
+}

package/src/math/linear-algebra/vector.test.js

@@ -0,0 +1,265 @@
+import { expect, test } from "vitest"
+
+import { sqrt } from "../numbers.js"
+import { cos, pi, sin } from "../trigonometry.js"
+import {
+  abs,
+  angle,
+  clamp,
+  conjugate,
+  createVector,
+  divide,
+  fromAngle,
+  magnitude,
+  mod,
+  multiply,
+  normalize,
+  rotate,
+  setAngle,
+  setMagnitude,
+  shift,
+  snap,
+  toCartesian,
+  toCylindrical,
+  toPolar,
+  toSpherical,
+  toString,
+  unit,
+} from "./vector.js"
+
+test("it should compute the absolute value of a vector's coordinates", () => {
+  const vector = [-2, 0, 3]
+  const expectedResult = [2, 0, 3]
+
+  expect(abs(vector)).toStrictEqual(expectedResult)
+})
+
+test("it should compute the angle of a 2D vector", () => {
+  const vector = [1, 1]
+  const expectedResult = pi() / 4
+
+  expect(angle(vector)).toBe(expectedResult)
+})
+
+test("it should compute the angle of a 3D vector", () => {
+  const vector = [1, 0, 1]
+  const expectedResult = pi() / 4
+
+  expect(angle(vector)).toBe(expectedResult)
+})
+
+test("it should clamp the magnitude of a vector to a certain length if too long", () => {
+  const vector = [6, 8]
+  const min = 0
+  const max = 5
+  const expectedResult = [3, 4]
+
+  expect(clamp(vector, min, max)).toStrictEqual(expectedResult)
+})
+
+test("it should not clamp the magnitude of a vector to a certain length if not too long", () => {
+  const vector = [3, 4]
+  const min = 0
+  const max = 6
+  const expectedResult = [3, 4]
+
+  expect(clamp(vector, min, max)).toStrictEqual(expectedResult)
+})
+
+test("it should clamp the magnitude of a vector to the values of other vector bounds", () => {
+  const vector = [6, 8]
+  const lowerBound = [0, 0]
+  const upperBound = [3, 4]
+  const expectedResult = [3, 4]
+
+  expect(clamp(vector, lowerBound, upperBound)).toStrictEqual(expectedResult)
+})
+
+test("it should conjugate a vector", () => {
+  const vector = [1, 2, 3]
+  const expectedResult = [1, -2, -3]
+
+  expect(conjugate(vector)).toStrictEqual(expectedResult)
+})
+
+test("it should create a 3D vector given its magnitude and angle", () => {
+  const magnitude = sqrt(2)
+  const angle = pi() / 4
+  const expectedResult = [1, -0, 1.0000000000000002] // close to [1, 0, 1]
+
+  expect(createVector(magnitude, angle)).toStrictEqual(expectedResult)
+})
+
+test("it should divide a vector by a scalar", () => {
+  const vector = [4, 8, 12]
+  const scalar = 4
+  const expectedResult = [1, 2, 3]
+
+  expect(divide(vector, scalar)).toStrictEqual(expectedResult)
+})
+
+test("it should create a 3D unit vector from an angle", () => {
+  const angle = pi() / 4
+  const expectedResult = [0.7071067811865475, -0, 0.7071067811865476] // close to [cos(angle), 0, sin(angle)]
+
+  expect(fromAngle(angle)).toStrictEqual(expectedResult)
+})
+
+test("it should compute the magnitude of a vector (aka length)", () => {
+  const vector = [3, 4]
+  const expectedResult = 5
+
+  expect(magnitude(vector)).toBe(expectedResult)
+})
+
+test("it should apply the mod operator (aka remainder) on a vector", () => {
+  const vector = [10, 12, -18]
+  const divisor = 12
+  const expectedResult = [10, 0, 6]
+
+  expect(mod(vector, divisor)).toStrictEqual(expectedResult)
+})
+
+test("it should multiply a vector with a scalar (aka times)", () => {
+  const vector = [1, 2, 3]
+  const scalar = 4
+  const expectedResult = [4, 8, 12]
+
+  expect(multiply(vector, scalar)).toStrictEqual(expectedResult)
+})
+
+test("it should normalize a vector so it has unit length", () => {
+  const vector = [3, 4]
+  const expectedResult = [0.6, 0.8]
+
+  expect(normalize(vector)).toStrictEqual(expectedResult)
+})
+
+test("it should normalize a negative vector", () => {
+  const vector = [-3, -4]
+  const expectedResult = [-0.6, -0.8]
+
+  expect(normalize(vector)).toStrictEqual(expectedResult)
+})
+
+test("it should rotate a 2D vector by a certain angle", () => {
+  const vector = [1, 0]
+  const angle = pi() / 4
+  const expectedResult = [0.7071067811865475, 0.7071067811865476] // close to [cos(pi/4), sin(pi/4)]
+
+  expect(rotate(vector, angle)).toStrictEqual(expectedResult)
+})
+
+test("it should not rotate a vector when the angle is zero", () => {
+  const vector = [1, 0, 0]
+  const angle = 0
+  const expectedResult = [1, 0, 0]
+
+  expect(rotate(vector, angle)).toStrictEqual(expectedResult)
+})
+
+test("it should rotate a vector by a certain angle", () => {
+  const vector = [1, 0, 0]
+  const angle = pi() / 4
+  const expectedResult = [0.7071067811865475, -0, 0.7071067811865476] // close to [cos(pi/4), 0, sin(pi/4)]
+
+  expect(rotate(vector, angle)).toStrictEqual(expectedResult)
+})
+
+test("it should rotate a vector that faces left by a certain angle", () => {
+  const vector = [-1, 0, 0]
+  const angle = pi() / 4
+  const expectedResult = [-0.7071067811865475, -0, -0.7071067811865476] // close to [cos(-3/4pi), 0, sin(-3/4pi)]
+
+  expect(rotate(vector, angle)).toStrictEqual(expectedResult)
+})
+
+test("it should change the angle of a vector", () => {
+  const vector = [cos(pi() / 4), 0, sin(pi() / 4)]
+  const expectedResult = [6.123233995736766e-17, 0, 1] // close to [0, 0, 1]
+
+  expect(setAngle(vector, 1.5707963267948966)).toStrictEqual(expectedResult)
+})
+
+test("it should change magnitude of a vector (aka setLength)", () => {
+  const vector = [3, 4]
+  const magnitude = 10
+  const expectedResult = [6, 8]
+
+  expect(setMagnitude(vector, magnitude)).toStrictEqual(expectedResult)
+})
+
+test("it should change magnitude of a negative vector", () => {
+  const vector = [-3, -4]
+  const magnitude = 10
+  const expectedResult = [-6, -8]
+
+  expect(setMagnitude(vector, magnitude)).toStrictEqual(expectedResult)
+})
+
+test("it should shift a vector at a certain index", () => {
+  const vector = [1, 2, 3, 4, 5]
+  const index = 2
+  const expectedResult = [3, 4, 5, 1, 2]
+
+  expect(shift(vector, index)).toStrictEqual(expectedResult)
+})
+
+test("it should snap a floating vector to a certain precision", () => {
+  const vector = [1, 1.5, 1.7]
+  const precision = 1
+  const expectedResult = [1, 1, 2]
+
+  expect(snap(vector, precision)).toStrictEqual(expectedResult)
+})
+
+test("it should convert a 2D polar vector to cartesian coordinates", () => {
+  const vector = [sqrt(2), pi() / 4]
+  const expectedResult = [1.0000000000000002, 1]
+
+  expect(toCartesian(vector)).toStrictEqual(expectedResult)
+})
+
+test("it should convert a 3D cartesian vector to cylindrical coordinates", () => {
+  const vector = [1, 1, 1]
+  const expectedResult = [1.2247448713915892, 1.224744871391589, 1]
+
+  expect(toCylindrical(vector)).toStrictEqual(expectedResult)
+})
+
+test("it should convert a 2D cartesian vector to polar coordinates", () => {
+  const vector = [1, 1]
+  const expectedResult = [sqrt(2), pi() / 4]
+
+  expect(toPolar(vector)).toStrictEqual(expectedResult)
+})
+
+test("it should convert a 3D cartesian vector to spherical coordinates", () => {
+  const vector = [1, 1, 1]
+  const expectedResult = [sqrt(3), Math.acos(1 / sqrt(3)), pi() / 4]
+
+  expect(toSpherical(vector)).toStrictEqual(expectedResult)
+})
+
+test("it should create a string representation of an integer vector", () => {
+  const vector = [3, 4]
+  const expectedResult = "[3, 4]"
+
+  expect(toString(vector)).toBe(expectedResult)
+})
+
+test("it should create a string representation of a float vector", () => {
+  const vector = [pi() / 4, pi() / 4]
+  const decimals = 2
+  const expectedResult = "[0.79, 0.79]"
+
+  expect(toString(vector, decimals)).toBe(expectedResult)
+})
+
+test("it should create a unit vector oriented on the X-axis", () => {
+  expect(unit()).toStrictEqual([1, 0, 0])
+})
+
+test("it should create a unit vector oriented on the Z-axis", () => {
+  expect(unit(pi() / 2)).toStrictEqual([6.123233995736766e-17, 0, 1]) // close to [0, 0, 1]
+})