tessl/npm-jscad--modeling

Constructive Solid Geometry (CSG) Library for 2D and 3D geometries with boolean operations, transformations, and mathematical utilities

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Mathematical Operations

Name: tessl/npm-jscad--modeling
Author: tessl

Maths are computational units for fundamental Euclidean geometry. All maths operate upon array data structures and are considered immutable, so never change the contents directly. Most computations are based upon the glMatrix library for robust mathematical operations.

Capabilities

Vector Operations

2D Vectors (vec2)

2D vector operations for planar geometry calculations.

const vec2: {
  /**
   * Create a new 2D vector
   * @returns {vec2} New 2D vector [0, 0]
   */
  create(): vec2;

  /**
   * Create 2D vector from values
   * @param {Number} x - X component
   * @param {Number} y - Y component  
   * @returns {vec2} New 2D vector [x, y]
   */
  fromValues(x: number, y: number): vec2;

  /**
   * Copy a 2D vector
   * @param {vec2} vector - Vector to copy
   * @returns {vec2} New vector copy
   */
  clone(vector: vec2): vec2;

  /**
   * Add two 2D vectors
   * @param {vec2} out - Output vector
   * @param {vec2} a - First vector
   * @param {vec2} b - Second vector
   * @returns {vec2} Sum vector
   */
  add(out: vec2, a: vec2, b: vec2): vec2;

  /**
   * Subtract 2D vectors
   * @param {vec2} out - Output vector
   * @param {vec2} a - First vector  
   * @param {vec2} b - Second vector
   * @returns {vec2} Difference vector
   */
  subtract(out: vec2, a: vec2, b: vec2): vec2;

  /**
   * Multiply 2D vector by scalar
   * @param {vec2} out - Output vector
   * @param {vec2} vector - Input vector
   * @param {Number} scalar - Scalar multiplier
   * @returns {vec2} Scaled vector
   */
  scale(out: vec2, vector: vec2, scalar: number): vec2;

  /**
   * Calculate length of 2D vector
   * @param {vec2} vector - Input vector
   * @returns {Number} Vector length
   */
  length(vector: vec2): number;

  /**
   * Normalize 2D vector to unit length
   * @param {vec2} out - Output vector
   * @param {vec2} vector - Input vector
   * @returns {vec2} Normalized vector
   */
  normalize(out: vec2, vector: vec2): vec2;

  /**
   * Calculate dot product of 2D vectors
   * @param {vec2} a - First vector
   * @param {vec2} b - Second vector  
   * @returns {Number} Dot product
   */
  dot(a: vec2, b: vec2): number;

  /**
   * Calculate angle between 2D vectors
   * @param {vec2} a - First vector
   * @param {vec2} b - Second vector
   * @returns {Number} Angle in radians
   */
  angle(a: vec2, b: vec2): number;

  /**
   * Rotate 2D vector by angle
   * @param {vec2} out - Output vector
   * @param {vec2} vector - Input vector
   * @param {Number} angle - Rotation angle in radians
   * @returns {vec2} Rotated vector
   */
  rotate(out: vec2, vector: vec2, angle: number): vec2;
};

3D Vectors (vec3)

3D vector operations for spatial geometry calculations.

