0
# Extrusions
1

2
All 2D shapes (primitives or the results of operations) can be extruded in various ways to create 3D geometry. In all cases, the functions return new results and never change the original shapes. Extrusions convert 2D geometries (geom2) into 3D geometries (geom3).
3

4
## Capabilities
5

6
### Linear Extrusion
7

8
Extrude 2D shapes linearly along the Z-axis to create 3D solids.
9

10
```javascript { .api }
11
/**
12
 * Extrude 2D geometry linearly along the Z axis
13
 * @param {Object} options - Extrusion options
14
 * @param {Number} [options.height=1] - Height of the extrusion
15
 * @param {Number} [options.twistAngle=0] - Twist angle in radians along the height
16
 * @param {Number} [options.twistSteps=1] - Number of steps for twist (more steps = smoother twist)
17
 * @param {...Object} objects - 2D objects to extrude (geom2)
18
 * @returns {geom3|Array} Extruded 3D geometry
19
 */
20
function extrudeLinear(options?: {
21
  height?: number,
22
  twistAngle?: number,
23
  twistSteps?: number
24
}, ...objects: geom2[]): geom3 | geom3[];
25
```
26

27
**Usage Examples:**
28

29
```javascript
30
const { circle, rectangle, extrudeLinear } = require('@jscad/modeling');
31

32
// Simple linear extrusion
33
const circle2D = circle({ radius: 5 });
34
const cylinder = extrudeLinear({ height: 10 }, circle2D);
35

36
// Extrusion with twist
37
const square2D = rectangle({ size: [6, 6] });
38
const twistedExtrusion = extrudeLinear({
39
  height: 20,
40
  twistAngle: Math.PI,
41
  twistSteps: 20
42
}, square2D);
43
```
44

45
### Rotational Extrusion
46

47
Extrude 2D shapes by rotating them around the Y-axis to create rotationally symmetric 3D shapes.
48

49
```javascript { .api }
50
/**
51
 * Extrude 2D geometry by rotating around the Y axis
52
 * @param {Object} options - Rotation extrusion options
53
 * @param {Number} [options.angle=Math.PI*2] - Angle of rotation in radians (default: full rotation)
54
 * @param {Number} [options.startAngle=0] - Starting angle in radians
55
 * @param {Number} [options.segments=12] - Number of segments for the rotation
56
 * @param {...Object} objects - 2D objects to extrude (geom2)
57
 * @returns {geom3|Array} Rotationally extruded 3D geometry
58
 */
59
function extrudeRotate(options?: {
60
  angle?: number,
61
  startAngle?: number,
62
  segments?: number
63
}, ...objects: geom2[]): geom3 | geom3[];
64
```
65

66
**Usage Examples:**
67

68
```javascript
69
const { polygon, extrudeRotate } = require('@jscad/modeling');
70

71
// Create a bowl by rotating a profile
72
const profile = polygon({
73
  points: [[0, 0], [10, 0], [12, 2], [10, 8], [8, 10], [0, 10]]
74
});
75
const bowl = extrudeRotate({ segments: 32 }, profile);
76

77
// Create partial rotation (e.g., 3/4 of a circle)
78
const partialRotation = extrudeRotate({
79
  angle: Math.PI * 1.5,
80
  segments: 24
81
}, profile);
82
```
83

84
### Rectangular Extrusion
85

86
Extrude 2D shapes in a rectangular pattern, creating multiple extruded copies arranged in a grid.
87

88
```javascript { .api }
89
/**
90
 * Extrude 2D geometry in a rectangular pattern
91
 * @param {Object} options - Rectangular extrusion options
92
 * @param {Number} [options.height=1] - Height of each extrusion
93
 * @param {Array} [options.size=[1,1]] - Number of copies in [X,Y] directions
94
 * @param {Array} [options.spacing=[1,1]] - Spacing between copies in [X,Y] directions
95
 * @param {...Object} objects - 2D objects to extrude (geom2)
96
 * @returns {geom3|Array} Rectangular pattern of extruded geometries
97
 */
98
function extrudeRectangular(options?: {
99
  height?: number,
100
  size?: [number, number],
101
  spacing?: [number, number]
102
}, ...objects: geom2[]): geom3 | geom3[];
103
```
104

