or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

booleans.mdcolors.mdcurves.mdexpansions-modifiers.mdextrusions.mdgeometries.mdhulls.mdindex.mdmaths.mdmeasurements.mdprimitives.mdtext-utils.mdtransforms.md
tile.json

tessl/npm-jscad--modeling

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@jscad/modeling@2.12.x

To install, run

npx @tessl/cli install tessl/npm-jscad--modeling@2.12.0

index.mddocs/

JSCAD Modeling

JSCAD Modeling is a comprehensive Constructive Solid Geometry (CSG) library that provides robust 2D and 3D geometry modeling capabilities. It implements boolean operations like union and intersection on meshes using BSP trees, offering an elegant and concise implementation of CSG algorithms. The library is designed for parametric modeling applications and serves as the core modeling engine for the OpenJSCAD ecosystem.

Package Information

  • Package Name: @jscad/modeling
  • Package Type: npm
  • Language: JavaScript (CommonJS)
  • Installation: npm install @jscad/modeling
  • Version: 2.12.5

Core Imports

const { 
  colors, curves, geometries, maths, measurements, primitives, text, utils,
  booleans, expansions, extrusions, hulls, modifiers, transforms 
} = require('@jscad/modeling');

Import specific modules:

const { colorize } = require('@jscad/modeling').colors;
const { cube, sphere } = require('@jscad/modeling').primitives;
const { union, subtract } = require('@jscad/modeling').booleans;
const { translate, rotate } = require('@jscad/modeling').transforms;

Basic Usage

const { cube, sphere, union, subtract, translate, colorize } = require('@jscad/modeling');

// Create basic shapes
const redCube = colorize([1, 0, 0], cube({ size: 10 }));
const blueSphere = colorize([0, 0, 1], sphere({ radius: 6 }));

// Position shapes
const offsetSphere = translate([5, 5, 5], blueSphere);

// Perform boolean operations  
const combined = union(redCube, offsetSphere);
const withHole = subtract(redCube, sphere({ radius: 4 }));

Architecture

JSCAD Modeling is built around several key architectural components:

  • Immutable Geometries: All geometry objects are immutable; operations return new objects
  • Functional API: Pure functions that never modify input parameters
  • Type System: Consistent geometry types (geom2, geom3, path2, etc.) with type validation
  • Mathematical Foundation: Built on glMatrix library for robust linear algebra operations
  • CSG Engine: Implements CSG algorithms using Binary Space Partitioning (BSP) trees
  • Modular Design: 16 main modules covering different aspects of 3D modeling

Capabilities

Primitive Shapes

Create mathematically precise geometric primitives including 2D shapes (circles, rectangles, polygons) and 3D solids (cubes, spheres, cylinders, torus).

// 2D Primitives
function circle(options?: { center?: [number, number], radius?: number, segments?: number }): geom2;
function rectangle(options?: { center?: [number, number], size?: [number, number] }): geom2;
function polygon(options: { points: Array<[number, number]> }): geom2;

// 3D Primitives  
function cube(options?: { center?: [number, number, number], size?: number }): geom3;
function sphere(options?: { center?: [number, number, number], radius?: number, segments?: number }): geom3;
function cylinder(options?: { center?: [number, number, number], height?: number, radius?: number }): geom3;

Primitive Shapes

Boolean Operations

Perform logical operations on shapes using Constructive Solid Geometry algorithms including union, intersection, and subtraction.

function union(...geometries: (geom2 | geom3)[]): geom2 | geom3;
function intersect(...geometries: (geom2 | geom3)[]): geom2 | geom3;
function subtract(...geometries: (geom2 | geom3)[]): geom2 | geom3;
function scission(...geometries: (geom2 | geom3)[]): Array<geom2 | geom3>;

Boolean Operations

Transformations

Transform shapes through translation, rotation, scaling, mirroring, and matrix operations with full 3D support.

function translate(offsets: [number, number] | [number, number, number], ...objects: any[]): any;
function rotate(angles: [number, number, number] | number, ...objects: any[]): any;
function scale(factors: [number, number] | [number, number, number] | number, ...objects: any[]): any;
function mirror(plane: [number, number, number, number], ...objects: any[]): any;

Transformations

Extrusions

Convert 2D shapes into 3D geometry using linear, rotational, rectangular, and helical extrusion methods.

function extrudeLinear(options: { height?: number, twistAngle?: number, twistSteps?: number }, ...objects: geom2[]): geom3;
function extrudeRotate(options?: { angle?: number, segments?: number, startAngle?: number }, ...objects: geom2[]): geom3;
function extrudeHelical(options: { angle: number, pitch: number, height?: number }, ...objects: geom2[]): geom3;

