pcb-scene3d-viewer 1.1.49 → 1.2.0

package/src/PcbScene3dPreparedPolygonSet.mjs

@@ -0,0 +1,70 @@
+import { PcbScene3dAabbIndex } from './PcbScene3dAabbIndex.mjs'
+
+/**
+ * Request-scoped broad-phase index for prepared polygons.
+ */
+export class PcbScene3dPreparedPolygonSet {
+    /** @type {PcbScene3dAabbIndex} */
+    #index
+
+    /** @type {Map<*, *>} */
+    #sourceMap
+
+    /**
+     * Builds a set index while retaining supplied prepared object identities.
+     * @param {Iterable<{ source: *, bounds: { minX: number, maxX: number, minY: number, maxY: number } }>} polygons
+     */
+    constructor(polygons) {
+        const preparedPolygons = Array.from(polygons || [])
+
+        this.#index = new PcbScene3dAabbIndex(preparedPolygons, {
+            resolveBounds: PcbScene3dPreparedPolygonSet.#resolveBounds,
+            resolveSourceIndex: PcbScene3dPreparedPolygonSet.#resolveSetPosition
+        })
+        this.#sourceMap = new Map()
+
+        for (const polygon of preparedPolygons) {
+            if (!this.#sourceMap.has(polygon.source)) {
+                this.#sourceMap.set(polygon.source, polygon)
+            }
+        }
+    }
+
+    /**
+     * Returns prepared polygons whose bounds overlap requested bounds.
+     * @param {{ minX: number, maxX: number, minY: number, maxY: number }} bounds
+     * @param {{ epsilon?: number, stable?: boolean }} [options]
+     * @returns {*[]}
+     */
+    query(bounds, options = {}) {
+        return this.#index.query(bounds, options)
+    }
+
+    /**
+     * Returns the earliest prepared polygon for one source identity.
+     * @param {*} source
+     * @returns {* | null}
+     */
+    resolveSource(source) {
+        return this.#sourceMap.get(source) ?? null
+    }
+
+    /**
+     * Resolves prepared polygon bounds for the top-level AABB index.
+     * @param {{ bounds: { minX: number, maxX: number, minY: number, maxY: number } }} polygon
+     * @returns {{ minX: number, maxX: number, minY: number, maxY: number }}
+     */
+    static #resolveBounds(polygon) {
+        return polygon.bounds
+    }
+
+    /**
+     * Resolves stable order from a polygon's position in this specific set.
+     * @param {*} _polygon
+     * @param {number} index
+     * @returns {number}
+     */
+    static #resolveSetPosition(_polygon, index) {
+        return index
+    }
+}

package/src/PcbScene3dRuntime.mjs

@@ -8,6 +8,7 @@ import { PcbScene3dCompanionBasePlacementAdjuster } from './PcbScene3dCompanionB
 import { PcbScene3dCopperDetailGroupBuilder } from './PcbScene3dCopperDetailGroupBuilder.mjs'
 import { PcbScene3dCopperFactory } from './PcbScene3dCopperFactory.mjs'
 import { PcbScene3dDetailCoordinateNormalizer } from './PcbScene3dDetailCoordinateNormalizer.mjs'
+import { PcbScene3dDeferredModelFinalizer } from './PcbScene3dDeferredModelFinalizer.mjs'
 import { PcbScene3dDrillVoidFactory } from './PcbScene3dDrillVoidFactory.mjs'
 import { PcbScene3dExternalCompanionFallback } from './PcbScene3dExternalCompanionFallback.mjs'
 import { PcbScene3dExternalModels } from './PcbScene3dExternalModels.mjs'
