@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,30 +1,62 @@
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 hulls from JSCAD library https://github.com/jscad/OpenJSCAD.org
5
- * Thanks JSCAD community for developing this kernel
4
+ * Wrapping JSCAD geometry in its convex hull, the shape a tight sheet would take around it: `hull`
5
+ * wraps everything at once and `hullChain` wraps each consecutive pair, so a row of shapes becomes
6
+ * a bent tube rather than one lump. All inputs of a call must be of the same kind, solids, 2D
7
+ * shapes or paths.
6
8
  */
7
9
  export declare class JSCADHulls {
8
10
  private readonly jscad;
9
11
  constructor(jscad: typeof JSCAD);
10
12
  /**
11
- * Hull chain connects solids or 2d geometries by filling an empty space in between objects in order.
12
- * Geometries need to be of the same type.
13
- * @param inputs Geometries
14
- * @returns Chain hulled geometry
13
+ * Wraps each consecutive pair of inputs in a convex hull and fuses the hulls, so a row of
14
+ * shapes becomes a continuous strand that follows their order.
15
+ *
16
+ * A bend in the row is kept, where `hull` would fill it in. All inputs must be of the same
17
+ * kind.
18
+ * @param inputs - The solids, 2D shapes or paths, in the order they connect
19
+ * @returns The chained hull
15
20
  * @group hulls
16
21
  * @shortname hull chain
17
22
  * @drawable true
23
+ * @example
24
+ * ```typescript
25
+ * const spheres = await bitbybit.jscad.shapes.spheresOnCenterPoints({ centers: [[0, 0, 0], [10, 0, 0], [10, 10, 0]], radius: 1, segments: 16 });
26
+ * const strand = await bitbybit.jscad.hulls.hullChain({ meshes: spheres });
27
+ * ```
18
28
  */
19
29
  hullChain(inputs: Inputs.JSCAD.HullDto): Inputs.JSCAD.JSCADEntity;
20
30
  /**
21
- * Convex hull connects solids or 2d geometries by filling an empty space in between without following order.
22
- * Geometries need to be of the same type.
23
- * @param inputs Geometries
24
- * @returns Hulled geometry
31
+ * Wraps all the inputs in one convex hull, the smallest shape without dents that contains them
32
+ * all, regardless of their order.
33
+ *
34
+ * All inputs must be of the same kind, solids, 2D shapes or paths.
35
+ * @param inputs - The solids, 2D shapes or paths
36
+ * @returns The convex hull
25
37
  * @group hulls
26
38
  * @shortname hull
27
39
  * @drawable true
40
+ * @example
41
+ * ```typescript
42
+ * const wrapped = await bitbybit.jscad.hulls.hull({ meshes: [cube, sphere] });
43
+ * ```
28
44
  */
29
45
  hull(inputs: Inputs.JSCAD.HullDto): Inputs.JSCAD.JSCADEntity;
46
+ /**
47
+ * Tells whether a solid is convex, meaning it already equals its own hull: every straight line
48
+ * between two of its points stays inside it.
49
+ *
50
+ * Solids only; a 2D shape or a path throws an error.
51
+ * @param inputs - The solid to examine
52
+ * @returns True when the solid is convex
53
+ * @group hulls
54
+ * @shortname is convex
55
+ * @drawable false
56
+ * @example
57
+ * ```typescript
58
+ * const convex = await bitbybit.jscad.hulls.isConvex({ mesh: shape });
59
+ * ```
60
+ */
61
+ isConvex(inputs: Inputs.JSCAD.SolidDto): boolean;
30
62
  }
@@ -1,34 +1,68 @@
1
- import { asKind } from "./entity-narrowing";
1
+ import { asKind, asSolid } from "./entity-narrowing";
2
2
  /**
3
- * Contains various functions for Solid hulls from JSCAD library https://github.com/jscad/OpenJSCAD.org
4
- * Thanks JSCAD community for developing this kernel
3
+ * Wrapping JSCAD geometry in its convex hull, the shape a tight sheet would take around it: `hull`
4
+ * wraps everything at once and `hullChain` wraps each consecutive pair, so a row of shapes becomes
5
+ * a bent tube rather than one lump. All inputs of a call must be of the same kind, solids, 2D
6
+ * shapes or paths.
5
7
  */