105
**Usage Examples:**
106

107
```javascript
108
const { circle, extrudeRectangular } = require('@jscad/modeling');
109

110
// Create a grid of extruded circles
111
const smallCircle = circle({ radius: 2 });
112
const pillarsGrid = extrudeRectangular({
113
  height: 15,
114
  size: [4, 3],    // 4x3 grid
115
  spacing: [8, 8]   // 8 units apart
116
}, smallCircle);
117
```
118

119
### Helical Extrusion
120

121
Extrude 2D shapes along a helical (spiral) path to create twisted, coiled geometries.
122

123
```javascript { .api }
124
/**
125
 * Extrude 2D geometry along a helical path
126
 * @param {Object} options - Helical extrusion options
127
 * @param {Number} options.angle - Total rotation angle in radians
128
 * @param {Number} options.pitch - Vertical distance per rotation
129
 * @param {Number} [options.height] - Total height (alternative to pitch*rotations)
130
 * @param {Number} [options.segments=32] - Number of segments for the helix
131
 * @param {...Object} objects - 2D objects to extrude (geom2)
132
 * @returns {geom3|Array} Helically extruded 3D geometry
133
 */
134
function extrudeHelical(options: {
135
  angle: number,
136
  pitch: number,
137
  height?: number,
138
  segments?: number
139
}, ...objects: geom2[]): geom3 | geom3[];
140
```
141

142
**Usage Examples:**
143

144
```javascript
145
const { rectangle, extrudeHelical } = require('@jscad/modeling');
146

147
// Create a helical spring profile
148
const springProfile = rectangle({ size: [1, 0.5] });
149
const spring = extrudeHelical({
150
  angle: Math.PI * 10,  // 5 full rotations
151
  pitch: 2,             // 2 units vertical per rotation
152
  segments: 100
153
}, springProfile);
154

155
// Create a twisted tower
156
const { polygon } = require('@jscad/modeling').primitives;
157
const towerProfile = polygon({
158
  points: [[0, 0], [2, 0], [1.5, 3], [0.5, 3]]
159
});
160
const twistedTower = extrudeHelical({
161
  angle: Math.PI * 4,
162
  pitch: 5,
163
  segments: 64
164
}, towerProfile);
165
```
166

167
### Slice-Based Extrusion
168

169
Extrude using a series of 2D slices to create complex shapes with varying cross-sections.
170

171
```javascript { .api }
172
/**
173
 * Extrude from a series of 2D slices
174
 * @param {Object} options - Slice extrusion options
175
 * @param {Function} [options.callback] - Function to transform each slice
176
 * @param {Number} [options.numberOfSlices=2] - Number of slices to create
177
 * @param {Boolean} [options.capStart=true] - Whether to cap the start
178
 * @param {Boolean} [options.capEnd=true] - Whether to cap the end
179
 * @param {Array} slices - Array of 2D geometries representing each slice
180
 * @returns {geom3} 3D geometry created from slices
181
 */
182
function extrudeFromSlices(options?: {
183
  callback?: (progress: number, index: number, base: geom2) => geom2,
184
  numberOfSlices?: number,
185
  capStart?: boolean,
186
  capEnd?: boolean
187
}, slices: geom2[]): geom3;
188
```
189

190
**Usage Examples:**
191

192
```javascript
193
const { circle, rectangle, extrudeFromSlices, scale, translate } = require('@jscad/modeling');
194

195
// Create a shape that transitions from circle to rectangle
196
const bottomSlice = circle({ radius: 5 });
197
const topSlice = rectangle({ size: [8, 8] });
198

199
// Create intermediate slices
200
const slices = [];
201
for (let i = 0; i <= 10; i++) {
202
  const t = i / 10;
203
  const slice = translate([0, 0, i * 2], 
204
    scale([1 - t * 0.3, 1 - t * 0.3], bottomSlice)
205
  );
206
  slices.push(slice);
207
}
208
slices.push(translate([0, 0, 22], topSlice));
209

210
const morphedShape = extrudeFromSlices({}, slices);
211
```
212