@@ -76,7 +77,7 @@ export class PcbScene3dRuntime {
     /**
      * @param {HTMLElement} viewportNode
      * @param {any} sceneDescription Scene description or CircuitJSON model.
-     * @param {{ setDiagnostics?: (messages: string[]) => void, setSelection?: (selection: any | null) => void, loadRuntimeModules?: () => Promise<{ THREE: any, OrbitControls: any }>, translate?: ((key: string) => string) | null }} [hooks]
+     * @param {{ setDiagnostics?: (messages: string[]) => void, setSelection?: (selection: any | null) => void, loadRuntimeModules?: () => Promise<{ THREE: any, OrbitControls: any }>, translate?: ((key: string) => string) | null, modelLoaderOptions?: object }} [hooks]
      */
     constructor(viewportNode, sceneDescription, hooks = {}) {
         const renderModel =
@@ -264,7 +265,6 @@ export class PcbScene3dRuntime {
             this.#settleReady()
             return
         }
-
         try {
             const { THREE, OrbitControls } =
                 (await this.#hooks.loadRuntimeModules?.()) ||
@@ -274,7 +274,6 @@ export class PcbScene3dRuntime {
             if (this.#isDisposed || !this.#viewportNode) {
                 return
             }
-
             this.#createRenderer()
             this.#createSceneGraph()
             this.#createControls()
@@ -291,7 +290,6 @@ export class PcbScene3dRuntime {
             this.#settleReady()
         }
     }
-
     /**
      * Creates the Three.js renderer, camera, and scene.
      * @returns {void}
@@ -299,7 +297,6 @@ export class PcbScene3dRuntime {
     #createRenderer() {
         const THREE = this.#three
         const size = PcbScene3dViewportResize.resolveSize(this.#viewportNode)
-
         this.#renderer = new THREE.WebGLRenderer({
             antialias: true,
             alpha: true,
@@ -310,7 +307,6 @@ export class PcbScene3dRuntime {
         this.#renderer.domElement.className = 'scene-3d__canvas'
         this.#renderer.domElement.style.width = '100%'
         this.#renderer.domElement.style.height = '100%'
-
         this.#scene = new THREE.Scene()
         this.#camera = new THREE.PerspectiveCamera(
             38,
@@ -321,7 +317,6 @@ export class PcbScene3dRuntime {
         this.#camera.up.set(0, 0, 1)
         this.#viewportNode?.replaceChildren(this.#renderer.domElement)
     }
-
     /**
      * Creates the initial board shell, fallback bodies, and placeholder detail
      * groups used by the deferred loading stages.
@@ -330,7 +325,6 @@ export class PcbScene3dRuntime {
     #createSceneGraph() {
         const THREE = this.#three
         const board = this.#sceneDescription.board
-
         this.#viewOrientationGroup = new THREE.Group()
         this.#scene.add(this.#viewOrientationGroup)
         this.#rootGroup = new THREE.Group()
@@ -368,7 +362,11 @@ export class PcbScene3dRuntime {
                 (x, y) => this.#normalizeDetailPoint(x, y),
                 {
                     enabled: true,
-                    board
+                    board,
+                    hasBoardAssemblyModel: Boolean(
+                        this.#sceneDescription.boardAssemblyModel
+                    ),
+                    sourceFormat: this.#sceneDescription.sourceFormat
                 }
             )
         )
@@ -400,7 +398,6 @@ export class PcbScene3dRuntime {
             if (component?.renderFallbackBody === false) {
                 return
             }
-
             const isCompanionBase =
                 PcbScene3dExternalCompanionFallback.shouldKeepFallback(
                     this.#sceneDescription,
@@ -470,7 +467,6 @@ export class PcbScene3dRuntime {
             boardSpan * 7
         )
     }
-
     /**
      * Applies the active preset's scene-scale transform.
      * @param {string} preset
@@ -496,27 +492,47 @@ export class PcbScene3dRuntime {
             )
         )
     }
-
     /**
      * Loads silkscreen, copper, and external model detail after the initial
      * shell render and keeps readiness pending until settlement completes.
      * @returns {Promise<void>}
      */
     async #loadDeferredDetail() {
+        let externalModels = null
+        let hasDeferredStageFailure = false
         try {
             await PcbScene3dRuntimeHelpers.yieldToNextFrame(globalThis)
             if (this.#isDisposed) {
                 return
             }
-
+            externalModels = new PcbScene3dDeferredModelFinalizer(
+                this.#loadExternalModels(),
+                {
+                    isDisposed: () => this.#isDisposed,
+                    onSuccess: (diagnostics) => {
+                        if (!hasDeferredStageFailure && diagnostics.length) {
+                            this.#hooks.setDiagnostics?.(diagnostics)
+                        }
+                        this.#applyViewScale(this.#presetState.get())
+                        this.#render()
+                    },
+                    onError: (error) => {
+                        this.#hooks.setDiagnostics?.([
+                            'Deferred 3D detail could not finish loading: ' +
+                                String(
+                                    error?.message || error || 'Unknown error.'
+                                )
+                        ])
+                        this.#render()
+                    }
+                }
+            )
             await this.#loadDeferredSurfaceArtwork()
             this.#render()
-
             await PcbScene3dRuntimeHelpers.yieldToNextFrame(globalThis)
             if (this.#isDisposed) {
                 return
             }
-
             this.#loadDeferredCopper()
             this.#applyToggleVisibility()
             this.#render()
@@ -525,18 +541,13 @@ export class PcbScene3dRuntime {
             if (this.#isDisposed) {
                 return
             }
-
-            await this.#loadExternalModels()
-            if (this.#isDisposed) {
-                return
-            }
-
-            this.#render()
+            await externalModels.release()
         } catch (error) {
             if (this.#isDisposed) {
                 return
             }
-
+            hasDeferredStageFailure = true
+            externalModels?.release({ reportError: false }).catch(() => {})
             this.#hooks.setDiagnostics?.([
                 'Deferred 3D detail could not finish loading: ' +
                     String(error?.message || error || 'Unknown error.')
@@ -544,7 +555,6 @@ export class PcbScene3dRuntime {
             this.#render()
         }
     }
-
     /**
      * Builds and attaches surface artwork detail once after the first frame.
      * @returns {Promise<void>}
@@ -557,7 +567,6 @@ export class PcbScene3dRuntime {
             ['silkscreen', silkscreen, Z_MIL.silk, true],
             ['paste', this.#sceneDescription.detail.paste, Z_MIL.paste, false]
         ]
-
         for (const [groupName, artwork, z, prepareFonts] of overlays) {
             if (artwork == null) {
                 continue
@@ -578,7 +587,6 @@ export class PcbScene3dRuntime {
                     ? await loaded
                     : loaded) || didLoad
         }
-
         if (didLoad) {
             this.#applyViewScale(this.#presetState.get())
         }
@@ -600,33 +608,39 @@ export class PcbScene3dRuntime {
             topZ,
             (x, y) => this.#normalizeDetailPoint(x, y)
         )
-
         if (detailGroup.children.length) {
             copperGroup.add(detailGroup)
             this.#applyViewScale(this.#presetState.get())
         }
     }
-
     /**
      * Attempts to load any resolved external 3D models.
-     * @returns {Promise<void>}
+     * @returns {Promise<string[]>}
      */
     async #loadExternalModels() {
         const externalModelsGroup = this.#groups.get('external-models')
         if (!externalModelsGroup) {
-            return
+            return []
         }
 
         const diagnostics = await PcbScene3dExternalModels.loadIntoScene({
             three: this.#three,
             sceneDescription: this.#placementSceneDescription,
             externalModelsGroup,
+            modelLoaderOptions: this.#hooks.modelLoaderOptions,
             modelViewScale: PcbScene3dRuntime.resolveViewScale(
                 this.#presetState.get(),
                 this.#sceneDescription
             ),
             isDisposed: () => this.#isDisposed,
             onPlacementGroup: (placement, placementGroup) => {
+                PcbScene3dExternalModels.applyViewCompensation(
+                    placementGroup,
+                    PcbScene3dRuntime.resolveViewScale(
+                        this.#presetState.get(),
+                        this.#sceneDescription
+                    )
+                )
                 this.#registerSelectionRoot(
                     placement?.designator,
                     placementGroup
@@ -658,12 +672,8 @@ export class PcbScene3dRuntime {
                 this.#applyToggleVisibility()
             }
         })
-
-        if (diagnostics.length) {
-            this.#hooks.setDiagnostics?.(diagnostics)
-        }
+        return diagnostics
     }
-
     /**
      * Creates and configures orbit/pan/zoom controls using Three's standard
      * OrbitControls implementation in the same z-up world as the PCB scene.
@@ -673,13 +683,11 @@ export class PcbScene3dRuntime {
         if (!this.#camera || !this.#renderer || !this.#orbitControlsClass) {
             return
         }
-
         const THREE = this.#three
         const domElement = this.#renderer?.domElement
         if (!domElement) {
             return
         }
-
         this.#controls = new this.#orbitControlsClass(this.#camera, domElement)
         this.#controls.enableDamping = false
         this.#controls.screenSpacePanning = true
@@ -691,14 +699,12 @@ export class PcbScene3dRuntime {
             THREE,
             this.#presetState.get()
         )
-
         PcbScene3dCameraRig.applyPreset(
             this.#camera,
             this.#controls,
             this.#presetState.get(),
             this.#sceneDescription
         )
-
         this.#bindListener(this.#controls, 'change', () => {
             this.#renderScheduler.schedule()
         })
@@ -712,22 +718,18 @@ export class PcbScene3dRuntime {
             () => this.#handleResize()
         )
     }
-
     /** @returns {void} */
     #bindSelectionInteraction() {
         if (!this.#renderer || !this.#camera || !this.#three) {
             return
         }
-
         this.#raycaster = new this.#three.Raycaster()
         this.#pointer = new this.#three.Vector2()
         const domElement = this.#renderer.domElement
-
         this.#bindListener(domElement, 'pointerdown', (event) => {
             if (Number(event?.button) !== 0) {
                 return
             }
-
             this.#pointerDownPosition = {
                 x: Number(event?.clientX || 0),
                 y: Number(event?.clientY || 0)
@@ -737,7 +739,6 @@ export class PcbScene3dRuntime {
             if (Number(event?.button) !== 0) {
                 return
             }
-
             if (
                 !this.#pointerDownPosition ||
                 PcbScene3dRuntimeHelpers.pointerTravel(
@@ -751,7 +752,6 @@ export class PcbScene3dRuntime {
                 this.#pointerDownPosition = null
                 return
             }
-
             this.#pointerDownPosition = null
             this.#handleSelectionPointer(event)
         })

package/src/PcbScene3dRuntimeBoardMeshes.mjs

@@ -68,6 +68,39 @@ export class PcbScene3dRuntimeBoardMeshes {
      * @returns {any}
      */
     static buildBoardMesh(THREE, sceneDescription, normalizeDetailPoint) {
+        const contours = PcbScene3dRuntimeBoardMeshes.#boardContours(
+            sceneDescription.board
+        )
+        if (contours.length === 1) {
+            return PcbScene3dRuntimeBoardMeshes.#buildBoardMesh(
+                THREE,
+                { ...sceneDescription, board: contours[0] },
+                normalizeDetailPoint
+            )
+        }
+
+        const group = new THREE.Group()
+        group.name = 'board-contours'
+        contours.forEach((board, index) => {
+            const mesh = PcbScene3dRuntimeBoardMeshes.#buildBoardMesh(
+                THREE,
+                { ...sceneDescription, board },
+                normalizeDetailPoint
+            )
+            mesh.name = 'board-contour-' + (index + 1)
+            group.add(mesh)
+        })
+        return group
+    }
+
+    /**
+     * Builds one independently extruded board contour.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ board?: any, detail?: any, boardAssemblyModel?: any }} sceneDescription Scene metadata.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeDetailPoint Detail coordinate normalizer.
+     * @returns {any}
+     */
+    static #buildBoardMesh(THREE, sceneDescription, normalizeDetailPoint) {
         const board = sceneDescription.board
         const geometry = PcbScene3dBoardShapeFactory.buildGeometry(
             THREE,
@@ -97,7 +130,7 @@ export class PcbScene3dRuntimeBoardMeshes {
             : 0xc9ca78
         const surfaceColor = hasBoardAssemblyModel
             ? resolvedEdgeColor
-            : PcbScene3dBoardMaterialPalette.resolveSurfaceColor(board, {
+            : PcbScene3dBoardMaterialPalette.resolveBoardSurfaceColor(board, {
                   hasBoardAssemblyModel
               })
 
@@ -140,6 +173,39 @@ export class PcbScene3dRuntimeBoardMeshes {
      * @returns {any}
      */
     static buildBoardOutline(THREE, sceneDescription, normalizeDetailPoint) {
+        const contours = PcbScene3dRuntimeBoardMeshes.#boardContours(
+            sceneDescription.board
+        )
+        if (contours.length === 1) {
+            return PcbScene3dRuntimeBoardMeshes.#buildBoardOutline(
+                THREE,
+                { ...sceneDescription, board: contours[0] },
+                normalizeDetailPoint
+            )
+        }
+
+        const group = new THREE.Group()
+        group.name = 'board-contour-outlines'
+        contours.forEach((board, index) => {
+            const outline = PcbScene3dRuntimeBoardMeshes.#buildBoardOutline(
+                THREE,
+                { ...sceneDescription, board },
+                normalizeDetailPoint
+            )
+            outline.name = 'board-contour-outline-' + (index + 1)
+            group.add(outline)
+        })
+        return group
+    }
+
+    /**
+     * Builds one independently rendered board contour outline.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ board?: any, detail?: any }} sceneDescription Scene metadata.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeDetailPoint Detail coordinate normalizer.
+     * @returns {any}
+     */
+    static #buildBoardOutline(THREE, sceneDescription, normalizeDetailPoint) {
         const shape = PcbScene3dBoardShapeFactory.buildShape(
             THREE,
             sceneDescription.board,
@@ -166,6 +232,24 @@ export class PcbScene3dRuntimeBoardMeshes {
         )
     }
 
+    /**
+     * Resolves independently renderable contours while preserving legacy boards.
+     * @param {object} board Aggregate board metadata.
+     * @returns {object[]}
+     */
+    static #boardContours(board) {
+        const contours = Array.isArray(board?.contours)
+            ? board.contours.filter(Boolean)
+            : []
+        if (!contours.length) return [board || {}]
+
+        return contours.map((contour) => ({
+            ...board,
+            ...contour,
+            contours: []
+        }))
+    }
+
     /**
      * Traverses the board render group.
      * @param {any} root Root group or mesh.

package/src/PcbScene3dShapeHoleGeometryCleaner.mjs

@@ -12,9 +12,10 @@ export class PcbScene3dShapeHoleGeometryCleaner {
      * @param {any} THREE Three.js namespace.
      * @param {any} geometry Shape geometry.
      * @param {{ x: number, y: number }[][]} holes Shape hole polygons.
+     * @param {{ preparedPolygonCache?: Map }} [options] Request-scoped options.
      * @returns {any}
      */
-    static removeCoveredHoleCenters(THREE, geometry, holes) {
+    static removeCoveredHoleCenters(THREE, geometry, holes, options = {}) {
         const coveredHoles =
             PcbScene3dShapeHoleGeometryCleaner.resolveCoveredHoleCenters(
                 geometry,
@@ -32,7 +33,8 @@ export class PcbScene3dShapeHoleGeometryCleaner {
             {
                 maxDepth: 12,
                 maxEdgeLength:
-                    PcbScene3dShapeHoleGeometryCleaner.#CUTOUT_MAX_EDGE_LENGTH
+                    PcbScene3dShapeHoleGeometryCleaner.#CUTOUT_MAX_EDGE_LENGTH,
+                preparedPolygonCache: options?.preparedPolygonCache
             }
         )
     }

package/src/PcbScene3dShellRenderer.mjs

@@ -1,3 +1,7 @@
+import { CircuitJsonDocumentContext } from 'circuitjson-toolkit'
+import { CircuitJsonBomBuilder } from 'circuitjson-toolkit/extensions'
+import { PcbScene3dCircuitJsonGeometry } from './PcbScene3dCircuitJsonGeometry.mjs'
+import { PcbScene3dCircuitJsonInput } from './PcbScene3dCircuitJsonInput.mjs'
 import { PcbScene3dText } from './PcbScene3dText.mjs'
 
 /**
@@ -13,8 +17,8 @@ export class PcbScene3dShellRenderer {
      */
     static render(documentModel, translate = null, options = {}) {
         const t = PcbScene3dText.createTranslator(translate)
-        const pcb = documentModel?.pcb
-        if (!pcb) {
+        const summary = PcbScene3dShellRenderer.#summary(documentModel, options)
+        if (!summary) {
             return (
                 '<section class="viewer-empty">' +
                 PcbScene3dShellRenderer.#escapeHtml(t('scene3d.noPcb')) +
@@ -22,10 +26,10 @@ export class PcbScene3dShellRenderer {
             )
         }
 
-        const widthMil = Math.round(pcb.boardOutline.widthMil || 0)
-        const heightMil = Math.round(pcb.boardOutline.heightMil || 0)
-        const componentCount = pcb.components.length
-        const bomRows = documentModel?.bom?.length || 0
+        const widthMil = Math.round(summary.widthMil || 0)
+        const heightMil = Math.round(summary.heightMil || 0)
+        const componentCount = summary.componentCount
+        const bomRows = summary.bomRows
 
         return (
             '<section class="scene-3d"><header class="svg-panel__header"><h3>' +
@@ -129,6 +133,71 @@ export class PcbScene3dShellRenderer {
         )
     }
 
+    /**
+     * Resolves shell statistics from legacy or canonical CircuitJSON input.
+     * @param {unknown} documentModel Document input.
+     * @param {{ drawFauxBoard?: boolean }} options Shell and adapter options.
+     * @returns {{ widthMil: number, heightMil: number, componentCount: number, bomRows: number } | null}
+     */
+    static #summary(documentModel, options) {
+        const legacyPcb = PcbScene3dShellRenderer.#ownData(documentModel, 'pcb')
+        if (legacyPcb && typeof legacyPcb === 'object') {
+            const boardOutline = legacyPcb.boardOutline || {}
+            const components = Array.isArray(legacyPcb.components)
+                ? legacyPcb.components
+                : []
+            const bom = PcbScene3dShellRenderer.#ownData(documentModel, 'bom')
+            return {
+                widthMil: Number(boardOutline.widthMil || 0),
+                heightMil: Number(boardOutline.heightMil || 0),
+                componentCount: components.length,
+                bomRows: Array.isArray(bom) ? bom.length : 0
+            }
+        }
+        if (!PcbScene3dCircuitJsonInput.isModel(documentModel)) return null
+
+        const context = CircuitJsonDocumentContext.prepare(documentModel, {
+            indexes: ['elements']
+        })
+        const index = context.getIndex('elements')
+        if (
+            !index.elementsByType.get('pcb_board')?.length &&
+            !index.elementsByType.get('pcb_panel')?.length &&
+            !(
+                options?.drawFauxBoard === true &&
+                index.elementsByType.get('pcb_component')?.length
+            )
+        ) {
+            return null
+        }
+        const board = PcbScene3dCircuitJsonGeometry.buildBoard(index, options)
+        return {
+            widthMil: board.widthMil,
+            heightMil: board.heightMil,
+            componentCount: (index.elementsByType.get('pcb_component') || [])
+                .length,
+            bomRows: CircuitJsonBomBuilder.build(context.model).length
+        }
+    }
+
+    /**
+     * Reads one own data property without invoking accessors.
+     * @param {unknown} value Record candidate.
+     * @param {PropertyKey} key Property key.
+     * @returns {unknown}
+     */
+    static #ownData(value, key) {
+        if (!value || typeof value !== 'object') return undefined
+        try {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key)
+            return descriptor && Object.hasOwn(descriptor, 'value')
+                ? descriptor.value
+                : undefined
+        } catch {
+            return undefined
+        }
+    }
+
     /**
      * Returns the checkbox checked attribute for one scene toggle.
      * @param {{ initialToggles?: Record<string, boolean> }} options Renderer options.