0
# Primitive Shapes
1

2
Primitives provide the building blocks for complex parts. Each primitive is a geometrical object that can be described mathematically, and therefore precise. Primitives can be logically combined, transformed, extruded, etc.
3

4
## Capabilities
5

6
### 2D Primitives
7

8
#### Arc
9

10
Creates a 2D arc segment defined by radius, start angle, and end angle.
11

12
```javascript { .api }
13
/**
14
 * Create a 2D arc segment
15
 * @param {Object} options - Arc configuration
16
 * @param {Array} [options.center=[0,0]] - Center point of the arc
17
 * @param {Number} [options.radius=1] - Radius of the arc
18
 * @param {Number} [options.startAngle=0] - Starting angle in radians
19
 * @param {Number} [options.endAngle=TAU] - Ending angle in radians (default: 2π)
20
 * @param {Number} [options.segments=32] - Number of segments for arc approximation
21
 * @param {Boolean} [options.makeTangent=false] - Make arc tangent at start/end
22
 * @returns {path2} 2D path representing the arc
23
 */
24
function arc(options?: {
25
  center?: [number, number],
26
  radius?: number,
27
  startAngle?: number,
28
  endAngle?: number,
29
  segments?: number,
30
  makeTangent?: boolean
31
}): path2;
32
```
33

34
#### Circle
35

36
Creates a 2D circle with specified center and radius.
37

38
```javascript { .api }
39
/**
40
 * Create a 2D circle
41
 * @param {Object} options - Circle configuration  
42
 * @param {Array} [options.center=[0,0]] - Center point of the circle
43
 * @param {Number} [options.radius=1] - Radius of the circle
44
 * @param {Number} [options.segments=32] - Number of segments for circle approximation
45
 * @param {Number} [options.startAngle=0] - Starting angle in radians
46
 * @param {Number} [options.endAngle=TAU] - Ending angle in radians (default: 2π)
47
 * @returns {geom2} 2D geometry representing the circle
48
 */
49
function circle(options?: {
50
  center?: [number, number],
51
  radius?: number,
52
  segments?: number,
53
  startAngle?: number,
54
  endAngle?: number
55
}): geom2;
56
```
57

58
#### Ellipse
59

60
Creates a 2D ellipse with configurable radii and rotation.
61

62
```javascript { .api }
63
/**
64
 * Create a 2D ellipse
65
 * @param {Object} options - Ellipse configuration
66
 * @param {Array} [options.center=[0,0]] - Center point of the ellipse
67
 * @param {Array} [options.radius=[1,1]] - X and Y radii of the ellipse  
68
 * @param {Number} [options.segments=32] - Number of segments for ellipse approximation
69
 * @param {Number} [options.startAngle=0] - Starting angle in radians
70
 * @param {Number} [options.endAngle=Math.PI*2] - Ending angle in radians
71
 * @returns {geom2} 2D geometry representing the ellipse
72
 */
73
function ellipse(options?: {
74
  center?: [number, number],
75
  radius?: [number, number],
76
  segments?: number,
77
  startAngle?: number,
78
  endAngle?: number
79
}): geom2;
80
```
81

82
#### Rectangle
83

84
Creates a 2D rectangle with specified dimensions and center.
85

86
```javascript { .api }
87
/**
88
 * Create a 2D rectangle
89
 * @param {Object} options - Rectangle configuration
90
 * @param {Array} [options.center=[0,0]] - Center point of the rectangle
91
 * @param {Array} [options.size=[2,2]] - Width and height of the rectangle
92
 * @returns {geom2} 2D geometry representing the rectangle
93
 */
94
function rectangle(options?: {
95
  center?: [number, number],
96
  size?: [number, number]
97
}): geom2;
98
```
99

100
#### Square
101

102
Creates a 2D square with specified size and center.
103

104
```javascript { .api }
105
/**
106
 * Create a 2D square
107
 * @param {Object} options - Square configuration
108
 * @param {Array} [options.center=[0,0]] - Center point of the square
109
 * @param {Number} [options.size=2] - Side length of the square
110
 * @returns {geom2} 2D geometry representing the square
111
 */
112
function square(options?: {
113
  center?: [number, number],
114
  size?: number
115
}): geom2;
116
```
117

118
#### Rounded Rectangle
119

120
Creates a 2D rectangle with rounded corners.
121

