0
# Geometry Types
1

2
Geometries are objects that represent the contents of primitives or the results of operations. Note: Geometries are considered immutable, so never change the contents directly. The library provides five main geometry types for different geometric representations.
3

4
## Capabilities
5

6
### 2D Geometry (geom2)
7

8
2D geometry consisting of sides (line segments) that form closed shapes.
9

10
```javascript { .api }
11
const geom2: {
12
  /**
13
   * Create a new 2D geometry from sides
14
   * @param {Array} [sides] - Array of sides, each side is array of two points
15
   * @returns {geom2} New 2D geometry
16
   */
17
  create(sides?: Array<[[number, number], [number, number]]>): geom2;
18

19
  /**
20
   * Create deep copy of 2D geometry
21
   * @param {geom2} geometry - Geometry to clone
22
   * @returns {geom2} Cloned geometry
23
   */
24
  clone(geometry: geom2): geom2;
25

26
  /**
27
   * Check if object is a geom2
28
   * @param {Object} object - Object to test
29
   * @returns {Boolean} True if object is geom2
30
   */
31
  isA(object: any): boolean;
32

33
  /**
34
   * Get the sides of a 2D geometry
35
   * @param {geom2} geometry - Input geometry
36
   * @returns {Array} Array of sides
37
   */
38
  toSides(geometry: geom2): Array<[[number, number], [number, number]]>;
39

40
  /**
41
   * Get outline points of 2D geometry
42
   * @param {geom2} geometry - Input geometry
43
   * @returns {Array} Array of [x,y] points
44
   */
45
  toPoints(geometry: geom2): Array<[number, number]>;
46

47
  /**
48
   * Reverse the orientation of 2D geometry
49
   * @param {geom2} geometry - Input geometry
50
   * @returns {geom2} Reversed geometry
51
   */
52
  reverse(geometry: geom2): geom2;
53

54
  /**
55
   * Transform 2D geometry using matrix
56
   * @param {mat4} matrix - Transformation matrix
57
   * @param {geom2} geometry - Input geometry
58
   * @returns {geom2} Transformed geometry
59
   */
60
  transform(matrix: mat4, geometry: geom2): geom2;
61

62
  /**
63
   * Validate 2D geometry for errors
64
   * @param {geom2} geometry - Geometry to validate
65
   * @returns {Boolean} True if valid
66
   */
67
  validate(geometry: geom2): boolean;
68
};
69
```
70

71
**Usage Examples:**
72

73
```javascript
74
const { geom2 } = require('@jscad/modeling').geometries;
75

76
// Create geometry from sides
77
const sides = [
78
  [[0, 0], [5, 0]],
79
  [[5, 0], [5, 3]], 
80
  [[5, 3], [0, 3]],
81
  [[0, 3], [0, 0]]
82
];
83
const rect = geom2.create(sides);
84

85
// Clone geometry
86
const rectCopy = geom2.clone(rect);
87

88
// Get outline points
89
const points = geom2.toPoints(rect);
90
// [[0, 0], [5, 0], [5, 3], [0, 3]]
91

92
// Check if valid geometry
93
const isValid = geom2.validate(rect);
94
```
95

96
### 3D Geometry (geom3)
97

98
3D geometry consisting of polygons that form solid shapes.
99

100
```javascript { .api }
101
const geom3: {
102
  /**
103
   * Create a new 3D geometry from polygons
104
   * @param {Array} [polygons] - Array of poly3 objects
105
   * @returns {geom3} New 3D geometry
106
   */
107
  create(polygons?: poly3[]): geom3;
108

109
  /**
110
   * Create deep copy of 3D geometry
111
   * @param {geom3} geometry - Geometry to clone
112
   * @returns {geom3} Cloned geometry
113
   */
114
  clone(geometry: geom3): geom3;
115

116
  /**
117
   * Check if object is a geom3
118
   * @param {Object} object - Object to test
119
   * @returns {Boolean} True if object is geom3
120
   */
121
  isA(object: any): boolean;
122

123
  /**
124
   * Get the polygons of a 3D geometry
125
   * @param {geom3} geometry - Input geometry
126
   * @returns {Array} Array of poly3 objects
127
   */
128
  toPolygons(geometry: geom3): poly3[];
129

130
  /**
131
   * Get all vertices of 3D geometry
132
   * @param {geom3} geometry - Input geometry
133
   * @returns {Array} Array of [x,y,z] vertices
134
   */
135
  toVertices(geometry: geom3): Array<[number, number, number]>;
136

137
  /**
138
   * Reverse the orientation of 3D geometry
139
   * @param {geom3} geometry - Input geometry
140
   * @returns {geom3} Reversed geometry
141
   */
142
  reverse(geometry: geom3): geom3;
143

144
  /**
145
   * Transform 3D geometry using matrix
146
   * @param {mat4} matrix - Transformation matrix
147
   * @param {geom3} geometry - Input geometry
148
   * @returns {geom3} Transformed geometry
149
   */
150
  transform(matrix: mat4, geometry: geom3): geom3;
151

152
  /**
153
   * Validate 3D geometry for errors
154
   * @param {geom3} geometry - Geometry to validate
155
   * @returns {Boolean} True if valid
156
   */
157
  validate(geometry: geom3): boolean;
158
};
159
```
160

