@fimbul-works/vec 1.0.2 → 1.1.0

package/README.md

@@ -14,6 +14,7 @@ A high-performance TypeScript vector math library providing 2D, 3D, and 4D vecto
 - 🎮 **Graphics Ready**: Homogeneous coordinates and transformation support
 - 🧮 **Math Features**: Comprehensive geometric and arithmetic operations
 - ⚡ **Memory Efficient**: Zero-allocation options for performance-critical code
+- 🎨 **Color Support**: RGB/RGBA accessors for seamless color manipulation
 
 ## Installation
 
@@ -36,6 +37,15 @@ position.add(movement);
 // 3D graphics with homogeneous coordinates
 const point = new Vec4(x, y, z, 1);    // Point in 3D space
 const vector = new Vec4(dx, dy, dz, 0); // Direction in 3D space
+
+// Color manipulation with RGB accessors
+const color = new Vec3(0.8, 0.2, 0.4); // RGB values
+color.r = 1.0; // Set red component
+const [red, green, blue] = color.rgb;
+
+// RGBA colors with transparency
+const colorWithAlpha = new Vec4(0.8, 0.2, 0.4, 0.9);
+colorWithAlpha.a = 0.5; // Set alpha to 50%
 ```
 
 ## Zero-Allocation Usage

package/VEC2.md

@@ -0,0 +1,147 @@
+# Vec2
+
+A 2D vector implementation with comprehensive mathematical operations and utility methods.
+
+## Constructor
+
+### Vec2
+
+- `constructor(x: number = 0, y: number = x)`: Creates a new vector with the given x and y coordinates
+
+## Static Methods
+
+### Creation and Conversion
+
+- `fromArray(arr: [number, number] | number[])`: Creates a Vec2 from an array
+- `fromObject(obj: { x: number; y: number })`: Creates a Vec2 from an object with x and y properties
+- `fromJSON(json: { x: number; y: number })`: Creates a Vec2 from a JSON object
+- `fromPolarCoords(r: number, theta: number)`: Creates a Vec2 from polar coordinates
+- `immutable(x: number = 0, y: number = 0)`: Creates an immutable Vec2-like object
+- `one()`: Creates a vector with all components set to 1.0
+- `random(random: () => number = Math.random)`: Creates a random unit vector
+- `zero()`: Creates a zero vector
+
+### Vector Operations
+
+- `add(v: Vec2, w: Vec2)`: Adds two vectors
+- `subtract(v: Vec2, w: Vec2)`: Subtracts one vector from another
+- `multiply(v: Vec2, w: Vec2)`: Multiplies two vectors component-wise
+- `divide(v: Vec2, w: Vec2)`: Divides two vectors component-wise
+- `dot(v: Vec2, w: Vec2)`: Calculates the dot product
+- `cross(v: Vec2, w: Vec2)`: Calculates the cross product
+- `scale(v: Vec2, c: number)`: Scales a vector by a scalar value
+- `negate(v: Vec2)`: Negates a vector
+- `normalize(v: Vec2)`: Normalizes a vector
+- `project(v: Vec2, w: Vec2)`: Projects one vector onto another
+- `reflect(v: Vec2, normal: Vec2)`: Reflects a vector across a normal vector
+- `lerp(v: Vec2, w: Vec2, t: number)`: Performs linear interpolation between vectors
+
+### Distance Calculations
+
+- `distance(v: Vec2, w: Vec2)`: Calculates Euclidean distance between vectors
+- `distanceSq(v: Vec2, w: Vec2)`: Calculates squared Euclidean distance
+- `distanceChebyshev(v: Vec2, w: Vec2)`: Calculates Chebyshev distance
+- `distanceManhattan(v: Vec2, w: Vec2)`: Calculates Manhattan distance
+- `distanceMinkowski(v: Vec2, w: Vec2, p: number)`: Calculates Minkowski distance
+
+### Comparison and State
+
+- `angleBetween(v: Vec2, w: Vec2)`: Calculates angle between vectors
+- `equals(v: Vec2, w: Vec2, epsilon?: number)`: Compares vectors with optional epsilon
+- `isInfinite(v: Vec2)`: Checks if vector has infinite components
+- `isNaN(v: Vec2)`: Checks if vector has NaN components
+- `isZero(v: Vec2)`: Checks if vector is zero
+- `satisfyEquality(v: Vec2, w: Vec2)`: Checks if vectors are equal
+- `satisfyOpposition(v: Vec2, w: Vec2)`: Checks if vectors are opposite
+
+## Instance Properties
+
+### Getters and Setters
+
+- `x`: Gets or sets the x-component
+- `y`: Gets or sets the y-component
+- `xy`: Gets or sets both components as an array
+- `magnitude`: Gets or sets the vector's magnitude
+- `magnitudeSq`: Gets the squared magnitude (read-only)
+- `angleX`: Gets or sets the angle with positive x-axis
+- `angleY`: Gets or sets the angle with positive y-axis
+
+## Instance Methods
+
+### Vector Operations
+
+- `add(v: Vec2)`: Adds another vector
+- `subtract(v: Vec2)`: Subtracts another vector
+- `multiply(v: Vec2)`: Multiplies with another vector
+- `divide(v: Vec2)`: Divides by another vector
+- `scale(c: number)`: Scales by a scalar value
+- `normalize()`: Normalizes the vector
+- `negate()`: Negates the vector
+- `project(v: Vec2)`: Projects onto another vector
+- `reflect(normal: Vec2)`: Reflects across a normal vector
+- `rotateZ(phi: number)`: Rotates around Z-axis
+- `turnLeft()`: Rotates 90 degrees left
+- `turnRight()`: Rotates 90 degrees right
+- `zero()`: Sets to zero vector
+- `random(random?: () => number)`: Sets to random direction
+
+### Distance Calculations
+
+- `distance(v: Vec2)`: Calculates Euclidean distance to another vector
+- `distanceSq(v: Vec2)`: Calculates squared Euclidean distance
+- `distanceChebyshev(v: Vec2)`: Calculates Chebyshev distance
+- `distanceManhattan(v: Vec2)`: Calculates Manhattan distance
+- `distanceMinkowski(v: Vec2, p: number)`: Calculates Minkowski distance
+
+### Comparison and State
+
+- `angleBetween(v: Vec2)`: Calculates angle to another vector
+- `equals(v: Vec2, epsilon?: number)`: Compares with another vector
+- `isInfinite()`: Checks for infinite components
+- `isNaN()`: Checks for NaN components
+- `isZero()`: Checks if zero vector
+- `satisfyEquality(v: Vec2)`: Checks equality with another vector
+- `satisfyOpposition(v: Vec2)`: Checks opposition with another vector
+
+### Magnitude Operations
+
+- `clamp(min: number, max: number)`: Clamps magnitude between values
+- `limitMax(max: number)`: Limits maximum magnitude
+- `limitMin(min: number)`: Limits minimum magnitude
+
+### Utility Methods
+
+- `clone()`: Creates a copy of the vector
+- `copy(v: Vec2)`: Copies components from another vector
+- `lookAt(v: Vec2)`: Points towards another vector
+- `toString()`: Returns string representation
+- `toObject()`: Converts to plain object
+- `toJSON()`: Converts to JSON format
+
+## Iteration
+
+Vec2 implements the iterator protocol, allowing it to be used with for...of loops and spread operators. The iterator yields the x and y components in order.
+
+## Example Usage
+
+```typescript
+// Create vectors
+const v1 = new Vec2(3, 4);
+const v2 = new Vec2(1, 2);
+
+// Basic operations
+const sum = Vec2.add(v1, v2);
+const dot = Vec2.dot(v1, v2);
+
+// Method chaining
+v1.normalize()
+  .scale(2)
+  .rotate(Math.PI / 4);
+
+// Get properties
+console.log(v1.magnitude);
+console.log(v1.angleX);
+
+// Convert to array
+const [x, y] = v1;
+```

package/VEC3.md

@@ -0,0 +1,172 @@
+# Vec3
+
+A 3D vector implementation with comprehensive mathematical operations and utility methods.
+
+## Constructor
+
+### Vec3
+
+- `constructor(x: number = 0, y: number = 0, z: number = 0)`: Creates a new vector with the given x, y and z coordinates
+
+## Static Methods
+
+### Creation and Conversion
+
+- `fromArray(arr: [number, number, number] | number[])`: Creates a Vec3 from an array
+- `fromObject(obj: { x: number; y: number; z: number })`: Creates a Vec3 from an object with x, y and z properties
+- `fromJSON(json: { x: number; y: number; z: number })`: Creates a Vec3 from a JSON object
+- `fromCylindricalCoords(r: number, phi: number, z: number)`: Creates a Vec3 from cylindrical coordinates
+- `fromSphericalCoords(r: number, theta: number, phi: number)`: Creates a Vec3 from spherical coordinates
+- `immutable(x: number = 0, y: number = 0, z: number = 0)`: Creates an immutable Vec3-like object
+- `one()`: Creates a vector with all components set to 1.0
+- `random(random: () => number = Math.random)`: Creates a random unit vector
+- `zero()`: Creates a zero vector
+
+### Vector Operations
+
+- `add(v: Vec3, w: Vec3)`: Adds two vectors
+- `subtract(v: Vec3, w: Vec3)`: Subtracts one vector from another
+- `multiply(v: Vec3, w: Vec3)`: Multiplies two vectors component-wise
+- `divide(v: Vec3, w: Vec3)`: Divides two vectors component-wise
+- `dot(v: Vec3, w: Vec3)`: Calculates the dot product
+- `cross(v: Vec3, w: Vec3)`: Calculates the cross product
+- `scale(v: Vec3, c: number)`: Scales a vector by a scalar value
+- `negate(v: Vec3)`: Negates a vector
+- `normalize(v: Vec3)`: Normalizes a vector
+- `project(v: Vec3, w: Vec3)`: Projects one vector onto another
+- `reflect(v: Vec3, normal: Vec3)`: Reflects a vector across a normal vector
+- `lerp(v: Vec3, w: Vec3, t: number)`: Performs linear interpolation between vectors
+
+### Distance Calculations
+
+- `distance(v: Vec3, w: Vec3)`: Calculates Euclidean distance between vectors
+- `distanceSq(v: Vec3, w: Vec3)`: Calculates squared Euclidean distance
+- `distanceChebyshev(v: Vec3, w: Vec3)`: Calculates Chebyshev distance
+- `distanceManhattan(v: Vec3, w: Vec3)`: Calculates Manhattan distance
+- `distanceMinkowski(v: Vec3, w: Vec3, p: number)`: Calculates Minkowski distance
+
+### Comparison and State
+
+- `angleBetween(v: Vec3, w: Vec3)`: Calculates angle between vectors
+- `equals(v: Vec3, w: Vec3, epsilon?: number)`: Compares vectors with optional epsilon
+- `isInfinite(v: Vec3)`: Checks if vector has infinite components
+- `isNaN(v: Vec3)`: Checks if vector has NaN components
+- `isZero(v: Vec3)`: Checks if vector is zero
+- `satisfyEquality(v: Vec3, w: Vec3)`: Checks if vectors are equal
+- `satisfyOpposition(v: Vec3, w: Vec3)`: Checks if vectors are opposite
+
+## Instance Properties
+
+### Getters and Setters
+
+- `x`: Gets or sets the x-component
+- `y`: Gets or sets the y-component
+- `z`: Gets or sets the z-component
+- `xyz`: Gets or sets all components as an array
+- `r`: Gets or sets the red component (alias for x)
+- `g`: Gets or sets the green component (alias for y)
+- `b`: Gets or sets the blue component (alias for z)
+- `rgb`: Gets or sets all color components as an array (alias for xyz)
+- `magnitude`: Gets or sets the vector's magnitude
+- `magnitudeSq`: Gets the squared magnitude (read-only)
+- `angleX`: Gets the angle with positive x-axis
+- `angleY`: Gets the angle with positive y-axis
+- `angleZ`: Gets the angle with positive z-axis
+
+## Instance Methods
+
+### Vector Operations
+
+- `add(v: Vec3)`: Adds another vector
+- `subtract(v: Vec3)`: Subtracts another vector
+- `multiply(v: Vec3)`: Multiplies with another vector
+- `divide(v: Vec3)`: Divides by another vector
+- `scale(c: number)`: Scales by a scalar value
+- `normalize()`: Normalizes the vector
+- `negate()`: Negates the vector
+- `project(v: Vec3)`: Projects onto another vector
+- `reflect(normal: Vec3)`: Reflects across a normal vector
+- `rotateX(phi: number)`: Rotates around X-axis
+- `rotateY(phi: number)`: Rotates around Y-axis
+- `rotateZ(phi: number)`: Rotates around Z-axis
+- `zero()`: Sets to zero vector
+- `random(random?: () => number)`: Sets to random direction
+
+### Distance Calculations
+
+- `distance(v: Vec3)`: Calculates Euclidean distance to another vector
+- `distanceSq(v: Vec3)`: Calculates squared Euclidean distance
+- `distanceChebyshev(v: Vec3)`: Calculates Chebyshev distance
+- `distanceManhattan(v: Vec3)`: Calculates Manhattan distance
+- `distanceMinkowski(v: Vec3, p: number)`: Calculates Minkowski distance
+
+### Cross Product
+
+- `cross(v: Vec3)`: Calculates the cross product with another vector
+
+### Comparison and State
+
+- `angleBetween(v: Vec3)`: Calculates angle to another vector
+- `equals(v: Vec3, epsilon?: number)`: Compares with another vector
+- `isInfinite()`: Checks for infinite components
+- `isNaN()`: Checks for NaN components
+- `isZero()`: Checks if zero vector
+- `satisfyEquality(v: Vec3)`: Checks equality with another vector
+- `satisfyOpposition(v: Vec3)`: Checks opposition with another vector
+
+### Magnitude Operations
+
+- `clamp(min: number, max: number)`: Clamps magnitude between values
+- `limitMax(max: number)`: Limits maximum magnitude
+- `limitMin(min: number)`: Limits minimum magnitude
+
+### Utility Methods
+
+- `clone()`: Creates a copy of the vector
+- `copy(v: Vec3)`: Copies components from another vector
+- `lookAt(v: Vec3)`: Points towards another vector
+- `toString()`: Returns string representation
+- `toObject()`: Converts to plain object
+- `toJSON()`: Converts to JSON format
+
+## Iteration
+
+Vec3 implements the iterator protocol, allowing it to be used with for...of loops and spread operators. The iterator yields the x, y, and z components in order.
+
+## Example Usage
+
+```typescript
+// Create vectors
+const v1 = new Vec3(3, 4, 5);
+const v2 = new Vec3(1, 2, 3);
+
+// Basic operations
+const sum = Vec3.add(v1, v2);
+const crossProduct = Vec3.cross(v1, v2);
+const dot = Vec3.dot(v1, v2);
+
+// Method chaining
+v1.normalize()
+  .scale(2)
+  .rotateX(Math.PI / 4);
+
+// Get properties
+console.log(v1.magnitude);
+console.log(v1.angleX);
+
+// Convert to array
+const [x, y, z] = v1;
+
+// Create from special coordinates
+const cylindrical = Vec3.fromCylindricalCoords(2, Math.PI/4, 5);
+const spherical = Vec3.fromSphericalCoords(2, Math.PI/3, Math.PI/4);
+
+// Color operations
+const color = new Vec3(1.0, 0.5, 0.2); // RGB color
+color.r = 0.8; // Modify red channel
+color.g *= 0.9; // Darken green channel
+
+// Access as RGB array
+const [red, green, blue] = color.rgb;
+color.rgb = [0.2, 0.7, 0.9]; // Set new RGB values
+```

package/VEC4.md

@@ -0,0 +1,161 @@
+# Vec4
+
+A 4D vector implementation with comprehensive mathematical operations and utility methods.
+
+## Constructor
+
+### Vec4
+
+- `constructor(x: number = 0, y: number = 0, z: number = 0, w: number = 0)`: Creates a new vector with the given x, y, z, and w coordinates
+
+## Static Methods
+
+### Creation and Conversion
+
+- `fromArray(arr: [number, number, number, number] | number[])`: Creates a Vec4 from an array
+- `fromObject(obj: { x: number; y: number; z: number; w: number })`: Creates a Vec4 from an object with x, y, z, and w properties
+- `fromJSON(json: { x: number; y: number; z: number; w: number })`: Creates a Vec4 from a JSON object
+- `immutable(x: number = 0, y: number = 0, z: number = 0, w: number = 0)`: Creates an immutable Vec4-like object
+- `one()`: Creates a vector with all components set to 1.0
+- `random(random: () => number = Math.random)`: Creates a random unit vector
+- `zero()`: Creates a zero vector
+
+### Vector Operations
+
+- `add(v: Vec4, w: Vec4)`: Adds two vectors
+- `subtract(v: Vec4, w: Vec4)`: Subtracts one vector from another
+- `multiply(v: Vec4, w: Vec4)`: Multiplies two vectors component-wise
+- `divide(v: Vec4, w: Vec4)`: Divides two vectors component-wise
+- `dot(v: Vec4, w: Vec4)`: Calculates the dot product
+- `scale(v: Vec4, c: number)`: Scales a vector by a scalar value
+- `negate(v: Vec4)`: Negates a vector
+- `normalize(v: Vec4)`: Normalizes a vector
+- `project(v: Vec4, w: Vec4)`: Projects one vector onto another
+- `reflect(v: Vec4, normal: Vec4)`: Reflects a vector across a normal vector
+- `lerp(v: Vec4, w: Vec4, t: number)`: Performs linear interpolation between vectors
+
+### Distance Calculations
+
+- `distance(v: Vec4, w: Vec4)`: Calculates Euclidean distance between vectors
+- `distanceSq(v: Vec4, w: Vec4)`: Calculates squared Euclidean distance
+- `distanceChebyshev(v: Vec4, w: Vec4)`: Calculates Chebyshev distance
+- `distanceManhattan(v: Vec4, w: Vec4)`: Calculates Manhattan distance
+- `distanceMinkowski(v: Vec4, w: Vec4, p: number)`: Calculates Minkowski distance
+
+### Comparison and State
+
+- `angleBetween(v: Vec4, w: Vec4)`: Calculates angle between vectors
+- `equals(v: Vec4, w: Vec4, epsilon?: number)`: Compares vectors with optional epsilon
+- `isInfinite(v: Vec4)`: Checks if vector has infinite components
+- `isNaN(v: Vec4)`: Checks if vector has NaN components
+- `isZero(v: Vec4)`: Checks if vector is zero
+- `satisfyEquality(v: Vec4, w: Vec4)`: Checks if vectors are equal
+- `satisfyOpposition(v: Vec4, w: Vec4)`: Checks if vectors are opposite
+
+## Instance Properties
+
+### Getters and Setters
+
+- `x`: Gets or sets the x-component
+- `y`: Gets or sets the y-component
+- `z`: Gets or sets the z-component
+- `w`: Gets or sets the w-component
+- `xyzw`: Gets or sets all components as an array
+- `r`: Gets or sets the red component (alias for x)
+- `g`: Gets or sets the green component (alias for y)
+- `b`: Gets or sets the blue component (alias for z)
+- `a`: Gets or sets the alpha component (alias for w)
+- `rgba`: Gets or sets all color components as an array (alias for xyzw)
+- `magnitude`: Gets or sets the vector's magnitude
+- `magnitudeSq`: Gets the squared magnitude (read-only)
+- `angleX`: Gets the angle with positive x-axis
+- `angleY`: Gets the angle with positive y-axis
+- `angleZ`: Gets the angle with positive z-axis
+- `angleW`: Gets the angle with positive w-axis
+
+## Instance Methods
+
+### Vector Operations
+
+- `add(v: Vec4)`: Adds another vector
+- `subtract(v: Vec4)`: Subtracts another vector
+- `multiply(v: Vec4)`: Multiplies with another vector
+- `divide(v: Vec4)`: Divides by another vector
+- `scale(c: number)`: Scales by a scalar value
+- `normalize()`: Normalizes the vector
+- `negate()`: Negates the vector
+- `project(v: Vec4)`: Projects onto another vector
+- `reflect(normal: Vec4)`: Reflects across a normal vector
+- `zero()`: Sets to zero vector
+- `random(random?: () => number)`: Sets to random direction
+
+### Distance Calculations
+
+- `distance(v: Vec4)`: Calculates Euclidean distance to another vector
+- `distanceSq(v: Vec4)`: Calculates squared Euclidean distance
+- `distanceChebyshev(v: Vec4)`: Calculates Chebyshev distance
+- `distanceManhattan(v: Vec4)`: Calculates Manhattan distance
+- `distanceMinkowski(v: Vec4, p: number)`: Calculates Minkowski distance
+
+### Comparison and State
+
+- `angleBetween(v: Vec4)`: Calculates angle to another vector
+- `equals(v: Vec4, epsilon?: number)`: Compares with another vector
+- `isInfinite()`: Checks for infinite components
+- `isNaN()`: Checks for NaN components
+- `isZero()`: Checks if zero vector
+- `satisfyEquality(v: Vec4)`: Checks equality with another vector
+- `satisfyOpposition(v: Vec4)`: Checks opposition with another vector
+
+### Magnitude Operations
+
+- `clamp(min: number, max: number)`: Clamps magnitude between values
+- `limitMax(max: number)`: Limits maximum magnitude
+- `limitMin(min: number)`: Limits minimum magnitude
+
+### Utility Methods
+
+- `clone()`: Creates a copy of the vector
+- `copy(v: Vec4)`: Copies components from another vector
+- `lookAt(v: Vec4)`: Points towards another vector
+- `toString()`: Returns string representation
+- `toObject()`: Converts to plain object
+- `toJSON()`: Converts to JSON format
+
+## Iteration
+
+Vec4 implements the iterator protocol, allowing it to be used with for...of loops and spread operators. The iterator yields the x, y, z, and w components in order.
+
+## Example Usage
+
+```typescript
+// Create vectors
+const v1 = new Vec4(1, 2, 3, 1);  // Homogeneous coordinates
+const v2 = new Vec4(0, 1, 0, 0);  // Direction vector
+
+// Basic operations
+const sum = Vec4.add(v1, v2);
+const dot = Vec4.dot(v1, v2);
+
+// Method chaining
+v1.normalize()
+  .scale(2)
+  .limitMax(5);
+
+// Get properties
+console.log(v1.magnitude);
+console.log(v1.angleX);
+
+// Convert to array
+const [x, y, z, w] = v1;
+
+// RGBA color with transparency
+const color = new Vec4(1.0, 0.5, 0.2, 0.8); // RGBA color
+color.r = 0.8; // Modify red channel
+color.g *= 0.9; // Darken green channel
+color.a = 1.0; // Make fully opaque
+
+// Access as RGBA array
+const [red, green, blue, alpha] = color.rgba;
+color.rgba = [0.2, 0.7, 0.9, 0.6]; // Set new RGBA values
+```

package/dist/cjs/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./vec2.js"), exports);
+__exportStar(require("./vec3.js"), exports);
+__exportStar(require("./vec4.js"), exports);

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}