circuit-json-to-gltf 0.0.158 → 0.0.160

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
@@ -80,8 +80,63 @@ models throw; open surfaces remain open for the caller's solid validation.
80
80
  Model-loading options `projectBaseUrl`, `authHeaders` and `coordinateTransform`
81
81
  are also supported. Indexed vertices retain their coordinates without snapping.
82
82
 
83
+ ### Assembly explosion stages
84
+
85
+ The real RP2040/NEMA17 example below lifts the cover and bolts together, then
86
+ separates the bolts, motor and spacers. These snapshots render the serialized
87
+ Circuit JSON program directly, including a halfway bolt-removal pose. The TSX
88
+ beside each view is the source that authored that stage.
89
+
90
+ ![RP2040 assembly explosion stages with TSX](./docs/images/rp2040-explosion-stages.png)
91
+
92
+ `cad_explosion_stage` and `cad_explosion_move` records describe a playback program.
93
+ Exports remain assembled by default. Select a pose with the `explosion` option.
94
+ Exploded exports always include motion paths in the selected scene's
95
+ `extras.poppygl.explosionLines`, using final glTF world coordinates (+Y up, mm).
96
+ PoppyGL renders these as dashed overlays; they do not add meshes or affect model
97
+ bounds. Generic glTF viewers may ignore the extras.
98
+
99
+ ```typescript
100
+ import {
101
+ convertCircuitJsonToGltf,
102
+ getAssemblyExplosionFrames,
103
+ } from "circuit-json-to-gltf"
104
+
105
+ const halfway = await convertCircuitJsonToGltf(circuitJson, {
106
+ format: "glb",
107
+ explosion: { throughStageRef: "DEVICE.lift-cover", stageProgress: 0.5 },
108
+ })
109
+
110
+ // Assembled, then every completed stage in declared order. Keep one camera
111
+ // across these GLBs and label each image with frame.name for a storyboard.
112
+ for (const frame of getAssemblyExplosionFrames(circuitJson)) {
113
+ const glb = await convertCircuitJsonToGltf(circuitJson, {
114
+ format: "glb",
115
+ explosion: frame.explosion,
116
+ })
117
+ // Save/render glb and label it with frame.name.
118
+ }
119
+ ```
120
+
121
+ `explosion: {}` finishes all stages. Progress divides the selected stage into its
122
+ ordered moves, retaining all earlier displacement. A stage target expands its
123
+ explicit CAD/reference-surface membership; overlapping targets move once per
124
+ instruction. All references, orders and memberships are validated even when
125
+ selecting an early pose. The assembled input is never mutated.
126
+
127
+ Frames also include evaluated `circuitJson` and guide `lines` in circuit-world
128
+ XYZ (mm, right-handed +X right, +Y top, +Z above). Evaluated poses omit explosion
129
+ instructions to prevent applying them twice after saving. The usual exporter
130
+ converts these positions to glTF +Y-up coordinates. Node and browser entry points
131
+ support the same program, including assemblies without a PCB.
132
+
133
+ Each export is a static pose, not a glTF animation track. Playback supports CAD
134
+ and reference-surface translations; PCB/cable movement, rotation instructions
135
+ and swept collision checking are not supported.
136
+
83
137
  ### Options
84
138
 
139
+ - `explosion`: Optional `{ throughStageRef?, stageProgress? }` selecting a serialized assembly pose; omitted means assembled.
85
140
  - `format`: "gltf" (JSON) or "glb" (binary) - default: "gltf"
86
141
  - `boardTextureResolution`: Resolution for board texture rendering - default: 1024
87
142
  - `showPcbNotes`: Include `pcb_note*` elements in board texture rendering (default: `false`)
