0
# Mathematical Operations
1

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

4
## Capabilities
5

6
### Vector Operations
7

8
#### 2D Vectors (vec2)
9

10
2D vector operations for planar geometry calculations.
11

12
```javascript { .api }
13
const vec2: {
14
  /**
15
   * Create a new 2D vector
16
   * @returns {vec2} New 2D vector [0, 0]
17
   */
18
  create(): vec2;
19

20
  /**
21
   * Create 2D vector from values
22
   * @param {Number} x - X component
23
   * @param {Number} y - Y component  
24
   * @returns {vec2} New 2D vector [x, y]
25
   */
26
  fromValues(x: number, y: number): vec2;
27

28
  /**
29
   * Copy a 2D vector
30
   * @param {vec2} vector - Vector to copy
31
   * @returns {vec2} New vector copy
32
   */
33
  clone(vector: vec2): vec2;
34

35
  /**
36
   * Add two 2D vectors
37
   * @param {vec2} out - Output vector
38
   * @param {vec2} a - First vector
39
   * @param {vec2} b - Second vector
40
   * @returns {vec2} Sum vector
41
   */
42
  add(out: vec2, a: vec2, b: vec2): vec2;
43

44
  /**
45
   * Subtract 2D vectors
46
   * @param {vec2} out - Output vector
47
   * @param {vec2} a - First vector  
48
   * @param {vec2} b - Second vector
49
   * @returns {vec2} Difference vector
50
   */
51
  subtract(out: vec2, a: vec2, b: vec2): vec2;
52

53
  /**
54
   * Multiply 2D vector by scalar
55
   * @param {vec2} out - Output vector
56
   * @param {vec2} vector - Input vector
57
   * @param {Number} scalar - Scalar multiplier
58
   * @returns {vec2} Scaled vector
59
   */
60
  scale(out: vec2, vector: vec2, scalar: number): vec2;
61

62
  /**
63
   * Calculate length of 2D vector
64
   * @param {vec2} vector - Input vector
65
   * @returns {Number} Vector length
66
   */
67
  length(vector: vec2): number;
68

69
  /**
70
   * Normalize 2D vector to unit length
71
   * @param {vec2} out - Output vector
72
   * @param {vec2} vector - Input vector
73
   * @returns {vec2} Normalized vector
74
   */
75
  normalize(out: vec2, vector: vec2): vec2;
76

77
  /**
78
   * Calculate dot product of 2D vectors
79
   * @param {vec2} a - First vector
80
   * @param {vec2} b - Second vector  
81
   * @returns {Number} Dot product
82
   */
83
  dot(a: vec2, b: vec2): number;
84

85
  /**
86
   * Calculate angle between 2D vectors
87
   * @param {vec2} a - First vector
88
   * @param {vec2} b - Second vector
89
   * @returns {Number} Angle in radians
90
   */
91
  angle(a: vec2, b: vec2): number;
92

93
  /**
94
   * Rotate 2D vector by angle
95
   * @param {vec2} out - Output vector
96
   * @param {vec2} vector - Input vector
97
   * @param {Number} angle - Rotation angle in radians
98
   * @returns {vec2} Rotated vector
99
   */
100
  rotate(out: vec2, vector: vec2, angle: number): vec2;
101
};
102
```
103

104
#### 3D Vectors (vec3)
105

106
3D vector operations for spatial geometry calculations.
107