213
### Projection
214

215
Project 3D geometries onto 2D planes, essentially the reverse of extrusion.
216

217
```javascript { .api }
218
/**
219
 * Project 3D geometry onto a 2D plane
220
 * @param {Object} options - Projection options
221
 * @param {Array} [options.axis=[0,0,1]] - Axis to project along
222
 * @param {Number} [options.origin=0] - Origin point on the axis
223
 * @param {...Object} objects - 3D objects to project
224
 * @returns {geom2|Array} Projected 2D geometry
225
 */
226
function project(options?: {
227
  axis?: [number, number, number],
228
  origin?: number
229
}, ...objects: geom3[]): geom2 | geom2[];
230
```
231

232
**Usage Examples:**
233

234
```javascript
235
const { cube, sphere, project, union } = require('@jscad/modeling');
236

237
// Project a 3D shape to get its 2D footprint
238
const complex3D = union(
239
  cube({ size: 10 }),
240
  sphere({ radius: 8, center: [5, 5, 5] })
241
);
242
const footprint = project({}, complex3D);
243

244
// Project along different axis
245
const sideView = project({ axis: [1, 0, 0] }, complex3D);
246
```
247

248
## Advanced Extrusion Techniques
249

250
### Multi-Step Extrusions
251

252
Combine multiple extrusion operations for complex shapes:
253

254
```javascript
255
const { circle, extrudeLinear, extrudeRotate } = require('@jscad/modeling');
256

257
// Create a complex bottle shape
258
const baseProfile = circle({ radius: 3 });
259
const cylinder1 = extrudeLinear({ height: 10 }, baseProfile);
260

261
const neckProfile = circle({ radius: 1 });
262
const neck = translate([0, 0, 10], extrudeLinear({ height: 5 }, neckProfile));
263

264
const bottle = union(cylinder1, neck);
265
```
266

267
### Custom Slice Functions
268

269
Create complex shapes using mathematical functions for slice generation:
270

271
```javascript
272
const { circle, extrudeFromSlices, scale, translate } = require('@jscad/modeling');
273

274
const createSlices = (baseShape, height, steps) => {
275
  const slices = [];
276
  
277
  for (let i = 0; i <= steps; i++) {
278
    const t = i / steps;
279
    const z = t * height;
280
    
281
    // Create scaling that varies with height
282
    const scaleX = 1 + 0.5 * Math.sin(t * Math.PI * 4);
283
    const scaleY = 1 + 0.3 * Math.cos(t * Math.PI * 6);
284
    
285
    const slice = translate([0, 0, z],
286
      scale([scaleX, scaleY], baseShape)
287
    );
288
    slices.push(slice);
289
  }
290
  
291
  return slices;
292
};
293

294
const base = circle({ radius: 3 });
295
const complexShape = extrudeFromSlices({}, createSlices(base, 20, 30));
296
```
297

298
### Performance Considerations
299

300
- Higher segment counts create smoother curves but increase computation time
301
- Twist operations with many steps can be CPU-intensive
302
- Consider the final application when choosing segment counts
303
- For 3D printing, moderate segment counts often provide the best balance
304

305
### Common Extrusion Patterns
306

307
```javascript
308
const { rectangle, circle, extrudeLinear, extrudeRotate } = require('@jscad/modeling');
309

310
// Architectural column
311
const columnBase = circle({ radius: 5 });
312
const column = extrudeLinear({ height: 30 }, columnBase);
313

314
// Gear tooth profile
315
const toothProfile = polygon({
316
  points: [[0, 0], [1, 0], [1.2, 0.3], [1, 0.6], [0, 0.6]]
317
});
318
const gear = extrudeRotate({ segments: 24 }, toothProfile);
319

320
// Threaded rod
321
const threadProfile = polygon({
322
  points: [[2.8, -0.1], [3.2, -0.1], [3.2, 0.1], [2.8, 0.1]]
323
});
324
const threadedRod = extrudeHelical({
325
  angle: Math.PI * 20,
326
  pitch: 0.5,
327
  segments: 200
328
}, threadProfile);
329
```