0
# Transformations
1

2
All shapes (primitives or the results of operations) can be transformed, such as scaled or rotated. In all cases, the functions return new results and never change the original shapes. Transformations use a right-handed coordinate system with consistent mathematical conventions.
3

4
## Capabilities
5

6
### Translation
7

8
Move shapes to new positions in 2D or 3D space.
9

10
```javascript { .api }
11
/**
12
 * Translate geometries by the given offsets
13
 * @param {Array} offsets - [x,y] for 2D or [x,y,z] for 3D translation
14
 * @param {...Object} objects - Objects to translate
15
 * @returns {Object|Array} Translated object(s)
16
 */
17
function translate(offsets: [number, number] | [number, number, number], ...objects: any[]): any;
18

19
/**
20
 * Translate geometries along the X axis
21
 * @param {Number} offset - Distance to translate along X axis
22
 * @param {...Object} objects - Objects to translate
23
 * @returns {Object|Array} Translated object(s)
24
 */
25
function translateX(offset: number, ...objects: any[]): any;
26

27
/**
28
 * Translate geometries along the Y axis  
29
 * @param {Number} offset - Distance to translate along Y axis
30
 * @param {...Object} objects - Objects to translate
31
 * @returns {Object|Array} Translated object(s)
32
 */
33
function translateY(offset: number, ...objects: any[]): any;
34

35
/**
36
 * Translate geometries along the Z axis
37
 * @param {Number} offset - Distance to translate along Z axis
38
 * @param {...Object} objects - Objects to translate
39
 * @returns {Object|Array} Translated object(s)
40
 */
41
function translateZ(offset: number, ...objects: any[]): any;
42
```
43

44
**Usage Examples:**
45

46
```javascript
47
const { cube, sphere, translate, translateX, translateY, translateZ } = require('@jscad/modeling');
48

49
// 3D translation
50
const myCube = cube({ size: 10 });
51
const movedCube = translate([5, 10, 15], myCube);
52

53
// Individual axis translations
54
const sphere1 = sphere({ radius: 3 });
55
const movedRight = translateX(10, sphere1);
56
const movedUp = translateY(5, sphere1);  
57
const movedForward = translateZ(-8, sphere1);
58

59
// Multiple objects
60
const objects = [cube({ size: 5 }), sphere({ radius: 3 })];
61
const allMoved = translate([0, 0, 10], ...objects);
62
```
63

64
### Rotation
65

66
Rotate shapes around axes or arbitrary vectors.
67

68
```javascript { .api }
69
/**
70
 * Rotate geometries by the given angles
71
 * @param {Array|Number} angles - [x,y,z] angles in radians, or single angle for Z rotation
72
 * @param {...Object} objects - Objects to rotate  
73
 * @returns {Object|Array} Rotated object(s)
74
 */
75
function rotate(angles: [number, number, number] | number, ...objects: any[]): any;
76

77
/**
78
 * Rotate geometries around the X axis
79
 * @param {Number} angle - Angle in radians
80
 * @param {...Object} objects - Objects to rotate
81
 * @returns {Object|Array} Rotated object(s)
82
 */
83
function rotateX(angle: number, ...objects: any[]): any;
84

85
/**
86
 * Rotate geometries around the Y axis
87
 * @param {Number} angle - Angle in radians  
88
 * @param {...Object} objects - Objects to rotate
89
 * @returns {Object|Array} Rotated object(s)
90
 */
91
function rotateY(angle: number, ...objects: any[]): any;
92

93
/**
94
 * Rotate geometries around the Z axis
95
 * @param {Number} angle - Angle in radians
96
 * @param {...Object} objects - Objects to rotate
97
 * @returns {Object|Array} Rotated object(s)
98
 */
99
function rotateZ(angle: number, ...objects: any[]): any;
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
const { cube, cylinder, rotate, rotateX, rotateY, rotateZ } = require('@jscad/modeling');
106

107
// Rotate around multiple axes
108
const myCube = cube({ size: 10 });
109
const rotatedCube = rotate([Math.PI/4, Math.PI/6, Math.PI/3], myCube);
110

111
// Single axis rotations  
112
const myCylinder = cylinder({ height: 20, radius: 5 });
113
const sidewaysCylinder = rotateY(Math.PI/2, myCylinder);
114

115
// 2D rotation (Z axis)
116
const { rectangle } = require('@jscad/modeling').primitives;
117
const rect = rectangle({ size: [10, 5] });
118
const rotatedRect = rotateZ(Math.PI/4, rect);
119
```
120

121
### Scaling
122

123
Scale shapes by factors along each axis.
124