122
```javascript { .api }
123
/**
124
 * Create a 2D rounded rectangle
125
 * @param {Object} options - Rounded rectangle configuration
126
 * @param {Array} [options.center=[0,0]] - Center point of the rectangle
127
 * @param {Array} [options.size=[2,2]] - Width and height of the rectangle
128
 * @param {Number} [options.roundRadius=0.2] - Radius of the corner rounds
129
 * @param {Number} [options.segments=16] - Number of segments for rounded corners
130
 * @returns {geom2} 2D geometry representing the rounded rectangle
131
 */
132
function roundedRectangle(options?: {
133
  center?: [number, number],
134
  size?: [number, number],
135
  roundRadius?: number,
136
  segments?: number
137
}): geom2;
138
```
139

140
### Polygons and Lines
141

142
#### Polygon
143

144
Creates a 2D polygon from an array of points.
145

146
```javascript { .api }
147
/**
148
 * Create a 2D polygon from points with optional paths and orientation
149
 * @param {Object} options - Polygon configuration
150
 * @param {Array} options.points - Array of [x,y] points or nested arrays defining the polygon
151
 * @param {Array} [options.paths=[]] - Array of point indices or nested arrays of point indices
152
 * @param {String} [options.orientation='counterclockwise'] - Orientation of points ('counterclockwise' or 'clockwise')
153
 * @returns {geom2} 2D geometry representing the polygon
154
 */
155
function polygon(options: {
156
  points: Array<[number, number]> | Array<Array<[number, number]>>,
157
  paths?: Array<number> | Array<Array<number>>,
158
  orientation?: string
159
}): geom2;
160
```
161

162
#### Star
163

164
Creates a 2D star shape with configurable inner and outer radii.
165

166
```javascript { .api }
167
/**
168
 * Create a 2D star shape with configurable density
169
 * @param {Object} options - Star configuration
170
 * @param {Array} [options.center=[0,0]] - Center point of the star
171
 * @param {Number} [options.vertices=5] - Number of star vertices
172
 * @param {Number} [options.density=2] - Density (Q) of star for calculating inner radius
173
 * @param {Number} [options.outerRadius=1] - Outer radius of the star
174
 * @param {Number} [options.innerRadius=0] - Inner radius of the star (0 to calculate from density)
175
 * @param {Number} [options.startAngle=0] - Starting angle rotation in radians
176
 * @returns {geom2} 2D geometry representing the star
177
 */
178
function star(options?: {
179
  center?: [number, number],
180
  vertices?: number,
181
  density?: number,
182
  outerRadius?: number,
183
  innerRadius?: number,
184
  startAngle?: number
185
}): geom2;
186
```
187

188
#### Triangle
189

190
Creates a 2D triangle from three points.
191

192
```javascript { .api }
193
/**
194
 * Construct a triangle in two dimensional space using mathematical relationships
195
 * @param {Object} [options] - Triangle configuration
196
 * @param {String} [options.type='SSS'] - Type of triangle to construct (AAA, AAS, ASA, SAS, SSA, SSS)
197
 *   - A = angle (in radians), S = side length
198
 * @param {Array} [options.values=[1,1,1]] - Array of 3 values (angles in radians or side lengths)
199
 * @returns {geom2} 2D geometry representing the triangle
200
 */
201
function triangle(options?: {
202
  type?: string,
203
  values?: [number, number, number]
204
}): geom2;
205
```
206

207
#### Line
208

209
Creates a 2D line (path) from an array of points.
210

211
```javascript { .api }
212
/**
213
 * Create a 2D line from points
214
 * @param {Array} points - Array of [x,y] points defining the line path
215
 * @returns {path2} 2D path geometry representing the line
216
 */
217
function line(points: Array<[number, number]>): path2;
218
```
219

220
### 3D Primitives
221

222
#### Cube
223

224
Creates a 3D cube with equal sides.
225

226
```javascript { .api }
227
/**
228
 * Create a 3D cube with equal sides
229
 * @param {Object} options - Cube configuration
230
 * @param {Array} [options.center=[0,0,0]] - Center point of the cube
231
 * @param {Number} [options.size=2] - Side length of the cube
232
 * @returns {geom3} 3D geometry representing the cube
233
 */
234
function cube(options?: {
235
  center?: [number, number, number],
236
  size?: number
237
}): geom3;
238
```
239

240
#### Cuboid
241

242
Creates a 3D rectangular box with configurable dimensions.
243

244
```javascript { .api }
245
/**
246
 * Create a 3D rectangular box
247
 * @param {Object} options - Cuboid configuration
248
 * @param {Array} [options.center=[0,0,0]] - Center point of the cuboid
249
 * @param {Array} [options.size=[2,2,2]] - Width, depth, and height dimensions
250
 * @returns {geom3} 3D geometry representing the cuboid
251
 */
252
function cuboid(options?: {
253
  center?: [number, number, number],
254
  size?: [number, number, number]
255
}): geom3;
256
```
257

