pcb-scene3d-viewer 1.1.21 → 1.1.31

package/README.md

@@ -17,8 +17,9 @@ runtime.
 
 The package was extracted from [ECAD Forge](https://ecadforge.app/), where it
 is used for browser-based PCB 3D scene rendering. Its runtime, geometry
-factories, model loading, component picking, view presets, archive export, and
-optional DOM shell can be reused by other browser-based ECAD tools.
+factories, model loading, component picking, view presets, archive export,
+GLTF/GLB assembly writing, and optional DOM shell can be reused by other
+browser-based ECAD tools.
 
 ## Install
 

package/docs/api.md

@@ -63,7 +63,9 @@ Methods:
 - `isCircuitJsonModel(value)`: returns true for serialized CircuitJSON arrays.
 - `isDirectCircuitJsonModel(value)`: returns true when the array should bypass
   host `buildScene` callbacks.
-- `build(circuitJson)`: returns a runtime-ready scene description.
+- `build(circuitJson, options?)`: returns a runtime-ready scene description.
+  `options.modelUrlResolver` can attach caller-owned URL resolution metadata to
+  `cad_component` external models without fetching them.
 
 `PcbScene3dController` and `PcbScene3dRuntime` call this adapter automatically
 when they receive direct CircuitJSON input. See
@@ -121,6 +123,30 @@ worker.postMessage({
 Workers respond with `scene3d:success` and `sceneDescription`, or
 `scene3d:error` and `message`.
 
+## Assembly Geometry Export
+
+### `PcbAssemblyGeometryBuilder.build(sceneDescription, options?)`
+
+Builds export meshes from a prepared scene description. `options.modelMeshLoader`
+can provide external model meshes, `options.includeModels: false` skips external
+model loading, and `options.renderFallbackBodies: false` disables procedural
+component bodies for unresolved models.
+
+### `PcbAssemblyGltfWriter.write(options?)`
+
+Writes faceted assembly meshes as GLTF 2.0 JSON or binary GLB.
+
+Options:
+
+- `name`: scene name.
+- `meshes`: export meshes with `vertices`, `faces`, optional RGB or RGBA
+  `color`, optional `opacity`, and optional board `texture` data URIs.
+- `format`: `gltf` or `glb`.
+- `binary`: optional boolean equivalent to `format: 'glb'`.
+
+Returns a GLTF JSON object for `gltf` and a `Uint8Array` for `glb`. RGBA colors
+or opacity values below `1` are emitted as blended GLTF materials.
+
 ## Model Archive Export
 
 ### `PcbModelArchiveExporter.buildArchive(options?)`

package/docs/circuitjson.md

@@ -109,6 +109,21 @@ if (PcbScene3dCircuitJsonAdapter.isCircuitJsonModel(circuitJson)) {
 }
 ```
 
+Hosts that need URL policy control can pass a synchronous `modelUrlResolver`.
+The adapter records the returned metadata on each external model but does not
+fetch the referenced file:
+
+```js
+const sceneDescription = PcbScene3dCircuitJsonAdapter.build(circuitJson, {
+    modelUrlResolver(url, context) {
+        return {
+            resolvedUrl: sameOriginProxyUrl(url),
+            sameOrigin: context.format === 'step'
+        }
+    }
+})
+```
+
 `isDirectCircuitJsonModel(value)` returns `false` for compatibility arrays that
 also carry legacy parser fields such as `pcb`, `schematic`, or `bom`. Those
 arrays continue through the host-provided `buildScene` callback so existing
@@ -120,9 +135,10 @@ CircuitJSON input uses millimeters. The adapter converts all board, component,
 pad, via, trace, and silkscreen dimensions into mils before handing the scene to
 the Three.js runtime.
 
-The board center defaults to `{ x: 0, y: 0 }` when omitted. If no `pcb_board`
-element is present, the adapter creates a 25.4 mm by 25.4 mm board with a
-1.6 mm thickness so incomplete test or preview models still render.
+The board center defaults to `{ x: 0, y: 0 }` when omitted. If no `pcb_panel`
+or `pcb_board` element is present, the adapter creates a 25.4 mm by 25.4 mm
+board with a 1.6 mm thickness so incomplete test or preview models still
+render.
 
 Layer values resolve as follows:
 
@@ -135,18 +151,28 @@ Layer values resolve as follows:
 The adapter focuses on renderer-ready PCB geometry and ignores unsupported
 CircuitJSON elements instead of failing the whole scene.
 
-| Element type          | Rendered as                                         |
-| --------------------- | --------------------------------------------------- |
-| `pcb_board`           | Board size, thickness, center, and optional outline |
-| `source_component`    | Component designator and package metadata           |
-| `pcb_component`       | Fallback component body and selection target        |
-| `pcb_smtpad`          | Top or bottom SMT pad copper                        |
-| `pcb_plated_hole`     | Through-hole pad copper and drill                   |
-| `pcb_hole`            | Non-plated drill opening                            |
-| `pcb_via`             | Via copper and drill                                |
-| `pcb_trace`           | Routed copper track segments                        |
-| `pcb_silkscreen_line` | Top or bottom silkscreen stroke                     |
-| `pcb_silkscreen_text` | Top or bottom silkscreen text placeholder           |
+| Element type          | Rendered as                                                         |
+| --------------------- | ------------------------------------------------------------------- |
+| `pcb_panel`           | Preferred board/panel size, thickness, center, and optional outline |
+| `pcb_board`           | Board size, thickness, center, and optional outline                 |
+| `pcb_cutout`          | Through-board cutout loop                                           |
+| `source_component`    | Component designator and package metadata                           |
+| `pcb_component`       | Fallback component body and selection target                        |
+| `cad_component`       | External model URL metadata and placement data                      |
+| `pcb_smtpad`          | Top or bottom SMT pad copper                                        |
+| `pcb_plated_hole`     | Through-hole pad copper and drill                                   |
+| `pcb_hole`            | Non-plated drill opening                                            |
+| `pcb_via`             | Via copper and drill                                                |
+| `pcb_trace`           | Routed copper track segments                                        |
+| `pcb_silkscreen_line` | Top or bottom silkscreen stroke                                     |
+| `pcb_silkscreen_text` | Top or bottom silkscreen text placeholder                           |
+
+`cad_component` entries can provide external model URLs and model-local
+placement hints. The adapter maps `model_unit_to_mm_scale_factor`,
+`model_origin_position`, `model_offset`, `model_origin_alignment`,
+`model_object_fit`, `model_board_normal_direction`, and `size` into normalized
+model transforms, and maps `show_as_translucent_model` into export/display
+opacity metadata.
 
 Board outlines can be supplied as `pcb_board.outline`, using an array of points:
 
@@ -162,6 +188,24 @@ Board outlines can be supplied as `pcb_board.outline`, using an array of points:
 }
 ```
 
+Through-board cutouts can be supplied as polygon, rectangle, or circle
+`pcb_cutout` elements:
+
+```js
+{
+    type: 'pcb_cutout',
+    shape: 'rect',
+    center: { x: 25, y: 15 },
+    width: 4,
+    height: 2
+}
+```
+
+Component model metadata can be supplied on `cad_component` elements with
+`model_step_url`, `model_wrl_url`, `model_glb_url`, `model_gltf_url`,
+`model_stl_url`, or `model_obj_url`. The adapter emits external placement
+metadata for the host runtime or export pipeline to resolve.
+
 Traces can be supplied as a `route` array. Each adjacent point pair becomes one
 track segment:
 
@@ -185,6 +229,7 @@ model conversion. Use `PcbScene3dCircuitJsonAdapter.isCircuitJsonModel(value)`
 for a cheap guard when accepting untrusted JSON from users, and catch conversion
 errors around `build(value)` when you need to show a custom diagnostic.
 
-The viewer does not fetch external assets for CircuitJSON input. STEP and WRL
-model matching remains the responsibility of source-specific toolkits or host
-applications that create normalized scene descriptions.
+The viewer does not fetch external assets for CircuitJSON input by itself.
+Model URL matching, same-origin checks, proxying, and file loading remain the
+responsibility of source-specific toolkits or host applications that create or
+post-process normalized scene descriptions.

package/docs/model-format.md

@@ -66,7 +66,7 @@ Components describe fallback package bodies and selection metadata:
 
 ## External Placements
 
-External placements describe STEP or WRL model instances:
+External placements describe STEP, WRL, GLB, GLTF, STL, or OBJ model instances:
 
 ```js
 {
@@ -78,8 +78,15 @@ External placements describe STEP or WRL model instances:
     bodyRotationDeg: 0,
     modelTransform: {
         rotationDeg: { x: 90, y: 0, z: 0 },
-        dzMil: 0
+        offsetMil: { x: 0, y: 0, z: 0 },
+        scale: { x: 1, y: 1, z: 1 },
+        originPositionMil: { x: 0, y: 0, z: 0 },
+        originAlignment: 'center_of_component_on_board_surface',
+        objectFit: 'fill_bounds',
+        boardNormalDirection: 'z+',
+        targetSizeMil: { x: 200, y: 300, z: 60 }
     },
+    bodyOpacity: 0.5,
     externalModel: {
         origin: 'session',
         name: 'soic-8.step',
@@ -90,6 +97,10 @@ External placements describe STEP or WRL model instances:
 }
 ```
 
+OBJ models can carry sidecar material libraries in `resources`, `relatedFiles`,
+`assets`, or similar metadata collections. GLTF/GLB material alpha and mesh
+opacity are preserved in exported GLTF/GLB materials.
+
 Embedded STEP models can use:
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pcb-scene3d-viewer",
-    "version": "1.1.21",
+    "version": "1.1.31",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",

package/spec/library-scope.md

@@ -8,12 +8,12 @@ scene descriptions.
 - Three.js runtime orchestration for PCB scenes.
 - Board, copper, via, drill, silkscreen, solder-mask, and fallback package mesh
   factories.
-- STEP and WRL model loading and placement.
+- STEP, WRL, GLB, GLTF, STL, and OBJ model loading and placement.
 - Camera presets, view compensation, selection styling, picking, and visibility
   toggles.
 - Optional DOM shell/controller helpers for hosts that want ready-made scene
   chrome.
-- ZIP export of resolved STEP and WRL model assets.
+- ZIP export of resolved component model assets.
 - CSS for the optional scene shell.
 
 ## Out of Scope

package/src/PcbAssemblyBoardSubstrateBuilder.mjs

@@ -145,13 +145,20 @@ export class PcbAssemblyBoardSubstrateBuilder {
      * @returns {number[][][]}
      */
     static #boardHoleLoops(sceneDescription, outer) {
-        const contourLoops =
-            PcbAssemblyBoardSubstrateBuilder.#drillCutoutLoops(sceneDescription)
-        const rawLoops = contourLoops.length
-            ? contourLoops
-            : PcbAssemblyBoardSubstrateBuilder.#primitiveHoleLoops(
+        const explicitLoops =
+            PcbAssemblyBoardSubstrateBuilder.#explicitCutoutLoops(
+                sceneDescription
+            )
+        const primitiveLoops =
+            PcbAssemblyBoardSubstrateBuilder.#primitiveHoleLoops(
+                sceneDescription
+            )
+        const fallbackLoops = primitiveLoops.length
+            ? primitiveLoops
+            : PcbAssemblyBoardSubstrateBuilder.#drillCutoutLoops(
                   sceneDescription
               )
+        const rawLoops = [...explicitLoops, ...fallbackLoops]
         const seen = new Set()
         const holes = []
 
@@ -187,6 +194,19 @@ export class PcbAssemblyBoardSubstrateBuilder {
         return holes
     }
 
+    /**
+     * Reads explicit board cutout contours from the scene board metadata.
+     * @param {object} sceneDescription Prepared scene description.
+     * @returns {Array<Array<object | number[]>>}
+     */
+    static #explicitCutoutLoops(sceneDescription) {
+        return PcbAssemblyBoardSubstrateBuilder.#array(
+            sceneDescription?.board?.cutouts
+        )
+            .map((cutout) => cutout?.points || cutout?.vertices || cutout)
+            .filter((loop) => Array.isArray(loop))
+    }
+
     /**
      * Reads existing drill cutout contours from scene silkscreen details.
      * @param {object} sceneDescription Prepared scene description.