@bitbybit-dev/jscad 1.2.0-rc.2 → 1.3.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,191 +2,319 @@ import * as Inputs from "../inputs/jscad-inputs";
2
2
  import { MathBitByBit } from "@bitbybit-dev/base";
3
3
  import * as JSCAD from "@jscad/modeling";
4
4
  /**
5
- * Contains various functions for solid 3D shapes from JSCAD library https://github.com/jscad/OpenJSCAD.org
6
- * Thanks JSCAD community for developing this kernel
5
+ * Building JSCAD solids: cubes, cuboids, spheres, ellipsoids, cylinders, a torus and a solid from
6
+ * raw polygon points, each with a variant that places one copy on every point of a list. The kernel
7
+ * keeps Z as its own axis, so a cylinder stands along Z and a torus lies flat in the XY plane;
8
+ * every solid is a closed mesh of polygons and `segments` says how many flat facets approximate a
9
+ * round surface.
7
10
  */
8
11
  export declare class JSCADShapes {
9
12
  private readonly math;
10
13
  jscad: typeof JSCAD;
11
14
  constructor(jscad: typeof JSCAD, math: MathBitByBit);
12
15
  /**
13
- * Create a 3D cube shape
14
- * @param inputs Cube parameters
15
- * @returns Cube solid
16
+ * Builds a cube of edge length `size` centered on `center`, with its faces parallel to the
17
+ * axes.
18
+ * @param inputs - The center and the edge length
19
+ * @returns The cube solid
16
20
  * @group primitives
17
21
  * @shortname cube
18
22
  * @drawable true
23
+ * @example
24
+ * ```typescript
25
+ * const cube = await bitbybit.jscad.shapes.cube({ center: [0, 0, 0], size: 10 });
26
+ * ```
19
27
  */
20
28
  cube(inputs: Inputs.JSCAD.CubeDto): Inputs.JSCAD.JSCADEntity;
21
29
  /**
22
- * Create a 3D cubes on multiple center points
23
- * @param inputs Cube with multiple center points parameters
24
- * @returns List of cube solids
30
+ * Builds one cube of edge length `size` on every point of `centers`, in the same order.
31
+ * @param inputs - The center points and the edge length
32
+ * @returns One cube per center point
25
33
  * @group primitives on centers
26
34
  * @shortname cubes
27
35
  * @drawable true
36
+ * @example
37
+ * ```typescript
38
+ * const cubes = await bitbybit.jscad.shapes.cubesOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0], [40, 0, 0]], size: 10 });
39
+ * ```
28
40
  */
29
41
  cubesOnCenterPoints(inputs: Inputs.JSCAD.CubeCentersDto): Inputs.JSCAD.JSCADEntity[];
30
42
  /**
31
- * Create a 3D cuboid shape
32
- * @param inputs Cuboid parameters
33
- * @returns Cuboid solid
43
+ * Builds a box centered on `center` with `width` along X, `height` along Y and `length` along
44
+ * Z, its faces parallel to the axes.
45
+ * @param inputs - The center and the three side lengths
46
+ * @returns The box solid
34
47
  * @group primitives
35
48
  * @shortname cuboid
36
49
  * @drawable true
50
+ * @example
51
+ * ```typescript
52
+ * const box = await bitbybit.jscad.shapes.cuboid({ center: [0, 0, 0], width: 10, height: 5, length: 20 });
53
+ * ```
37
54
  */
38
55
  cuboid(inputs: Inputs.JSCAD.CuboidDto): Inputs.JSCAD.JSCADEntity;
39
56
  /**
40
- * Create a 3D cuboids on multiple center points
41
- * @param inputs Cuboids with multiple center point parameters
42
- * @returns List of cuboid solids
57
+ * Builds one box of the given `width`, `height` and `length` on every point of `centers`, in
58
+ * the same order.
59
+ * @param inputs - The center points and the three side lengths
60
+ * @returns One box per center point
43
61
  * @group primitives on centers
44
62
  * @shortname cuboids
45
63
  * @drawable true
64
+ * @example
65
+ * ```typescript
66
+ * const boxes = await bitbybit.jscad.shapes.cuboidsOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0]], width: 10, height: 5, length: 20 });
67
+ * ```
46
68
  */
47
69
  cuboidsOnCenterPoints(inputs: Inputs.JSCAD.CuboidCentersDto): Inputs.JSCAD.JSCADEntity[];
48
70
  /**
49
- * Create a 3D elliptic cylinder solid
50
- * @param inputs Elliptic cylinder parameters
51
- * @returns Elliptic cylinder solid
71
+ * Builds a cylinder with an elliptical cross-section whose radii can differ at the two ends,
72
+ * standing along Z and centered on `center`.
73
+ *
74
+ * `startRadius` is the X and Y radius at the bottom end and `endRadius` at the top, so unequal
75
+ * pairs make a tapered or cone-like solid; `height` is split evenly above and below `center`.
76
+ * @param inputs - The center, the height, the two radius pairs and the segment count
77
+ * @returns The elliptic cylinder solid
52
78
  * @group primitives
53
79
  * @shortname cylinder elliptic
54
80
  * @drawable true
81
+ * @example
82
+ * ```typescript
83
+ * const cone = await bitbybit.jscad.shapes.cylinderElliptic({ center: [0, 0, 0], height: 10, startRadius: [4, 2], endRadius: [1, 0.5], segments: 32 });
84
+ * ```
55
85
  */
56
86
  cylinderElliptic(inputs: Inputs.JSCAD.CylidnerEllipticDto): Inputs.JSCAD.JSCADEntity;
57
87
  /**
58
- * Create a 3D elliptic cylinders on multiple center points
59
- * @param inputs Elliptic cylinders with multiple center point parameters
60
- * @returns List of elliptic cylinders solids
88
+ * Builds one elliptic cylinder with the given radii and height on every point of `centers`, in
89
+ * the same order, as `cylinderElliptic` does for one.
90
+ * @param inputs - The center points, the height, the two radius pairs and the segment count
91
+ * @returns One elliptic cylinder per center point
61
92
  * @group primitives on centers
62
93
  * @shortname cylinder elliptic
63
94
  * @drawable true
95
+ * @example
96
+ * ```typescript
97
+ * const cones = await bitbybit.jscad.shapes.cylinderEllipticOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0]], height: 10, startRadius: [4, 2], endRadius: [1, 0.5], segments: 32 });
98
+ * ```
64
99
  */
65
100
  cylinderEllipticOnCenterPoints(inputs: Inputs.JSCAD.CylidnerCentersEllipticDto): Inputs.JSCAD.JSCADEntity[];
66
101
  /**
67
- * Create a 3D cylinder solid
68
- * @param inputs Cylinder parameters
69
- * @returns Cylinder solid
102
+ * Builds a round cylinder of the given `radius` standing along Z, with `height` split evenly
103
+ * above and below `center`.
104
+ *
105
+ * `segments` is the number of flat sides around it; more makes it rounder.
106
+ * @param inputs - The center, the height, the radius and the segment count
107
+ * @returns The cylinder solid
70
108
  * @group primitives
71
109
  * @shortname cylinder
72
110
  * @drawable true
111
+ * @example
112
+ * ```typescript
113
+ * const cylinder = await bitbybit.jscad.shapes.cylinder({ center: [0, 0, 0], height: 10, radius: 3, segments: 32 });
114
+ * ```
73
115
  */
74
116
  cylinder(inputs: Inputs.JSCAD.CylidnerDto): Inputs.JSCAD.JSCADEntity;
75
117
  /**
76
- * Create a 3D cylinders on multiple center points
77
- * @param inputs Cylinders with multiple center point parameters
78
- * @returns List of cylinder solids
118
+ * Builds one cylinder of the given `radius` and `height` on every point of `centers`, in the
119
+ * same order, as `cylinder` does for one.
120
+ * @param inputs - The center points, the height, the radius and the segment count
121
+ * @returns One cylinder per center point
79
122
  * @group primitives on centers
80
123
  * @shortname cylinder
81
124
  * @drawable true
125
+ * @example
126
+ * ```typescript
127
+ * const posts = await bitbybit.jscad.shapes.cylindersOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0], [40, 0, 0]], height: 10, radius: 1, segments: 16 });
128
+ * ```
82
129
  */
83
130
  cylindersOnCenterPoints(inputs: Inputs.JSCAD.CylidnerCentersDto): Inputs.JSCAD.JSCADEntity[];
84
131
  /**
85
- * Create a 3D ellipsoid solid
86
- * @param inputs Ellipsoid parameters
87
- * @returns Ellipsoid solid
132
+ * Builds an ellipsoid, a sphere stretched separately along X, Y and Z, centered on `center`.
133
+ *
134
+ * `radius` holds the three half-sizes in `[x, y, z]` order; equal values make a sphere.
135
+ * @param inputs - The center, the three radii and the segment count
136
+ * @returns The ellipsoid solid
88
137
  * @group primitives
89
138
  * @shortname ellipsoid
90
139
  * @drawable true
140
+ * @example
141
+ * ```typescript
142
+ * const egg = await bitbybit.jscad.shapes.ellipsoid({ center: [0, 0, 0], radius: [5, 3, 8], segments: 32 });
143
+ * ```
91
144
  */
92
145
  ellipsoid(inputs: Inputs.JSCAD.EllipsoidDto): Inputs.JSCAD.JSCADEntity;
93
146
  /**
94
- * Create a 3D ellipsoids on multiple center points
95
- * @param inputs Ellipsoid parameters with multiple center points
96
- * @returns List of ellipsoid solids
147
+ * Builds one ellipsoid with the given radii on every point of `centers`, in the same order, as
148
+ * `ellipsoid` does for one.
149
+ * @param inputs - The center points, the three radii and the segment count
150
+ * @returns One ellipsoid per center point
97
151
  * @group primitives on centers
98
152
  * @shortname ellipsoid
99
153
  * @drawable true
154
+ * @example
155
+ * ```typescript
156
+ * const eggs = await bitbybit.jscad.shapes.ellipsoidsOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0]], radius: [5, 3, 8], segments: 32 });
157
+ * ```
100
158
  */
101
159
  ellipsoidsOnCenterPoints(inputs: Inputs.JSCAD.EllipsoidCentersDto): Inputs.JSCAD.JSCADEntity[];
102
160
  /**
103
- * Create a 3D geodesic sphere solid
104
- * @param inputs Geodesic sphere parameters
105
- * @returns Geodesic sphere solid
161
+ * Builds a sphere from evenly sized triangles, the way a geodesic dome is built, centered on
162
+ * `center`.
163
+ *
164
+ * `frequency` is how finely the twenty starting faces are subdivided; it is used in whole
165
+ * multiples of 6 and must be at least 6, and higher values give a rounder sphere.
166
+ * @param inputs - The center, the radius and the subdivision frequency
167
+ * @returns The geodesic sphere solid
106
168
  * @group primitives
107
169
  * @shortname geodesic sphere
108
170
  * @drawable true
171
+ * @example
172
+ * ```typescript
173
+ * const dome = await bitbybit.jscad.shapes.geodesicSphere({ center: [0, 0, 0], radius: 5, frequency: 12 });
174
+ * ```
109
175
  */
110
176
  geodesicSphere(inputs: Inputs.JSCAD.GeodesicSphereDto): Inputs.JSCAD.JSCADEntity;
111
177
  /**
112
- * Create a 3D geodesic spheres on multiple center points
113
- * @param inputs Geodesic sphere parameters with multiple center points
114
- * @returns List of geodesic spheres
178
+ * Builds one geodesic sphere of the given `radius` on every point of `centers`, in the same
179
+ * order, as `geodesicSphere` does for one.
180
+ * @param inputs - The center points, the radius and the subdivision frequency
181
+ * @returns One geodesic sphere per center point
115
182
  * @group primitives on centers
116
183
  * @shortname geodesic sphere
117
184
  * @drawable true
185
+ * @example
186
+ * ```typescript
187
+ * const domes = await bitbybit.jscad.shapes.geodesicSpheresOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0]], radius: 5, frequency: 12 });
188
+ * ```
118
189
  */
119
190
  geodesicSpheresOnCenterPoints(inputs: Inputs.JSCAD.GeodesicSphereCentersDto): Inputs.JSCAD.JSCADEntity[];
120
191
  /**
121
- * Create a 3D rounded cuboid solid
122
- * @param inputs Rounded cuboid parameters
123
- * @returns Rounded cuboid solid
192
+ * Builds a box with all its edges and corners rounded by `roundRadius`, centered on `center`
193
+ * with `width` along X, `height` along Y and `length` along Z.
194
+ *
195
+ * `roundRadius` must be less than half of the smallest side or an error is thrown; `segments`
196
+ * sets how smoothly the rounding is faceted.
197
+ * @param inputs - The center, the three side lengths, the rounding radius and the segment count
198
+ * @returns The rounded box solid
124
199
  * @group primitives
125
200
  * @shortname rounded cuboid
126
201
  * @drawable true
202
+ * @example
203
+ * ```typescript
204
+ * const soft = await bitbybit.jscad.shapes.roundedCuboid({ center: [0, 0, 0], width: 10, height: 5, length: 20, roundRadius: 1, segments: 16 });
205
+ * ```
127
206
  */
128
207
  roundedCuboid(inputs: Inputs.JSCAD.RoundedCuboidDto): Inputs.JSCAD.JSCADEntity;
129
208
  /**
130
- * Create a 3D rounded cuboids on multiple center points
131
- * @param inputs Rounded cuboids parameters with multiple center points
132
- * @returns List of rounded cuboids
209
+ * Builds one rounded box with the given sides and rounding on every point of `centers`, in the
210
+ * same order, as `roundedCuboid` does for one.
211
+ * @param inputs - The center points, the three side lengths, the rounding radius and the segment count
212
+ * @returns One rounded box per center point
133
213
  * @group primitives on centers
134
214
  * @shortname rounded cuboid
135
215
  * @drawable true
216
+ * @example
217
+ * ```typescript
218
+ * const softBoxes = await bitbybit.jscad.shapes.roundedCuboidsOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0]], width: 10, height: 5, length: 20, roundRadius: 1, segments: 16 });
219
+ * ```
136
220
  */
137
221
  roundedCuboidsOnCenterPoints(inputs: Inputs.JSCAD.RoundedCuboidCentersDto): Inputs.JSCAD.JSCADEntity[];
138
222
  /**
139
- * Create a 3D rounded cylinder solid
140
- * @param inputs Rounded cylinder parameters
141
- * @returns Rounded cylinder solid
223
+ * Builds a cylinder standing along Z whose two rims are rounded by `roundRadius`, with `height`
224
+ * split evenly above and below `center`.
225
+ *
226
+ * `height` must be more than twice `roundRadius` or an error is thrown.
227
+ * @param inputs - The center, the rounding radius, the height, the radius and the segment count
228
+ * @returns The rounded cylinder solid
142
229
  * @group primitives
143
230
  * @shortname rounded cylinder
144
231
  * @drawable true
232
+ * @example
233
+ * ```typescript
234
+ * const pill = await bitbybit.jscad.shapes.roundedCylinder({ center: [0, 0, 0], roundRadius: 1, height: 10, radius: 3, segments: 32 });
235
+ * ```
145
236
  */
146
237
  roundedCylinder(inputs: Inputs.JSCAD.RoundedCylidnerDto): Inputs.JSCAD.JSCADEntity;
147
238
  /**
148
- * Create a 3D rounded cylinders on multiple center points
149
- * @param inputs Rounded cylinders parameters with multiple center points
150
- * @returns List of rounded cylinders
239
+ * Builds one rounded cylinder with the given size and rounding on every point of `centers`, in
240
+ * the same order, as `roundedCylinder` does for one.
241
+ * @param inputs - The center points, the rounding radius, the height, the radius and the segment count
242
+ * @returns One rounded cylinder per center point
151
243
  * @group primitives on centers
152
244
  * @shortname rounded cylinder
153
245
  * @drawable true
246
+ * @example
247
+ * ```typescript
248
+ * const pills = await bitbybit.jscad.shapes.roundedCylindersOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0]], roundRadius: 1, height: 10, radius: 3, segments: 32 });
249
+ * ```
154
250
  */
155
251
  roundedCylindersOnCenterPoints(inputs: Inputs.JSCAD.RoundedCylidnerCentersDto): Inputs.JSCAD.JSCADEntity[];
156
252
  /**
157
- * Create a 3D sphere solid
158
- * @param inputs Sphere parameters
159
- * @returns Sphere solid
253
+ * Builds a sphere of the given `radius` centered on `center`; `segments` is the number of
254
+ * facets around it, so more makes it rounder.
255
+ * @param inputs - The center, the radius and the segment count
256
+ * @returns The sphere solid
160
257
  * @group primitives
161
258
  * @shortname sphere
162
259
  * @drawable true
260
+ * @example
261
+ * ```typescript
262
+ * const ball = await bitbybit.jscad.shapes.sphere({ center: [0, 0, 0], radius: 5, segments: 32 });
263
+ * ```
163
264
  */
164
265
  sphere(inputs: Inputs.JSCAD.SphereDto): Inputs.JSCAD.JSCADEntity;
165
266
  /**
166
- * Create a 3D sphere on multiple center points
167
- * @param inputs Sphere parameters with multiple center points
168
- * @returns List of spheres
267
+ * Builds one sphere of the given `radius` on every point of `centers`, in the same order, as
268
+ * `sphere` does for one.
269
+ * @param inputs - The center points, the radius and the segment count
270
+ * @returns One sphere per center point
169
271
  * @group primitives on centers
170
272
  * @shortname sphere
171
273
  * @drawable true
274
+ * @example
275
+ * ```typescript
276
+ * const balls = await bitbybit.jscad.shapes.spheresOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0], [40, 0, 0]], radius: 5, segments: 32 });
277
+ * ```
172
278
  */
173
279
  spheresOnCenterPoints(inputs: Inputs.JSCAD.SphereCentersDto): Inputs.JSCAD.JSCADEntity[];
174
280
  /**
175
- * Create a 3D torus solid
176
- * @param inputs Torus parameters
177
- * @returns Torus solid
281
+ * Builds a torus, a ring with a round cross-section, lying flat in the XY plane around `center`
282
+ * with Z through its hole.
283
+ *
284
+ * `outerRadius` is the distance from the center to the middle of the tube and `innerRadius` the
285
+ * tube's own radius, which must be smaller. Rotations and `startAngle` are in degrees; an
286
+ * `outerRotation` below 360 leaves the ring open.
287
+ * @param inputs - The center, the two radii, the two segment counts, the two rotations and the start angle
288
+ * @returns The torus solid
178
289
  * @group primitives
179
290
  * @shortname torus
180
291
  * @drawable true
292
+ * @example
293
+ * ```typescript
294
+ * const ring = await bitbybit.jscad.shapes.torus({ center: [0, 0, 0], innerRadius: 1, outerRadius: 5, innerSegments: 16, outerSegments: 48, innerRotation: 0, outerRotation: 360, startAngle: 0 });
295
+ * ```
181
296
  */
182
297
  torus(inputs: Inputs.JSCAD.TorusDto): Inputs.JSCAD.JSCADEntity;
183
298
  /**
184
- * Create a 3D shape from poylgon points that have to be nested arrays of points
185
- * @param inputs points
186
- * @returns shape
299
+ * Builds a solid from its faces, each given as a list of points that go around the face.
300
+ *
301
+ * List the points of every face clockwise as seen from outside the solid; the faces must close
302
+ * the solid for booleans to work on it. Each list is read in reverse order and the input is not
303
+ * changed.
304
+ * @param inputs - The faces as lists of points
305
+ * @returns The solid
187
306
  * @group shapes
188
307
  * @shortname from polygon points
189
308
  * @drawable true
309
+ * @example
310
+ * ```typescript
311
+ * const tetrahedron = await bitbybit.jscad.shapes.fromPolygonPoints({ polygonPoints: [
312
+ * [[0, 0, 0], [10, 0, 0], [0, 10, 0]],
313
+ * [[0, 0, 0], [0, 10, 0], [0, 0, 10]],
314
+ * [[0, 0, 0], [0, 0, 10], [10, 0, 0]],
315
+ * [[10, 0, 0], [0, 0, 10], [0, 10, 0]],
316
+ * ] });
317
+ * ```
190
318
  */
191
319
  fromPolygonPoints(inputs: Inputs.JSCAD.FromPolygonPoints): Inputs.JSCAD.JSCADEntity;
192
320
  }