258
#### Rounded Cuboid
259

260
Creates a 3D rectangular box with rounded edges.
261

262
```javascript { .api }
263
/**
264
 * Create a 3D rounded rectangular box
265
 * @param {Object} options - Rounded cuboid configuration
266
 * @param {Array} [options.center=[0,0,0]] - Center point of the cuboid
267
 * @param {Array} [options.size=[2,2,2]] - Width, depth, and height dimensions
268
 * @param {Number} [options.roundRadius=0.2] - Radius of the edge rounds
269
 * @param {Number} [options.segments=16] - Number of segments for rounded edges
270
 * @returns {geom3} 3D geometry representing the rounded cuboid
271
 */
272
function roundedCuboid(options?: {
273
  center?: [number, number, number],
274
  size?: [number, number, number],
275
  roundRadius?: number,
276
  segments?: number
277
}): geom3;
278
```
279

280
#### Sphere
281

282
Creates a 3D sphere with specified radius and center.
283

284
```javascript { .api }
285
/**
286
 * Create a 3D sphere
287
 * @param {Object} options - Sphere configuration
288
 * @param {Array} [options.center=[0,0,0]] - Center point of the sphere
289
 * @param {Number} [options.radius=1] - Radius of the sphere
290
 * @param {Number} [options.segments=32] - Number of segments for sphere tessellation
291
 * @returns {geom3} 3D geometry representing the sphere
292
 */
293
function sphere(options?: {
294
  center?: [number, number, number],
295
  radius?: number,
296
  segments?: number
297
}): geom3;
298
```
299

300
#### Ellipsoid
301

302
Creates a 3D ellipsoid with configurable radii for each axis.
303

304
```javascript { .api }
305
/**
306
 * Create a 3D ellipsoid
307
 * @param {Object} options - Ellipsoid configuration
308
 * @param {Array} [options.center=[0,0,0]] - Center point of the ellipsoid
309
 * @param {Array} [options.radius=[1,1,1]] - X, Y, and Z radii of the ellipsoid
310
 * @param {Number} [options.segments=32] - Number of segments for ellipsoid tessellation
311
 * @returns {geom3} 3D geometry representing the ellipsoid
312
 */
313
function ellipsoid(options?: {
314
  center?: [number, number, number],
315
  radius?: [number, number, number],
316
  segments?: number
317
}): geom3;
318
```
319

320
#### Cylinder
321

322
Creates a 3D cylinder with specified height and radius.
323

324
```javascript { .api }
325
/**
326
 * Create a 3D cylinder
327
 * @param {Object} options - Cylinder configuration
328
 * @param {Array} [options.center=[0,0,0]] - Center point of the cylinder
329
 * @param {Number} [options.height=2] - Height of the cylinder
330
 * @param {Number} [options.radius=1] - Radius of the cylinder
331
 * @param {Number} [options.segments=32] - Number of segments for cylinder circumference
332
 * @returns {geom3} 3D geometry representing the cylinder
333
 */
334
function cylinder(options?: {
335
  center?: [number, number, number],
336
  height?: number,
337
  radius?: number,
338
  segments?: number
339
}): geom3;
340
```
341

342
#### Elliptic Cylinder
343

344
Creates a 3D cylinder with elliptical cross-section.
345

346
```javascript { .api }
347
/**
348
 * Create a 3D elliptic cylinder
349
 * @param {Object} options - Elliptic cylinder configuration
350
 * @param {Array} [options.center=[0,0,0]] - Center point of the cylinder
351
 * @param {Number} [options.height=2] - Height of the cylinder
352
 * @param {Array} [options.radius=[1,1]] - X and Y radii of the elliptical base
353
 * @param {Number} [options.segments=32] - Number of segments for cylinder circumference
354
 * @returns {geom3} 3D geometry representing the elliptic cylinder
355
 */
356
function cylinderElliptic(options?: {
357
  center?: [number, number, number],
358
  height?: number,
359
  radius?: [number, number],
360
  segments?: number
361
}): geom3;
362
```
363

364
#### Rounded Cylinder
365

366
Creates a 3D cylinder with rounded top and bottom edges.
367

