@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.
@@ -1,91 +1,151 @@
1
- import { asKind } from "./entity-narrowing";
1
+ import { asKind, asSolid } from "./entity-narrowing";
2
2
  /**
3
- * Contains various functions for Solid booleans from JSCAD library https://github.com/jscad/OpenJSCAD.org
4
- * Thanks JSCAD community for developing this kernel
3
+ * Combining JSCAD geometry: union fuses, subtract cuts and intersect keeps the overlap, in a
4
+ * two-input form and a many-input form. All inputs of one call must be of the same kind, either
5
+ * solids or flat 2D shapes, or the kernel throws an error; a path cannot be combined. Every method
6
+ * gives new geometry and leaves the inputs as they are.
5
7
  */
6
8
  export class JSCADBooleans {
7
9
  constructor(jscad) {
8
10
  this.jscad = jscad;
9
11
  }
10
12
  /**
11
- * Intersect multiple solid mesh objects
12
- * @param inputs Contains multiple solids for intersection
13
- * @returns Solid mesh
13
+ * Keeps only the volume or area that all the inputs share, dropping everything else.
14
+ *
15
+ * The inputs must all be solids or all be 2D shapes; an empty result is possible when they do
16
+ * not overlap.
17
+ * @param inputs - The solids or 2D shapes to intersect
18
+ * @returns The shared part as one solid or 2D shape
14
19
  * @group boolean
15
20
  * @shortname intersect
16
21
  * @drawable true
22
+ * @example
23
+ * ```typescript
24
+ * const common = await bitbybit.jscad.booleans.intersect({ meshes: [cube, sphere] });
25
+ * ```
17
26
  */
18
27
  intersect(inputs) {
19
28
  return this.jscad.booleans.intersect(...asKind(inputs.meshes));
20
29
  }
21
30
  /**
22
- * Subtract multiple solid mesh objects
23
- * @param inputs Contains multiple solids for subtraction
24
- * @returns Solid mesh
31
+ * Cuts every later input out of the first one, leaving what remains of the first.
32
+ *
33
+ * The inputs must all be solids or all be 2D shapes; the order matters, the first is the one
34
+ * being cut.
35
+ * @param inputs - The geometry to cut from, first, followed by the geometry to cut with
36
+ * @returns The first input minus the others
25
37
  * @group boolean
26
38
  * @shortname subtract
27
39
  * @drawable true
40
+ * @example
41
+ * ```typescript
42
+ * const holed = await bitbybit.jscad.booleans.subtract({ meshes: [cube, cylinder1, cylinder2] });
43
+ * ```
28
44
  */
29
45
  subtract(inputs) {
30
46
  return this.jscad.booleans.subtract(...asKind(inputs.meshes));
31
47
  }
32
48
  /**
33
- * Union multiple solid mesh objects
34
- * @param inputs Contains multiple solids for union
35
- * @returns Solid mesh
49
+ * Fuses all the inputs into one solid or one 2D shape, merging where they overlap and keeping
50
+ * separate parts as one entity.
51
+ *
52
+ * The inputs must all be solids or all be 2D shapes.
53
+ * @param inputs - The solids or 2D shapes to fuse
54
+ * @returns The fused solid or 2D shape
36
55
  * @group boolean
37
56
  * @shortname union
38
57
  * @drawable true
58
+ * @example
59
+ * ```typescript
60
+ * const fused = await bitbybit.jscad.booleans.union({ meshes: [cube, sphere] });
61
+ * ```
39
62
  */
40
63
  union(inputs) {
41
64
  return this.jscad.booleans.union(...asKind(inputs.meshes));
42
65
  }
43
66
  /**
44
- * Intersect two solid mesh objects
45
- * @param inputs Contains multiple solids for intersection
46
- * @returns Solid mesh
67
+ * Keeps only the volume or area that `first` and `second` share, the two-input form of
68
+ * `intersect`.
69
+ * @param inputs - The two solids or two 2D shapes
70
+ * @returns The shared part
47
71
  * @group boolean
48
72
  * @shortname intersect two
49
73
  * @drawable true
74
+ * @example
75
+ * ```typescript
76
+ * const common = await bitbybit.jscad.booleans.intersectTwo({ first: cube, second: sphere });
77
+ * ```
50
78
  */
51
79
  intersectTwo(inputs) {
52
80
  const meshes = asKind([inputs.first, inputs.second]);
53
81
  return this.jscad.booleans.intersect(...meshes);
54
82
  }
55
83
  /**
56
- * Subtract two solid mesh objects
57
- * @param inputs Contains multiple solids for subtraction
58
- * @returns Solid mesh
84
+ * Cuts `second` out of `first`, the two-input form of `subtract`.
85
+ * @param inputs - The geometry to cut from and the geometry to cut with
86
+ * @returns The first input minus the second
59
87
  * @group boolean
60
88
  * @shortname subtract two
61
89
  * @drawable true
90
+ * @example
91
+ * ```typescript
92
+ * const holed = await bitbybit.jscad.booleans.subtractTwo({ first: cube, second: sphere });
93
+ * ```
62
94
  */
63
95
  subtractTwo(inputs) {
64
96
  const meshes = asKind([inputs.first, inputs.second]);
65
97
  return this.jscad.booleans.subtract(...meshes);
66
98
  }
67
99
  /**
68
- * Union two solid mesh objects
69
- * @param inputs Contains multiple solids for union
70
- * @returns Solid mesh
100
+ * Fuses `first` and `second` into one, the two-input form of `union`.
101
+ * @param inputs - The two solids or two 2D shapes
102
+ * @returns The fused solid or 2D shape
71
103
  * @group boolean
72
104
  * @shortname union two
73
105
  * @drawable true
106
+ * @example
107
+ * ```typescript
108
+ * const fused = await bitbybit.jscad.booleans.unionTwo({ first: cube, second: sphere });
109
+ * ```
74
110
  */
75
111
  unionTwo(inputs) {
76
112
  const meshes = asKind([inputs.first, inputs.second]);
77
113
  return this.jscad.booleans.union(...meshes);
78
114
  }
79
115
  /**
80
- * Subtract multiple meshes from one mesh object
81
- * @param inputs Contains mesh from which to subtract and multiple meshes for subtraction
82
- * @returns mesh
116
+ * Cuts every entry of `meshes` out of `from`, leaving what remains of `from`; the same as
117
+ * `subtract` with the base geometry named separately.
118
+ * @param inputs - The geometry to cut from and the list of geometry to cut with
119
+ * @returns The base geometry minus the others
83
120
  * @group boolean
84
121
  * @shortname subtract from
85
122
  * @drawable true
123
+ * @example
124
+ * ```typescript
125
+ * const holed = await bitbybit.jscad.booleans.subtractFrom({ from: cube, meshes: [cylinder1, cylinder2] });
126
+ * ```
86
127
  */
87
128
  subtractFrom(inputs) {
88
129
  const meshes = asKind([inputs.from, ...inputs.meshes]);
89
130
  return this.jscad.booleans.subtract(...meshes);
90
131
  }
132
+ /**
133
+ * Sweeps each later solid over the whole surface of the running result and fuses everything it
134
+ * passes through, so the first solid grows by the shape of the others - the Minkowski sum,
135
+ * which is how a solid is rounded or padded by a sphere.
136
+ *
137
+ * Solids only; a 2D shape or a path throws an error.
138
+ * @param inputs - The solids to sum, at least two
139
+ * @returns The grown solid
140
+ * @group minkowski
141
+ * @shortname minkowski sum
142
+ * @drawable true
143
+ * @example
144
+ * ```typescript
145
+ * const padded = await bitbybit.jscad.booleans.minkowskiSum({ meshes: [cube, sphere] });
146
+ * ```
147
+ */
148
+ minkowskiSum(inputs) {
149
+ return this.jscad.minkowski.minkowskiSum(...inputs.meshes.map((mesh) => asSolid(mesh, "minkowskiSum")));
150
+ }
91
151
  }