125
```javascript { .api }
126
/**
127
 * Scale geometries by the given factors  
128
 * @param {Array|Number} factors - [x,y,z] scale factors, [x,y] for 2D, or single factor for uniform scaling
129
 * @param {...Object} objects - Objects to scale
130
 * @returns {Object|Array} Scaled object(s)
131
 */
132
function scale(factors: [number, number, number] | [number, number] | number, ...objects: any[]): any;
133

134
/**
135
 * Scale geometries along the X axis
136
 * @param {Number} factor - Scale factor for X axis
137
 * @param {...Object} objects - Objects to scale
138
 * @returns {Object|Array} Scaled object(s)
139
 */
140
function scaleX(factor: number, ...objects: any[]): any;
141

142
/**
143
 * Scale geometries along the Y axis
144
 * @param {Number} factor - Scale factor for Y axis
145
 * @param {...Object} objects - Objects to scale  
146
 * @returns {Object|Array} Scaled object(s)
147
 */
148
function scaleY(factor: number, ...objects: any[]): any;
149

150
/**
151
 * Scale geometries along the Z axis
152
 * @param {Number} factor - Scale factor for Z axis
153
 * @param {...Object} objects - Objects to scale
154
 * @returns {Object|Array} Scaled object(s)
155
 */
156
function scaleZ(factor: number, ...objects: any[]): any;
157
```
158

159
**Usage Examples:**
160

161
```javascript
162
const { cube, sphere, scale, scaleX, scaleY, scaleZ } = require('@jscad/modeling');
163

164
// Uniform scaling
165
const myCube = cube({ size: 10 });
166
const biggerCube = scale(2, myCube);
167
const smallerCube = scale(0.5, myCube);
168

169
// Non-uniform scaling
170
const mySphere = sphere({ radius: 5 });  
171
const ellipsoid = scale([2, 1, 0.5], mySphere);
172

173
// Individual axis scaling
174
const stretched = scaleX(3, myCube);
175
const flattened = scaleZ(0.1, myCube);
176
```
177

178
### Mirroring
179

180
Mirror shapes across planes or axes.
181

182
```javascript { .api }
183
/**
184
 * Mirror geometries across a plane
185
 * @param {Array} plane - [a,b,c,d] plane equation coefficients  
186
 * @param {...Object} objects - Objects to mirror
187
 * @returns {Object|Array} Mirrored object(s)
188
 */
189
function mirror(plane: [number, number, number, number], ...objects: any[]): any;
190

191
/**
192
 * Mirror geometries across the YZ plane (X=0)
193
 * @param {...Object} objects - Objects to mirror
194
 * @returns {Object|Array} Mirrored object(s)
195
 */
196
function mirrorX(...objects: any[]): any;
197

198
/**
199
 * Mirror geometries across the XZ plane (Y=0)  
200
 * @param {...Object} objects - Objects to mirror
201
 * @returns {Object|Array} Mirrored object(s)
202
 */
203
function mirrorY(...objects: any[]): any;
204

205
/**
206
 * Mirror geometries across the XY plane (Z=0)
207
 * @param {...Object} objects - Objects to mirror
208
 * @returns {Object|Array} Mirrored object(s)
209
 */
210
function mirrorZ(...objects: any[]): any;
211
```
212

213
**Usage Examples:**
214

215
```javascript
216
const { cube, cylinder, mirror, mirrorX, mirrorY, mirrorZ, translate } = require('@jscad/modeling');
217

218
// Mirror across coordinate planes
219
const rightCube = translate([10, 0, 0], cube({ size: 5 }));
220
const leftCube = mirrorX(rightCube);
221

222
// Mirror across custom plane
223
const myCylinder = cylinder({ height: 10, radius: 3 });
224
const customPlane = [1, 1, 0, 0]; // Plane through origin with normal [1,1,0]
225
const mirroredCylinder = mirror(customPlane, myCylinder);
226

227
// Create symmetric objects
228
const { union } = require('@jscad/modeling').booleans;
229
const rightHalf = translate([5, 0, 0], cube({ size: [10, 5, 5] }));
230
const symmetric = union(rightHalf, mirrorX(rightHalf));
231
```
232

233
### Centering and Alignment
234

235
Center shapes at the origin or align them to specific positions.
236

