0
# JSCAD Modeling
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @jscad/modeling
7
- **Package Type**: npm
8
- **Language**: JavaScript (CommonJS)
9
- **Installation**: `npm install @jscad/modeling`
10
- **Version**: 2.12.5
11

12
## Core Imports
13

14
```javascript
15
const { 
16
  colors, curves, geometries, maths, measurements, primitives, text, utils,
17
  booleans, expansions, extrusions, hulls, modifiers, transforms 
18
} = require('@jscad/modeling');
19
```
20

21
Import specific modules:
22

23
```javascript
24
const { colorize } = require('@jscad/modeling').colors;
25
const { cube, sphere } = require('@jscad/modeling').primitives;
26
const { union, subtract } = require('@jscad/modeling').booleans;
27
const { translate, rotate } = require('@jscad/modeling').transforms;
28
```
29

30
## Basic Usage
31

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

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

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

42
// Perform boolean operations  
43
const combined = union(redCube, offsetSphere);
44
const withHole = subtract(redCube, sphere({ radius: 4 }));
45
```
46

47
## Architecture
48

49
JSCAD Modeling is built around several key architectural components:
50

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

58
## Capabilities
59

60
### Primitive Shapes
61

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

64
```javascript { .api }
65
// 2D Primitives
66
function circle(options?: { center?: [number, number], radius?: number, segments?: number }): geom2;
67
function rectangle(options?: { center?: [number, number], size?: [number, number] }): geom2;
68
function polygon(options: { points: Array<[number, number]> }): geom2;
69

70
// 3D Primitives  
71
function cube(options?: { center?: [number, number, number], size?: number }): geom3;
72
function sphere(options?: { center?: [number, number, number], radius?: number, segments?: number }): geom3;
73
function cylinder(options?: { center?: [number, number, number], height?: number, radius?: number }): geom3;
74
```
75

76
[Primitive Shapes](./primitives.md)
77

78
### Boolean Operations
79

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

82
```javascript { .api }
83
function union(...geometries: (geom2 | geom3)[]): geom2 | geom3;
84
function intersect(...geometries: (geom2 | geom3)[]): geom2 | geom3;
85
function subtract(...geometries: (geom2 | geom3)[]): geom2 | geom3;
86
function scission(...geometries: (geom2 | geom3)[]): Array<geom2 | geom3>;
87
```
88

89
[Boolean Operations](./booleans.md)
90

91
### Transformations
92

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

95
```javascript { .api }
96
function translate(offsets: [number, number] | [number, number, number], ...objects: any[]): any;
97
function rotate(angles: [number, number, number] | number, ...objects: any[]): any;
98
function scale(factors: [number, number] | [number, number, number] | number, ...objects: any[]): any;
99
function mirror(plane: [number, number, number, number], ...objects: any[]): any;
100
```
101

102
[Transformations](./transforms.md)
103

104
### Extrusions
105

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

108
```javascript { .api }
109
function extrudeLinear(options: { height?: number, twistAngle?: number, twistSteps?: number }, ...objects: geom2[]): geom3;
110
function extrudeRotate(options?: { angle?: number, segments?: number, startAngle?: number }, ...objects: geom2[]): geom3;
111
function extrudeHelical(options: { angle: number, pitch: number, height?: number }, ...objects: geom2[]): geom3;
112
```
113

114
[Extrusions](./extrusions.md)
115

116
### Expansions and Modifications
117

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

120
```javascript { .api }
121
function expand(options: { delta: number, corners?: string, segments?: number }, ...objects: any[]): any;
122
function offset(options: { delta: number, corners?: string, segments?: number }, ...objects: geom2[]): geom2;
123
function snap(options: { snapFunction: (vertex: [number, number, number]) => [number, number, number] }, ...objects: any[]): any;
124
```
125

126
[Expansions and Modifications](./expansions-modifiers.md)
127

128
### Measurements and Analysis
129

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

132
```javascript { .api }
133
function measureArea(geometry: geom2 | geom3): number;
134
function measureVolume(geometry: geom3): number;
135
function measureBoundingBox(geometry: any): [[number, number, number], [number, number, number]];
136
function measureCenter(geometry: any): [number, number] | [number, number, number];
137
```
138

139
[Measurements](./measurements.md)
140

141
### Mathematical Operations
142

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

145
```javascript { .api }
146
// Vector operations
147
const vec2: {
148
  add(out: [number, number], a: [number, number], b: [number, number]): [number, number];
149
  normalize(out: [number, number], a: [number, number]): [number, number];
150
  // ... additional vec2 functions
151
};
152