const vec3: {
  /**
   * Create a new 3D vector
   * @returns {vec3} New 3D vector [0, 0, 0]
   */
  create(): vec3;

  /**
   * Create 3D vector from values
   * @param {Number} x - X component
   * @param {Number} y - Y component
   * @param {Number} z - Z component
   * @returns {vec3} New 3D vector [x, y, z]
   */
  fromValues(x: number, y: number, z: number): vec3;

  /**
   * Add two 3D vectors
   * @param {vec3} out - Output vector
   * @param {vec3} a - First vector
   * @param {vec3} b - Second vector
   * @returns {vec3} Sum vector
   */
  add(out: vec3, a: vec3, b: vec3): vec3;

  /**
   * Subtract 3D vectors
   * @param {vec3} out - Output vector
   * @param {vec3} a - First vector
   * @param {vec3} b - Second vector
   * @returns {vec3} Difference vector
   */
  subtract(out: vec3, a: vec3, b: vec3): vec3;

  /**
   * Calculate cross product of 3D vectors
   * @param {vec3} out - Output vector
   * @param {vec3} a - First vector
   * @param {vec3} b - Second vector
   * @returns {vec3} Cross product vector
   */
  cross(out: vec3, a: vec3, b: vec3): vec3;

  /**
   * Calculate dot product of 3D vectors
   * @param {vec3} a - First vector
   * @param {vec3} b - Second vector
   * @returns {Number} Dot product
   */
  dot(a: vec3, b: vec3): number;

  /**
   * Normalize 3D vector to unit length
   * @param {vec3} out - Output vector
   * @param {vec3} vector - Input vector
   * @returns {vec3} Normalized vector
   */
  normalize(out: vec3, vector: vec3): vec3;

  /**
   * Calculate length of 3D vector
   * @param {vec3} vector - Input vector
   * @returns {Number} Vector length
   */
  length(vector: vec3): number;

  /**
   * Scale 3D vector by scalar
   * @param {vec3} out - Output vector
   * @param {vec3} vector - Input vector
   * @param {Number} scalar - Scalar multiplier
   * @returns {vec3} Scaled vector
   */
  scale(out: vec3, vector: vec3, scalar: number): vec3;
};

Matrix Operations

4x4 Matrices (mat4)

4x4 transformation matrices for 3D graphics and transformations.

const mat4: {
  /**
   * Create identity 4x4 matrix
   * @returns {mat4} Identity matrix
   */
  create(): mat4;

  /**
   * Create 4x4 matrix from values
   * @param {...Number} values - 16 matrix elements in column-major order
   * @returns {mat4} New matrix
   */
  fromValues(...values: number[]): mat4;

  /**
   * Copy a 4x4 matrix
   * @param {mat4} matrix - Matrix to copy
   * @returns {mat4} Matrix copy
   */
  clone(matrix: mat4): mat4;

  /**
   * Set matrix to identity
   * @param {mat4} out - Output matrix
   * @returns {mat4} Identity matrix
   */
  identity(out: mat4): mat4;

  /**
   * Multiply two 4x4 matrices
   * @param {mat4} out - Output matrix
   * @param {mat4} a - First matrix
   * @param {mat4} b - Second matrix
   * @returns {mat4} Product matrix
   */
  multiply(out: mat4, a: mat4, b: mat4): mat4;

  /**
   * Translate matrix by vector
   * @param {mat4} out - Output matrix
   * @param {mat4} matrix - Input matrix
   * @param {vec3} translation - Translation vector
   * @returns {mat4} Translated matrix
   */
  translate(out: mat4, matrix: mat4, translation: vec3): mat4;

  /**
   * Rotate matrix around X axis
   * @param {mat4} out - Output matrix
   * @param {mat4} matrix - Input matrix
   * @param {Number} angle - Rotation angle in radians
   * @returns {mat4} Rotated matrix
   */
  rotateX(out: mat4, matrix: mat4, angle: number): mat4;

  /**
   * Rotate matrix around Y axis
   * @param {mat4} out - Output matrix
   * @param {mat4} matrix - Input matrix
   * @param {Number} angle - Rotation angle in radians
   * @returns {mat4} Rotated matrix
   */
  rotateY(out: mat4, matrix: mat4, angle: number): mat4;

  /**
   * Rotate matrix around Z axis
   * @param {mat4} out - Output matrix
   * @param {mat4} matrix - Input matrix
   * @param {Number} angle - Rotation angle in radians
   * @returns {mat4} Rotated matrix
   */
  rotateZ(out: mat4, matrix: mat4, angle: number): mat4;

  /**
   * Scale matrix by factors
   * @param {mat4} out - Output matrix
   * @param {mat4} matrix - Input matrix
   * @param {vec3} scaling - Scale factors [x, y, z]
   * @returns {mat4} Scaled matrix
   */
  scale(out: mat4, matrix: mat4, scaling: vec3): mat4;
};

