0
# Measurements
1

2
All shapes (primitives or the results of operations) can be measured to calculate various geometric properties like area, volume, bounding boxes, centers, and dimensions. These functions are essential for analysis, positioning, and manufacturing preparation.
3

4
## Capabilities
5

6
### Area Measurements
7

8
Calculate the area of 2D shapes or surface area of 3D shapes.
9

10
```javascript { .api }
11
/**
12
 * Measure the area of a 2D shape or surface area of a 3D shape
13
 * @param {...Object} geometries - Geometries to measure (geom2 or geom3)
14
 * @returns {Number|Array} Area value, or array of areas for multiple geometries
15
 */
16
function measureArea(...geometries: (geom2 | geom3)[]): number | number[];
17

18
/**
19
 * Measure the total area of multiple geometries
20
 * @param {Array} objects - Array of geometries to measure
21
 * @returns {Number} Total area of all objects
22
 */
23
function measureAggregateArea(objects: any[]): number;
24
```
25

26
**Usage Examples:**
27

28
```javascript
29
const { circle, rectangle, cube, sphere, measureArea, measureAggregateArea, union } = require('@jscad/modeling');
30

31
// Measure 2D area
32
const myCircle = circle({ radius: 5 });
33
const circleArea = measureArea(myCircle); // ≈ 78.54
34

35
const myRect = rectangle({ size: [10, 6] });
36
const rectArea = measureArea(myRect); // = 60
37

38
// Measure 3D surface area
39
const myCube = cube({ size: 10 });
40
const cubeArea = measureArea(myCube); // = 600 (6 faces × 100)
41

42
const mySphere = sphere({ radius: 4 });
43
const sphereArea = measureArea(mySphere); // ≈ 201.06
44

45
// Measure total area of multiple shapes
46
const shapes = [myCircle, myRect];
47
const totalArea = measureAggregateArea(shapes);
48
```
49

50
### Volume Measurements
51

52
Calculate the volume of 3D shapes.
53

54
```javascript { .api }
55
/**
56
 * Measure the volume of a 3D shape
57
 * @param {...Object} geometries - Geometries to measure (accepts any geometry type, but only geom3 has volume)
58
 * @returns {Number|Array} Volume value, or array of volumes for multiple geometries
59
 */
60
function measureVolume(...geometries: any[]): number | number[];
61

62
/**
63
 * Measure the total volume of multiple 3D geometries
64
 * @param {Array} objects - Array of 3D geometries to measure
65
 * @returns {Number} Total volume of all objects
66
 */
67
function measureAggregateVolume(objects: geom3[]): number;
68
```
69

70
**Usage Examples:**
71

72
```javascript
73
const { cube, sphere, cylinder, measureVolume, measureAggregateVolume, subtract } = require('@jscad/modeling');
74

75
// Measure basic volumes
76
const myCube = cube({ size: 10 });
77
const cubeVolume = measureVolume(myCube); // = 1000
78

79
const mySphere = sphere({ radius: 3 });
80
const sphereVolume = measureVolume(mySphere); // ≈ 113.10
81

82
const myCylinder = cylinder({ height: 8, radius: 2 });
83
const cylinderVolume = measureVolume(myCylinder); // ≈ 100.53
84

85
// Measure volume of complex shape
86
const cubeWithHole = subtract(myCube, mySphere);
87
const complexVolume = measureVolume(cubeWithHole); // ≈ 886.90
88

89
// Measure total volume
90
const solids = [myCube, mySphere, myCylinder];
91
const totalVolume = measureAggregateVolume(solids);
92
```
93

94
### Bounding Box Measurements
95

96
Calculate bounding boxes that completely enclose geometries.
97

98
```javascript { .api }
99
/**
100
 * Measure the bounding box of a geometry
101
 * @param {Object} geometry - Geometry to measure
102
 * @returns {Array} Bounding box as [[minX, minY, minZ], [maxX, maxY, maxZ]]
103
 */
104
function measureBoundingBox(geometry: any): [[number, number, number], [number, number, number]];
105

106
/**
107
 * Measure bounding box that contains all given geometries
108
 * @param {Array} objects - Array of geometries
109
 * @returns {Array} Aggregate bounding box containing all objects
110
 */
111
function measureAggregateBoundingBox(objects: any[]): [[number, number, number], [number, number, number]];
112
```
113

114
**Usage Examples:**
115

