arctan.meridian v2.0.1

Arctan Meridian

View on NPMjs here

A Vector and Color API for Javascript

Ideas barrowed from jxu/vector.js

Jump to Euler api here Jump to color api here

Vector Usage

You can create a vector from an array or spread values between 2 and 4 dimensions:

(The 4th dimension is not calculated as a quaternion, but rather as a 4th imaginary axis that can be converted with other libraries) (Its mainly meant to be used to store the alpha value of colors, as they can be represented as Vectors in certain scenarios)

const { Vector } = require('arctan.meridian');

let pos = new Vector(1, 2, 3);
let pos2 = new Vector([1, 2, 3]);

// pos and pos2 are identical

let pos = new Vector(1, 2);

// 2D vectors will just use zero for the Z axis

Constants

Each vector has "constants" that are calculated based on their existing values

let vec = new Vector(1, 2, 3);

vec.v       => [1, 2, 3]            // The "value" of the vector (an array of its values)
vec.copy    => Vector(1, 2, 3)      // New instance of the same vector
vec.dot2    => 14                   // The dot product of the vector itself
vec.sum     => 6                    // Total of all the values in the vector
vec.len     => 2.41014226...        // Length or Magnitude of the current vector
vec.norm    => Vector(0.414..., 0.829..., 1.244...) // Normalized vector
vec.x       => 1                    // X axis
vec.y       => 2                    // Y axis
vec.z       => 3                    // Z axis
vec.w       => 0                    // W axis

// Aliases

vec.normalized  // vec.norm
vec.length      // vec.len
vec.mag         // vec.len
vec.magnitude   // vec.len

Methods

Each vector also supports a good range of mathematical operations, as javascript doesnt support vector math by default

(I will add more as I go)

let vec1 = new Vector(1, 2, 3);
let vec2 = new Vector(3, 2, 1);

map(callback)   // Backend function meant as an alias for use with vector math only

// Global Methods

Vector.isVector(vec1) => true // Check if value is an instance of meridian

// All of these math operations will retain and edit the current vector, and will not edit the input vector
// Vec1 = Vec1 + Vec2
vec1.add(vec2)      => vec1 = Vector(4, 4, 4);
vec1.sub(vec2)      => vec1 = Vector(-2, 0, 2);
vec1.mul(vec2)      => vec1 = Vector(3, 4, 3);
vec1.div(vec2)      => vec1 = Vector(0.333..., 1, 3);
vec1.pow(vec2)      => vec1 = Vector(1, 4, 3);  // Exponent
vec1.dot(vec2)      => 10                       // Dot Product
vec1.dist(vec2)     => 2.3697581012031717       // Distance between vectors
vec1.scale(2)       => vec1 = Vector(2, 4, 6)   // Scale up or down vector

// Utility methods
vec1.htmlY(height) // Returns the Y axis corrected for HTML and Canvas using Height (In pixels)

// Unfinished / Unperfected / WIP methods
vec1.rotate2d(origin, angle, reverse) // Fast 2D rotation that ignores the Z axis

// Planned methods
vec1.rotate(origin, angle, reverse) // Full 3D rotation

Euler Usage

You can also create polar coordinates besides just normal cartesian. These are referred to as Euler coordinates. You can also convert between them. (More advanced math features will be added later on)

(This is really new, but I hope youll like it anyways)

const { Euler } = require('arctan.meridian');

let eul = new Euler(1, 0.5, 0.2);
let vec = eul.toVector();

let vec2 = new Vector() // See vector api above
let eul2 = vec2.toEuler();

// Static methods

Euler.fromVector(Vector) // Returns a euler system from a cartesian
Vector.fromEuler(Euler) // Returns a cartesian system from a euler

Color Usage

You can create a color from an array or spread values with either RGB, RGBA, Hexidecimal, or an existing Color instance:

const { Color } = require('arctan.meridian');

let col = new Color(255, 78, 24);
let col2 = new Color([255, 78, 24]);
let col3 = new Color(col);
let col4 = col.copy;

// col, col2, col3, and col4 are identical.

Constants

Each color has "constants" that are calculated based on their existing values

let col = new Color(255, 25, 89);

col.rgb       => [255, 25, 89]      // An RGB Array
col.copy    => Color(255, 25, 89)   // New instance of the same color
col.r       => 255                  // Red
col.g       => 25                   // Green
col.b       => 89                   // Blue
col.h       => 343.30..             // HSV Hue
col.s       => 0.90..               // HSV Saturation
col.v       => 255                  // HSV Value
col.a       => 255                  // Alpha (Always separate because alpha is a format-dependent value)

Methods

Each color has a few utility methods, along with some internal methods which you dont need to touch..

(more to come, this library is very basic)

// Global Methods

Color.isColor(col) => true // Detects if a variable / instance is a color from meridian

// Inherited Methods

col.toString(<'html' / 'hex'>) => ColorString // Returns a formatted color string for Canvas/HTML/CSS or a Hexadecimal Hash
col.toRGBFloat()               => Array       // Returns an array in RGB format with all values through 0 and 1, rather than 0 and 255
col.mix(color, fac)            => Color       // Mix two colors together by a factor

// Backend Methods

col.evalColor(val)      => undefined     // Sets values in the Color based on the color's constructor
col.identify(val)       => [value, type] // Identifies the format of a string
col.updateColors()      => undefined     // Manually refreshes the HSV / HSL / HEX values based on the RGB value (You probably wont need to use this ever)
col.lerp(inp, out, fac) => val           // Internal linear interpolation function for use with color.mix();