161
**Usage Examples:**
162

163
```javascript
164
const { geom3, poly3 } = require('@jscad/modeling').geometries;
165

166
// Create simple tetrahedron
167
const vertices1 = [[0, 0, 0], [1, 0, 0], [0.5, 1, 0]];
168
const vertices2 = [[0, 0, 0], [0.5, 1, 0], [0.5, 0.5, 1]];
169
const vertices3 = [[1, 0, 0], [0.5, 1, 0], [0.5, 0.5, 1]];
170
const vertices4 = [[0, 0, 0], [1, 0, 0], [0.5, 0.5, 1]];
171

172
const polygons = [
173
  poly3.create(vertices1),
174
  poly3.create(vertices2),
175
  poly3.create(vertices3),
176
  poly3.create(vertices4)
177
];
178
const tetrahedron = geom3.create(polygons);
179

180
// Get all vertices
181
const allVertices = geom3.toVertices(tetrahedron);
182

183
// Validate geometry
184
const isValid = geom3.validate(tetrahedron);
185
```
186

187
### 2D Path (path2)
188

189
2D geometry consisting of ordered points that form an open or closed path.
190

191
```javascript { .api }
192
const path2: {
193
  /**
194
   * Create a new 2D path from points
195
   * @param {Array} [points] - Array of [x,y] points
196
   * @param {Boolean} [isClosed=false] - Whether path is closed
197
   * @returns {path2} New 2D path
198
   */
199
  create(points?: Array<[number, number]>, isClosed?: boolean): path2;
200

201
  /**
202
   * Create 2D path from points array
203
   * @param {Array} points - Array of [x,y] points
204
   * @returns {path2} New path
205
   */
206
  fromPoints(points: Array<[number, number]>): path2;
207

208
  /**
209
   * Create deep copy of 2D path
210
   * @param {path2} geometry - Path to clone
211
   * @returns {path2} Cloned path
212
   */
213
  clone(geometry: path2): path2;
214

215
  /**
216
   * Check if object is a path2
217
   * @param {Object} object - Object to test
218
   * @returns {Boolean} True if object is path2
219
   */
220
  isA(object: any): boolean;
221

222
  /**
223
   * Get points of 2D path
224
   * @param {path2} geometry - Input path
225
   * @returns {Array} Array of [x,y] points
226
   */
227
  toPoints(geometry: path2): Array<[number, number]>;
228

229
  /**
230
   * Close the 2D path by connecting last point to first
231
   * @param {path2} geometry - Input path
232
   * @returns {path2} Closed path
233
   */
234
  close(geometry: path2): path2;
235

236
  /**
237
   * Reverse the direction of 2D path
238
   * @param {path2} geometry - Input path
239
   * @returns {path2} Reversed path
240
   */
241
  reverse(geometry: path2): path2;
242

243
  /**
244
   * Transform 2D path using matrix
245
   * @param {mat4} matrix - Transformation matrix
246
   * @param {path2} geometry - Input path
247
   * @returns {path2} Transformed path
248
   */
249
  transform(matrix: mat4, geometry: path2): path2;
250

251
  /**
252
   * Append points to existing path
253
   * @param {path2} geometry - Input path
254
   * @param {...Array} points - Points to append
255
   * @returns {path2} Extended path
256
   */
257
  appendPoints(geometry: path2, ...points: Array<[number, number]>): path2;
258
};
259
```
260

261
**Usage Examples:**
262