116
```javascript
117
const { cube, sphere, translate, measureBoundingBox, measureAggregateBoundingBox } = require('@jscad/modeling');
118

119
// Measure single object bounding box
120
const myCube = cube({ size: 10, center: [5, 0, 0] });
121
const cubeBounds = measureBoundingBox(myCube);
122
// Returns [[0, -5, -5], [10, 5, 5]]
123

124
// Measure aggregate bounding box
125
const sphere1 = sphere({ radius: 3, center: [-8, 0, 0] });
126
const sphere2 = sphere({ radius: 2, center: [12, 5, 3] });
127
const objects = [myCube, sphere1, sphere2];
128
const totalBounds = measureAggregateBoundingBox(objects);
129
// Returns [[-11, -5, -5], [14, 7, 5]]
130

131
// Extract bounding box dimensions
132
const [[minX, minY, minZ], [maxX, maxY, maxZ]] = cubeBounds;
133
const width = maxX - minX;   // 10
134
const height = maxY - minY;  // 10  
135
const depth = maxZ - minZ;   // 10
136
```
137

138
### Bounding Sphere Measurements
139

140
Calculate the smallest sphere that completely encloses a geometry.
141

142
```javascript { .api }
143
/**
144
 * Measure the bounding sphere of a geometry
145
 * @param {Object} geometry - Geometry to measure
146
 * @returns {Array} Bounding sphere as [centerX, centerY, centerZ, radius]
147
 */
148
function measureBoundingSphere(geometry: any): [number, number, number, number];
149
```
150

151
**Usage Examples:**
152

153
```javascript
154
const { cube, cylinder, measureBoundingSphere } = require('@jscad/modeling');
155

156
// Measure bounding sphere
157
const myCube = cube({ size: 10 });
158
const [centerX, centerY, centerZ, radius] = measureBoundingSphere(myCube);
159
// Center at [0, 0, 0], radius ≈ 8.66 (half diagonal of cube)
160

161
const myCylinder = cylinder({ height: 10, radius: 3 });
162
const cylinderSphere = measureBoundingSphere(myCylinder);
163
// Sphere that encloses the entire cylinder
164
```
165

166
### Center and Centroid Measurements
167

168
Calculate geometric centers and centers of mass.
169

170
```javascript { .api }
171
/**
172
 * Measure the geometric center (centroid) of a geometry
173
 * @param {Object} geometry - Geometry to measure
174
 * @returns {Array} Center point as [x, y] for 2D or [x, y, z] for 3D
175
 */
176
function measureCenter(geometry: any): [number, number] | [number, number, number];
177

178
/**
179
 * Measure the center of mass of a geometry (considering uniform density)
180
 * @param {Object} geometry - Geometry to measure  
181
 * @returns {Array} Center of mass as [x, y] for 2D or [x, y, z] for 3D
182
 */
183
function measureCenterOfMass(geometry: any): [number, number] | [number, number, number];
184
```
185

186
**Usage Examples:**
187

188
```javascript
189
const { rectangle, cube, sphere, union, measureCenter, measureCenterOfMass, translate } = require('@jscad/modeling');
190

191
// Measure center of simple shapes
192
const rect = rectangle({ size: [10, 6], center: [5, 3] });
193
const rectCenter = measureCenter(rect); // [5, 3]
194

195
const myCube = cube({ size: 10, center: [0, 0, 0] });
196
const cubeCenter = measureCenter(myCube); // [0, 0, 0]
197

198
// Measure center of complex shape
199
const offsetSphere = translate([8, 0, 0], sphere({ radius: 3 }));
200
const combined = union(myCube, offsetSphere);
201
const combinedCenter = measureCenter(combined); // Weighted toward sphere
202

203
// Center of mass (useful for balancing)
204
const centerOfMass = measureCenterOfMass(combined);
205
```
206

207
### Dimension Measurements
208

209
Calculate the overall dimensions (width, height, depth) of geometries.
210

211
```javascript { .api }
212
/**
213
 * Measure the dimensions of a geometry
214
 * @param {Object} geometry - Geometry to measure
215
 * @returns {Array} Dimensions as [width, height] for 2D or [width, height, depth] for 3D
216
 */
217
function measureDimensions(geometry: any): [number, number] | [number, number, number];
218
```
219

220
**Usage Examples:**
221

222
```javascript
223
const { rectangle, cube, sphere, union, measureDimensions } = require('@jscad/modeling');
224

225
// Measure 2D dimensions
226
const rect = rectangle({ size: [15, 8] });
227
const [width, height] = measureDimensions(rect); // [15, 8]
228

229
// Measure 3D dimensions  
230
const myCube = cube({ size: 12 });
231
const [cubeWidth, cubeHeight, cubeDepth] = measureDimensions(myCube); // [12, 12, 12]
232

233
// Measure complex shape dimensions
234
const complex = union(myCube, sphere({ radius: 8, center: [10, 0, 0] }));
235
const complexDims = measureDimensions(complex); // Overall envelope dimensions
236
```
237

238
### Epsilon Measurements
239

240
Calculate epsilon values for numerical precision in operations.
241

