@bitbybit-dev/jscad 1.1.1 → 1.2.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.
package/README.md CHANGED
@@ -41,7 +41,17 @@ Choose from 5 backend templates: Hono + SDK, Hono + REST, Node.js + SDK, Node.js
41
41
  | **Monorepo** | https://github.com/bitbybit-dev/bitbybit |
42
42
  | **NPM** | https://www.npmjs.com/package/@bitbybit-dev/jscad |
43
43
  | **Documentation** | https://learn.bitbybit.dev/learn/npm-packages/intro |
44
- | **Unit Test Coverage** | https://tests.bitbybit.dev/jscad |
44
+ | **API Reference** | https://docs.bitbybit.dev/classes/Bit.JSCAD |
45
+ | **Unit Test Coverage** | https://github.com/bitbybit-dev/bitbybit/actions/workflows/verify.yml |
46
+
47
+ ### API reference
48
+
49
+ Every class, method and input type in this package is documented in the generated TypeScript API reference:
50
+
51
+ - [JSCAD](https://docs.bitbybit.dev/classes/Bit.JSCAD)
52
+ - [JSCAD shapes](https://docs.bitbybit.dev/classes/Bit.JSCADShapes)
53
+ - [JSCAD booleans](https://docs.bitbybit.dev/classes/Bit.JSCADBooleans)
54
+ - [JSCAD input types](https://docs.bitbybit.dev/modules/Bit.Inputs.JSCAD)
45
55
 
46
56
  ## Example Applications
47
57
 
@@ -58,10 +68,10 @@ Choose from 5 backend templates: Hono + SDK, Hono + REST, Node.js + SDK, Node.js
58
68
  npm run build-p
59
69
 
60
70
  # Run unit tests with coverage
61
- npm run test-c
71
+ npm run test:coverage
62
72
 
63
- # Run live unit tests with coverage on save
64
- npm run test-c-l
73
+ # Re-run them as you edit
74
+ npm run test:watch
65
75
  ```
66
76
 
67
77
  ## Bitbybit Platform
package/index.js CHANGED
@@ -1,4 +1 @@
1
- /*
2
- * Public API Surface of bitbybit-core
3
- */
4
1
  export * from "./lib";
@@ -1,4 +1,3 @@
1
- /* eslint-disable @typescript-eslint/no-namespace */
2
1
  /**
3
2
  * Re-export Base namespace from @bitbybit-dev/base.
4
3
  * JSCAD package uses the same foundational types without additions.
@@ -1,6 +1,84 @@
1
1
  import { Base } from "./base-inputs";
2
+ /**
3
+ * Every parameter object the JSCAD kernel accepts. JSCAD models by combining primitives with
4
+ * booleans, expansions, hulls and extrusions, working on tessellated geometry rather than exact
5
+ * surfaces, so its DTOs carry mesh-level settings - segment counts, corner styles, expansion deltas -
6
+ * where the OCCT equivalents would carry tolerances.
7
+ *
8
+ * It is lighter and quicker to start with than OCCT and a good fit when a shape is a combination of
9
+ * simple volumes and manufacturing-grade surface accuracy is not required. Names repeat across
10
+ * kernels: the CircleDto here is not the one in Inputs.OCCT.
11
+ */
2
12
  export declare namespace JSCAD {
3
- type JSCADEntity = any;
13
+ /** A 2D point or vector, `[x, y]`. */
14
+ type JSCADVec2 = [number, number];
15
+ /** A 3D point or vector, `[x, y, z]`. */
16
+ type JSCADVec3 = [number, number, number];
17
+ /** A 4x4 transformation matrix, in column-major order. */
18
+ type JSCADMat4 = [
19
+ number,
20
+ number,
21
+ number,
22
+ number,
23
+ number,
24
+ number,
25
+ number,
26
+ number,
27
+ number,
28
+ number,
29
+ number,
30
+ number,
31
+ number,
32
+ number,
33
+ number,
34
+ number
35
+ ];
36
+ /** A plane, `[normalX, normalY, normalZ, distanceFromOrigin]`. */
37
+ type JSCADPlane = [number, number, number, number];
38
+ /** A colour, either `[r, g, b]` or `[r, g, b, a]`, each channel from 0 to 1. */
39
+ type JSCADColor = [number, number, number] | [number, number, number, number];
40
+ /** A convex polygon in 3D - the face of a solid. */
41
+ type JSCADPoly3 = {
42
+ vertices: JSCADVec3[];
43
+ color?: JSCADColor;
44
+ plane?: JSCADPlane;
45
+ };
46
+ /** 2D geometry: a closed region, held as the edges that bound it. */
47
+ type JSCADGeom2 = {
48
+ sides: [JSCADVec2, JSCADVec2][];
49
+ transforms: JSCADMat4;
50
+ color?: JSCADColor;
51
+ };
52
+ /** 3D geometry: a solid, held as the polygons that enclose it. */
53
+ type JSCADGeom3 = {
54
+ polygons: JSCADPoly3[];
55
+ transforms: JSCADMat4;
56
+ color?: JSCADColor;
57
+ };
58
+ /** A 2D path: an open or closed sequence of points, with no enclosed area. */
59
+ type JSCADPath2 = {
60
+ points: JSCADVec2[];
61
+ isClosed: boolean;
62
+ transforms: JSCADMat4;
63
+ color?: JSCADColor;
64
+ };
65
+ /**
66
+ * Anything JSCAD hands back: a 2D region, a 3D solid, or a 2D path. The three share no members
67
+ * beyond their transform, so narrow on the one you want - `"polygons" in entity` for a solid,
68
+ * `"isClosed" in entity` for a path, `"sides" in entity` for a 2D region.
69
+ *
70
+ * These are structural mirrors of the library's own types rather than imports of them, so the
71
+ * published declarations stay self-contained; jscad-entity.test.ts fails the build if the two
72
+ * ever stop matching.
73
+ */
74
+ type JSCADEntity = JSCADGeom2 | JSCADGeom3 | JSCADPath2;
75
+ /** A geometry flattened for rendering: triangle positions, normals, indices and its transform. */
76
+ type JSCADMeshData = {
77
+ positions: number[];
78
+ normals: number[];
79
+ indices: number[];
80
+ transforms: JSCADMat4;
81
+ };
4
82
  class PolylinePropertiesDto {
5
83
  /**
6
84
  * Provide options without default values
@@ -13,12 +91,15 @@ export declare namespace JSCAD {
13
91
  /**
14
92
  * Can contain is closed information
15
93
  */
16
- isClosed?: boolean;
94
+ isClosed?: boolean | undefined;
17
95
  /**
18
96
  * Can contain color information
19
97
  */
20
- color?: string | number[];
98
+ color?: string | number[] | undefined;
21
99
  }
100
+ /**
101
+ * How the corners of an expanded or rounded solid are formed.
102
+ */
22
103
  enum solidCornerTypeEnum {
23
104
  /**
24
105
  * Edges will meet at a corner
@@ -33,6 +114,9 @@ export declare namespace JSCAD {
33
114
  */
34
115
  chamfer = "chamfer"
35
116
  }
117
+ /**
118
+ * Horizontal alignment of JSCAD text against its anchor point.
119
+ */
36
120
  enum jscadTextAlignEnum {
37
121
  /**
38
122
  * Aligns text to the left
@@ -99,7 +183,7 @@ export declare namespace JSCAD {
99
183
  * @optional true
100
184
  * @ignore true
101
185
  */
102
- jscadMesh?: T;
186
+ jscadMesh?: T | undefined;
103
187
  /**
104
188
  * Draw two-sided faces with different colors for front and back. This helps visualize face orientation.
105
189
  * @default true
@@ -159,7 +243,7 @@ export declare namespace JSCAD {
159
243
  * @optional true
160
244
  * @ignore true
161
245
  */
162
- jscadMesh?: T;
246
+ jscadMesh?: T | undefined;
163
247
  /**
164
248
  * Draw two-sided faces with different colors for front and back. This helps visualize face orientation.
165
249
  * @default true
@@ -221,7 +305,7 @@ export declare namespace JSCAD {
221
305
  * @optional true
222
306
  * @ignore true
223
307
  */
224
- pathMesh?: T;
308
+ pathMesh?: T | undefined;
225
309
  }
226
310
  class TransformSolidsDto {
227
311
  constructor(meshes?: JSCADEntity[], transformation?: Base.TransformMatrixes);
@@ -1691,6 +1775,6 @@ export declare namespace JSCAD {
1691
1775
  /**
1692
1776
  * Points describing polygons
1693
1777
  */
1694
- polygonPoints?: Base.Point3[][];
1778
+ polygonPoints: Base.Point3[][];
1695
1779
  }
1696
1780
  }
@@ -1,4 +1,14 @@
1
- // tslint:disable-next-line: no-namespace
1
+ // GENERATED by scripts/gen-inputs.mjs from the fragments in ./jscad/ - do not edit; edit a fragment and run `npm run gen:inputs`.
2
+ /**
3
+ * Every parameter object the JSCAD kernel accepts. JSCAD models by combining primitives with
4
+ * booleans, expansions, hulls and extrusions, working on tessellated geometry rather than exact
5
+ * surfaces, so its DTOs carry mesh-level settings - segment counts, corner styles, expansion deltas -
6
+ * where the OCCT equivalents would carry tolerances.
7
+ *
8
+ * It is lighter and quicker to start with than OCCT and a good fit when a shape is a combination of
9
+ * simple volumes and manufacturing-grade surface accuracy is not required. Names repeat across
10
+ * kernels: the CircleDto here is not the one in Inputs.OCCT.
11
+ */
2
12
  export var JSCAD;
3
13
  (function (JSCAD) {
4
14
  class PolylinePropertiesDto {
@@ -19,6 +29,9 @@ export var JSCAD;
19
29
  }
20
30
  }
21
31
  JSCAD.PolylinePropertiesDto = PolylinePropertiesDto;
32
+ /**
33
+ * How the corners of an expanded or rounded solid are formed.
34
+ */
22
35
  let solidCornerTypeEnum;
23
36
  (function (solidCornerTypeEnum) {
24
37
  /**
@@ -34,6 +47,9 @@ export var JSCAD;
34
47
  */
35
48
  solidCornerTypeEnum["chamfer"] = "chamfer";
36
49
  })(solidCornerTypeEnum = JSCAD.solidCornerTypeEnum || (JSCAD.solidCornerTypeEnum = {}));
50
+ /**
51
+ * Horizontal alignment of JSCAD text against its anchor point.
52
+ */
37
53
  let jscadTextAlignEnum;
38
54
  (function (jscadTextAlignEnum) {
39
55
  /**
@@ -10,6 +10,10 @@ import { Base } from "./inputs/base-inputs";
10
10
  import { JSCADHulls } from "./services/jscad-hulls";
11
11
  import { JSCADColors } from "./services/jscad-colors";
12
12
  import * as JSCAD from "@jscad/modeling";
13
+ /**
14
+ * Contains various functions for Solid meshes from JSCAD library https://github.com/jscad/OpenJSCAD.org
15
+ * Thanks JSCAD community for developing this kernel
16
+ */
13
17
  export declare class Jscad {
14
18
  private jscad;
15
19
  booleans: JSCADBooleans;
@@ -23,32 +27,82 @@ export declare class Jscad {
23
27
  colors: JSCADColors;
24
28
  private point;
25
29
  constructor(jscad: typeof JSCAD);
30
+ /**
31
+ * Converts the Jscad mesh to polygon points representing triangles of the mesh.
32
+ * @param inputs Jscad mesh
33
+ * @returns polygon points
34
+ * @group conversions
35
+ * @shortname to polygon points
36
+ * @drawable false
37
+ */
26
38
  toPolygonPoints(inputs: Inputs.JSCAD.MeshDto): Base.Mesh3;
27
- shapesToMeshes(inputs: Inputs.JSCAD.MeshesDto): {
28
- positions: number[];
29
- normals: number[];
30
- indices: number[];
31
- transforms: [];
32
- }[];
33
- shapeToMesh(inputs: Inputs.JSCAD.MeshDto): {
34
- positions: number[];
35
- normals: number[];
36
- indices: number[];
37
- transforms: [];
38
- };
39
- transformSolids(inputs: Inputs.JSCAD.TransformSolidsDto): any;
40
- transformSolid(inputs: Inputs.JSCAD.TransformSolidDto): any;
39
+ shapesToMeshes(inputs: Inputs.JSCAD.MeshesDto): Inputs.JSCAD.JSCADMeshData[];
40
+ shapeToMesh(inputs: Inputs.JSCAD.MeshDto): Inputs.JSCAD.JSCADMeshData;
41
+ /**
42
+ * Transforms the Jscad solid meshes with a given list of transformations.
43
+ * @param inputs Solids with the transformation matrixes
44
+ * @returns Solids with a transformation
45
+ * @group transforms
46
+ * @shortname transform solids
47
+ * @drawable true
48
+ */
49
+ transformSolids(inputs: Inputs.JSCAD.TransformSolidsDto): Inputs.JSCAD.JSCADEntity[];
50
+ /**
51
+ * Transforms the Jscad solid mesh with a given list of transformations.
52
+ * @param inputs Solid with the transformation matrixes
53
+ * @returns Solid with a transformation
54
+ * @group transforms
55
+ * @shortname transform solid
56
+ * @drawable true
57
+ */
58
+ transformSolid(inputs: Inputs.JSCAD.TransformSolidDto): Inputs.JSCAD.JSCADEntity;
59
+ /**
60
+ * Downloads the binary STL file from a 3D solid
61
+ * @param inputs 3D Solid
62
+ * @group io
63
+ * @shortname solid to stl
64
+ */
41
65
  downloadSolidSTL(inputs: Inputs.JSCAD.DownloadSolidDto): {
42
66
  blob: Blob;
43
67
  };
44
- downloadGeometryDxf(inputs: Inputs.JSCAD.DownloadGeometryDto): {
68
+ /**
69
+ * Downloads the binary STL file from a 3D solids
70
+ * @param inputs 3D Solid
71
+ * @group io
72
+ * @shortname solids to stl
73
+ */
74
+ downloadSolidsSTL(inputs: Inputs.JSCAD.DownloadSolidsDto): {
45
75
  blob: Blob;
46
76
  };
47
- downloadGeometry3MF(inputs: Inputs.JSCAD.DownloadGeometryDto): {
77
+ /**
78
+ * Downloads the dxf file from jscad geometry. Supports paths and meshes in array.
79
+ * @param inputs 3D geometry
80
+ * @group io
81
+ * @shortname geometry to dxf
82
+ */
83
+ downloadGeometryDxf(inputs: Inputs.JSCAD.DownloadGeometryDto): {
48
84
  blob: Blob;
49
85
  };
50
- downloadSolidsSTL(inputs: Inputs.JSCAD.DownloadSolidsDto): {
86
+ /**
87
+ * Downloads the 3MF file from jscad geometry.
88
+ * @param inputs 3D geometry
89
+ * @group io
90
+ * @shortname geometry to 3mf
91
+ */
92
+ downloadGeometry3MF(inputs: Inputs.JSCAD.DownloadGeometryDto): {
51
93
  blob: Blob;
52
94
  };
95
+ /**
96
+ * JSCAD v1 handed back objects that carried their own `toPolygons()`; a v2 geometry is plain
97
+ * data and the equivalent is a free function. Anything still arriving in the old shape is read
98
+ * the old way, which is why this asks the value rather than trusting the type.
99
+ */
100
+ private legacyPolygons;
101
+ /**
102
+ * Narrows an entity to the solid an operation needs, and says which operation wanted one. The
103
+ * kernel's own failure for a 2D shape here is a property access on undefined, several frames
104
+ * deep, which tells a script author nothing.
105
+ */
106
+ private asSolid;
53
107
  private getArrayDepth;
54
108
  }
@@ -1,5 +1,6 @@
1
1
  import { GeometryHelper, Lists, Point, Transforms, Vector } from "@bitbybit-dev/base";
2
2
  import { MathBitByBit } from "@bitbybit-dev/base";
3
+ import { computeVertexNormals } from "@bitbybit-dev/base/lib/api/services/helpers/mesh-normals";
3
4
  import { JSCADExpansions } from "./services/jscad-expansions";
4
5
  import { JSCADBooleans } from "./services/jscad-booleans";
5
6
  import { JSCADExtrusions } from "./services/jscad-extrusions";
@@ -9,7 +10,10 @@ import { JSCADShapes } from "./services/jscad-shapes";
9
10
  import { JSCADText } from "./services/jscad-text";
10
11
  import { JSCADHulls } from "./services/jscad-hulls";
11
12
  import { JSCADColors } from "./services/jscad-colors";
12
- // Worker make an instance of this class itself
13
+ /**
14
+ * Contains various functions for Solid meshes from JSCAD library https://github.com/jscad/OpenJSCAD.org
15
+ * Thanks JSCAD community for developing this kernel
16
+ */
13
17
  export class Jscad {
14
18
  constructor(jscad) {
15
19
  this.getArrayDepth = (value) => {
@@ -34,18 +38,17 @@ export class Jscad {
34
38
  this.colors = new JSCADColors(jscad);
35
39
  this.jscad = jscad;
36
40
  }
41
+ /**
42
+ * Converts the Jscad mesh to polygon points representing triangles of the mesh.
43
+ * @param inputs Jscad mesh
44
+ * @returns polygon points
45
+ * @group conversions
46
+ * @shortname to polygon points
47
+ * @drawable false
48
+ */
37
49
  toPolygonPoints(inputs) {
38
50
  const meshData = this.shapeToMesh({ mesh: inputs.mesh });
39
- if (!meshData || !meshData.positions || !meshData.indices) {
40
- throw new Error("Invalid input: 'data', 'data.positions', and 'data.indices' must be provided.");
41
- }
42
51
  const { positions, indices } = meshData;
43
- if (positions.length % 3 !== 0) {
44
- throw new Error(`Invalid input: 'positions' array length (${positions.length}) must be a multiple of 3.`);
45
- }
46
- if (indices.length % 3 !== 0) {
47
- throw new Error(`Invalid input: 'indices' array length (${indices.length}) must be a multiple of 3.`);
48
- }
49
52
  if (positions.length === 0) {
50
53
  return [];
51
54
  }
@@ -53,41 +56,20 @@ export class Jscad {
53
56
  return [];
54
57
  }
55
58
  const polygons = [];
56
- const numVertices = positions.length / 3;
57
- // --- Triangle Reconstruction ---
58
59
  for (let i = 0; i < indices.length; i += 3) {
59
60
  const index1 = indices[i];
60
61
  const index2 = indices[i + 1];
61
62
  const index3 = indices[i + 2];
62
- if (index1 >= numVertices || index2 >= numVertices || index3 >= numVertices ||
63
- index1 < 0 || index2 < 0 || index3 < 0) {
64
- console.error(`Invalid vertex index found in 'indices' array at triangle starting at index ${i}. Max vertex index is ${numVertices - 1}. Indices: ${index1}, ${index2}, ${index3}. Skipping triangle.`);
65
- continue;
66
- }
67
63
  const offset1 = index1 * 3;
68
64
  const offset2 = index2 * 3;
69
65
  const offset3 = index3 * 3;
70
66
  const point1 = [positions[offset1], positions[offset1 + 1], positions[offset1 + 2]];
71
67
  const point2 = [positions[offset2], positions[offset2 + 1], positions[offset2 + 2]];
72
68
  const point3 = [positions[offset3], positions[offset3 + 1], positions[offset3 + 2]];
73
- // We must bake the transformations as JSCAD uses those extensively
74
- const transformation = inputs.mesh.transforms;
75
- let transformedPoints = [point1, point2, point3];
76
- if (this.getArrayDepth(transformation) === 2) {
77
- transformation.forEach(transform => {
78
- transformedPoints = this.point.transformPoints({ points: transformedPoints, transformation: [transform] });
79
- });
80
- }
81
- else if (this.getArrayDepth(transformation) === 3) {
82
- transformation.forEach(transforms => {
83
- transforms.forEach(mat => {
84
- transformedPoints = this.point.transformPoints({ points: transformedPoints, transformation: [mat] });
85
- });
86
- });
87
- }
88
- else {
89
- transformedPoints = this.point.transformPoints({ points: transformedPoints, transformation: [transformation] });
90
- }
69
+ const transformedPoints = this.point.transformPoints({
70
+ points: [point1, point2, point3],
71
+ transformation: [inputs.mesh.transforms],
72
+ });
91
73
  const triangle = transformedPoints;
92
74
  polygons.push(triangle);
93
75
  }
@@ -100,28 +82,28 @@ export class Jscad {
100
82
  }
101
83
  shapeToMesh(inputs) {
102
84
  let polygons = [];
103
- if (inputs.mesh.toPolygons) {
104
- polygons = inputs.mesh.toPolygons();
85
+ if (this.legacyPolygons(inputs.mesh)) {
86
+ polygons = this.legacyPolygons(inputs.mesh)();
105
87
  }
106
- else if (inputs.mesh.polygons) {
88
+ else if ("polygons" in inputs.mesh) {
107
89
  polygons = inputs.mesh.polygons;
108
90
  }
109
- else if (inputs.mesh.sides || inputs.mesh.vertices) {
91
+ else {
110
92
  const extrusion = this.extrusions.extrudeLinear({ height: 0.001, twistAngle: 0, twistSteps: 1, geometry: inputs.mesh });
111
- if (extrusion.toPolygons) {
112
- polygons = extrusion.toPolygons();
93
+ const legacy = this.legacyPolygons(extrusion);
94
+ if (legacy) {
95
+ polygons = legacy();
113
96
  }
114
- else if (extrusion.polygons) {
97
+ else if ("polygons" in extrusion) {
115
98
  polygons = extrusion.polygons;
116
99
  }
117
100
  }
118
101
  const positions = [];
119
- const normals = [];
120
102
  const indices = [];
121
103
  let countIndices = 0;
122
104
  for (const polygon of polygons) {
123
105
  if (polygon.vertices.length === 3) {
124
- polygon.vertices.forEach(vert => {
106
+ polygon.vertices.forEach((vert) => {
125
107
  positions.push(vert[0], vert[1], vert[2]);
126
108
  indices.push(countIndices);
127
109
  countIndices++;
@@ -138,7 +120,7 @@ export class Jscad {
138
120
  reversedVertices[i + 2],
139
121
  ]);
140
122
  }
141
- triangles.forEach((triangle, index) => {
123
+ triangles.forEach((triangle, _index) => {
142
124
  triangle.forEach(vert => {
143
125
  positions.push(vert[0], vert[1], vert[2]);
144
126
  indices.push(countIndices);
@@ -148,26 +130,45 @@ export class Jscad {
148
130
  }
149
131
  }
150
132
  return {
151
- positions, normals, indices, transforms: inputs.mesh.transforms,
133
+ positions,
134
+ normals: computeVertexNormals(positions, indices),
135
+ indices,
136
+ transforms: inputs.mesh.transforms,
152
137
  };
153
138
  }
139
+ /**
140
+ * Transforms the Jscad solid meshes with a given list of transformations.
141
+ * @param inputs Solids with the transformation matrixes
142
+ * @returns Solids with a transformation
143
+ * @group transforms
144
+ * @shortname transform solids
145
+ * @drawable true
146
+ */
154
147
  transformSolids(inputs) {
155
148
  const solidsToTransform = inputs.meshes;
156
149
  return solidsToTransform.map(mesh => {
157
150
  return this.transformSolid({ mesh, transformation: inputs.transformation });
158
151
  });
159
152
  }
153
+ /**
154
+ * Transforms the Jscad solid mesh with a given list of transformations.
155
+ * @param inputs Solid with the transformation matrixes
156
+ * @returns Solid with a transformation
157
+ * @group transforms
158
+ * @shortname transform solid
159
+ * @drawable true
160
+ */
160
161
  transformSolid(inputs) {
161
162
  const transformation = inputs.transformation;
162
- let transformedMesh = this.jscad.geometries.geom3.clone(inputs.mesh);
163
+ let transformedMesh = this.asSolid(inputs.mesh, "transformSolid");
163
164
  if (this.getArrayDepth(transformation) === 2) {
164
- transformation.forEach(transform => {
165
+ transformation.forEach((transform) => {
165
166
  transformedMesh = this.jscad.transforms.transform(transform, transformedMesh);
166
167
  });
167
168
  }
168
169
  else if (this.getArrayDepth(transformation) === 3) {
169
- transformation.forEach(transforms => {
170
- transforms.forEach(mat => {
170
+ transformation.forEach((transforms) => {
171
+ transforms.forEach((mat) => {
171
172
  transformedMesh = this.jscad.transforms.transform(mat, transformedMesh);
172
173
  });
173
174
  });
@@ -177,26 +178,70 @@ export class Jscad {
177
178
  }
178
179
  return transformedMesh;
179
180
  }
181
+ /**
182
+ * Downloads the binary STL file from a 3D solid
183
+ * @param inputs 3D Solid
184
+ * @group io
185
+ * @shortname solid to stl
186
+ */
180
187
  downloadSolidSTL(inputs) {
181
188
  const rawData = this.jscad.STLSERIALIZER.serialize({ binary: true }, inputs.mesh);
182
189
  const madeBlob = new Blob(rawData, { type: "application/sla" });
183
190
  return { blob: madeBlob };
184
191
  }
192
+ /**
193
+ * Downloads the binary STL file from a 3D solids
194
+ * @param inputs 3D Solid
195
+ * @group io
196
+ * @shortname solids to stl
197
+ */
198
+ downloadSolidsSTL(inputs) {
199
+ const rawData = this.jscad.STLSERIALIZER.serialize({ binary: true }, ...inputs.meshes);
200
+ const madeBlob = new Blob(rawData, { type: "application/sla" });
201
+ return { blob: madeBlob };
202
+ }
203
+ /**
204
+ * Downloads the dxf file from jscad geometry. Supports paths and meshes in array.
205
+ * @param inputs 3D geometry
206
+ * @group io
207
+ * @shortname geometry to dxf
208
+ */
185
209
  downloadGeometryDxf(inputs) {
186
210
  const options = inputs.options ? inputs.options : {};
187
211
  const rawData = this.jscad.DXFSERIALIZER.serialize(options, inputs.geometry);
188
212
  const madeBlob = new Blob(rawData);
189
213
  return { blob: madeBlob };
190
214
  }
215
+ /**
216
+ * Downloads the 3MF file from jscad geometry.
217
+ * @param inputs 3D geometry
218
+ * @group io
219
+ * @shortname geometry to 3mf
220
+ */
191
221
  downloadGeometry3MF(inputs) {
192
222
  const options = inputs.options ? inputs.options : {};
193
223
  const rawData = this.jscad.THREEMFSERIALIZER.serialize(options, inputs.geometry);
194
224
  const madeBlob = new Blob(rawData);
195
225
  return { blob: madeBlob };
196
226
  }
197
- downloadSolidsSTL(inputs) {
198
- const rawData = this.jscad.STLSERIALIZER.serialize({ binary: true }, ...inputs.meshes);
199
- const madeBlob = new Blob(rawData, { type: "application/sla" });
200
- return { blob: madeBlob };
227
+ /**
228
+ * JSCAD v1 handed back objects that carried their own `toPolygons()`; a v2 geometry is plain
229
+ * data and the equivalent is a free function. Anything still arriving in the old shape is read
230
+ * the old way, which is why this asks the value rather than trusting the type.
231
+ */
232
+ legacyPolygons(entity) {
233
+ const candidate = entity.toPolygons;
234
+ return typeof candidate === "function" ? candidate.bind(entity) : undefined;
235
+ }
236
+ /**
237
+ * Narrows an entity to the solid an operation needs, and says which operation wanted one. The
238
+ * kernel's own failure for a 2D shape here is a property access on undefined, several frames
239
+ * deep, which tells a script author nothing.
240
+ */
241
+ asSolid(entity, operation) {
242
+ if (!("polygons" in entity)) {
243
+ throw new Error(`${operation} needs a 3D solid, but was given a 2D geometry or a path.`);
244
+ }
245
+ return entity;
201
246
  }
202
247
  }
@@ -0,0 +1,30 @@
1
+ import * as Inputs from "../inputs/jscad-inputs";
2
+ /**
3
+ * Reads an input that the kernel accepts either singly or as a list. The published type says one
4
+ * entity, and a list has always worked too because the kernel's operations are variadic; declaring
5
+ * the union would change the published type, so the coercion lives here instead.
6
+ */
7
+ export declare function oneOrMany(geometry: Inputs.JSCAD.JSCADEntity): Inputs.JSCAD.JSCADEntity[];
8
+ /**
9
+ * Hands a list of entities to an operation overloaded per geometry kind. The kernel still rejects a
10
+ * genuinely mixed list, and it is the right thing to decide that - it knows which combinations its
11
+ * operations support and we would only be guessing ahead of it. The type parameter is constrained to
12
+ * the three kinds, so this narrows within the union rather than escaping it.
13
+ */
14
+ export declare function asKind<T extends Inputs.JSCAD.JSCADEntity>(entities: Inputs.JSCAD.JSCADEntity[]): T[];
15
+ /**
16
+ * Narrows to the solid an operation needs, naming the operation that wanted one. Without this the
17
+ * kernel fails several frames deep on a property access, which tells a script author nothing about
18
+ * what they passed.
19
+ */
20
+ export declare function asSolid(entity: Inputs.JSCAD.JSCADEntity, operation: string): Inputs.JSCAD.JSCADGeom3;
21
+ /** Narrows to the 2D path an operation needs, naming the operation that wanted one. */
22
+ export declare function asPath(entity: Inputs.JSCAD.JSCADEntity, operation: string): Inputs.JSCAD.JSCADPath2;
23
+ /** Narrows to the 2D region an operation needs, naming the operation that wanted one. */
24
+ export declare function asRegion(entity: Inputs.JSCAD.JSCADEntity, operation: string): Inputs.JSCAD.JSCADGeom2;
25
+ /**
26
+ * Reads back what a variadic operation returned. The kernel hands back the geometry when it was
27
+ * given one and a list when it was given several, while the published return type describes only
28
+ * the first of those - so this is where the two meet.
29
+ */
30
+ export declare function asEntity(result: unknown): Inputs.JSCAD.JSCADEntity;