263
```javascript
264
const { path2 } = require('@jscad/modeling').geometries;
265

266
// Create open path
267
const points = [[0, 0], [5, 0], [5, 5], [2, 8], [0, 5]];
268
const openPath = path2.fromPoints(points);
269

270
// Create closed path
271
const closedPath = path2.close(openPath);
272

273
// Append more points
274
const extended = path2.appendPoints(openPath, [10, 10], [15, 5]);
275

276
// Get path points
277
const pathPoints = path2.toPoints(extended);
278
```
279

280
### 2D Polygon (poly2)
281

282
2D polygon consisting of ordered vertices that form a closed shape.
283

284
```javascript { .api }
285
const poly2: {
286
  /**
287
   * Create a new 2D polygon from vertices
288
   * @param {Array} [vertices] - Array of [x,y] vertices
289
   * @returns {poly2} New 2D polygon
290
   */
291
  create(vertices?: Array<[number, number]>): poly2;
292

293
  /**
294
   * Create deep copy of 2D polygon
295
   * @param {poly2} geometry - Polygon to clone
296
   * @returns {poly2} Cloned polygon
297
   */
298
  clone(geometry: poly2): poly2;
299

300
  /**
301
   * Check if object is a poly2
302
   * @param {Object} object - Object to test
303
   * @returns {Boolean} True if object is poly2
304
   */
305
  isA(object: any): boolean;
306

307
  /**
308
   * Get vertices of 2D polygon
309
   * @param {poly2} geometry - Input polygon
310
   * @returns {Array} Array of [x,y] vertices
311
   */
312
  toVertices(geometry: poly2): Array<[number, number]>;
313

314
  /**
315
   * Reverse the orientation of 2D polygon
316
   * @param {poly2} geometry - Input polygon
317
   * @returns {poly2} Reversed polygon
318
   */
319
  reverse(geometry: poly2): poly2;
320

321
  /**
322
   * Transform 2D polygon using matrix
323
   * @param {mat4} matrix - Transformation matrix
324
   * @param {poly2} geometry - Input polygon
325
   * @returns {poly2} Transformed polygon
326
   */
327
  transform(matrix: mat4, geometry: poly2): poly2;
328
};
329
```
330

331
**Usage Examples:**
332

333
```javascript
334
const { poly2 } = require('@jscad/modeling').geometries;
335

336
// Create triangle
337
const vertices = [[0, 0], [5, 0], [2.5, 4]];
338
const triangle = poly2.create(vertices);
339

340
// Get vertices
341
const triangleVertices = poly2.toVertices(triangle);
342

343
// Reverse orientation (clockwise to counter-clockwise)
344
const reversed = poly2.reverse(triangle);
345
```
346

347
### 3D Polygon (poly3)
348

349
3D polygon consisting of ordered vertices that form a planar face in 3D space.
350

351
```javascript { .api }
352
const poly3: {
353
  /**
354
   * Create a new 3D polygon from vertices
355
   * @param {Array} [vertices] - Array of [x,y,z] vertices
356
   * @returns {poly3} New 3D polygon
357
   */
358
  create(vertices?: Array<[number, number, number]>): poly3;
359

360
  /**
361
   * Create deep copy of 3D polygon
362
   * @param {poly3} geometry - Polygon to clone
363
   * @returns {poly3} Cloned polygon
364
   */
365
  clone(geometry: poly3): poly3;
366

367
  /**
368
   * Check if object is a poly3
369
   * @param {Object} object - Object to test
370
   * @returns {Boolean} True if object is poly3
371
   */
372
  isA(object: any): boolean;
373

374
  /**
375
   * Get vertices of 3D polygon
376
   * @param {poly3} geometry - Input polygon
377
   * @returns {Array} Array of [x,y,z] vertices
378
   */
379
  toVertices(geometry: poly3): Array<[number, number, number]>;
380

381
  /**
382
   * Get plane equation of 3D polygon
383
   * @param {poly3} geometry - Input polygon
384
   * @returns {Array} Plane as [a,b,c,d]
385
   */
386
  plane(geometry: poly3): [number, number, number, number];
387

388
  /**
389
   * Reverse the orientation of 3D polygon
390
   * @param {poly3} geometry - Input polygon
391
   * @returns {poly3} Reversed polygon
392
   */
393
  reverse(geometry: poly3): poly3;
394

395
  /**
396
   * Transform 3D polygon using matrix
397
   * @param {mat4} matrix - Transformation matrix
398
   * @param {poly3} geometry - Input polygon
399
   * @returns {poly3} Transformed polygon
400
   */
401
  transform(matrix: mat4, geometry: poly3): poly3;
402
};
403
```
404

