@inglorious/engine 0.2.0 → 0.4.0

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

@@ -1,327 +0,0 @@
-/**
- * @typedef {import('./types').Vector2} Vector2
- * @typedef {import('./types').Vector3} Vector3
- */
-
-import { hypothenuse } from "@inglorious/utils/math/geometry/triangle.js"
-import {
-  abs as nAbs,
-  clamp as nClamp,
-  mod as nMod,
-  snap as nSnap,
-} from "@inglorious/utils/math/numbers.js"
-import { atan2, cos, sin } from "@inglorious/utils/math/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
-}
-
-/**
- * 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]
-}
-
-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/utils/math/linear-algebra/vector.test.js

@@ -1,265 +0,0 @@
-import { sqrt } from "@inglorious/utils/math/numbers.js"
-import { cos, pi, sin } from "@inglorious/utils/math/trigonometry.js"
-import { expect, test } from "vitest"
-
-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]
-})

package/src/utils/math/linear-algebra/vectors.js

@@ -1,122 +0,0 @@
-/**
- * @typedef {import('./types').Vector2} Vector2
- * @typedef {import('./types').Vector3} Vector3
- * @typedef {import('./types').Vector7} Vector7
- */
-
-import { magnitude, shift } from "./vector.js"
-
-/**
- * Alias for the sum function.
- * @type {typeof sum}
- */
-export const add = sum
-
-/**
- * Computes the cross product of multiple vectors.
- * @param {...Vector3 | Vector7} vectors - The vectors to compute the cross product for.
- * @returns {Vector3 | Vector7} The resulting vector after the cross product.
- */
-export function cross(...vectors) {
-  return vectors.reduce(crossMultiplyCoordinates)
-}
-
-/**
- * Computes the distance between multiple vectors.
- * @param {...Vector2 | Vector3} vectors - The vectors to compute the distance between.
- * @returns {number} The distance between the vectors.
- */
-export function distance(...vectors) {
-  return magnitude(subtract(...vectors))
-}
-
-/**
- * Computes the dot product of multiple vectors.
- * @param {...Vector2 | Vector3} vectors - The vectors to compute the dot product for.
- * @returns {number} The resulting scalar value of the dot product.
- */
-export function dot(...vectors) {
-  return vectors
-    .reduce(dotMultiplyCoordinates)
-    .reduce((coord1, coord2) => coord1 + coord2)
-}
-
-/**
- * Alias for the dot product function.
- * @type {typeof dot}
- */
-export const scalarProduct = dot
-
-/**
- * Subtracts multiple vectors.
- * @param {...Vector2 | Vector3} vectors - The vectors to subtract.
- * @returns {Vector2 | Vector3} The resulting vector after subtraction.
- */
-export function subtract(...vectors) {
-  return vectors.reduce(subtractCoordinates)
-}
-
-/**
- * Sums multiple vectors.
- * @param {...Vector2 | Vector3} vectors - The vectors to sum.
- * @returns {Vector2 | Vector3} The resulting vector after summation.
- */
-export function sum(...vectors) {
-  return vectors.reduce(sumCoordinates)
-}
-
-/**
- * Alias for the cross product function.
- * @type {typeof cross}
- */
-export const vectorProduct = cross
-
-/**
- * Adds the coordinates of two vectors.
- * @param {Vector2 | Vector3} vector1 - The first vector.
- * @param {Vector2 | Vector3} vector2 - The second vector.
- * @returns {Vector2 | Vector3} The resulting vector after addition.
- */
-function sumCoordinates(vector1, vector2) {
-  return vector1.map((coordinate, index) => coordinate + vector2[index])
-}
-
-/**
- * Subtracts the coordinates of two vectors.
- * @param {Vector2 | Vector3} vector1 - The first vector.
- * @param {Vector2 | Vector3} vector2 - The second vector.
- * @returns {Vector2 | Vector3} The resulting vector after subtraction.
- */
-function subtractCoordinates(vector1, vector2) {
-  return vector1.map((coordinate, index) => coordinate - vector2[index])
-}
-
-/**
- * Computes the cross product of two vectors' coordinates.
- * @param {Vector3} vector1 - The first vector.
- * @param {Vector3} vector2 - The second vector.
- * @returns {Vector3} The resulting vector after the cross product.
- */
-function crossMultiplyCoordinates(vector1, vector2) {
-  const indexes = Array(vector1.length)
-    .fill(null)
-    .map((_, index) => index)
-
-  return indexes.map((_, index) => {
-    const [index1, index2] = shift(
-      indexes.filter((_, i) => i !== index),
-      index,
-    )
-    return vector1[index1] * vector2[index2] - vector1[index2] * vector2[index1]
-  })
-}
-
-/**
- * Multiplies the coordinates of two vectors.
- * @param {Vector2 | Vector3} vector1 - The first vector.
- * @param {Vector2 | Vector3} vector2 - The second vector.
- * @returns {Vector2 | Vector3} The resulting vector containing multiplied coordinates.
- */
-function dotMultiplyCoordinates(vector1, vector2) {
-  return vector1.map((coordinate, index) => coordinate * vector2[index])
-}