package/dist/index.d.ts CHANGED
@@ -32,7 +32,30 @@ type CircuitJsonWithPcbFlex = (CircuitJson[number] | PcbBendRecord | PcbStiffene
32
32
  interface AuthHeaders extends Record<string, string> {
33
33
  Authorization: string;
34
34
  }
35
+ /** A pose within the serialized explosion program. Earlier stages stay applied. */
36
+ interface AssemblyExplosionOptions {
37
+ /** Inclusive qualified stage name. Omit to finish all stages. */
38
+ throughStageRef?: string;
39
+ /** Fraction of the selected stage's sequential moves, from 0 to 1. */
40
+ stageProgress?: number;
41
+ }
42
+ /** Circuit-world points in mm: right-handed +X right, +Y top, +Z above. */
43
+ interface AssemblyExplosionLine {
44
+ stageRef: string;
45
+ targetRef: string;
46
+ points: Point3[];
47
+ }
48
+ interface AssemblyExplosionFrame {
49
+ name: string;
50
+ /** Options for rendering the original assembled document at this pose. */
51
+ explosion?: AssemblyExplosionOptions;
52
+ /** Evaluated pose without instructions, safe to save and reopen. */
53
+ circuitJson: CircuitJsonWithPcbFlex;
54
+ lines: AssemblyExplosionLine[];
55
+ }
35
56
  interface ConversionOptions {
57
+ /** Render a serialized explosion pose. Omit to keep the assembly assembled. */
58
+ explosion?: AssemblyExplosionOptions;
36
59
  /** Override the render fold state. Undefined follows CAD is_on_folded_board in Circuit JSON. */
37
60
  foldPcbs?: boolean;
38
61
  format?: "gltf" | "glb";
@@ -165,7 +188,14 @@ interface Box3D {
165
188
  isTranslucent?: boolean;
166
189
  showHiddenEdges?: boolean;
167
190
  }
191
+ /** Guide points in Scene3D world coordinates: +Y up, mm, before glTF X reflection. */
192
+ interface SceneExplosionLine {
193
+ stageRef: string;
194
+ targetRef: string;
195
+ points: Point3[];
196
+ }
168
197
  interface Scene3D {
198
+ explosionLines?: SceneExplosionLine[];
169
199
  boxes: Box3D[];
170
200
  camera?: Camera3D;
171
201
  lights?: Light3D[];
@@ -198,6 +228,8 @@ interface GLTFExportOptions {
198
228
  includeCustomExtensions?: boolean;
199
229
  }
200
230
  interface CircuitTo3DOptions {
231
+ /** Evaluate CAD explosion instructions before conversion to scene coordinates. */
232
+ explosion?: AssemblyExplosionOptions;
201
233
  /** Override folding for supported PCB bend regions. Undefined follows CAD is_on_folded_board. */
202
234
  foldPcbs?: boolean;
203
235
  pcbColor?: Color;
@@ -235,6 +267,12 @@ interface BoardRenderOptions {
235
267
  showPcbNotes?: boolean;
236
268
  }
237
269
 
270
+ /** Named assembled and end-of-stage poses for storyboard snapshots or playback.
271
+ * Positions and guide points remain in circuit-world XYZ, mm, right-handed +Z up.
272
+ * Rendering uses the normal exporter frame conversion. Input is never mutated.
273
+ */
274
+ declare function getAssemblyExplosionFrames(assembled: CircuitJsonWithPcbFlex): AssemblyExplosionFrame[];
275
+
238
276
  interface PoppyglErrorOverlayOptions {
239
277
  /** Final image dimensions in pixels, before PoppyGL supersampling. */
240
278
  width: number;
@@ -435,4 +473,4 @@ interface BRepShape {
435
473
  is_negative?: boolean;
436
474
  }
437
475
 
438
- export { type BRepShape, type BoardRenderOptions, type BoundingBox, type Box3D, CAMERA_PRESET_DIRECTIONS, COORDINATE_TRANSFORMS, type CadComponentMesh, type CadComponentMeshOptions, type Camera3D, type CameraFitOptions, type CameraPreset, type CircuitJsonWithPcbFlex, type CircuitTo3DOptions, type Color, type ConversionOptions, type CoordinateTransformConfig, type GLTFExportOptions, type LayerRef, type Light3D, type OBJMaterial, type OBJMesh, type OcctImportJsFactory, type PcbBendRecord, type PcbStiffenerRecord, type Point, type Point3, type PoppyglErrorOverlay, type PoppyglErrorOverlayOptions, type STLMesh, type Scene3D, type Size3, type Triangle, applyCoordinateTransform, clearGLBCache, clearOBJCache, clearSTLCache, convertCircuitJsonTo3D, convertCircuitJsonToGltf, convertSceneToGLTF, getBestCameraPosition, getPoppyglErrorOverlayOptions, loadCadComponentMesh, loadGLB, loadJscadPlan, loadOBJ, loadSTL, renderBoardLayer, renderBoardTextures, setOcctImportJs, transformTriangles };
476
+ export { type AssemblyExplosionFrame, type AssemblyExplosionLine, type AssemblyExplosionOptions, type BRepShape, type BoardRenderOptions, type BoundingBox, type Box3D, CAMERA_PRESET_DIRECTIONS, COORDINATE_TRANSFORMS, type CadComponentMesh, type CadComponentMeshOptions, type Camera3D, type CameraFitOptions, type CameraPreset, type CircuitJsonWithPcbFlex, type CircuitTo3DOptions, type Color, type ConversionOptions, type CoordinateTransformConfig, type GLTFExportOptions, type LayerRef, type Light3D, type OBJMaterial, type OBJMesh, type OcctImportJsFactory, type PcbBendRecord, type PcbStiffenerRecord, type Point, type Point3, type PoppyglErrorOverlay, type PoppyglErrorOverlayOptions, type STLMesh, type Scene3D, type Size3, type Triangle, applyCoordinateTransform, clearGLBCache, clearOBJCache, clearSTLCache, convertCircuitJsonTo3D, convertCircuitJsonToGltf, convertSceneToGLTF, getAssemblyExplosionFrames, getBestCameraPosition, getPoppyglErrorOverlayOptions, loadCadComponentMesh, loadGLB, loadJscadPlan, loadOBJ, loadSTL, renderBoardLayer, renderBoardTextures, setOcctImportJs, transformTriangles };