Line Operations

2D Lines (line2)

2D line operations for planar geometry.

const line2: {
  /**
   * Create 2D line from two points
   * @param {vec2} point1 - First point
   * @param {vec2} point2 - Second point
   * @returns {line2} New 2D line
   */
  fromPoints(point1: vec2, point2: vec2): line2;

  /**
   * Get direction vector of 2D line
   * @param {line2} line - Input line
   * @returns {vec2} Direction vector
   */
  direction(line: line2): vec2;

  /**
   * Calculate distance from point to 2D line
   * @param {line2} line - Input line
   * @param {vec2} point - Test point
   * @returns {Number} Distance to line
   */
  distanceToPoint(line: line2, point: vec2): number;

  /**
   * Find closest point on 2D line to given point
   * @param {line2} line - Input line
   * @param {vec2} point - Reference point
   * @returns {vec2} Closest point on line
   */
  closestPoint(line: line2, point: vec2): vec2;
};

3D Lines (line3)

3D line operations for spatial geometry.

const line3: {
  /**
   * Create 3D line from two points
   * @param {vec3} point1 - First point
   * @param {vec3} point2 - Second point
   * @returns {line3} New 3D line
   */
  fromPoints(point1: vec3, point2: vec3): line3;

  /**
   * Get direction vector of 3D line
   * @param {line3} line - Input line
   * @returns {vec3} Direction vector
   */
  direction(line: line3): vec3;

  /**
   * Calculate distance from point to 3D line
   * @param {line3} line - Input line
   * @param {vec3} point - Test point
   * @returns {Number} Distance to line
   */
  distanceToPoint(line: line3, point: vec3): number;
};

Plane Operations

3D plane operations for spatial geometry calculations.

const plane: {
  /**
   * Create plane from normal vector and distance
   * @param {vec3} normal - Plane normal vector
   * @param {Number} distance - Distance from origin
   * @returns {plane} New plane [a, b, c, d]
   */
  fromNormalAndPoint(normal: vec3, point: vec3): plane;

  /**
   * Create plane from three points
   * @param {vec3} point1 - First point
   * @param {vec3} point2 - Second point  
   * @param {vec3} point3 - Third point
   * @returns {plane} New plane
   */
  fromPoints(point1: vec3, point2: vec3, point3: vec3): plane;

  /**
   * Get normal vector of plane
   * @param {plane} plane - Input plane
   * @returns {vec3} Normal vector
   */
  normal(plane: plane): vec3;

  /**
   * Calculate distance from point to plane
   * @param {plane} plane - Input plane
   * @param {vec3} point - Test point
   * @returns {Number} Signed distance to plane
   */
  distanceToPoint(plane: plane, point: vec3): number;

  /**
   * Project point onto plane
   * @param {plane} plane - Input plane
   * @param {vec3} point - Point to project
   * @returns {vec3} Projected point
   */
  projectPoint(plane: plane, point: vec3): vec3;
};

Mathematical Constants

Mathematical constants used throughout the library.

const constants: {
  /** Epsilon value for floating-point comparisons */
  EPS: number;
  
  /** Tau constant (2 * PI) */
  TAU: number;
  
  /** Pi constant */
  PI: number;
};

Utility Functions

Mathematical utility functions for common operations.

const utils: {
  /**
   * Convert degrees to radians
   * @param {Number} degrees - Angle in degrees
   * @returns {Number} Angle in radians
   */
  degToRad(degrees: number): number;

  /**
   * Convert radians to degrees
   * @param {Number} radians - Angle in radians
   * @returns {Number} Angle in degrees
   */
  radToDeg(radians: number): number;

  /**
   * Check if two numbers are equal within epsilon
   * @param {Number} a - First number
   * @param {Number} b - Second number
   * @param {Number} [epsilon] - Tolerance value
   * @returns {Boolean} True if equal within tolerance
   */
  aboutEqualNormals(a: number, b: number, epsilon?: number): boolean;
};

Usage Examples

Vector Calculations