108
```javascript { .api }
109
const vec3: {
110
  /**
111
   * Create a new 3D vector
112
   * @returns {vec3} New 3D vector [0, 0, 0]
113
   */
114
  create(): vec3;
115

116
  /**
117
   * Create 3D vector from values
118
   * @param {Number} x - X component
119
   * @param {Number} y - Y component
120
   * @param {Number} z - Z component
121
   * @returns {vec3} New 3D vector [x, y, z]
122
   */
123
  fromValues(x: number, y: number, z: number): vec3;
124

125
  /**
126
   * Add two 3D vectors
127
   * @param {vec3} out - Output vector
128
   * @param {vec3} a - First vector
129
   * @param {vec3} b - Second vector
130
   * @returns {vec3} Sum vector
131
   */
132
  add(out: vec3, a: vec3, b: vec3): vec3;
133

134
  /**
135
   * Subtract 3D vectors
136
   * @param {vec3} out - Output vector
137
   * @param {vec3} a - First vector
138
   * @param {vec3} b - Second vector
139
   * @returns {vec3} Difference vector
140
   */
141
  subtract(out: vec3, a: vec3, b: vec3): vec3;
142

143
  /**
144
   * Calculate cross product of 3D vectors
145
   * @param {vec3} out - Output vector
146
   * @param {vec3} a - First vector
147
   * @param {vec3} b - Second vector
148
   * @returns {vec3} Cross product vector
149
   */
150
  cross(out: vec3, a: vec3, b: vec3): vec3;
151

152
  /**
153
   * Calculate dot product of 3D vectors
154
   * @param {vec3} a - First vector
155
   * @param {vec3} b - Second vector
156
   * @returns {Number} Dot product
157
   */
158
  dot(a: vec3, b: vec3): number;
159

160
  /**
161
   * Normalize 3D vector to unit length
162
   * @param {vec3} out - Output vector
163
   * @param {vec3} vector - Input vector
164
   * @returns {vec3} Normalized vector
165
   */
166
  normalize(out: vec3, vector: vec3): vec3;
167

168
  /**
169
   * Calculate length of 3D vector
170
   * @param {vec3} vector - Input vector
171
   * @returns {Number} Vector length
172
   */
173
  length(vector: vec3): number;
174

175
  /**
176
   * Scale 3D vector by scalar
177
   * @param {vec3} out - Output vector
178
   * @param {vec3} vector - Input vector
179
   * @param {Number} scalar - Scalar multiplier
180
   * @returns {vec3} Scaled vector
181
   */
182
  scale(out: vec3, vector: vec3, scalar: number): vec3;
183
};
184
```
185

186
### Matrix Operations
187

188
#### 4x4 Matrices (mat4)
189

190
4x4 transformation matrices for 3D graphics and transformations.
191

192
```javascript { .api }
193
const mat4: {
194
  /**
195
   * Create identity 4x4 matrix
196
   * @returns {mat4} Identity matrix
197
   */
198
  create(): mat4;
199

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

207
  /**
208
   * Copy a 4x4 matrix
209
   * @param {mat4} matrix - Matrix to copy
210
   * @returns {mat4} Matrix copy
211
   */
212
  clone(matrix: mat4): mat4;
213

214
  /**
215
   * Set matrix to identity
216
   * @param {mat4} out - Output matrix
217
   * @returns {mat4} Identity matrix
218
   */
219
  identity(out: mat4): mat4;
220

221
  /**
222
   * Multiply two 4x4 matrices
223
   * @param {mat4} out - Output matrix
224
   * @param {mat4} a - First matrix
225
   * @param {mat4} b - Second matrix
226
   * @returns {mat4} Product matrix
227
   */
228
  multiply(out: mat4, a: mat4, b: mat4): mat4;
229

230
  /**
231
   * Translate matrix by vector
232
   * @param {mat4} out - Output matrix
233
   * @param {mat4} matrix - Input matrix
234
   * @param {vec3} translation - Translation vector
235
   * @returns {mat4} Translated matrix
236
   */
237
  translate(out: mat4, matrix: mat4, translation: vec3): mat4;
238

239
  /**
240
   * Rotate matrix around X axis
241
   * @param {mat4} out - Output matrix
242
   * @param {mat4} matrix - Input matrix
243
   * @param {Number} angle - Rotation angle in radians
244
   * @returns {mat4} Rotated matrix
245
   */
246
  rotateX(out: mat4, matrix: mat4, angle: number): mat4;
247

248
  /**
249
   * Rotate matrix around Y axis
250
   * @param {mat4} out - Output matrix
251
   * @param {mat4} matrix - Input matrix
252
   * @param {Number} angle - Rotation angle in radians
253
   * @returns {mat4} Rotated matrix
254
   */
255
  rotateY(out: mat4, matrix: mat4, angle: number): mat4;
256

257
  /**
258
   * Rotate matrix around Z axis
259
   * @param {mat4} out - Output matrix
260
   * @param {mat4} matrix - Input matrix
261
   * @param {Number} angle - Rotation angle in radians
262
   * @returns {mat4} Rotated matrix
263
   */
264
  rotateZ(out: mat4, matrix: mat4, angle: number): mat4;
265

266
  /**
267
   * Scale matrix by factors
268
   * @param {mat4} out - Output matrix
269
   * @param {mat4} matrix - Input matrix
270
   * @param {vec3} scaling - Scale factors [x, y, z]
271
   * @returns {mat4} Scaled matrix
272
   */
273
  scale(out: mat4, matrix: mat4, scaling: vec3): mat4;
274
};
275
```
276