153
const mat4: {
154
  multiply(out: mat4, a: mat4, b: mat4): mat4;
155
  translate(out: mat4, a: mat4, v: [number, number, number]): mat4;
156
  // ... additional mat4 functions
157
};
158
```
159

160
[Mathematical Operations](./maths.md)
161

162
### Geometry Types
163

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

166
```javascript { .api }
167
const geom2: {
168
  create(sides?: Array<[number, number][]>): geom2;
169
  clone(geometry: geom2): geom2;  
170
  isA(object: any): boolean;
171
  // ... additional geom2 functions
172
};
173

174
const geom3: {
175
  create(polygons?: poly3[]): geom3;
176
  clone(geometry: geom3): geom3;
177
  isA(object: any): boolean;
178
  // ... additional geom3 functions  
179
};
180
```
181

182
[Geometry Types](./geometries.md)
183

184
### Curves and Paths
185

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

188
```javascript { .api }
189
const bezier: {
190
  create(points: Array<number> | Array<Array<number>>): Bezier;
191
  valueAt(t: number, bezier: Bezier): Array<number> | number;
192
  tangentAt(t: number, bezier: Bezier): Array<number> | number;
193
  length(segments: number, bezier: Bezier): number;
194
  arcLengthToT(options: {distance?: number, segments?: number}, bezier: Bezier): number;
195
};
196
```
197

198
[Curves and Paths](./curves.md)
199

200
### Convex Hull Operations
201

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

204
```javascript { .api }
205
function hull(...geometries: RecursiveArray<Geom2>): Geom2;
206
function hull(...geometries: RecursiveArray<Geom3>): Geom3;
207
function hullChain(...geometries: RecursiveArray<Geom2>): Geom2;
208
function hullPoints2(uniquePoints: Array<[number, number]>): Array<[number, number]>;
209
function hullPoints3(uniquePoints: Array<[number, number, number]>): Array<Poly3>;
210
```
211

212
[Convex Hull Operations](./hulls.md)
213

214
### Color Management
215

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

218
```javascript { .api }
219
function colorize(color: [number, number, number] | [number, number, number, number], ...objects: any[]): any;
220
function hexToRgb(hex: string): [number, number, number];
221
function rgbToHsl(rgb: [number, number, number]): [number, number, number];
222
function colorNameToRgb(name: string): [number, number, number];
223
```
224

225
[Color Management](./colors.md)
226

227
### Text and Utilities
228

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

231
```javascript { .api }
232
function vectorText(options: { xOffset?: number, yOffset?: number, height?: number, extrudeOffset?: number, input?: string }, text: string): Array<[number, number][]>;
233
function degToRad(degrees: number): number;
234
function radToDeg(radians: number): number;
235
```
236

237
[Text and Utilities](./text-utils.md)
238

239
## Type Definitions
240

241
```javascript { .api }
242
// Core geometry types
243
type geom2 = {
244
  sides: Array<[number, number][]>;
245
  color?: [number, number, number, number];
246
};
247

248
type geom3 = {
249
  polygons: poly3[];
250
  color?: [number, number, number, number];
251
};
252

253
type poly3 = {
254
  vertices: Array<[number, number, number]>;
255
};
256

257
// Mathematical types  
258
type vec2 = [number, number];
259
type vec3 = [number, number, number];
260
type vec4 = [number, number, number, number];
261
type mat4 = [
262
  number, number, number, number,
263
  number, number, number, number, 
264
  number, number, number, number,
265
  number, number, number, number
266
];
267

268
// Additional types for new modules
269
type RecursiveArray<T> = Array<T | RecursiveArray<T>>;
270
type Geom2 = geom2;
271
type Geom3 = geom3;
272
type Poly3 = poly3;
273

274
// Bézier curve types
275
type Bezier = {
276
  points: Array<number> | Array<Array<number>>;
277
  pointType: string;
278
  dimensions: number;
279
  permutations: Array<number>;
280
  tangentPermutations: Array<number>;
281
};
282
```