@@ -1,19 +1,28 @@
1
1
  import * as Inputs from "../inputs/jscad-inputs";
2
2
  import * as JSCAD from "@jscad/modeling";
3
3
  /**
4
- * Contains functions for colorizing objects
4
+ * Giving JSCAD geometry a color of its own. A colored entity is always drawn in that color, ahead
5
+ * of whatever color the drawing options ask for; the color survives transforms but a boolean result
6
+ * starts uncolored again.
5
7
  */
6
8
  export declare class JSCADColors {
7
9
  private readonly jscad;
8
10
  constructor(jscad: typeof JSCAD);
9
11
  /**
10
- * Colorizes geometry of jscad. If geometry is in the array it will colorize all items and return them. If geometry is a single item it will return a single item.
11
- * Keep in mind that colorized geometry in jscad will always be drawn in that color even if you try to change it via draw options.
12
- * @param inputs contain geometry and hex color
13
- * @returns Colorized geometry of jsacd
12
+ * Gives a solid, a 2D shape or a path a fixed color from a hex string, returning a colored
13
+ * copy; a list gives a list of colored copies in the same order.
14
+ *
15
+ * The color wins over the color of the drawing options, so leave the entity uncolored to
16
+ * control it there.
17
+ * @param inputs - The geometry, or a list of it, and the hex color
18
+ * @returns The colored geometry, one or a list to match the input
14
19
  * @group colorize
15
20
  * @shortname colorize geometry
16
21
  * @drawable true
22
+ * @example
23
+ * ```typescript
24
+ * const red = await bitbybit.jscad.colors.colorize({ geometry: cube, color: "#ff0000" });
25
+ * ```
17
26
  */
18
27
  colorize(inputs: Inputs.JSCAD.ColorizeDto): Inputs.JSCAD.JSCADEntity | Inputs.JSCAD.JSCADEntity[];
19
28
  }