277
### Line Operations
278

279
#### 2D Lines (line2)
280

281
2D line operations for planar geometry.
282

283
```javascript { .api }
284
const line2: {
285
  /**
286
   * Create 2D line from two points
287
   * @param {vec2} point1 - First point
288
   * @param {vec2} point2 - Second point
289
   * @returns {line2} New 2D line
290
   */
291
  fromPoints(point1: vec2, point2: vec2): line2;
292

293
  /**
294
   * Get direction vector of 2D line
295
   * @param {line2} line - Input line
296
   * @returns {vec2} Direction vector
297
   */
298
  direction(line: line2): vec2;
299

300
  /**
301
   * Calculate distance from point to 2D line
302
   * @param {line2} line - Input line
303
   * @param {vec2} point - Test point
304
   * @returns {Number} Distance to line
305
   */
306
  distanceToPoint(line: line2, point: vec2): number;
307

308
  /**
309
   * Find closest point on 2D line to given point
310
   * @param {line2} line - Input line
311
   * @param {vec2} point - Reference point
312
   * @returns {vec2} Closest point on line
313
   */
314
  closestPoint(line: line2, point: vec2): vec2;
315
};
316
```
317

318
#### 3D Lines (line3)
319

320
3D line operations for spatial geometry.
321

322
```javascript { .api }
323
const line3: {
324
  /**
325
   * Create 3D line from two points
326
   * @param {vec3} point1 - First point
327
   * @param {vec3} point2 - Second point
328
   * @returns {line3} New 3D line
329
   */
330
  fromPoints(point1: vec3, point2: vec3): line3;
331

332
  /**
333
   * Get direction vector of 3D line
334
   * @param {line3} line - Input line
335
   * @returns {vec3} Direction vector
336
   */
337
  direction(line: line3): vec3;
338

339
  /**
340
   * Calculate distance from point to 3D line
341
   * @param {line3} line - Input line
342
   * @param {vec3} point - Test point
343
   * @returns {Number} Distance to line
344
   */
345
  distanceToPoint(line: line3, point: vec3): number;
346
};
347
```
348

349
### Plane Operations
350

351
3D plane operations for spatial geometry calculations.
352

353
```javascript { .api }
354
const plane: {
355
  /**
356
   * Create plane from normal vector and distance
357
   * @param {vec3} normal - Plane normal vector
358
   * @param {Number} distance - Distance from origin
359
   * @returns {plane} New plane [a, b, c, d]
360
   */
361
  fromNormalAndPoint(normal: vec3, point: vec3): plane;
362

363
  /**
364
   * Create plane from three points
365
   * @param {vec3} point1 - First point
366
   * @param {vec3} point2 - Second point  
367
   * @param {vec3} point3 - Third point
368
   * @returns {plane} New plane
369
   */
370
  fromPoints(point1: vec3, point2: vec3, point3: vec3): plane;
371

372
  /**
373
   * Get normal vector of plane
374
   * @param {plane} plane - Input plane
375
   * @returns {vec3} Normal vector
376
   */
377
  normal(plane: plane): vec3;
378

379
  /**
380
   * Calculate distance from point to plane
381
   * @param {plane} plane - Input plane
382
   * @param {vec3} point - Test point
383
   * @returns {Number} Signed distance to plane
384
   */
385
  distanceToPoint(plane: plane, point: vec3): number;
386

387
  /**
388
   * Project point onto plane
389
   * @param {plane} plane - Input plane
390
   * @param {vec3} point - Point to project
391
   * @returns {vec3} Projected point
392
   */
393
  projectPoint(plane: plane, point: vec3): vec3;
394
};
395
```
396

397
### Mathematical Constants
398

399
Mathematical constants used throughout the library.
400

401
```javascript { .api }
402
const constants: {
403
  /** Epsilon value for floating-point comparisons */
404
  EPS: number;
405
  
406
  /** Tau constant (2 * PI) */
407
  TAU: number;
408
  
409
  /** Pi constant */
410
  PI: number;
411
};
412
```
413