237
```javascript { .api }
238
/**
239
 * Center geometries at the origin
240
 * @param {...Object} objects - Objects to center
241
 * @returns {Object|Array} Centered object(s)
242
 */
243
function center(...objects: any[]): any;
244

245
/**
246
 * Center geometries along the X axis
247
 * @param {...Object} objects - Objects to center on X axis
248
 * @returns {Object|Array} Centered object(s)
249
 */
250
function centerX(...objects: any[]): any;
251

252
/**
253
 * Center geometries along the Y axis
254
 * @param {...Object} objects - Objects to center on Y axis  
255
 * @returns {Object|Array} Centered object(s)
256
 */
257
function centerY(...objects: any[]): any;
258

259
/**
260
 * Center geometries along the Z axis
261
 * @param {...Object} objects - Objects to center on Z axis
262
 * @returns {Object|Array} Centered object(s)
263
 */
264
function centerZ(...objects: any[]): any;
265

266
/**
267
 * Align geometries to specific positions relative to their bounding boxes
268
 * @param {Object} options - Alignment options
269
 * @param {String} [options.modes=['center','center','min']] - Alignment modes per axis
270
 * @param {Array} [options.relativeTo] - Reference geometry for relative alignment
271
 * @param {...Object} objects - Objects to align
272
 * @returns {Object|Array} Aligned object(s)
273
 */
274
function align(options: {
275
  modes?: string[],
276
  relativeTo?: any
277
}, ...objects: any[]): any;
278
```
279

280
**Usage Examples:**
281

282
```javascript
283
const { cube, sphere, center, centerX, align, translate } = require('@jscad/modeling');
284

285
// Center objects at origin
286
const offCenterCube = translate([10, 5, 3], cube({ size: 8 }));
287
const centeredCube = center(offCenterCube);
288

289
// Center only on specific axes  
290
const partialCenter = centerX(offCenterCube);
291

292
// Advanced alignment
293
const referenceCube = cube({ size: 10 });
294
const smallCube = cube({ size: 3 });
295

296
// Align small cube to corner of reference cube
297
const aligned = align(
298
  { modes: ['min', 'min', 'max'], relativeTo: referenceCube },
299
  smallCube
300
);
301
```
302

303
### Matrix Transformations
304

305
Apply custom 4x4 transformation matrices for complex transformations.
306

307
```javascript { .api }
308
/**
309
 * Transform geometries using a 4x4 transformation matrix
310
 * @param {Array} matrix - 4x4 transformation matrix (16 elements in column-major order)
311
 * @param {...Object} objects - Objects to transform
312
 * @returns {Object|Array} Transformed object(s)
313
 */
314
function transform(matrix: mat4, ...objects: any[]): any;
315
```
316

317
**Usage Examples:**
318

319
```javascript
320
const { cube, transform, mat4 } = require('@jscad/modeling');
321

322
// Create custom transformation matrix
323
const { maths } = require('@jscad/modeling');
324
const customMatrix = maths.mat4.create();
325

326
// Combine rotation and translation
327
maths.mat4.rotateZ(customMatrix, customMatrix, Math.PI/4);
328
maths.mat4.translate(customMatrix, customMatrix, [10, 5, 0]);
329

330
const myCube = cube({ size: 5 });
331
const transformedCube = transform(customMatrix, myCube);
332

333
// Complex transformation combining multiple operations
334
const complexMatrix = maths.mat4.create();
335
maths.mat4.scale(complexMatrix, complexMatrix, [2, 1, 0.5]);
336
maths.mat4.rotateY(complexMatrix, complexMatrix, Math.PI/6);
337
maths.mat4.translate(complexMatrix, complexMatrix, [0, 0, 10]);
338

339
const complexTransform = transform(complexMatrix, myCube);
340
```
341

342
## Advanced Transformation Techniques
343

344
### Chaining Transformations
345

346
Transformations can be chained to create complex positioning:
347

348
```javascript
349
const { cube, translate, rotate, scale, mirrorX } = require('@jscad/modeling');
350

351
const baseCube = cube({ size: 5 });
352

353
// Chain multiple transformations
354
const finalCube = translate([10, 0, 0],
355
  rotate([0, Math.PI/4, 0],
356
    scale([2, 1, 1], baseCube)
357
  )
358
);
359

360
// Create arrays of transformed objects
361
const spacing = 15;
362
const cubes = [];
363
for (let i = 0; i < 5; i++) {
364
  const transformed = translate([i * spacing, 0, 0],
365
    rotate([0, 0, i * Math.PI/8], baseCube)
366
  );
367
  cubes.push(transformed);
368
}
369
```
370

371
### Coordinate System Considerations
372

373
JSCAD uses a right-handed coordinate system:
374
- +X points right
375
- +Y points up (or forward in some contexts)  
376
- +Z points toward viewer
377
- Rotations follow right-hand rule (counterclockwise when looking down axis)
378

379
### Performance Tips
380

381
- Combine multiple transformations into a single matrix when possible
382
- Avoid excessive chaining of small transformations
383
- Cache transformation matrices for repeated use
384
- Consider the order of operations (scale, then rotate, then translate)