immutable2d

Immutable 2D geometry library for Javascript/Typescript.

Features

• 2D geometry primitives and functions:
  • [X] Vector
  • [ ] Point
  • [ ] Box
  • [ ] Circle
  • [ ] Polygon
• Type definitions.
• Composable functions.
• High performance.
• 100% Test coverage.

Installation

npm

npm install immutable2d

CommonJS:

const { add, negate, Vector } = require('immutable2d/vector')

Typescript:

import { add, negate, Vector } from 'immutable2d/vector'

ES6 (module):

import { add, negate, Vector } from 'immutable2d/lib-esm/vector'

CDN

For CDN, you can use unpkg:

https://unpkg.com/immutable2d/dist/immutable2d.min.js

Or jsdelivr:

https://cdn.jsdelivr.net/npm/immutable2d/dist/immutable2d.min.js

const { add, negate, Vector } = immutable2d.vector

Usage

Note: This is work in progress.

Vectors

Creation

import { toVector, Vector } from 'immutable2d/vector'

const x = 10
const y = 10

const v1 = new Vector(x, y)
const v2 = new Vector([x, y]) // Tuples
const v3 = new Vector({ x: 10, y: 10 }) // Objects
const v4 = new Vector({ x, y }) // Objects (ES6)

// With functions
const v5 = toVector(x, y)
const v6 = toVector([x, y])
const v7 = toVector({ x, y })

Vectors can also be created with the next functions:

• fromPolarToVector
• fromPolarRadiansToVector

Operations

• All operations are static for ease of composability.
• All operations work with VectorLike objects. These objects are either a tuple (an array with at least two elements, in Javascript) or an object with x and y properties.
• Many operations have corresponding X and Y functions, that only operate over the specified component. e.g. negateX only negates the X component.

import { add, addX, Vector } from 'immutable2d/vector'

const v1 = new Vector(10, 10)

const v3 = add({ x: 20, y: 20 }, v1) // Vector { x: 30, y: 30 }
const v4 = addX(v1, [30, 30]) // Vector { x: 40, y: 10 }

• Unary operators:
  • flip: Flips the components of the vector.
  • length: Gets the length of the vector.
  • lengthSquared: Gets the squared length of a Vector.
  • negate: Negates both components.
  • normalize: Normalizes a vector.
  • rotate: Rotates the vector by a rotation angle given in degrees.
  • rotateRadians: Same as rotate, but in radians.
• Binary operators:
  • Basic:
    • add: Adds two vectors component-wise.
    • substract: Substracts a vector from another component-wise.
    • multiply: Multiplies each component by a number.
    • divide: Divides each component by a number.
    • dotProduct: Returns the dot product of two vectors.
  • Functional (curried by default):
    • fold: Applies a binary function with both components of a vector.
    • map: Applies a function to each component of a vector.
    • zipWith: Returns a Vector whose components are the result of applying a binary function component-wise.

The fold, map and zipWith functions let you define custom operators easily. In fact, many operations can be defined in terms of these three:

import { flip, map, toVector, zipWith } from 'immutable2d/vector'

const flip2 = fold((x, y) => toVector(y, x))
const negate2 = map(a => -a)
const add2 = zipWith((a, b) => a + b)

Note that the actual implementations are a little different; this is to allow to define all the map and zipWith based operations in one line.

See map based functions source
See zipWith based functions source