414
### Utility Functions
415

416
Mathematical utility functions for common operations.
417

418
```javascript { .api }
419
const utils: {
420
  /**
421
   * Convert degrees to radians
422
   * @param {Number} degrees - Angle in degrees
423
   * @returns {Number} Angle in radians
424
   */
425
  degToRad(degrees: number): number;
426

427
  /**
428
   * Convert radians to degrees
429
   * @param {Number} radians - Angle in radians
430
   * @returns {Number} Angle in degrees
431
   */
432
  radToDeg(radians: number): number;
433

434
  /**
435
   * Check if two numbers are equal within epsilon
436
   * @param {Number} a - First number
437
   * @param {Number} b - Second number
438
   * @param {Number} [epsilon] - Tolerance value
439
   * @returns {Boolean} True if equal within tolerance
440
   */
441
  aboutEqualNormals(a: number, b: number, epsilon?: number): boolean;
442
};
443
```
444

445
## Usage Examples
446

447
### Vector Calculations
448

449
```javascript
450
const { vec2, vec3 } = require('@jscad/modeling').maths;
451

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

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

462
// 3D vector operations
463
const a = vec3.fromValues(1, 0, 0);
464
const b = vec3.fromValues(0, 1, 0);
465
const cross = vec3.create();
466
vec3.cross(cross, a, b); // [0, 0, 1]
467

468
const dot = vec3.dot(a, b); // 0
469
```
470

471
### Matrix Transformations
472

473
```javascript
474
const { mat4, vec3 } = require('@jscad/modeling').maths;
475

476
// Create transformation matrix
477
const transform = mat4.create();
478
mat4.identity(transform);
479

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

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

489
const combined = mat4.create();
490
mat4.multiply(combined, transform, rotation);
491
```
492

493
### Geometric Calculations
494

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

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

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

506
// 3D plane operations
507
const p1 = vec3.fromValues(0, 0, 0);
508
const p2 = vec3.fromValues(1, 0, 0);
509
const p3 = vec3.fromValues(0, 1, 0);
510
const myPlane = plane.fromPoints(p1, p2, p3);
511

512
const point3D = vec3.fromValues(1, 1, 5);
513
const planeDistance = plane.distanceToPoint(myPlane, point3D);
514
const projected = plane.projectPoint(myPlane, point3D);
515
```
516

517
### Coordinate System Conversions
518

519
```javascript
520
const { utils } = require('@jscad/modeling').maths;
521

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

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

528
// Precision comparisons
529
const a = 1.0000001;
530
const b = 1.0000002;
531
const areEqual = utils.aboutEqualNormals(a, b, 0.00001); // true
532
```
533

534
## Advanced Mathematical Techniques
535

536
### Custom Transformations
537

538
```javascript
539
const { mat4, vec3, transform } = require('@jscad/modeling');
540

541
// Create complex transformation
542
const createTransform = (translation, rotation, scale) => {
543
  const matrix = mat4.create();
544
  mat4.identity(matrix);
545
  
546
  // Apply in order: scale, rotate, translate
547
  mat4.scale(matrix, matrix, scale);
548
  mat4.rotateX(matrix, matrix, rotation[0]);
549
  mat4.rotateY(matrix, matrix, rotation[1]);
550
  mat4.rotateZ(matrix, matrix, rotation[2]);
551
  mat4.translate(matrix, matrix, translation);
552
  
553
  return matrix;
554
};
555

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

562
### Intersection Calculations
563

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

567
// Line-plane intersection
568
const findLinePlaneIntersection = (line, plane) => {
569
  const dir = line3.direction(line);
570
  const normal = plane.normal(plane);
571
  const denom = vec3.dot(dir, normal);
572
  
573
  if (Math.abs(denom) < 1e-6) return null; // Parallel
574
  
575
  // Calculate intersection point
576
  const t = -plane.distanceToPoint(plane, line[0]) / denom;
577
  const intersection = vec3.create();
578
  vec3.scaleAndAdd(intersection, line[0], dir, t);
579
  
580
  return intersection;
581
};
582
```
583

584
### Performance Considerations
585

586
- Vector and matrix operations are optimized for performance
587
- Reuse output vectors/matrices when possible to reduce garbage collection
588
- Use the appropriate precision for your application
589
- Consider using typed arrays for large datasets