const { vec2, vec3 } = require('@jscad/modeling').maths;

// 2D vector operations
const v1 = vec2.fromValues(3, 4);
const v2 = vec2.fromValues(1, 2);
const sum = vec2.create();
vec2.add(sum, v1, v2); // [4, 6]

const length = vec2.length(v1); // 5
const normalized = vec2.create();
vec2.normalize(normalized, v1); // [0.6, 0.8]

// 3D vector operations
const a = vec3.fromValues(1, 0, 0);
const b = vec3.fromValues(0, 1, 0);
const cross = vec3.create();
vec3.cross(cross, a, b); // [0, 0, 1]

const dot = vec3.dot(a, b); // 0

Matrix Transformations

const { mat4, vec3 } = require('@jscad/modeling').maths;

// Create transformation matrix
const transform = mat4.create();
mat4.identity(transform);

// Apply transformations
mat4.translate(transform, transform, [10, 0, 0]);
mat4.rotateZ(transform, transform, Math.PI / 4);
mat4.scale(transform, transform, [2, 2, 1]);

// Combine matrices
const rotation = mat4.create();
mat4.rotateY(rotation, mat4.identity(rotation), Math.PI / 2);

const combined = mat4.create();
mat4.multiply(combined, transform, rotation);

Geometric Calculations

const { line2, plane, vec2, vec3 } = require('@jscad/modeling').maths;

// 2D line operations
const point1 = vec2.fromValues(0, 0);
const point2 = vec2.fromValues(5, 5);
const line = line2.fromPoints(point1, point2);

const testPoint = vec2.fromValues(2, 0);
const distance = line2.distanceToPoint(line, testPoint);

// 3D plane operations
const p1 = vec3.fromValues(0, 0, 0);
const p2 = vec3.fromValues(1, 0, 0);
const p3 = vec3.fromValues(0, 1, 0);
const myPlane = plane.fromPoints(p1, p2, p3);

const point3D = vec3.fromValues(1, 1, 5);
const planeDistance = plane.distanceToPoint(myPlane, point3D);
const projected = plane.projectPoint(myPlane, point3D);

Coordinate System Conversions

const { utils } = require('@jscad/modeling').maths;

// Angle conversions
const degreesAngle = 90;
const radiansAngle = utils.degToRad(degreesAngle); // π/2

const backToDegrees = utils.radToDeg(radiansAngle); // 90

// Precision comparisons
const a = 1.0000001;
const b = 1.0000002;
const areEqual = utils.aboutEqualNormals(a, b, 0.00001); // true

Advanced Mathematical Techniques

Custom Transformations

const { mat4, vec3, transform } = require('@jscad/modeling');

// Create complex transformation
const createTransform = (translation, rotation, scale) => {
  const matrix = mat4.create();
  mat4.identity(matrix);
  
  // Apply in order: scale, rotate, translate
  mat4.scale(matrix, matrix, scale);
  mat4.rotateX(matrix, matrix, rotation[0]);
  mat4.rotateY(matrix, matrix, rotation[1]);
  mat4.rotateZ(matrix, matrix, rotation[2]);
  mat4.translate(matrix, matrix, translation);
  
  return matrix;
};

// Apply to geometry
const cube = require('@jscad/modeling').primitives.cube({ size: 5 });
const matrix = createTransform([10, 0, 0], [0, Math.PI/4, 0], [2, 1, 1]);
const transformed = transform(matrix, cube);

Intersection Calculations

const { line2, plane, vec2, vec3 } = require('@jscad/modeling').maths;

// Line-plane intersection
const findLinePlaneIntersection = (line, plane) => {
  const dir = line3.direction(line);
  const normal = plane.normal(plane);
  const denom = vec3.dot(dir, normal);
  
  if (Math.abs(denom) < 1e-6) return null; // Parallel
  
  // Calculate intersection point
  const t = -plane.distanceToPoint(plane, line[0]) / denom;
  const intersection = vec3.create();
  vec3.scaleAndAdd(intersection, line[0], dir, t);
  
  return intersection;
};