6
8
  export class JSCADHulls {
7
9
  constructor(jscad) {
8
10
  this.jscad = jscad;
9
11
  }
10
12
  /**
11
- * Hull chain connects solids or 2d geometries by filling an empty space in between objects in order.
12
- * Geometries need to be of the same type.
13
- * @param inputs Geometries
14
- * @returns Chain hulled geometry
13
+ * Wraps each consecutive pair of inputs in a convex hull and fuses the hulls, so a row of
14
+ * shapes becomes a continuous strand that follows their order.
15
+ *
16
+ * A bend in the row is kept, where `hull` would fill it in. All inputs must be of the same
17
+ * kind.
18
+ * @param inputs - The solids, 2D shapes or paths, in the order they connect
19
+ * @returns The chained hull
15
20
  * @group hulls
16
21
  * @shortname hull chain
17
22
  * @drawable true
23
+ * @example
24
+ * ```typescript
25
+ * const spheres = await bitbybit.jscad.shapes.spheresOnCenterPoints({ centers: [[0, 0, 0], [10, 0, 0], [10, 10, 0]], radius: 1, segments: 16 });
26
+ * const strand = await bitbybit.jscad.hulls.hullChain({ meshes: spheres });
27
+ * ```
18
28
  */
19
29
  hullChain(inputs) {
20
30
  return this.jscad.hulls.hullChain(...asKind(inputs.meshes));
21
31
  }
22
32
  /**
23
- * Convex hull connects solids or 2d geometries by filling an empty space in between without following order.
24
- * Geometries need to be of the same type.
25
- * @param inputs Geometries
26
- * @returns Hulled geometry
33
+ * Wraps all the inputs in one convex hull, the smallest shape without dents that contains them
34
+ * all, regardless of their order.
35
+ *
36
+ * All inputs must be of the same kind, solids, 2D shapes or paths.
37
+ * @param inputs - The solids, 2D shapes or paths
38
+ * @returns The convex hull
27
39
  * @group hulls
28
40
  * @shortname hull
29
41
  * @drawable true
42
+ * @example
43
+ * ```typescript
44
+ * const wrapped = await bitbybit.jscad.hulls.hull({ meshes: [cube, sphere] });
45
+ * ```
30
46
  */
31
47
  hull(inputs) {
32
48
  return this.jscad.hulls.hull(...asKind(inputs.meshes));
33
49
  }
50
+ /**
51
+ * Tells whether a solid is convex, meaning it already equals its own hull: every straight line
52
+ * between two of its points stays inside it.
53
+ *
54
+ * Solids only; a 2D shape or a path throws an error.
55
+ * @param inputs - The solid to examine
56
+ * @returns True when the solid is convex
57
+ * @group hulls
58
+ * @shortname is convex
59
+ * @drawable false
60
+ * @example
61
+ * ```typescript
62
+ * const convex = await bitbybit.jscad.hulls.isConvex({ mesh: shape });
63
+ * ```
64
+ */
65
+ isConvex(inputs) {
66
+ return this.jscad.geometries.geom3.isConvex(asSolid(inputs.mesh, "isConvex"));
67
+ }
34
68
  }
@@ -3,8 +3,10 @@ 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 Path from JSCAD library https://github.com/jscad/OpenJSCAD.org
7
- * Thanks JSCAD community for developing this kernel
6
+ * Building JSCAD paths, the 2D polylines that walls are extruded along, offsets follow and filled
7
+ * shapes are closed from. A path lies in the XY plane and is open or closed; it grows by appending
8
+ * points, polylines and arcs to its end, and a closed path accepts nothing more. Points given in 3D
9
+ * keep only X and Y.
8
10
  */
