@bitbybit-dev/jscad 1.2.0 → 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.
@@ -1,6 +1,9 @@
1
1
  /**
2
- * Contains various functions for solid 3D shapes from JSCAD library https://github.com/jscad/OpenJSCAD.org
3
- * Thanks JSCAD community for developing this kernel
2
+ * Building JSCAD solids: cubes, cuboids, spheres, ellipsoids, cylinders, a torus and a solid from
3
+ * raw polygon points, each with a variant that places one copy on every point of a list. The kernel
4
+ * keeps Z as its own axis, so a cylinder stands along Z and a torus lies flat in the XY plane;
5
+ * every solid is a closed mesh of polygons and `segments` says how many flat facets approximate a
6
+ * round surface.
4
7
  */
5
8
  export class JSCADShapes {
6
9
  constructor(jscad, math) {
@@ -8,12 +11,17 @@ export class JSCADShapes {
8
11
  this.jscad = jscad;
9
12
  }
10
13
  /**
11
- * Create a 3D cube shape
12
- * @param inputs Cube parameters
13
- * @returns Cube solid
14
+ * Builds a cube of edge length `size` centered on `center`, with its faces parallel to the
15
+ * axes.
16
+ * @param inputs - The center and the edge length
17
+ * @returns The cube solid
14
18
  * @group primitives
15
19
  * @shortname cube
16
20
  * @drawable true
21
+ * @example
22
+ * ```typescript
23
+ * const cube = await bitbybit.jscad.shapes.cube({ center: [0, 0, 0], size: 10 });
24
+ * ```
17
25
  */
18
26
  cube(inputs) {
19
27
  return this.jscad.primitives.cube({
@@ -22,12 +30,16 @@ export class JSCADShapes {
22
30
  });
23
31
  }
24
32
  /**
25
- * Create a 3D cubes on multiple center points
26
- * @param inputs Cube with multiple center points parameters
27
- * @returns List of cube solids
33
+ * Builds one cube of edge length `size` on every point of `centers`, in the same order.
34
+ * @param inputs - The center points and the edge length
35
+ * @returns One cube per center point
28
36
  * @group primitives on centers
29
37
  * @shortname cubes
30
38
  * @drawable true
39
+ * @example
40
+ * ```typescript
41
+ * const cubes = await bitbybit.jscad.shapes.cubesOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0], [40, 0, 0]], size: 10 });
42
+ * ```
31
43
  */
32
44
  cubesOnCenterPoints(inputs) {
33
45
  return inputs.centers.map(center => {
@@ -35,12 +47,17 @@ export class JSCADShapes {
35
47
  });
36
48
  }
37
49
  /**
38
- * Create a 3D cuboid shape
39
- * @param inputs Cuboid parameters
40
- * @returns Cuboid solid
50
+ * Builds a box centered on `center` with `width` along X, `height` along Y and `length` along
51
+ * Z, its faces parallel to the axes.
52
+ * @param inputs - The center and the three side lengths
53
+ * @returns The box solid
41
54
  * @group primitives
42
55
  * @shortname cuboid
43
56
  * @drawable true
57
+ * @example
58
+ * ```typescript
59
+ * const box = await bitbybit.jscad.shapes.cuboid({ center: [0, 0, 0], width: 10, height: 5, length: 20 });
60
+ * ```
44
61
  */
45
62
  cuboid(inputs) {
46
63
  return this.jscad.primitives.cuboid({
@@ -49,12 +66,17 @@ export class JSCADShapes {
49
66
  });
50
67
  }
51
68
  /**
52
- * Create a 3D cuboids on multiple center points
53
- * @param inputs Cuboids with multiple center point parameters
54
- * @returns List of cuboid solids
69
+ * Builds one box of the given `width`, `height` and `length` on every point of `centers`, in
70
+ * the same order.
71
+ * @param inputs - The center points and the three side lengths
72
+ * @returns One box per center point
55
73
  * @group primitives on centers
56
74
  * @shortname cuboids
57
75
  * @drawable true
76
+ * @example
77
+ * ```typescript
78
+ * const boxes = await bitbybit.jscad.shapes.cuboidsOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0]], width: 10, height: 5, length: 20 });
79
+ * ```
58
80
  */
59
81
  cuboidsOnCenterPoints(inputs) {
60
82
  return inputs.centers.map(center => {
@@ -67,12 +89,20 @@ export class JSCADShapes {
67
89
  });
68
90
  }
69
91
  /**
70
- * Create a 3D elliptic cylinder solid
71
- * @param inputs Elliptic cylinder parameters
72
- * @returns Elliptic cylinder solid
92
+ * Builds a cylinder with an elliptical cross-section whose radii can differ at the two ends,
93
+ * standing along Z and centered on `center`.
94
+ *
95
+ * `startRadius` is the X and Y radius at the bottom end and `endRadius` at the top, so unequal
96
+ * pairs make a tapered or cone-like solid; `height` is split evenly above and below `center`.
97
+ * @param inputs - The center, the height, the two radius pairs and the segment count
98
+ * @returns The elliptic cylinder solid
73
99
  * @group primitives
74
100
  * @shortname cylinder elliptic
75
101
  * @drawable true
102
+ * @example
103
+ * ```typescript
104
+ * const cone = await bitbybit.jscad.shapes.cylinderElliptic({ center: [0, 0, 0], height: 10, startRadius: [4, 2], endRadius: [1, 0.5], segments: 32 });
105
+ * ```
76
106
  */
77
107
  cylinderElliptic(inputs) {
78
108
  return this.jscad.primitives.cylinderElliptic({
@@ -84,12 +114,17 @@ export class JSCADShapes {
84
114
  });
85
115
  }
86
116
  /**
87
- * Create a 3D elliptic cylinders on multiple center points
88
- * @param inputs Elliptic cylinders with multiple center point parameters
89
- * @returns List of elliptic cylinders solids
117
+ * Builds one elliptic cylinder with the given radii and height on every point of `centers`, in
118
+ * the same order, as `cylinderElliptic` does for one.
119
+ * @param inputs - The center points, the height, the two radius pairs and the segment count
120
+ * @returns One elliptic cylinder per center point
90
121
  * @group primitives on centers
91
122
  * @shortname cylinder elliptic
92
123
  * @drawable true
124
+ * @example
125
+ * ```typescript
126
+ * 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 });
127
+ * ```
93
128
  */
94
129
  cylinderEllipticOnCenterPoints(inputs) {
95
130
  return inputs.centers.map(center => {
@@ -103,12 +138,19 @@ export class JSCADShapes {
103
138
  });
104
139
  }
105
140
  /**
106
- * Create a 3D cylinder solid
107
- * @param inputs Cylinder parameters
108
- * @returns Cylinder solid
141
+ * Builds a round cylinder of the given `radius` standing along Z, with `height` split evenly
142
+ * above and below `center`.
143
+ *
144
+ * `segments` is the number of flat sides around it; more makes it rounder.
145
+ * @param inputs - The center, the height, the radius and the segment count
146
+ * @returns The cylinder solid
109
147
  * @group primitives
110
148
  * @shortname cylinder
111
149
  * @drawable true
150
+ * @example
151
+ * ```typescript
152
+ * const cylinder = await bitbybit.jscad.shapes.cylinder({ center: [0, 0, 0], height: 10, radius: 3, segments: 32 });
153
+ * ```
112
154
  */
113
155
  cylinder(inputs) {
114
156
  return this.jscad.primitives.cylinder({
@@ -119,12 +161,17 @@ export class JSCADShapes {
119
161
  });
120
162
  }
121
163
  /**
122
- * Create a 3D cylinders on multiple center points
123
- * @param inputs Cylinders with multiple center point parameters
124
- * @returns List of cylinder solids
164
+ * Builds one cylinder of the given `radius` and `height` on every point of `centers`, in the
165
+ * same order, as `cylinder` does for one.
166
+ * @param inputs - The center points, the height, the radius and the segment count
167
+ * @returns One cylinder per center point
125
168
  * @group primitives on centers
126
169
  * @shortname cylinder
127
170
  * @drawable true
171
+ * @example
172
+ * ```typescript
173
+ * const posts = await bitbybit.jscad.shapes.cylindersOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0], [40, 0, 0]], height: 10, radius: 1, segments: 16 });
174
+ * ```
128
175
  */
129
176
  cylindersOnCenterPoints(inputs) {
130
177
  return inputs.centers.map(center => {
@@ -137,12 +184,18 @@ export class JSCADShapes {
137
184
  });
138
185
  }
139
186
  /**
140
- * Create a 3D ellipsoid solid
141
- * @param inputs Ellipsoid parameters
142
- * @returns Ellipsoid solid
187
+ * Builds an ellipsoid, a sphere stretched separately along X, Y and Z, centered on `center`.
188
+ *
189
+ * `radius` holds the three half-sizes in `[x, y, z]` order; equal values make a sphere.
190
+ * @param inputs - The center, the three radii and the segment count
191
+ * @returns The ellipsoid solid
143
192
  * @group primitives
144
193
  * @shortname ellipsoid
145
194
  * @drawable true
195
+ * @example
196
+ * ```typescript
197
+ * const egg = await bitbybit.jscad.shapes.ellipsoid({ center: [0, 0, 0], radius: [5, 3, 8], segments: 32 });
198
+ * ```
146
199
  */
147
200
  ellipsoid(inputs) {
148
201
  return this.jscad.primitives.ellipsoid({
@@ -157,12 +210,17 @@ export class JSCADShapes {
157
210
  });
158
211
  }
159
212
  /**
160
- * Create a 3D ellipsoids on multiple center points
161
- * @param inputs Ellipsoid parameters with multiple center points
162
- * @returns List of ellipsoid solids
213
+ * Builds one ellipsoid with the given radii on every point of `centers`, in the same order, as
214
+ * `ellipsoid` does for one.
215
+ * @param inputs - The center points, the three radii and the segment count
216
+ * @returns One ellipsoid per center point
163
217
  * @group primitives on centers
164
218
  * @shortname ellipsoid
165
219
  * @drawable true
220
+ * @example
221
+ * ```typescript
222
+ * const eggs = await bitbybit.jscad.shapes.ellipsoidsOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0]], radius: [5, 3, 8], segments: 32 });
223
+ * ```
166
224
  */
167
225
  ellipsoidsOnCenterPoints(inputs) {
168
226
  return inputs.centers.map(center => {
@@ -174,12 +232,20 @@ export class JSCADShapes {
174
232
  });
175
233
  }
176
234
  /**
177
- * Create a 3D geodesic sphere solid
178
- * @param inputs Geodesic sphere parameters
179
- * @returns Geodesic sphere solid
235
+ * Builds a sphere from evenly sized triangles, the way a geodesic dome is built, centered on
236
+ * `center`.
237
+ *
238
+ * `frequency` is how finely the twenty starting faces are subdivided; it is used in whole
239
+ * multiples of 6 and must be at least 6, and higher values give a rounder sphere.
240
+ * @param inputs - The center, the radius and the subdivision frequency
241
+ * @returns The geodesic sphere solid
180
242
  * @group primitives
181
243
  * @shortname geodesic sphere
182
244
  * @drawable true
245
+ * @example
246
+ * ```typescript
247
+ * const dome = await bitbybit.jscad.shapes.geodesicSphere({ center: [0, 0, 0], radius: 5, frequency: 12 });
248
+ * ```
183
249
  */
184
250
  geodesicSphere(inputs) {
185
251
  let sphere = this.jscad.primitives.geodesicSphere({ radius: inputs.radius, frequency: inputs.frequency });
@@ -187,12 +253,17 @@ export class JSCADShapes {
187
253
  return sphere;
188
254
  }
189
255
  /**
190
- * Create a 3D geodesic spheres on multiple center points
191
- * @param inputs Geodesic sphere parameters with multiple center points
192
- * @returns List of geodesic spheres
256
+ * Builds one geodesic sphere of the given `radius` on every point of `centers`, in the same
257
+ * order, as `geodesicSphere` does for one.
258
+ * @param inputs - The center points, the radius and the subdivision frequency
259
+ * @returns One geodesic sphere per center point
193
260
  * @group primitives on centers
194
261
  * @shortname geodesic sphere
195
262
  * @drawable true
263
+ * @example
264
+ * ```typescript
265
+ * const domes = await bitbybit.jscad.shapes.geodesicSpheresOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0]], radius: 5, frequency: 12 });
266
+ * ```
196
267
  */
197
268
  geodesicSpheresOnCenterPoints(inputs) {
198
269
  return inputs.centers.map(center => {
@@ -204,12 +275,20 @@ export class JSCADShapes {
204
275
  });
205
276
  }
206
277
  /**
207
- * Create a 3D rounded cuboid solid
208
- * @param inputs Rounded cuboid parameters
209
- * @returns Rounded cuboid solid
278
+ * Builds a box with all its edges and corners rounded by `roundRadius`, centered on `center`
279
+ * with `width` along X, `height` along Y and `length` along Z.
280
+ *
281
+ * `roundRadius` must be less than half of the smallest side or an error is thrown; `segments`
282
+ * sets how smoothly the rounding is faceted.
283
+ * @param inputs - The center, the three side lengths, the rounding radius and the segment count
284
+ * @returns The rounded box solid
210
285
  * @group primitives
211
286
  * @shortname rounded cuboid
212
287
  * @drawable true
288
+ * @example
289
+ * ```typescript
290
+ * const soft = await bitbybit.jscad.shapes.roundedCuboid({ center: [0, 0, 0], width: 10, height: 5, length: 20, roundRadius: 1, segments: 16 });
291
+ * ```
213
292
  */
214
293
  roundedCuboid(inputs) {
215
294
  return this.jscad.primitives.roundedCuboid({
@@ -220,12 +299,17 @@ export class JSCADShapes {
220
299
  });
221
300
  }
222
301
  /**
223
- * Create a 3D rounded cuboids on multiple center points
224
- * @param inputs Rounded cuboids parameters with multiple center points
225
- * @returns List of rounded cuboids
302
+ * Builds one rounded box with the given sides and rounding on every point of `centers`, in the
303
+ * same order, as `roundedCuboid` does for one.
304
+ * @param inputs - The center points, the three side lengths, the rounding radius and the segment count
305
+ * @returns One rounded box per center point
226
306
  * @group primitives on centers
227
307
  * @shortname rounded cuboid
228
308
  * @drawable true
309
+ * @example
310
+ * ```typescript
311
+ * const softBoxes = await bitbybit.jscad.shapes.roundedCuboidsOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0]], width: 10, height: 5, length: 20, roundRadius: 1, segments: 16 });
312
+ * ```
229
313
  */
230
314
  roundedCuboidsOnCenterPoints(inputs) {
231
315
  return inputs.centers.map(center => {
@@ -240,12 +324,19 @@ export class JSCADShapes {
240
324
  });
241
325
  }
242
326
  /**
243
- * Create a 3D rounded cylinder solid
244
- * @param inputs Rounded cylinder parameters
245
- * @returns Rounded cylinder solid
327
+ * Builds a cylinder standing along Z whose two rims are rounded by `roundRadius`, with `height`
328
+ * split evenly above and below `center`.
329
+ *
330
+ * `height` must be more than twice `roundRadius` or an error is thrown.
331
+ * @param inputs - The center, the rounding radius, the height, the radius and the segment count
332
+ * @returns The rounded cylinder solid
246
333
  * @group primitives
247
334
  * @shortname rounded cylinder
248
335
  * @drawable true
336
+ * @example
337
+ * ```typescript
338
+ * const pill = await bitbybit.jscad.shapes.roundedCylinder({ center: [0, 0, 0], roundRadius: 1, height: 10, radius: 3, segments: 32 });
339
+ * ```
249
340
  */
250
341
  roundedCylinder(inputs) {
251
342
  return this.jscad.primitives.roundedCylinder({
@@ -257,12 +348,17 @@ export class JSCADShapes {
257
348
  });
258
349
  }
259
350
  /**
260
- * Create a 3D rounded cylinders on multiple center points
261
- * @param inputs Rounded cylinders parameters with multiple center points
262
- * @returns List of rounded cylinders
351
+ * Builds one rounded cylinder with the given size and rounding on every point of `centers`, in
352
+ * the same order, as `roundedCylinder` does for one.
353
+ * @param inputs - The center points, the rounding radius, the height, the radius and the segment count
354
+ * @returns One rounded cylinder per center point
263
355
  * @group primitives on centers
264
356
  * @shortname rounded cylinder
265
357
  * @drawable true
358
+ * @example
359
+ * ```typescript
360
+ * const pills = await bitbybit.jscad.shapes.roundedCylindersOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0]], roundRadius: 1, height: 10, radius: 3, segments: 32 });
361
+ * ```
266
362
  */
267
363
  roundedCylindersOnCenterPoints(inputs) {
268
364
  return inputs.centers.map(center => {
@@ -276,12 +372,17 @@ export class JSCADShapes {
276
372
  });
277
373
  }
278
374
  /**
279
- * Create a 3D sphere solid
280
- * @param inputs Sphere parameters
281
- * @returns Sphere solid
375
+ * Builds a sphere of the given `radius` centered on `center`; `segments` is the number of
376
+ * facets around it, so more makes it rounder.
377
+ * @param inputs - The center, the radius and the segment count
378
+ * @returns The sphere solid
282
379
  * @group primitives
283
380
  * @shortname sphere
284
381
  * @drawable true
382
+ * @example
383
+ * ```typescript
384
+ * const ball = await bitbybit.jscad.shapes.sphere({ center: [0, 0, 0], radius: 5, segments: 32 });
385
+ * ```
285
386
  */
286
387
  sphere(inputs) {
287
388
  return this.jscad.primitives.sphere({
@@ -291,12 +392,17 @@ export class JSCADShapes {
291
392
  });
292
393
  }
293
394
  /**
294
- * Create a 3D sphere on multiple center points
295
- * @param inputs Sphere parameters with multiple center points
296
- * @returns List of spheres
395
+ * Builds one sphere of the given `radius` on every point of `centers`, in the same order, as
396
+ * `sphere` does for one.
397
+ * @param inputs - The center points, the radius and the segment count
398
+ * @returns One sphere per center point
297
399
  * @group primitives on centers
298
400
  * @shortname sphere
299
401
  * @drawable true
402
+ * @example
403
+ * ```typescript
404
+ * const balls = await bitbybit.jscad.shapes.spheresOnCenterPoints({ centers: [[0, 0, 0], [20, 0, 0], [40, 0, 0]], radius: 5, segments: 32 });
405
+ * ```
300
406
  */
301
407
  spheresOnCenterPoints(inputs) {
302
408
  return inputs.centers.map(center => {
@@ -308,15 +414,24 @@ export class JSCADShapes {
308
414
  });
309
415
  }
310
416
  /**
311
- * Create a 3D torus solid
312
- * @param inputs Torus parameters
313
- * @returns Torus solid
417
+ * Builds a torus, a ring with a round cross-section, lying flat in the XY plane around `center`
418
+ * with Z through its hole.
419
+ *
420
+ * `outerRadius` is the distance from the center to the middle of the tube and `innerRadius` the
421
+ * tube's own radius, which must be smaller. Rotations and `startAngle` are in degrees; an
422
+ * `outerRotation` below 360 leaves the ring open.
423
+ * @param inputs - The center, the two radii, the two segment counts, the two rotations and the start angle
424
+ * @returns The torus solid
314
425
  * @group primitives
315
426
  * @shortname torus
316
427
  * @drawable true
428
+ * @example
429
+ * ```typescript
430
+ * 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 });
431
+ * ```
317
432
  */
318
433
  torus(inputs) {
319
- return this.jscad.primitives.torus({
434
+ const torus = this.jscad.primitives.torus({
320
435
  innerRadius: inputs.innerRadius,
321
436
  outerRadius: inputs.outerRadius,
322
437
  innerSegments: inputs.innerSegments,
@@ -325,17 +440,31 @@ export class JSCADShapes {
325
440
  outerRotation: this.math.degToRad({ number: inputs.outerRotation }),
326
441
  startAngle: this.math.degToRad({ number: inputs.startAngle }),
327
442
  });
443
+ return this.jscad.transforms.translate([inputs.center[0], inputs.center[1], inputs.center[2]], torus);
328
444
  }
329
445
  /**
330
- * Create a 3D shape from poylgon points that have to be nested arrays of points
331
- * @param inputs points
332
- * @returns shape
446
+ * Builds a solid from its faces, each given as a list of points that go around the face.
447
+ *
448
+ * List the points of every face clockwise as seen from outside the solid; the faces must close
449
+ * the solid for booleans to work on it. Each list is read in reverse order and the input is not
450
+ * changed.
451
+ * @param inputs - The faces as lists of points
452
+ * @returns The solid
333
453
  * @group shapes
334
454
  * @shortname from polygon points
335
455
  * @drawable true
456
+ * @example
457
+ * ```typescript
458
+ * const tetrahedron = await bitbybit.jscad.shapes.fromPolygonPoints({ polygonPoints: [
459
+ * [[0, 0, 0], [10, 0, 0], [0, 10, 0]],
460
+ * [[0, 0, 0], [0, 10, 0], [0, 0, 10]],
461
+ * [[0, 0, 0], [0, 0, 10], [10, 0, 0]],
462
+ * [[10, 0, 0], [0, 0, 10], [0, 10, 0]],
463
+ * ] });
464
+ * ```
336
465
  */
337
466
  fromPolygonPoints(inputs) {
338
- const pts = inputs.polygonPoints.map(vertices => vertices.reverse());
467
+ const pts = inputs.polygonPoints.map(vertices => [...vertices].reverse());
339
468
  return this.jscad.geometries.geom3.fromPoints(pts);
340
469
  }
341
470
  }
@@ -2,38 +2,65 @@ import { Base } from "@bitbybit-dev/base";
2
2
  import * as Inputs from "../inputs/jscad-inputs";
3
3
  import * as JSCAD from "@jscad/modeling";
4
4
  /**
5
- * Contains various functions for solid 3D texts from JSCAD library https://github.com/jscad/OpenJSCAD.org
6
- * Thanks JSCAD community for developing this kernel
5
+ * Writing text with JSCAD's built-in stroke font. `createVectorText` gives the pen strokes of the
6
+ * text as lists of 2D points in the XY plane; `cylindricalText` and `sphericalText` turn every
7
+ * stroke into a solid by chaining hulled cylinders or spheres along it, centered on the origin. The
8
+ * text `height` is the height of a capital letter in model units.
7
9
  */
8
10
  export declare class JSCADText {
9
11
  private readonly jscad;
10
12
  constructor(jscad: typeof JSCAD);
11
13
  /**
12
- * Creates a text that is based on chain hulling cylinders
13
- * @param inputs Cylindrical text parameters
14
- * @returns List of solids for text
14
+ * Writes text as solids: every pen stroke becomes a chain of cylinders standing along Z, hulled
15
+ * together into one smooth solid, so a letter like A gives several solids.
16
+ *
17
+ * The strokes lie in the XY plane, centered on the origin, and the cylinders are
18
+ * `extrusionHeight` long with half above and half below the plane.
19
+ * @param inputs - The text, the cylinder height and radius, the segment count and the font options
20
+ * @returns One solid per pen stroke
15
21
  * @group text
16
22
  * @shortname cylindrical
17
23
  * @drawable true
24
+ * @example
25
+ * ```typescript
26
+ * const letters = await bitbybit.jscad.text.cylindricalText({ text: "Hello", extrusionHeight: 2, extrusionSize: 0.5, segments: 16, xOffset: 0, yOffset: 0, height: 10, lineSpacing: 1.4, letterSpacing: 1, align: Bit.Inputs.JSCAD.jscadTextAlignEnum.center, extrudeOffset: 0 });
27
+ * ```
18
28
  */
19
29
  cylindricalText(inputs: Inputs.JSCAD.CylinderTextDto): Inputs.JSCAD.JSCADEntity[];
20
30
  /**
21
- * Creates a text that is based on chain hulling spheres
22
- * @param inputs Spherical text parameters
23
- * @returns List of solids for text
31
+ * Writes text as solids: every pen stroke becomes a chain of spheres hulled together into one
32
+ * rounded solid, so a letter like A gives several solids.
33
+ *
34
+ * The strokes lie in the XY plane, centered on the origin, and the spheres of `radius` sit on
35
+ * that plane.
36
+ * @param inputs - The text, the sphere radius, the segment count and the font options
37
+ * @returns One solid per pen stroke
24
38
  * @group text
25
39
  * @shortname spherical
26
40
  * @drawable true
41
+ * @example
42
+ * ```typescript
43
+ * const letters = await bitbybit.jscad.text.sphericalText({ text: "Hello", radius: 0.5, segments: 16, xOffset: 0, yOffset: 0, height: 10, lineSpacing: 1.4, letterSpacing: 1, align: Bit.Inputs.JSCAD.jscadTextAlignEnum.center, extrudeOffset: 0 });
44
+ * ```
27
45
  */
28
46
  sphericalText(inputs: Inputs.JSCAD.SphereTextDto): Inputs.JSCAD.JSCADEntity[];
29
47
  private adjustTextToBeOnCenter;
30
48
  /**
31
- * Creates a vector text
32
- * @param inputs Vector text parameters
33
- * @returns List of polygons
49
+ * Writes text as pen strokes: each stroke is a list of 2D points in the XY plane, and a letter
50
+ * may take several.
51
+ *
52
+ * The text starts at `xOffset`, `yOffset` and is not centered; `height` is the height of a
53
+ * capital letter, `lineSpacing` and `letterSpacing` scale the gaps and `align` places the lines
54
+ * of a multi-line text.
55
+ * @param inputs - The text and the font options
56
+ * @returns The strokes as lists of 2D points
34
57
  * @group text
35
58
  * @shortname vector
36
59
  * @drawable false
60
+ * @example
61
+ * ```typescript
62
+ * const strokes = await bitbybit.jscad.text.createVectorText({ text: "Hi", segments: 16, xOffset: 0, yOffset: 0, height: 10, lineSpacing: 1.4, letterSpacing: 1, align: Bit.Inputs.JSCAD.jscadTextAlignEnum.center, extrudeOffset: 0 });
63
+ * ```
37
64
  */
38
65
  createVectorText(inputs: Inputs.JSCAD.TextDto): Base.Point2[][];
39
66
  }
@@ -1,18 +1,28 @@
1
1
  /**
2
- * Contains various functions for solid 3D texts from JSCAD library https://github.com/jscad/OpenJSCAD.org
3
- * Thanks JSCAD community for developing this kernel
2
+ * Writing text with JSCAD's built-in stroke font. `createVectorText` gives the pen strokes of the
3
+ * text as lists of 2D points in the XY plane; `cylindricalText` and `sphericalText` turn every
4
+ * stroke into a solid by chaining hulled cylinders or spheres along it, centered on the origin. The
5
+ * text `height` is the height of a capital letter in model units.
4
6
  */
5
7
  export class JSCADText {
6
8
  constructor(jscad) {
7
9
  this.jscad = jscad;
8
10
  }
9
11
  /**
10
- * Creates a text that is based on chain hulling cylinders
11
- * @param inputs Cylindrical text parameters
12
- * @returns List of solids for text
12
+ * Writes text as solids: every pen stroke becomes a chain of cylinders standing along Z, hulled
13
+ * together into one smooth solid, so a letter like A gives several solids.
14
+ *
15
+ * The strokes lie in the XY plane, centered on the origin, and the cylinders are
16
+ * `extrusionHeight` long with half above and half below the plane.
17
+ * @param inputs - The text, the cylinder height and radius, the segment count and the font options
18
+ * @returns One solid per pen stroke
13
19
  * @group text
14
20
  * @shortname cylindrical
15
21
  * @drawable true
22
+ * @example
23
+ * ```typescript
24
+ * const letters = await bitbybit.jscad.text.cylindricalText({ text: "Hello", extrusionHeight: 2, extrusionSize: 0.5, segments: 16, xOffset: 0, yOffset: 0, height: 10, lineSpacing: 1.4, letterSpacing: 1, align: Bit.Inputs.JSCAD.jscadTextAlignEnum.center, extrudeOffset: 0 });
25
+ * ```
16
26
  */
17
27
  cylindricalText(inputs) {
18
28
  const text = this.createVectorText(inputs);
@@ -30,12 +40,20 @@ export class JSCADText {
30
40
  });
31
41
  }
32
42
  /**
33
- * Creates a text that is based on chain hulling spheres
34
- * @param inputs Spherical text parameters
35
- * @returns List of solids for text
43
+ * Writes text as solids: every pen stroke becomes a chain of spheres hulled together into one
44
+ * rounded solid, so a letter like A gives several solids.
45
+ *
46
+ * The strokes lie in the XY plane, centered on the origin, and the spheres of `radius` sit on
47
+ * that plane.
48
+ * @param inputs - The text, the sphere radius, the segment count and the font options
49
+ * @returns One solid per pen stroke
36
50
  * @group text
37
51
  * @shortname spherical
38
52
  * @drawable true
53
+ * @example
54
+ * ```typescript
55
+ * const letters = await bitbybit.jscad.text.sphericalText({ text: "Hello", radius: 0.5, segments: 16, xOffset: 0, yOffset: 0, height: 10, lineSpacing: 1.4, letterSpacing: 1, align: Bit.Inputs.JSCAD.jscadTextAlignEnum.center, extrudeOffset: 0 });
56
+ * ```
39
57
  */
40
58
  sphericalText(inputs) {
41
59
  const text = this.createVectorText(inputs);
@@ -70,12 +88,21 @@ export class JSCADText {
70
88
  });
71
89
  }
72
90
  /**
73
- * Creates a vector text
74
- * @param inputs Vector text parameters
75
- * @returns List of polygons
91
+ * Writes text as pen strokes: each stroke is a list of 2D points in the XY plane, and a letter
92
+ * may take several.
93
+ *
94
+ * The text starts at `xOffset`, `yOffset` and is not centered; `height` is the height of a
95
+ * capital letter, `lineSpacing` and `letterSpacing` scale the gaps and `align` places the lines
96
+ * of a multi-line text.
97
+ * @param inputs - The text and the font options
98
+ * @returns The strokes as lists of 2D points
76
99
  * @group text
77
100
  * @shortname vector
78
101
  * @drawable false
102
+ * @example
103
+ * ```typescript
104
+ * const strokes = await bitbybit.jscad.text.createVectorText({ text: "Hi", segments: 16, xOffset: 0, yOffset: 0, height: 10, lineSpacing: 1.4, letterSpacing: 1, align: Bit.Inputs.JSCAD.jscadTextAlignEnum.center, extrudeOffset: 0 });
105
+ * ```
79
106
  */
80
107
  createVectorText(inputs) {
81
108
  return this.jscad.text.vectorText({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bitbybit-dev/jscad",
3
- "version": "1.2.0",
3
+ "version": "1.3.0-rc.0",
4
4
  "description": "Bit By Bit Developers JSCAD based CAD Library to Program Geometry",
5
5
  "homepage": "https://docs.bitbybit.dev/classes/Bit.JSCAD",
6
6
  "main": "index.js",
@@ -54,11 +54,11 @@
54
54
  "types": "./index.d.ts",
55
55
  "type": "module",
56
56
  "dependencies": {
57
- "@bitbybit-dev/base": "1.2.0",
58
- "@jscad/io-utils": "2.0.28",
59
- "@jscad/modeling": "2.12.3",
60
- "@jscad/stl-serializer": "2.1.18",
61
- "@jscad/dxf-serializer": "2.1.18",
62
- "@jscad/3mf-serializer": "2.1.12"
57
+ "@bitbybit-dev/base": "1.3.0-rc.0",
58
+ "@jscad/io-utils": "2.0.33",
59
+ "@jscad/modeling": "2.13.0",
60
+ "@jscad/stl-serializer": "2.1.23",
61
+ "@jscad/dxf-serializer": "2.1.23",
62
+ "@jscad/3mf-serializer": "2.1.17"
63
63
  }
64
64
  }