@bitbybit-dev/jscad 1.2.0 → 1.3.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.
@@ -3,8 +3,10 @@ import * as Inputs from "../inputs";
3
3
  import { MathBitByBit } from "@bitbybit-dev/base";
4
4
  import * as JSCAD from "@jscad/modeling";
5
5
  /**
6
- * Contains various functions for Polygon from JSCAD library https://github.com/jscad/OpenJSCAD.org
7
- * Thanks JSCAD community for developing this kernel
6
+ * Building flat JSCAD shapes, the filled 2D regions that booleans combine and extrusions turn into
7
+ * solids. They lie in the XY plane: a shape made from points or a curve keeps only the X and Y
8
+ * coordinates, and the circle, ellipse, rectangle, square and star primitives take a 2D center.
9
+ * List outline points counter-clockwise.
8
10
  */
9
11
  export declare class JSCADPolygon {
10
12
  private readonly jscad;
@@ -12,97 +14,165 @@ export declare class JSCADPolygon {
12
14
  private readonly math;
13
15
  constructor(jscad: typeof JSCAD, geometryHelper: GeometryHelper, math: MathBitByBit);
14
16
  /**
15
- * Create a 2D polygon from a list of points
16
- * @param inputs Points
17
- * @returns Polygons
17
+ * Builds a filled 2D shape from the outline points, taken in order and closed back to the
18
+ * first.
19
+ *
20
+ * Only X and Y are used, Z is dropped; repeated consecutive points are removed and at least
21
+ * three distinct points are needed. Counter-clockwise order gives a normal shape, clockwise
22
+ * gives a negative one.
23
+ * @param inputs - The outline points
24
+ * @returns The 2D shape
18
25
  * @group from
19
26
  * @shortname polygon from points
20
27
  * @drawable true
28
+ * @example
29
+ * ```typescript
30
+ * const triangle = await bitbybit.jscad.polygon.createFromPoints({ points: [[0, 0, 0], [10, 0, 0], [5, 8, 0]] });
31
+ * ```
21
32
  */
22
33
  createFromPoints(inputs: Inputs.Point.PointsDto): Inputs.JSCAD.JSCADEntity;
23
34
  /**
24
- * Create a 2D polygon from a polyline
25
- * @param inputs Polyline
26
- * @returns Polygon
35
+ * Builds a filled 2D shape from the points of a polyline, closed back to the first point
36
+ * whatever the polyline says.
37
+ *
38
+ * Only X and Y are used, Z is dropped; repeated consecutive points are removed and at least
39
+ * three distinct points are needed.
40
+ * @param inputs - The polyline
41
+ * @returns The 2D shape
27
42
  * @group from
28
43
  * @shortname polyline
29
44
  * @drawable true
45
+ * @example
46
+ * ```typescript
47
+ * const shape = await bitbybit.jscad.polygon.createFromPolyline({ polyline: { points: [[0, 0, 0], [10, 0, 0], [10, 10, 0], [0, 10, 0]], isClosed: true } });
48
+ * ```
30
49
  */
31
50
  createFromPolyline(inputs: Inputs.JSCAD.PolylineDto): Inputs.JSCAD.JSCADEntity;
32
51
  /**
33
- * Create a 2D polygon from a curve
34
- * @param inputs Nurbs curve
35
- * @returns Polygon
52
+ * Builds a filled 2D shape from a NURBS curve by sampling it into points and closing the
53
+ * outline.
54
+ *
55
+ * Only X and Y of the sampled points are used, Z is dropped.
56
+ * @param inputs - The NURBS curve
57
+ * @returns The 2D shape
36
58
  * @group from
37
59
  * @shortname curve
38
60
  * @drawable true
39
61
  * @deprecated This takes a verb-nurbs curve, and verb is deprecated for removal in the next major,
40
- * so this goes with it. It is also the one method here that converts between two different CAD
41
- * kernels, which belongs above a kernel-specific package rather than inside one. Build the polygon
42
- * from points or from a polyline instead.
62
+ so this goes with it. It is also the one method here that converts between two different CAD
63
+ kernels, which belongs above a kernel-specific package rather than inside one. Build the polygon
64
+ from points or from a polyline instead.
65
+ * @example
66
+ * ```typescript
67
+ * const shape = await bitbybit.jscad.polygon.createFromCurve({ curve });
68
+ * ```
43
69
  */
44
70
  createFromCurve(inputs: Inputs.JSCAD.CurveDto): Inputs.JSCAD.JSCADEntity;
45
71
  /**
46
- * Create a 2D polygon from a path
47
- * @param inputs Path
48
- * @returns Polygon
72
+ * Builds a filled 2D shape from the points of a 2D path, closed back to the first point.
73
+ *
74
+ * Repeated consecutive points are removed and at least three distinct points are needed; a 2D
75
+ * shape or a solid throws an error.
76
+ * @param inputs - The 2D path
77
+ * @returns The 2D shape
49
78
  * @group from
50
79
  * @shortname path
51
80
  * @drawable true
81
+ * @example
82
+ * ```typescript
83
+ * const path = await bitbybit.jscad.path.createFromPoints({ points: [[0, 0], [10, 0], [10, 10]], closed: true });
84
+ * const shape = await bitbybit.jscad.polygon.createFromPath({ path });
85
+ * ```
52
86
  */
53
87
  createFromPath(inputs: Inputs.JSCAD.PathDto): Inputs.JSCAD.JSCADEntity;
54
88
  /**
55
- * Create a 2D polygon circle
56
- * @param inputs Circle parameters
57
- * @returns Circle polygon
89
+ * Builds a filled circle of the given `radius` around a 2D `center`; `segments` is the number
90
+ * of straight sides that approximate it.
91
+ * @param inputs - The center, the radius and the segment count
92
+ * @returns The circle as a 2D shape
58
93
  * @group primitives
59
94
  * @shortname circle
60
95
  * @drawable true
96
+ * @example
97
+ * ```typescript
98
+ * const disc = await bitbybit.jscad.polygon.circle({ center: [0, 0], radius: 5, segments: 32 });
99
+ * ```
61
100
  */
62
101
  circle(inputs: Inputs.JSCAD.CircleDto): Inputs.JSCAD.JSCADEntity;
63
102
  /**
64
- * Create a 2D polygon ellipse
65
- * @param inputs Ellipse parameters
66
- * @returns Ellipse polygon
103
+ * Builds a filled ellipse around a 2D `center`, with `radius` holding the X and Y half-sizes;
104
+ * `segments` is the number of straight sides that approximate it.
105
+ * @param inputs - The center, the two radii and the segment count
106
+ * @returns The ellipse as a 2D shape
67
107
  * @group primitives
68
108
  * @shortname ellipse
69
109
  * @drawable true
110
+ * @example
111
+ * ```typescript
112
+ * const oval = await bitbybit.jscad.polygon.ellipse({ center: [0, 0], radius: [10, 5], segments: 48 });
113
+ * ```
70
114
  */
71
115
  ellipse(inputs: Inputs.JSCAD.EllipseDto): Inputs.JSCAD.JSCADEntity;
72
116
  /**
73
- * Create a 2D polygon rectangle
74
- * @param inputs Rectangle parameters
75
- * @returns Rectangle polygon
117
+ * Builds a filled rectangle around a 2D `center`, with `width` along X and `length` along Y.
118
+ * @param inputs - The center, the width and the length
119
+ * @returns The rectangle as a 2D shape
76
120
  * @group primitives
77
121
  * @shortname rectangle
78
122
  * @drawable true
123
+ * @example
124
+ * ```typescript
125
+ * const plate = await bitbybit.jscad.polygon.rectangle({ center: [0, 0], width: 20, length: 10 });
126
+ * ```
79
127
  */
80
128
  rectangle(inputs: Inputs.JSCAD.RectangleDto): Inputs.JSCAD.JSCADEntity;
81
129
  /**
82
- * Create a 2D rounded rectangle
83
- * @param inputs Rounded rectangle parameters
84
- * @returns Rounded rectangle polygon
130
+ * Builds a filled rectangle with its four corners rounded by `roundRadius`, around a 2D
131
+ * `center` with `width` along X and `length` along Y.
132
+ *
133
+ * `roundRadius` must be less than half of the smaller side or an error is thrown; `segments`
134
+ * sets how smoothly each corner is faceted.
135
+ * @param inputs - The center, the rounding radius, the segment count, the width and the length
136
+ * @returns The rounded rectangle as a 2D shape
85
137
  * @group primitives
86
138
  * @shortname rounded rectangle
87
139
  * @drawable true
140
+ * @example
141
+ * ```typescript
142
+ * const plate = await bitbybit.jscad.polygon.roundedRectangle({ center: [0, 0], roundRadius: 2, segments: 16, width: 20, length: 10 });
143
+ * ```
88
144
  */
89
145
  roundedRectangle(inputs: Inputs.JSCAD.RoundedRectangleDto): Inputs.JSCAD.JSCADEntity;
90
146
  /**
91
- * Create a 2D polygon square
92
- * @param inputs Square parameters
93
- * @returns Square polygon
147
+ * Builds a filled square of side `size` around a 2D `center`, with its sides parallel to the
148
+ * axes.
149
+ * @param inputs - The center and the side length
150
+ * @returns The square as a 2D shape
94
151
  * @group primitives
95
152
  * @shortname square
96
153
  * @drawable true
154
+ * @example
155
+ * ```typescript
156
+ * const tile = await bitbybit.jscad.polygon.square({ center: [0, 0], size: 10 });
157
+ * ```
97
158
  */
98
159
  square(inputs: Inputs.JSCAD.SquareDto): Inputs.JSCAD.JSCADEntity;
99
160
  /**
100
- * Create a 2D polygon star
101
- * @param inputs Star parameters
102
- * @returns Star polygon
161
+ * Builds a filled star with `vertices` tips around a 2D `center`, the tips at `outerRadius` and
162
+ * the notches between them at `innerRadius`.
163
+ *
164
+ * `startAngle` in degrees turns the first tip away from the X axis. `density` matters only when
165
+ * `innerRadius` is 0: the notch radius is then derived from it, as in a pentagram with density
166
+ * 2.
167
+ * @param inputs - The center, the number of tips, the density, the two radii and the start angle
168
+ * @returns The star as a 2D shape
103
169
  * @group primitives
104
170
  * @shortname star
105
171
  * @drawable true
172
+ * @example
173
+ * ```typescript
174
+ * const star = await bitbybit.jscad.polygon.star({ center: [0, 0], vertices: 5, density: 2, outerRadius: 10, innerRadius: 4, startAngle: 90 });
175
+ * ```
106
176
  */
107
177
  star(inputs: Inputs.JSCAD.StarDto): Inputs.JSCAD.JSCADEntity;
108
178
  private removeDuplicatesAndCreateFromPoints;
@@ -1,7 +1,9 @@
1
1
  import { asPath } from "./entity-narrowing";
2
2
  /**
3
- * Contains various functions for Polygon from JSCAD library https://github.com/jscad/OpenJSCAD.org
4
- * Thanks JSCAD community for developing this kernel
3
+ * Building flat JSCAD shapes, the filled 2D regions that booleans combine and extrusions turn into
4
+ * solids. They lie in the XY plane: a shape made from points or a curve keeps only the X and Y
5
+ * coordinates, and the circle, ellipse, rectangle, square and star primitives take a 2D center.
6
+ * List outline points counter-clockwise.
5
7
  */
6
8
  export class JSCADPolygon {
7
9
  constructor(jscad, geometryHelper, math) {
@@ -10,74 +12,116 @@ export class JSCADPolygon {
10
12
  this.math = math;
11
13
  }
12
14
  /**
13
- * Create a 2D polygon from a list of points
14
- * @param inputs Points
15
- * @returns Polygons
15
+ * Builds a filled 2D shape from the outline points, taken in order and closed back to the
16
+ * first.
17
+ *
18
+ * Only X and Y are used, Z is dropped; repeated consecutive points are removed and at least
19
+ * three distinct points are needed. Counter-clockwise order gives a normal shape, clockwise
20
+ * gives a negative one.
21
+ * @param inputs - The outline points
22
+ * @returns The 2D shape
16
23
  * @group from
17
24
  * @shortname polygon from points
18
25
  * @drawable true
26
+ * @example
27
+ * ```typescript
28
+ * const triangle = await bitbybit.jscad.polygon.createFromPoints({ points: [[0, 0, 0], [10, 0, 0], [5, 8, 0]] });
29
+ * ```
19
30
  */
20
31
  createFromPoints(inputs) {
21
32
  const twoDimensionalPoints = inputs.points.map(pt => [pt[0], pt[1]]);
22
33
  return this.removeDuplicatesAndCreateFromPoints(twoDimensionalPoints);
23
34
  }
24
35
  /**
25
- * Create a 2D polygon from a polyline
26
- * @param inputs Polyline
27
- * @returns Polygon
36
+ * Builds a filled 2D shape from the points of a polyline, closed back to the first point
37
+ * whatever the polyline says.
38
+ *
39
+ * Only X and Y are used, Z is dropped; repeated consecutive points are removed and at least
40
+ * three distinct points are needed.
41
+ * @param inputs - The polyline
42
+ * @returns The 2D shape
28
43
  * @group from
29
44
  * @shortname polyline
30
45
  * @drawable true
46
+ * @example
47
+ * ```typescript
48
+ * const shape = await bitbybit.jscad.polygon.createFromPolyline({ polyline: { points: [[0, 0, 0], [10, 0, 0], [10, 10, 0], [0, 10, 0]], isClosed: true } });
49
+ * ```
31
50
  */
32
51
  createFromPolyline(inputs) {
33
52
  const twoDimensionalPoints = inputs.polyline.points.map(pt => [pt[0], pt[1]]);
34
53
  return this.removeDuplicatesAndCreateFromPoints(twoDimensionalPoints);
35
54
  }
36
55
  /**
37
- * Create a 2D polygon from a curve
38
- * @param inputs Nurbs curve
39
- * @returns Polygon
56
+ * Builds a filled 2D shape from a NURBS curve by sampling it into points and closing the
57
+ * outline.
58
+ *
59
+ * Only X and Y of the sampled points are used, Z is dropped.
60
+ * @param inputs - The NURBS curve
61
+ * @returns The 2D shape
40
62
  * @group from
41
63
  * @shortname curve
42
64
  * @drawable true
43
65
  * @deprecated This takes a verb-nurbs curve, and verb is deprecated for removal in the next major,
44
- * so this goes with it. It is also the one method here that converts between two different CAD
45
- * kernels, which belongs above a kernel-specific package rather than inside one. Build the polygon
46
- * from points or from a polyline instead.
66
+ so this goes with it. It is also the one method here that converts between two different CAD
67
+ kernels, which belongs above a kernel-specific package rather than inside one. Build the polygon
68
+ from points or from a polyline instead.
69
+ * @example
70
+ * ```typescript
71
+ * const shape = await bitbybit.jscad.polygon.createFromCurve({ curve });
72
+ * ```
47
73
  */
48
74
  createFromCurve(inputs) {
49
75
  const twoDimensionalPoints = inputs.curve.tessellate().map((pt) => [pt[0], pt[1]]);
50
76
  return this.removeDuplicatesAndCreateFromPoints(twoDimensionalPoints);
51
77
  }
52
78
  /**
53
- * Create a 2D polygon from a path
54
- * @param inputs Path
55
- * @returns Polygon
79
+ * Builds a filled 2D shape from the points of a 2D path, closed back to the first point.
80
+ *
81
+ * Repeated consecutive points are removed and at least three distinct points are needed; a 2D
82
+ * shape or a solid throws an error.
83
+ * @param inputs - The 2D path
84
+ * @returns The 2D shape
56
85
  * @group from
57
86
  * @shortname path
58
87
  * @drawable true
88
+ * @example
89
+ * ```typescript
90
+ * const path = await bitbybit.jscad.path.createFromPoints({ points: [[0, 0], [10, 0], [10, 10]], closed: true });
91
+ * const shape = await bitbybit.jscad.polygon.createFromPath({ path });
92
+ * ```
59
93
  */
60
94
  createFromPath(inputs) {
61
95
  return this.removeDuplicatesAndCreateFromPoints(asPath(inputs.path, "createFromPath").points);
62
96
  }
63
97
  /**
64
- * Create a 2D polygon circle
65
- * @param inputs Circle parameters
66
- * @returns Circle polygon
98
+ * Builds a filled circle of the given `radius` around a 2D `center`; `segments` is the number
99
+ * of straight sides that approximate it.
100
+ * @param inputs - The center, the radius and the segment count
101
+ * @returns The circle as a 2D shape
67
102
  * @group primitives
68
103
  * @shortname circle
69
104
  * @drawable true
105
+ * @example
106
+ * ```typescript
107
+ * const disc = await bitbybit.jscad.polygon.circle({ center: [0, 0], radius: 5, segments: 32 });
108
+ * ```
70
109
  */
71
110
  circle(inputs) {
72
111
  return this.jscad.primitives.circle({ center: inputs.center, radius: inputs.radius, segments: inputs.segments });
73
112
  }
74
113
  /**
75
- * Create a 2D polygon ellipse
76
- * @param inputs Ellipse parameters
77
- * @returns Ellipse polygon
114
+ * Builds a filled ellipse around a 2D `center`, with `radius` holding the X and Y half-sizes;
115
+ * `segments` is the number of straight sides that approximate it.
116
+ * @param inputs - The center, the two radii and the segment count
117
+ * @returns The ellipse as a 2D shape
78
118
  * @group primitives
79
119
  * @shortname ellipse
80
120
  * @drawable true
121
+ * @example
122
+ * ```typescript
123
+ * const oval = await bitbybit.jscad.polygon.ellipse({ center: [0, 0], radius: [10, 5], segments: 48 });
124
+ * ```
81
125
  */
82
126
  ellipse(inputs) {
83
127
  return this.jscad.primitives.ellipse({
@@ -87,12 +131,16 @@ export class JSCADPolygon {
87
131
  });
88
132
  }
89
133
  /**
90
- * Create a 2D polygon rectangle
91
- * @param inputs Rectangle parameters
92
- * @returns Rectangle polygon
134
+ * Builds a filled rectangle around a 2D `center`, with `width` along X and `length` along Y.
135
+ * @param inputs - The center, the width and the length
136
+ * @returns The rectangle as a 2D shape
93
137
  * @group primitives
94
138
  * @shortname rectangle
95
139
  * @drawable true
140
+ * @example
141
+ * ```typescript
142
+ * const plate = await bitbybit.jscad.polygon.rectangle({ center: [0, 0], width: 20, length: 10 });
143
+ * ```
96
144
  */
97
145
  rectangle(inputs) {
98
146
  return this.jscad.primitives.rectangle({
@@ -101,12 +149,20 @@ export class JSCADPolygon {
101
149
  });
102
150
  }
103
151
  /**
104
- * Create a 2D rounded rectangle
105
- * @param inputs Rounded rectangle parameters
106
- * @returns Rounded rectangle polygon
152
+ * Builds a filled rectangle with its four corners rounded by `roundRadius`, around a 2D
153
+ * `center` with `width` along X and `length` along Y.
154
+ *
155
+ * `roundRadius` must be less than half of the smaller side or an error is thrown; `segments`
156
+ * sets how smoothly each corner is faceted.
157
+ * @param inputs - The center, the rounding radius, the segment count, the width and the length
158
+ * @returns The rounded rectangle as a 2D shape
107
159
  * @group primitives
108
160
  * @shortname rounded rectangle
109
161
  * @drawable true
162
+ * @example
163
+ * ```typescript
164
+ * const plate = await bitbybit.jscad.polygon.roundedRectangle({ center: [0, 0], roundRadius: 2, segments: 16, width: 20, length: 10 });
165
+ * ```
110
166
  */
111
167
  roundedRectangle(inputs) {
112
168
  return this.jscad.primitives.roundedRectangle({
@@ -117,23 +173,37 @@ export class JSCADPolygon {
117
173
  });
118
174
  }
119
175
  /**
120
- * Create a 2D polygon square
121
- * @param inputs Square parameters
122
- * @returns Square polygon
176
+ * Builds a filled square of side `size` around a 2D `center`, with its sides parallel to the
177
+ * axes.
178
+ * @param inputs - The center and the side length
179
+ * @returns The square as a 2D shape
123
180
  * @group primitives
124
181
  * @shortname square
125
182
  * @drawable true
183
+ * @example
184
+ * ```typescript
185
+ * const tile = await bitbybit.jscad.polygon.square({ center: [0, 0], size: 10 });
186
+ * ```
126
187
  */
127
188
  square(inputs) {
128
189
  return this.jscad.primitives.square({ center: [inputs.center[0], inputs.center[1]], size: inputs.size });
129
190
  }
130
191
  /**
131
- * Create a 2D polygon star
132
- * @param inputs Star parameters
133
- * @returns Star polygon
192
+ * Builds a filled star with `vertices` tips around a 2D `center`, the tips at `outerRadius` and
193
+ * the notches between them at `innerRadius`.
194
+ *
195
+ * `startAngle` in degrees turns the first tip away from the X axis. `density` matters only when
196
+ * `innerRadius` is 0: the notch radius is then derived from it, as in a pentagram with density
197
+ * 2.
198
+ * @param inputs - The center, the number of tips, the density, the two radii and the start angle
199
+ * @returns The star as a 2D shape
134
200
  * @group primitives
135
201
  * @shortname star
136
202
  * @drawable true
203
+ * @example
204
+ * ```typescript
205
+ * const star = await bitbybit.jscad.polygon.star({ center: [0, 0], vertices: 5, density: 2, outerRadius: 10, innerRadius: 4, startAngle: 90 });
206
+ * ```
137
207
  */
138
208
  star(inputs) {
139
209
  return this.jscad.primitives.star({