9
11
  export declare class JSCADPath {
10
12
  private readonly jscad;
@@ -12,74 +14,132 @@ export declare class JSCADPath {
12
14
  private readonly math;
13
15
  constructor(jscad: typeof JSCAD, geometryHelper: GeometryHelper, math: MathBitByBit);
14
16
  /**
15
- * Create a 2D path from a list of points
16
- * @param inputs Points and indication if we want a closed path or not
17
- * @returns Path
17
+ * Builds a 2D path through the points in order, open or closed back to the first point as
18
+ * `closed` says.
19
+ *
20
+ * Only X and Y of each point are used and repeated consecutive points are removed.
21
+ * @param inputs - The points and whether to close the path
22
+ * @returns The 2D path
18
23
  * @group from
19
24
  * @shortname points
20
25
  * @drawable true
26
+ * @example
27
+ * ```typescript
28
+ * const path = await bitbybit.jscad.path.createFromPoints({ points: [[0, 0], [10, 0], [10, 10]], closed: false });
29
+ * ```
21
30
  */
22
31
  createFromPoints(inputs: Inputs.JSCAD.PathFromPointsDto): Inputs.JSCAD.JSCADEntity;
23
32
  /**
24
- * Create 2D paths from a lists of points
25
- * @param inputs Points lists
26
- * @returns Paths
33
+ * Builds one 2D path per list of points, in the same order; a list whose last point coincides
34
+ * with its first becomes a closed path, any other stays open.
35
+ *
36
+ * Only X and Y of each point are used and repeated consecutive points are removed.
37
+ * @param inputs - The lists of points
38
+ * @returns One 2D path per list
27
39
  * @group from
28
40
  * @shortname paths from points
29
41
  * @drawable true
42
+ * @example
43
+ * ```typescript
44
+ * const paths = await bitbybit.jscad.path.createPathsFromPoints({ pointsLists: [[[0, 0], [10, 0], [10, 10], [0, 0]], [[20, 0], [30, 0]]] });
45
+ * ```
30
46
  */
31
47
  createPathsFromPoints(inputs: Inputs.JSCAD.PathsFromPointsDto): Inputs.JSCAD.JSCADEntity[];
32
48
  /**
33
- * Create a 2D path from a polyline
34
- * @param inputs Polyline and indication if we want a closed path or not
35
- * @returns Path
49
+ * Builds a 2D path through the points of a polyline, open or closed back to the first point as
50
+ * `closed` says, whatever the polyline's own flag holds.
51
+ *
52
+ * Only X and Y of each point are used and repeated consecutive points are removed.
53
+ * @param inputs - The polyline and whether to close the path
54
+ * @returns The 2D path
36
55
  * @group from
37
56
  * @shortname polyline
38
57
  * @drawable true
58
+ * @example
59
+ * ```typescript
60
+ * const path = await bitbybit.jscad.path.createFromPolyline({ polyline: { points: [[0, 0, 0], [10, 0, 0], [10, 10, 0]] }, closed: true });
61
+ * ```
39
62
  */
40
63
  createFromPolyline(inputs: Inputs.JSCAD.PathFromPolylineDto): Inputs.JSCAD.JSCADEntity;
41
64
  /**
42
- * Create empty 2D path
43
- * @returns Empty path
65
+ * Makes an empty open 2D path with no points, a starting point for `appendPoints`,
66
+ * `appendPolyline` and `appendArc`.
67
+ * @returns The empty 2D path
44
68
  * @group create
45
69
  * @shortname empty
46
70
  * @drawable false
71
+ * @example
72
+ * ```typescript
73
+ * const empty = await bitbybit.jscad.path.createEmpty();
74
+ * const path = await bitbybit.jscad.path.appendPoints({ path: empty, points: [[0, 0], [10, 0], [10, 10]] });
75
+ * ```
47
76
  */
48
77
  createEmpty(): Inputs.JSCAD.JSCADEntity;
49
78
  /**
50
- * Closes an open 2D path
51
- * @param inputs Path
52
- * @returns Closed path
79
+ * Closes an open 2D path by joining its last point back to its first, giving a closed copy; a
80
+ * path that is already closed comes back closed.
81
+ *
82
+ * A 2D shape or a solid throws an error.
83
+ * @param inputs - The 2D path
84
+ * @returns The closed 2D path
53
85
  * @group edit
54
86
  * @shortname close
55
87
  * @drawable true
88
+ * @example
89
+ * ```typescript
90
+ * const closed = await bitbybit.jscad.path.close({ path });
91
+ * ```
56
92
  */
57
93
  close(inputs: Inputs.JSCAD.PathDto): Inputs.JSCAD.JSCADEntity;
58
94
  /**
59
- * Append the path with 2D points
60
- * @param inputs Path to append and points
61
- * @returns Appended path
95
+ * Adds points to the end of an open 2D path, giving a longer copy.
96
+ *
97
+ * Only X and Y of each point are used and repeated consecutive points are removed; a closed
98
+ * path throws an error.
99
+ * @param inputs - The 2D path and the points to add
100
+ * @returns The extended 2D path
62
101
  * @group append
63
102
  * @shortname points
64
103
  * @drawable true
104
+ * @example
105
+ * ```typescript
106
+ * const longer = await bitbybit.jscad.path.appendPoints({ path, points: [[20, 10], [20, 0]] });
107
+ * ```
65
108
  */
66
109
  appendPoints(inputs: Inputs.JSCAD.PathAppendPointsDto): Inputs.JSCAD.JSCADEntity;
67
110
  /**
68
- * Append the path with polyline
69
- * @param inputs Path to append and polyline
70
- * @returns Appended path
111
+ * Adds the points of a polyline to the end of an open 2D path, giving a longer copy.
112
+ *
113
+ * Only X and Y of each point are used and repeated consecutive points are removed; a closed
114
+ * path throws an error.
115
+ * @param inputs - The 2D path and the polyline to add
116
+ * @returns The extended 2D path
71
117
  * @group append
72
118
  * @shortname polyline
73
119
  * @drawable true
120
+ * @example
121
+ * ```typescript
122
+ * const longer = await bitbybit.jscad.path.appendPolyline({ path, polyline: { points: [[20, 10, 0], [20, 0, 0]] } });
123
+ * ```
74
124
  */
75
125
  appendPolyline(inputs: Inputs.JSCAD.PathAppendPolylineDto): Inputs.JSCAD.JSCADEntity;
76
126
  /**
77
- * Append the arc to the path
78
- * @param inputs Path and arc parameters
79
- * @returns Appended path
127
+ * Adds an elliptical arc from the last point of an open 2D path to `endPoint`, giving a longer
128
+ * copy.
129
+ *
130
+ * `radiusX` and `radiusY` size the ellipse and `xAxisRotation` tilts it in degrees; `clockwise`
131
+ * and `large` pick one of the four arcs that fit, and radii too small to reach the end point
132
+ * are scaled up.
133
+ * @param inputs - The 2D path, the end point, the two radii, the tilt, the arc choice and the segment count
134
+ * @returns The extended 2D path
80
135
  * @group append
81
136
  * @shortname arc
82
137
  * @drawable true
138
+ * @example
139
+ * ```typescript
140
+ * const start = await bitbybit.jscad.path.createFromPoints({ points: [[0, 0]], closed: false });
141
+ * const arc = await bitbybit.jscad.path.appendArc({ path: start, endPoint: [10, 10], radiusX: 10, radiusY: 10, xAxisRotation: 0, clockwise: false, large: false, segments: 32 });
142
+ * ```
83
143
  */
84
144
  appendArc(inputs: Inputs.JSCAD.PathAppendArcDto): Inputs.JSCAD.JSCADEntity;
85
145
  private removeDuplicatesAndCreateFromPoints;
@@ -1,7 +1,9 @@
1
1
  import { asPath } from "./entity-narrowing";
2
2
  /**
3
- * Contains various functions for Path from JSCAD library https://github.com/jscad/OpenJSCAD.org
4
- * Thanks JSCAD community for developing this kernel
3
+ * Building JSCAD paths, the 2D polylines that walls are extruded along, offsets follow and filled
4
+ * shapes are closed from. A path lies in the XY plane and is open or closed; it grows by appending
5
+ * points, polylines and arcs to its end, and a closed path accepts nothing more. Points given in 3D
6
+ * keep only X and Y.
5
7
  */
6
8
  export class JSCADPath {
7
9
  constructor(jscad, geometryHelper, math) {
@@ -10,24 +12,38 @@ export class JSCADPath {
10
12
  this.math = math;
11
13
  }
12
14
  /**
13
- * Create a 2D path from a list of points
14
- * @param inputs Points and indication if we want a closed path or not
15
- * @returns Path
15
+ * Builds a 2D path through the points in order, open or closed back to the first point as
16
+ * `closed` says.
17
+ *
18
+ * Only X and Y of each point are used and repeated consecutive points are removed.
19
+ * @param inputs - The points and whether to close the path
20
+ * @returns The 2D path
16
21
  * @group from
17
22
  * @shortname points
18
23
  * @drawable true
24
+ * @example
25
+ * ```typescript
26
+ * const path = await bitbybit.jscad.path.createFromPoints({ points: [[0, 0], [10, 0], [10, 10]], closed: false });
27
+ * ```
19
28
  */
20
29
  createFromPoints(inputs) {
21
30
  const twoDimensionalPoints = inputs.points.map(pt => [pt[0], pt[1]]);
22
31
  return this.removeDuplicatesAndCreateFromPoints(twoDimensionalPoints, inputs.closed);
23
32
  }
24
33
  /**
25
- * Create 2D paths from a lists of points
26
- * @param inputs Points lists
27
- * @returns Paths
34
+ * Builds one 2D path per list of points, in the same order; a list whose last point coincides
35
+ * with its first becomes a closed path, any other stays open.
36
+ *
37
+ * Only X and Y of each point are used and repeated consecutive points are removed.
38
+ * @param inputs - The lists of points
39
+ * @returns One 2D path per list
28
40
  * @group from
29
41
  * @shortname paths from points
30
42
  * @drawable true
43
+ * @example
44
+ * ```typescript
45
+ * const paths = await bitbybit.jscad.path.createPathsFromPoints({ pointsLists: [[[0, 0], [10, 0], [10, 10], [0, 0]], [[20, 0], [30, 0]]] });
46
+ * ```
31
47
  */
32
48
  createPathsFromPoints(inputs) {
33
49
  return inputs.pointsLists.map(points => {
@@ -40,45 +56,72 @@ export class JSCADPath {
40
56
  });
41
57
  }
42
58
  /**
43
- * Create a 2D path from a polyline
44
- * @param inputs Polyline and indication if we want a closed path or not
45
- * @returns Path
59
+ * Builds a 2D path through the points of a polyline, open or closed back to the first point as
60
+ * `closed` says, whatever the polyline's own flag holds.
61
+ *
62
+ * Only X and Y of each point are used and repeated consecutive points are removed.
63
+ * @param inputs - The polyline and whether to close the path
64
+ * @returns The 2D path
46
65
  * @group from
47
66
  * @shortname polyline
48
67
  * @drawable true
68
+ * @example
69
+ * ```typescript
70
+ * const path = await bitbybit.jscad.path.createFromPolyline({ polyline: { points: [[0, 0, 0], [10, 0, 0], [10, 10, 0]] }, closed: true });
71
+ * ```
49
72
  */
50
73
  createFromPolyline(inputs) {
51
74
  const twoDimensionalPoints = inputs.polyline.points.map(pt => [pt[0], pt[1]]);
52
75
  return this.removeDuplicatesAndCreateFromPoints(twoDimensionalPoints, inputs.closed);
53
76
  }
54
77
  /**
55
- * Create empty 2D path
56
- * @returns Empty path
78
+ * Makes an empty open 2D path with no points, a starting point for `appendPoints`,
79
+ * `appendPolyline` and `appendArc`.
80
+ * @returns The empty 2D path
57
81
  * @group create
58
82
  * @shortname empty
59
83
  * @drawable false
84
+ * @example
85
+ * ```typescript
86
+ * const empty = await bitbybit.jscad.path.createEmpty();
87
+ * const path = await bitbybit.jscad.path.appendPoints({ path: empty, points: [[0, 0], [10, 0], [10, 10]] });
88
+ * ```
60
89
  */
61
90
  createEmpty() {
62
91
  return this.jscad.geometries.path2.create();
63
92
  }
64
93
  /**
65
- * Closes an open 2D path
66
- * @param inputs Path
67
- * @returns Closed path
94
+ * Closes an open 2D path by joining its last point back to its first, giving a closed copy; a
95
+ * path that is already closed comes back closed.
96
+ *
97
+ * A 2D shape or a solid throws an error.
98
+ * @param inputs - The 2D path
99
+ * @returns The closed 2D path
68
100
  * @group edit
69
101
  * @shortname close
70
102
  * @drawable true
103
+ * @example
104
+ * ```typescript
105
+ * const closed = await bitbybit.jscad.path.close({ path });
106
+ * ```
71
107
  */
72
108
  close(inputs) {
73
109
  return this.jscad.geometries.path2.close(asPath(inputs.path, "path operations"));
74
110
  }
75
111
  /**
76
- * Append the path with 2D points
77
- * @param inputs Path to append and points
78
- * @returns Appended path
112
+ * Adds points to the end of an open 2D path, giving a longer copy.
113
+ *
114
+ * Only X and Y of each point are used and repeated consecutive points are removed; a closed
115
+ * path throws an error.
116
+ * @param inputs - The 2D path and the points to add
117
+ * @returns The extended 2D path
79
118
  * @group append
80
119
  * @shortname points
81
120
  * @drawable true
121
+ * @example
122
+ * ```typescript
123
+ * const longer = await bitbybit.jscad.path.appendPoints({ path, points: [[20, 10], [20, 0]] });
124
+ * ```
82
125
  */
83
126
  appendPoints(inputs) {
84
127
  const twoDimensionalPoints = inputs.points.map(pt => [pt[0], pt[1]]);
@@ -86,24 +129,41 @@ export class JSCADPath {
86
129
  return this.jscad.geometries.path2.appendPoints(duplicatePointsRemoved, asPath(inputs.path, "path operations"));
87
130
  }
88
131
  /**
89
- * Append the path with polyline
90
- * @param inputs Path to append and polyline
91
- * @returns Appended path
132
+ * Adds the points of a polyline to the end of an open 2D path, giving a longer copy.
133
+ *
134
+ * Only X and Y of each point are used and repeated consecutive points are removed; a closed
135
+ * path throws an error.
136
+ * @param inputs - The 2D path and the polyline to add
137
+ * @returns The extended 2D path
92
138
  * @group append
93
139
  * @shortname polyline
94
140
  * @drawable true
141
+ * @example
142
+ * ```typescript
143
+ * const longer = await bitbybit.jscad.path.appendPolyline({ path, polyline: { points: [[20, 10, 0], [20, 0, 0]] } });
144
+ * ```
95
145
  */
96
146
  appendPolyline(inputs) {
97
147
  const twoDimensionalPoints = inputs.polyline.points.map(pt => [pt[0], pt[1]]);
98
148
  return this.appendPoints({ points: twoDimensionalPoints, path: inputs.path });
99
149
  }
100
150
  /**
101
- * Append the arc to the path
102
- * @param inputs Path and arc parameters
103
- * @returns Appended path
151
+ * Adds an elliptical arc from the last point of an open 2D path to `endPoint`, giving a longer
152
+ * copy.
153
+ *
154
+ * `radiusX` and `radiusY` size the ellipse and `xAxisRotation` tilts it in degrees; `clockwise`
155
+ * and `large` pick one of the four arcs that fit, and radii too small to reach the end point
156
+ * are scaled up.
157
+ * @param inputs - The 2D path, the end point, the two radii, the tilt, the arc choice and the segment count
158
+ * @returns The extended 2D path
104
159
  * @group append
105
160
  * @shortname arc
106
161
  * @drawable true
162
+ * @example
163
+ * ```typescript
164
+ * const start = await bitbybit.jscad.path.createFromPoints({ points: [[0, 0]], closed: false });
165
+ * const arc = await bitbybit.jscad.path.appendArc({ path: start, endPoint: [10, 10], radiusX: 10, radiusY: 10, xAxisRotation: 0, clockwise: false, large: false, segments: 32 });
166
+ * ```
107
167
  */
108
168
  appendArc(inputs) {
109
169
  const endpoint = [inputs.endPoint[0], inputs.endPoint[1]];