@@ -1,18 +1,27 @@
1
1
  /**
2
- * Contains functions for colorizing objects
2
+ * Giving JSCAD geometry a color of its own. A colored entity is always drawn in that color, ahead
3
+ * of whatever color the drawing options ask for; the color survives transforms but a boolean result
4
+ * starts uncolored again.
3
5
  */
4
6
  export class JSCADColors {
5
7
  constructor(jscad) {
6
8
  this.jscad = jscad;
7
9
  }
8
10
  /**
9
- * Colorizes geometry of jscad. If geometry is in the array it will colorize all items and return them. If geometry is a single item it will return a single item.
10
- * Keep in mind that colorized geometry in jscad will always be drawn in that color even if you try to change it via draw options.
11
- * @param inputs contain geometry and hex color
12
- * @returns Colorized geometry of jsacd
11
+ * Gives a solid, a 2D shape or a path a fixed color from a hex string, returning a colored
12
+ * copy; a list gives a list of colored copies in the same order.
13
+ *
14
+ * The color wins over the color of the drawing options, so leave the entity uncolored to
15
+ * control it there.
16
+ * @param inputs - The geometry, or a list of it, and the hex color
17
+ * @returns The colored geometry, one or a list to match the input
13
18
  * @group colorize
14
19
  * @shortname colorize geometry
15
20
  * @drawable true
21
+ * @example
22
+ * ```typescript
23
+ * const red = await bitbybit.jscad.colors.colorize({ geometry: cube, color: "#ff0000" });
24
+ * ```
16
25
  */
17
26
  colorize(inputs) {
18
27
  const geometry = inputs.geometry;
@@ -1,28 +1,49 @@
1
1
  import * as Inputs from "../inputs/jscad-inputs";
2
2
  import * as JSCAD from "@jscad/modeling";
3
3
  /**
4
- * Contains various functions for Solid expansions from JSCAD library https://github.com/jscad/OpenJSCAD.org
5
- * Thanks JSCAD community for developing this kernel
4
+ * Growing and shrinking JSCAD geometry by a distance: `expand` moves every boundary outward, or
5
+ * inward for a negative distance, and `offset` builds the outline at that distance. Both work on
6
+ * flat 2D shapes and paths and shape their corners as `corners` says; `expand` also grows solids,
7
+ * with round corners only.
6
8
  */
7
9
  export declare class JSCADExpansions {
8
10
  private readonly jscad;
9
11
  constructor(jscad: typeof JSCAD);
10
12
  /**
11
- * Expand geometries of solid category
12
- * @param inputs Contains options and geometries for expansion
13
- * @returns Expanded geometry
13
+ * Grows geometry by moving its whole boundary outward by `delta`, or shrinks it when `delta` is
14
+ * negative.
15
+ *
16
+ * A 2D shape stays a 2D shape, a path becomes a 2D band of that width around it, and a solid
17
+ * grows into a bigger solid, with round corners and a positive `delta` only. Corners are
18
+ * rounded when `corners` is left out.
19
+ * @param inputs - The geometry, the distance, the corner style and the segments for round corners
20
+ * @returns The grown or shrunk geometry
14
21
  * @group expansion
15
22
  * @shortname expand
16
23
  * @drawable true
24
+ * @example
25
+ * ```typescript
26
+ * const square = await bitbybit.jscad.polygon.square({ center: [0, 0], size: 10 });
27
+ * const grown = await bitbybit.jscad.expansions.expand({ geometry: square, delta: 1, corners: Bit.Inputs.JSCAD.solidCornerTypeEnum.round, segments: 16 });
28
+ * ```
17
29
  */
18
30
  expand(inputs: Inputs.JSCAD.ExpansionDto): Inputs.JSCAD.JSCADEntity;
19
31
  /**
20
- * Offset 2d geometries of solid category
21
- * @param inputs Contains options and geometries for offset
22
- * @returns Expanded geometry
32
+ * Builds the outline of a 2D shape or path at distance `delta` from the original, outward for
33
+ * positive and inward for negative.
34
+ *
35
+ * A 2D shape gives a bigger or smaller 2D shape and a path gives a parallel path. When
36
+ * `corners` is left out, corners are kept sharp.
37
+ * @param inputs - The 2D shape or path, the distance, the corner style and the segments for round corners
38
+ * @returns The offset 2D shape or path
23
39
  * @group expansion
24
40
  * @shortname offset
25
41
  * @drawable true
42
+ * @example
43
+ * ```typescript
44
+ * const path = await bitbybit.jscad.path.createFromPoints({ points: [[0, 0], [10, 0], [10, 10]], closed: false });
45
+ * const parallel = await bitbybit.jscad.expansions.offset({ geometry: path, delta: 1, corners: Bit.Inputs.JSCAD.solidCornerTypeEnum.edge, segments: 16 });
46
+ * ```
26
47
  */
27
48
  offset(inputs: Inputs.JSCAD.ExpansionDto): Inputs.JSCAD.JSCADEntity;
28
49
  }
@@ -1,49 +1,66 @@
1
1
  import * as Inputs from "../inputs/jscad-inputs";
2
2
  import { asEntity, asKind, oneOrMany } from "./entity-narrowing";
3
3
  /**
4
- * Contains various functions for Solid expansions from JSCAD library https://github.com/jscad/OpenJSCAD.org
5
- * Thanks JSCAD community for developing this kernel
4
+ * Growing and shrinking JSCAD geometry by a distance: `expand` moves every boundary outward, or
5
+ * inward for a negative distance, and `offset` builds the outline at that distance. Both work on
6
+ * flat 2D shapes and paths and shape their corners as `corners` says; `expand` also grows solids,
7
+ * with round corners only.
6
8
  */
7
9
  export class JSCADExpansions {
8
10
  constructor(jscad) {
9
11
  this.jscad = jscad;
10
12
  }
11
13
  /**
12
- * Expand geometries of solid category
13
- * @param inputs Contains options and geometries for expansion
14
- * @returns Expanded geometry
14
+ * Grows geometry by moving its whole boundary outward by `delta`, or shrinks it when `delta` is
15
+ * negative.
16
+ *
17
+ * A 2D shape stays a 2D shape, a path becomes a 2D band of that width around it, and a solid
18
+ * grows into a bigger solid, with round corners and a positive `delta` only. Corners are
19
+ * rounded when `corners` is left out.
20
+ * @param inputs - The geometry, the distance, the corner style and the segments for round corners
21
+ * @returns The grown or shrunk geometry
15
22
  * @group expansion
16
23
  * @shortname expand
17
24
  * @drawable true
25
+ * @example
26
+ * ```typescript
27
+ * const square = await bitbybit.jscad.polygon.square({ center: [0, 0], size: 10 });
28
+ * const grown = await bitbybit.jscad.expansions.expand({ geometry: square, delta: 1, corners: Bit.Inputs.JSCAD.solidCornerTypeEnum.round, segments: 16 });
29
+ * ```
18
30
  */
19
31
  expand(inputs) {
20
32
  const geometry = asKind(oneOrMany(inputs.geometry));
21
- if (!inputs.corners) {
22
- inputs.corners = Inputs.JSCAD.solidCornerTypeEnum.round;
23
- }
33
+ const corners = inputs.corners || Inputs.JSCAD.solidCornerTypeEnum.round;
24
34
  const result = this.jscad.expansions.expand({
25
35
  delta: inputs.delta,
26
- corners: inputs.corners,
36
+ corners,
27
37
  segments: inputs.segments,
28
38
  }, ...geometry);
29
39
  return asEntity(result);
30
40
  }
31
41
  /**
32
- * Offset 2d geometries of solid category
33
- * @param inputs Contains options and geometries for offset
34
- * @returns Expanded geometry
42
+ * Builds the outline of a 2D shape or path at distance `delta` from the original, outward for
43
+ * positive and inward for negative.
44
+ *
45
+ * A 2D shape gives a bigger or smaller 2D shape and a path gives a parallel path. When
46
+ * `corners` is left out, corners are kept sharp.
47
+ * @param inputs - The 2D shape or path, the distance, the corner style and the segments for round corners
48
+ * @returns The offset 2D shape or path
35
49
  * @group expansion
36
50
  * @shortname offset
37
51
  * @drawable true
52
+ * @example
53
+ * ```typescript
54
+ * const path = await bitbybit.jscad.path.createFromPoints({ points: [[0, 0], [10, 0], [10, 10]], closed: false });
55
+ * const parallel = await bitbybit.jscad.expansions.offset({ geometry: path, delta: 1, corners: Bit.Inputs.JSCAD.solidCornerTypeEnum.edge, segments: 16 });
56
+ * ```
38
57
  */
39
58
  offset(inputs) {
40
59
  const geometry = asKind(oneOrMany(inputs.geometry));
41
- if (!inputs.corners) {
42
- inputs.corners = Inputs.JSCAD.solidCornerTypeEnum.edge;
43
- }
60
+ const corners = inputs.corners || Inputs.JSCAD.solidCornerTypeEnum.edge;
44
61
  const result = this.jscad.expansions.offset({
45
62
  delta: inputs.delta,
46
- corners: inputs.corners,
63
+ corners,
47
64
  segments: inputs.segments,
48
65
  }, ...geometry);
49
66
  return asEntity(result);
@@ -3,8 +3,9 @@ import * as Inputs from "../inputs/jscad-inputs";
3
3
  import { MathBitByBit } from "@bitbybit-dev/base";
4
4
  import * as JSCAD from "@jscad/modeling";
5
5
  /**
6
- * Contains various functions for Solid extrusions from JSCAD library https://github.com/jscad/OpenJSCAD.org
7
- * Thanks JSCAD community for developing this kernel
6
+ * Turning flat JSCAD shapes into solids: straight extrusion along Z with an optional twist, a wall
7
+ * built along an outline, and revolution around the Z axis. Every flat shape lies in the XY plane,
8
+ * so the result grows out of that plane along Z.
8
9
  */
9
10
  export declare class JSCADExtrusions {
10
11
  private readonly jscad;
@@ -12,39 +13,74 @@ export declare class JSCADExtrusions {
12
13
  private readonly math;
13
14
  constructor(jscad: typeof JSCAD, geometryHelper: GeometryHelper, math: MathBitByBit);
14
15
  /**
15
- * Linear extrude 2D geometries of solid category
16
- * @param inputs Contains options and geometries for linear extrude
17
- * @returns Extruded geometry
16
+ * Extrudes a flat 2D shape straight along Z by `height` into a solid, twisting it on the way
17
+ * when `twistAngle` is not zero.
18
+ *
19
+ * `twistAngle` in degrees turns the top relative to the bottom around Z and `twistSteps` is the
20
+ * number of slices used for it, at least 1. A negative `height` extrudes downward.
21
+ * @param inputs - The 2D shape, the height, the twist angle and the twist steps
22
+ * @returns The extruded solid
18
23
  * @group extrude
19
24
  * @shortname linear
20
25
  * @drawable true
26
+ * @example
27
+ * ```typescript
28
+ * const square = await bitbybit.jscad.polygon.square({ center: [0, 0], size: 10 });
29
+ * const twisted = await bitbybit.jscad.extrusions.extrudeLinear({ geometry: square, height: 20, twistAngle: 90, twistSteps: 15 });
30
+ * ```
21
31
  */
22
32
  extrudeLinear(inputs: Inputs.JSCAD.ExtrudeLinearDto): Inputs.JSCAD.JSCADEntity;
23
33
  /**
24
- * Rectangular extrude 2D geometries of solid category. Creates a wall-type extrusion of certain height and size.
25
- * @param inputs Contains options and geometries for rectangular extrude
26
- * @returns Extruded geometry
34
+ * Builds a wall along the outline of a 2D shape or path: the outline is thickened by `size` on
35
+ * each side and raised by `height` along Z.
36
+ *
37
+ * The wall stands on the XY plane and is twice `size` thick, centered on the outline; the
38
+ * inside of a 2D shape stays empty. A list of inputs gives a list of walls.
39
+ * @param inputs - The 2D shape or path, the height and the half thickness
40
+ * @returns The wall as a solid
27
41
  * @group extrude
28
42
  * @shortname rectangular
29
43
  * @drawable true
44
+ * @example
45
+ * ```typescript
46
+ * const circle = await bitbybit.jscad.polygon.circle({ center: [0, 0], radius: 10, segments: 32 });
47
+ * const ring = await bitbybit.jscad.extrusions.extrudeRectangular({ geometry: circle, height: 5, size: 0.5 });
48
+ * ```
30
49
  */
31
50
  extrudeRectangular(inputs: Inputs.JSCAD.ExtrudeRectangularDto): Inputs.JSCAD.JSCADEntity;
32
51
  /**
33
- * Rectangular extrude a list of 2D points. Creates a wall-type extrusion of certain height and size.
34
- * @param inputs Contains options and points for extrusion
35
- * @returns Extruded geometry
52
+ * Builds a wall along a polyline of points, as `extrudeRectangular` does for a path: the line
53
+ * is thickened by `size` on each side and raised by `height` along Z.
54
+ *
55
+ * Only the X and Y coordinates of the points are used and repeated consecutive points are
56
+ * dropped.
57
+ * @param inputs - The points, the height and the half thickness
58
+ * @returns The wall as a solid
36
59
  * @group extrude
37
60
  * @shortname rectangular points
38
61
  * @drawable true
62
+ * @example
63
+ * ```typescript
64
+ * const wall = await bitbybit.jscad.extrusions.extrudeRectangularPoints({ points: [[0, 0, 0], [10, 0, 0], [10, 10, 0]], height: 5, size: 0.5 });
65
+ * ```
39
66
  */
40
67
  extrudeRectangularPoints(inputs: Inputs.JSCAD.ExtrudeRectangularPointsDto): Inputs.JSCAD.JSCADEntity;
41
68
  /**
42
- * Rectangular extrude a list of 2D points. Creates a wall-type extrusion of certain height and size.
43
- * @param inputs Contains options and points for extrusion
44
- * @returns Extruded geometry
69
+ * Revolves a flat 2D shape around the Z axis into a solid.
70
+ *
71
+ * The shape lies in the XY plane, so its X coordinate is its distance from the axis, and a
72
+ * shape crossing the axis is clipped there. `angle` and `startAngle` are in degrees, 360 makes
73
+ * a full ring, and `segments` counts the steps of a full turn.
74
+ * @param inputs - The 2D shape, the sweep angle, the start angle and the segment count
75
+ * @returns The revolved solid
45
76
  * @group extrude
46
77
  * @shortname rotational
47
78
  * @drawable true
79
+ * @example
80
+ * ```typescript
81
+ * const profile = await bitbybit.jscad.polygon.circle({ center: [10, 0], radius: 3, segments: 24 });
82
+ * const ring = await bitbybit.jscad.extrusions.extrudeRotate({ polygon: profile, angle: 360, startAngle: 0, segments: 48 });
83
+ * ```
48
84
  */
49
85
  extrudeRotate(inputs: Inputs.JSCAD.ExtrudeRotateDto): Inputs.JSCAD.JSCADEntity;
50
86
  }
@@ -1,7 +1,8 @@
1
1
  import { asKind, asRegion, oneOrMany } from "./entity-narrowing";
2
2
  /**
3
- * Contains various functions for Solid extrusions from JSCAD library https://github.com/jscad/OpenJSCAD.org
4
- * Thanks JSCAD community for developing this kernel
3
+ * Turning flat JSCAD shapes into solids: straight extrusion along Z with an optional twist, a wall
4
+ * built along an outline, and revolution around the Z axis. Every flat shape lies in the XY plane,
5
+ * so the result grows out of that plane along Z.
5
6
  */
6
7
  export class JSCADExtrusions {
7
8
  constructor(jscad, geometryHelper, math) {
@@ -10,12 +11,21 @@ export class JSCADExtrusions {
10
11
  this.math = math;
11
12
  }
12
13
  /**
13
- * Linear extrude 2D geometries of solid category
14
- * @param inputs Contains options and geometries for linear extrude
15
- * @returns Extruded geometry
14
+ * Extrudes a flat 2D shape straight along Z by `height` into a solid, twisting it on the way
15
+ * when `twistAngle` is not zero.
16
+ *
17
+ * `twistAngle` in degrees turns the top relative to the bottom around Z and `twistSteps` is the
18
+ * number of slices used for it, at least 1. A negative `height` extrudes downward.
19
+ * @param inputs - The 2D shape, the height, the twist angle and the twist steps
20
+ * @returns The extruded solid
16
21
  * @group extrude
17
22
  * @shortname linear
18
23
  * @drawable true
24
+ * @example
25
+ * ```typescript
26
+ * const square = await bitbybit.jscad.polygon.square({ center: [0, 0], size: 10 });
27
+ * const twisted = await bitbybit.jscad.extrusions.extrudeLinear({ geometry: square, height: 20, twistAngle: 90, twistSteps: 15 });
28
+ * ```
19
29
  */
20
30
  extrudeLinear(inputs) {
21
31
  const geometry = asKind(oneOrMany(inputs.geometry));
@@ -27,12 +37,21 @@ export class JSCADExtrusions {
27
37
  return extrusions;
28
38
  }
29
39
  /**
30
- * Rectangular extrude 2D geometries of solid category. Creates a wall-type extrusion of certain height and size.
31
- * @param inputs Contains options and geometries for rectangular extrude
32
- * @returns Extruded geometry
40
+ * Builds a wall along the outline of a 2D shape or path: the outline is thickened by `size` on
41
+ * each side and raised by `height` along Z.
42
+ *
43
+ * The wall stands on the XY plane and is twice `size` thick, centered on the outline; the
44
+ * inside of a 2D shape stays empty. A list of inputs gives a list of walls.
45
+ * @param inputs - The 2D shape or path, the height and the half thickness
46
+ * @returns The wall as a solid
33
47
  * @group extrude
34
48
  * @shortname rectangular
35
49
  * @drawable true
50
+ * @example
51
+ * ```typescript
52
+ * const circle = await bitbybit.jscad.polygon.circle({ center: [0, 0], radius: 10, segments: 32 });
53
+ * const ring = await bitbybit.jscad.extrusions.extrudeRectangular({ geometry: circle, height: 5, size: 0.5 });
54
+ * ```
36
55
  */
37
56
  extrudeRectangular(inputs) {
38
57
  const geometry = asKind(oneOrMany(inputs.geometry));
@@ -40,12 +59,20 @@ export class JSCADExtrusions {
40
59
  return extrusions;
41
60
  }
42
61
  /**
43
- * Rectangular extrude a list of 2D points. Creates a wall-type extrusion of certain height and size.
44
- * @param inputs Contains options and points for extrusion
45
- * @returns Extruded geometry
62
+ * Builds a wall along a polyline of points, as `extrudeRectangular` does for a path: the line
63
+ * is thickened by `size` on each side and raised by `height` along Z.
64
+ *
65
+ * Only the X and Y coordinates of the points are used and repeated consecutive points are
66
+ * dropped.
67
+ * @param inputs - The points, the height and the half thickness
68
+ * @returns The wall as a solid
46
69
  * @group extrude
47
70
  * @shortname rectangular points
48
71
  * @drawable true
72
+ * @example
73
+ * ```typescript
74
+ * const wall = await bitbybit.jscad.extrusions.extrudeRectangularPoints({ points: [[0, 0, 0], [10, 0, 0], [10, 10, 0]], height: 5, size: 0.5 });
75
+ * ```
49
76
  */
50
77
  extrudeRectangularPoints(inputs) {
51
78
  const twoDimensionalPoints = inputs.points.map(pt => [pt[0], pt[1]]);
@@ -55,12 +82,21 @@ export class JSCADExtrusions {
55
82
  return extrusion;
56
83
  }
57
84
  /**
58
- * Rectangular extrude a list of 2D points. Creates a wall-type extrusion of certain height and size.
59
- * @param inputs Contains options and points for extrusion
60
- * @returns Extruded geometry
85
+ * Revolves a flat 2D shape around the Z axis into a solid.
86
+ *
87
+ * The shape lies in the XY plane, so its X coordinate is its distance from the axis, and a
88
+ * shape crossing the axis is clipped there. `angle` and `startAngle` are in degrees, 360 makes
89
+ * a full ring, and `segments` counts the steps of a full turn.
90
+ * @param inputs - The 2D shape, the sweep angle, the start angle and the segment count
91
+ * @returns The revolved solid
61
92
  * @group extrude
62
93
  * @shortname rotational
63
94
  * @drawable true
95
+ * @example
96
+ * ```typescript
97
+ * const profile = await bitbybit.jscad.polygon.circle({ center: [10, 0], radius: 3, segments: 24 });
98
+ * const ring = await bitbybit.jscad.extrusions.extrudeRotate({ polygon: profile, angle: 360, startAngle: 0, segments: 48 });
99
+ * ```
64
100
  */
65
101
  extrudeRotate(inputs) {
66
102
  const options = {