405
**Usage Examples:**
406

407
```javascript
408
const { poly3 } = require('@jscad/modeling').geometries;
409

410
// Create 3D triangle
411
const vertices = [[0, 0, 0], [5, 0, 0], [2.5, 4, 2]];
412
const triangle3D = poly3.create(vertices);
413

414
// Get plane equation
415
const trianglePlane = poly3.plane(triangle3D);
416

417
// Get vertices
418
const vertices3D = poly3.toVertices(triangle3D);
419
```
420

421
## Advanced Geometry Operations
422

423
### Geometry Conversion
424

425
Convert between different geometry types:
426

427
```javascript
428
const { geom2, path2, poly2 } = require('@jscad/modeling').geometries;
429

430
// Convert path to geom2 (if closed)
431
const points = [[0, 0], [5, 0], [5, 5], [0, 5], [0, 0]];
432
const closedPath = path2.fromPoints(points);
433
const convertedGeom = geom2.create(path2.toSides(closedPath));
434

435
// Extract polygon from geom2
436
const sides = geom2.toSides(convertedGeom);
437
const outline = sides.map(side => side[0]); // First point of each side
438
const polygon = poly2.create(outline);
439
```
440

441
### Geometry Validation and Repair
442

443
Validate and repair geometry issues:
444

445
```javascript
446
const { geom2, geom3 } = require('@jscad/modeling').geometries;
447

448
const validateAndRepair = (geometry) => {
449
  if (geom2.isA(geometry)) {
450
    const isValid = geom2.validate(geometry);
451
    if (!isValid) {
452
      console.warn('Invalid 2D geometry detected');
453
      // Attempt repair by removing duplicate points
454
      const points = geom2.toPoints(geometry);
455
      const uniquePoints = points.filter((point, index) => {
456
        return index === 0 || 
457
               point[0] !== points[index-1][0] || 
458
               point[1] !== points[index-1][1];
459
      });
460
      return geom2.fromPoints(uniquePoints);
461
    }
462
  }
463
  return geometry;
464
};
465
```
466

467
### Custom Geometry Creation
468

469
Create complex geometries programmatically:
470

471
```javascript
472
const { geom2, poly2 } = require('@jscad/modeling').geometries;
473

474
// Create star shape using polygon
475
const createStar = (points, outerRadius, innerRadius) => {
476
  const vertices = [];
477
  const angleStep = (Math.PI * 2) / points;
478
  
479
  for (let i = 0; i < points; i++) {
480
    // Outer point
481
    const outerAngle = i * angleStep;
482
    vertices.push([
483
      Math.cos(outerAngle) * outerRadius,
484
      Math.sin(outerAngle) * outerRadius
485
    ]);
486
    
487
    // Inner point
488
    const innerAngle = (i + 0.5) * angleStep;
489
    vertices.push([
490
      Math.cos(innerAngle) * innerRadius,
491
      Math.sin(innerAngle) * innerRadius
492
    ]);
493
  }
494
  
495
  return poly2.create(vertices);
496
};
497

498
const star = createStar(5, 10, 5);
499
```
500

501
### Geometry Analysis
502

503
Analyze geometry properties:
504

505
```javascript
506
const { geom2, geom3, measureArea, measureVolume } = require('@jscad/modeling');
507

508
const analyzeGeometry = (geometry) => {
509
  const analysis = {};
510
  
511
  if (geom2.isA(geometry)) {
512
    analysis.type = '2D';
513
    analysis.points = geom2.toPoints(geometry);
514
    analysis.sides = geom2.toSides(geometry).length;
515
    analysis.area = measureArea(geometry);
516
  } else if (geom3.isA(geometry)) {
517
    analysis.type = '3D';
518
    analysis.polygons = geom3.toPolygons(geometry).length;
519
    analysis.vertices = geom3.toVertices(geometry).length;
520
    analysis.volume = measureVolume(geometry);
521
    analysis.surfaceArea = measureArea(geometry);
522
  }
523
  
524
  return analysis;
525
};
526
```
527

528
### Performance Considerations
529

530
- Geometry objects are immutable - operations create new instances
531
- Use clone() for deep copies when modifying geometries
532
- Validate geometries after complex operations
533
- Consider using appropriate geometry type for your use case:
534
  - path2 for open curves and drawing operations
535
  - geom2 for solid 2D shapes and boolean operations
536
  - poly2/poly3 for direct polygon manipulation
537
  - geom3 for solid 3D shapes and volumes