368
```javascript { .api }
369
/**
370
 * Create a 3D rounded cylinder
371
 * @param {Object} options - Rounded cylinder configuration
372
 * @param {Array} [options.center=[0,0,0]] - Center point of the cylinder
373
 * @param {Number} [options.height=2] - Height of the cylinder
374
 * @param {Number} [options.radius=1] - Radius of the cylinder
375
 * @param {Number} [options.roundRadius=0.2] - Radius of the edge rounds
376
 * @param {Number} [options.segments=32] - Number of segments for cylinder circumference
377
 * @returns {geom3} 3D geometry representing the rounded cylinder
378
 */
379
function roundedCylinder(options?: {
380
  center?: [number, number, number],
381
  height?: number,
382
  radius?: number,
383
  roundRadius?: number,
384
  segments?: number
385
}): geom3;
386
```
387

388
#### Torus
389

390
Creates a 3D torus (donut shape) with major and minor radii.
391

392
```javascript { .api }
393
/**
394
 * Create a 3D torus
395
 * @param {Object} options - Torus configuration
396
 * @param {Array} [options.center=[0,0,0]] - Center point of the torus
397
 * @param {Number} [options.innerRadius=1] - Inner radius (minor radius)
398
 * @param {Number} [options.outerRadius=4] - Outer radius (major radius)
399
 * @param {Number} [options.innerSegments=32] - Number of segments for the inner circumference
400
 * @param {Number} [options.outerSegments=32] - Number of segments for the outer circumference
401
 * @param {Number} [options.innerRotation=0] - Rotation of the inner circumference
402
 * @param {Number} [options.startAngle=0] - Starting angle for partial torus
403
 * @param {Number} [options.outerRotation=Math.PI*2] - Ending angle for partial torus
404
 * @returns {geom3} 3D geometry representing the torus
405
 */
406
function torus(options?: {
407
  center?: [number, number, number],
408
  innerRadius?: number,
409
  outerRadius?: number,
410
  innerSegments?: number,
411
  outerSegments?: number,
412
  innerRotation?: number,
413
  startAngle?: number,
414
  outerRotation?: number
415
}): geom3;
416
```
417

418
### Advanced 3D Primitives
419

420
#### Geodesic Sphere
421

422
Creates a geodesic sphere with triangular faces for more uniform tessellation.
423

424
```javascript { .api }
425
/**
426
 * Create a geodesic sphere with triangular tessellation
427
 * @param {Object} options - Geodesic sphere configuration
428
 * @param {Array} [options.center=[0,0,0]] - Center point of the sphere
429
 * @param {Number} [options.radius=1] - Radius of the sphere
430
 * @param {Number} [options.frequency=6] - Frequency of subdivision (higher = more detailed)
431
 * @returns {geom3} 3D geometry representing the geodesic sphere
432
 */
433
function geodesicSphere(options?: {
434
  center?: [number, number, number],
435
  radius?: number,
436
  frequency?: number
437
}): geom3;
438
```
439

440
#### Polyhedron
441

442
Creates a custom 3D polyhedron from face definitions.
443

444
```javascript { .api }
445
/**
446
 * Create a custom 3D polyhedron from vertices and faces
447
 * @param {Object} options - Polyhedron configuration
448
 * @param {Array} options.points - Array of [x,y,z] vertex coordinates
449
 * @param {Array} options.faces - Array of face definitions (indices into points array)
450
 * @param {Array} [options.colors] - Optional array of RGBA colors per face
451
 * @returns {geom3} 3D geometry representing the polyhedron
452
 */
453
function polyhedron(options: {
454
  points: Array<[number, number, number]>,
455
  faces: Array<number[]>,
456
  colors?: Array<[number, number, number, number]>
457
}): geom3;
458
```
459

460
## Usage Examples
461

462
**Creating basic shapes:**
463

464
```javascript
465
const { arc, circle, cube, sphere } = require('@jscad/modeling').primitives;
466

467
// 2D shapes
468
const myCircle = circle({ radius: 5, segments: 64 });
469
const myArc = arc({ radius: 10, startAngle: 0, endAngle: Math.PI/2 });
470

471
// 3D shapes  
472
const myCube = cube({ size: 10, center: [0, 0, 5] });
473
const mySphere = sphere({ radius: 8, center: [10, 0, 0] });
474
```
475

476
**Creating complex shapes:**
477

478
```javascript
479
const { star, torus, geodesicSphere } = require('@jscad/modeling').primitives;
480

481
// Star with 8 points
482
const star8 = star({ 
483
  vertices: 8, 
484
  outerRadius: 10, 
485
  innerRadius: 5 
486
});
487

488
// Detailed torus
489
const detailedTorus = torus({
490
  innerRadius: 2,
491
  outerRadius: 8,
492
  innerSegments: 64,
493
  outerSegments: 128
494
});
495

496
// High-detail geodesic sphere
497
const geodesic = geodesicSphere({ 
498
  radius: 5, 
499
  frequency: 12 
500
});
501
```