242
```javascript { .api }
243
/**
244
 * Measure the epsilon value of a geometry (precision tolerance)
245
 * @param {Object} geometry - Geometry to measure
246
 * @returns {Number} Epsilon value for the geometry
247
 */
248
function measureEpsilon(geometry: any): number;
249

250
/**
251
 * Measure aggregate epsilon for multiple geometries
252
 * @param {Array} objects - Array of geometries
253
 * @returns {Number} Aggregate epsilon value
254
 */
255
function measureAggregateEpsilon(objects: any[]): number;
256
```
257

258
**Usage Examples:**
259

260
```javascript
261
const { cube, sphere, measureEpsilon, measureAggregateEpsilon } = require('@jscad/modeling');
262

263
// Measure precision tolerance
264
const myCube = cube({ size: 10 });
265
const cubeEpsilon = measureEpsilon(myCube);
266

267
// Use for precision-sensitive operations
268
const objects = [myCube, sphere({ radius: 5 })];
269
const tolerance = measureAggregateEpsilon(objects);
270
```
271

272
## Advanced Measurement Techniques
273

274
### Manufacturing Analysis
275

276
Use measurements for manufacturing preparation:
277

278
```javascript
279
const { cube, cylinder, subtract, measureVolume, measureArea, measureDimensions } = require('@jscad/modeling');
280

281
// Analyze a machined part
282
const stock = cube({ size: [50, 30, 20] });
283
const hole = cylinder({ height: 25, radius: 8 });
284
const part = subtract(stock, hole);
285

286
// Calculate material usage
287
const stockVolume = measureVolume(stock);
288
const partVolume = measureVolume(part);
289
const materialRemoved = stockVolume - partVolume;
290
const removalPercentage = (materialRemoved / stockVolume) * 100;
291

292
// Calculate surface area for coating
293
const surfaceArea = measureArea(part);
294

295
// Check dimensions for tolerances
296
const [width, height, depth] = measureDimensions(part);
297
console.log(`Part dimensions: ${width} × ${height} × ${depth}`);
298
```
299

300
### Assembly Analysis
301

302
Analyze assemblies and part relationships:
303

304
```javascript
305
const { cube, sphere, translateX, measureCenter, measureBoundingBox, measureAggregateBoundingBox } = require('@jscad/modeling');
306

307
// Assembly components
308
const base = cube({ size: [30, 20, 5] });
309
const pillar1 = translateX(-10, cube({ size: [4, 4, 15] }));
310
const pillar2 = translateX(10, cube({ size: [4, 4, 15] }));
311
const top = translateZ(15, cube({ size: [25, 15, 3] }));
312

313
const assembly = [base, pillar1, pillar2, top];
314

315
// Analyze assembly
316
const assemblyBounds = measureAggregateBoundingBox(assembly);
317
const assemblyCOG = measureCenter(union(...assembly));
318

319
// Check component alignment
320
const baseCOG = measureCenter(base);
321
const topCOG = measureCenter(top);
322
const alignment = [topCOG[0] - baseCOG[0], topCOG[1] - baseCOG[1]];
323
```
324

325
### Quality Control
326

327
Use measurements for quality validation:
328

329
```javascript
330
const { sphere, measureBoundingSphere, measureVolume } = require('@jscad/modeling');
331

332
// Check if sphere meets specifications
333
const testSphere = sphere({ radius: 10, segments: 32 });
334
const [cx, cy, cz, boundingRadius] = measureBoundingSphere(testSphere);
335
const volume = measureVolume(testSphere);
336

337
// Theoretical values for comparison
338
const theoreticalVolume = (4/3) * Math.PI * Math.pow(10, 3);
339
const volumeError = Math.abs(volume - theoreticalVolume) / theoreticalVolume;
340

341
// Quality check
342
const isWithinTolerance = volumeError < 0.01; // 1% tolerance
343
```
344

345
### Performance Optimization
346

347
Use measurements to optimize geometry complexity:
348

349
```javascript
350
const { sphere, measureArea, retessellate } = require('@jscad/modeling');
351

352
// Create spheres with different detail levels
353
const lowDetail = sphere({ radius: 5, segments: 8 });
354
const medDetail = sphere({ radius: 5, segments: 16 });
355
const highDetail = sphere({ radius: 5, segments: 32 });
356

357
// Compare surface areas (should be similar)
358
const areas = [lowDetail, medDetail, highDetail].map(measureArea);
359
const surfaceAreaVariation = Math.max(...areas) - Math.min(...areas);
360

361
// Choose appropriate detail level based on requirements
362
const targetArea = 4 * Math.PI * 25; // Theoretical sphere area
363
const errors = areas.map(area => Math.abs(area - targetArea) / targetArea);
364
```