Extrusions

Expansions and Modifications

Expand, contract, and modify shapes to add material, create offsets, or improve geometry quality.

function expand(options: { delta: number, corners?: string, segments?: number }, ...objects: any[]): any;
function offset(options: { delta: number, corners?: string, segments?: number }, ...objects: geom2[]): geom2;
function snap(options: { snapFunction: (vertex: [number, number, number]) => [number, number, number] }, ...objects: any[]): any;

Expansions and Modifications

Measurements and Analysis

Measure geometric properties including area, volume, bounding boxes, centers, and dimensions.

function measureArea(geometry: geom2 | geom3): number;
function measureVolume(geometry: geom3): number;
function measureBoundingBox(geometry: any): [[number, number, number], [number, number, number]];
function measureCenter(geometry: any): [number, number] | [number, number, number];

Measurements

Mathematical Operations

Low-level mathematical utilities for vectors, matrices, planes, and lines supporting the geometry engine.

// Vector operations
const vec2: {
  add(out: [number, number], a: [number, number], b: [number, number]): [number, number];
  normalize(out: [number, number], a: [number, number]): [number, number];
  // ... additional vec2 functions
};

const mat4: {
  multiply(out: mat4, a: mat4, b: mat4): mat4;
  translate(out: mat4, a: mat4, v: [number, number, number]): mat4;
  // ... additional mat4 functions
};

Mathematical Operations

Geometry Types

Work with different geometry representations including 2D/3D geometries, paths, and polygons.

const geom2: {
  create(sides?: Array<[number, number][]>): geom2;
  clone(geometry: geom2): geom2;  
  isA(object: any): boolean;
  // ... additional geom2 functions
};

const geom3: {
  create(polygons?: poly3[]): geom3;
  clone(geometry: geom3): geom3;
  isA(object: any): boolean;
  // ... additional geom3 functions  
};

Geometry Types

Curves and Paths

Bézier curve functionality for mathematical paths, animation easing, and parametric curve operations with arc length parameterization.

const bezier: {
  create(points: Array<number> | Array<Array<number>>): Bezier;
  valueAt(t: number, bezier: Bezier): Array<number> | number;
  tangentAt(t: number, bezier: Bezier): Array<number> | number;
  length(segments: number, bezier: Bezier): number;
  arcLengthToT(options: {distance?: number, segments?: number}, bezier: Bezier): number;
};

Curves and Paths

Convex Hull Operations

Create convex hulls and hull chains for outer bounds, smooth transitions, and protective casings.

function hull(...geometries: RecursiveArray<Geom2>): Geom2;
function hull(...geometries: RecursiveArray<Geom3>): Geom3;
function hullChain(...geometries: RecursiveArray<Geom2>): Geom2;
function hullPoints2(uniquePoints: Array<[number, number]>): Array<[number, number]>;
function hullPoints3(uniquePoints: Array<[number, number, number]>): Array<Poly3>;

Convex Hull Operations

Color Management

Assign and convert colors between different formats including RGB, HSL, HSV, and CSS color names.

function colorize(color: [number, number, number] | [number, number, number, number], ...objects: any[]): any;
function hexToRgb(hex: string): [number, number, number];
function rgbToHsl(rgb: [number, number, number]): [number, number, number];
function colorNameToRgb(name: string): [number, number, number];

Color Management

Text and Utilities

Generate vector text for creating 2D/3D text outlines and utility functions for angle conversion and data processing.

function vectorText(options: { xOffset?: number, yOffset?: number, height?: number, extrudeOffset?: number, input?: string }, text: string): Array<[number, number][]>;
function degToRad(degrees: number): number;
function radToDeg(radians: number): number;

Text and Utilities

Type Definitions

// Core geometry types
type geom2 = {
  sides: Array<[number, number][]>;
  color?: [number, number, number, number];
};

type geom3 = {
  polygons: poly3[];
  color?: [number, number, number, number];
};

type poly3 = {
  vertices: Array<[number, number, number]>;
};

// Mathematical types  
type vec2 = [number, number];
type vec3 = [number, number, number];
type vec4 = [number, number, number, number];
type mat4 = [
  number, number, number, number,
  number, number, number, number, 
  number, number, number, number,
  number, number, number, number
];

// Additional types for new modules
type RecursiveArray<T> = Array<T | RecursiveArray<T>>;
type Geom2 = geom2;
type Geom3 = geom3;
type Poly3 = poly3;

// Bézier curve types
type Bezier = {
  points: Array<number> | Array<Array<number>>;
  pointType: string;
  dimensions: number;
  permutations: Array<number>;
  tangentPermutations: Array<number>;
};