pcb-scene3d-viewer 1.1.21 → 1.1.31

package/src/PcbScene3dController.mjs

@@ -4,6 +4,7 @@ import { PcbScene3dCircuitJsonAdapter } from './PcbScene3dCircuitJsonAdapter.mjs
 import { PcbScene3dInteractionHints } from './PcbScene3dInteractionHints.mjs'
 import { PcbScene3dRuntime } from './PcbScene3dRuntime.mjs'
 import { PcbScene3dSelectionInspectorRenderer } from './PcbScene3dSelectionInspectorRenderer.mjs'
+import { PcbScene3dSelectionIndexBuilder } from './PcbScene3dSelectionIndexBuilder.mjs'
 import { PcbScene3dSelectionVisibilityBinder } from './PcbScene3dSelectionVisibilityBinder.mjs'
 import { PcbScene3dText } from './PcbScene3dText.mjs'
 
@@ -37,7 +38,7 @@ export class PcbScene3dController {
     /** @type {Array<{ node: EventTarget, type: string, listener: (event: any) => void }>} */
     #listeners
 
-    /** @type {Map<string, { component: any | null, externalPlacement: any | null }>} */
+    /** @type {Map<string, { component: any | null, externalPlacement: any | null, staticBodyPlacement: any | null }>} */
     #selectionIndex
 
     /** @type {Map<string, { scale: { x: number, y: number, z: number }, rotationDeg: { x: number, y: number, z: number }, offsetMil: { x: number, y: number, z: number } }>} */
@@ -259,7 +260,12 @@ export class PcbScene3dController {
      * @returns {void}
      */
     setAutoSearchMissingModels(enabled) {
-        this.#autoSearchMissingModels = enabled === true
+        const nextEnabled = enabled === true
+        if (this.#autoSearchMissingModels === nextEnabled) {
+            return
+        }
+
+        this.#autoSearchMissingModels = nextEnabled
         this.#runtime?.setToggle?.(
             'model-search-models',
             this.#autoSearchMissingModels
@@ -451,7 +457,7 @@ export class PcbScene3dController {
             PcbScene3dController.#normalizeSceneDescription(sceneDescription)
         this.#sceneDescription = renderModel
         this.#selectionIndex =
-            PcbScene3dController.#buildSelectionIndex(renderModel)
+            PcbScene3dSelectionIndexBuilder.build(renderModel)
         const createRuntime =
             options.createRuntime ||
             ((nextViewportNode, nextSceneDescription, hooks) =>
@@ -716,7 +722,9 @@ export class PcbScene3dController {
             this.#selectedComponentKey
                 ? {
                       designator: this.#selectedComponentKey,
-                      sourceType: 'sidebar'
+                      sourceType: this.#resolveSelectionSourceType(
+                          this.#selectedComponentKey
+                      )
                   }
                 : null
         )
@@ -783,7 +791,7 @@ export class PcbScene3dController {
 
     /**
      * Renders selected component transform controls into the external host.
-     * @param {{ designator?: string, selection?: { sourceType?: string } | null, selectionEntry?: { component: any | null, externalPlacement: any | null } | null, adjustment?: { scale: { x: number, y: number, z: number }, rotationDeg: { x: number, y: number, z: number }, offsetMil: { x: number, y: number, z: number } } } | null} state Selection state.
+     * @param {{ designator?: string, selection?: { sourceType?: string } | null, selectionEntry?: { component: any | null, externalPlacement: any | null, staticBodyPlacement?: any | null } | null, adjustment?: { scale: { x: number, y: number, z: number }, rotationDeg: { x: number, y: number, z: number }, offsetMil: { x: number, y: number, z: number } } } | null} state Selection state.
      * @returns {void}
      */
     #renderAdjustmentHost(state = null) {
@@ -855,9 +863,18 @@ export class PcbScene3dController {
      * @returns {string}
      */
     #resolveSelectionSourceType(designator) {
-        return this.#selectionIndex.get(designator)?.externalPlacement
-            ? 'external-model'
-            : 'component'
+        const selectionEntry = this.#selectionIndex.get(designator)
+        if (selectionEntry?.externalPlacement) {
+            return 'external-model'
+        }
+        if (selectionEntry?.component) {
+            return 'component'
+        }
+        if (selectionEntry?.staticBodyPlacement) {
+            return 'static-body'
+        }
+
+        return 'component'
     }
 
     /**
@@ -893,53 +910,6 @@ export class PcbScene3dController {
             : sceneDescription
     }
 
-    /**
-     * Builds one designator-keyed inspector lookup from the scene
-     * description.
-     * @param {{ components?: any[], externalPlacements?: any[] }} sceneDescription
-     * @returns {Map<string, { component: any | null, externalPlacement: any | null }>}
-     */
-    static #buildSelectionIndex(sceneDescription) {
-        const index = new Map()
-        const components = Array.isArray(sceneDescription?.components)
-            ? sceneDescription.components
-            : []
-        const externalPlacements = Array.isArray(
-            sceneDescription?.externalPlacements
-        )
-            ? sceneDescription.externalPlacements
-            : []
-
-        components.forEach((component) => {
-            const designator = String(component?.designator || '').trim()
-            if (!designator) {
-                return
-            }
-
-            index.set(designator, {
-                component,
-                externalPlacement:
-                    index.get(designator)?.externalPlacement || null
-            })
-        })
-
-        externalPlacements.forEach((externalPlacement) => {
-            const designator = String(
-                externalPlacement?.designator || ''
-            ).trim()
-            if (!designator) {
-                return
-            }
-
-            index.set(designator, {
-                component: index.get(designator)?.component || null,
-                externalPlacement
-            })
-        })
-
-        return index
-    }
-
     /**
      * Resolves one archive base name from the mounted document metadata.
      * @param {{ summary?: { title?: string }, fileName?: string } | null} documentModel

package/src/PcbScene3dCopperDetailFilter.mjs

@@ -31,18 +31,27 @@ export class PcbScene3dCopperDetailFilter {
             arcs: PcbScene3dCopperDetailFilter.#filterMaskOpenPrimitives(
                 detail.arcs
             ),
+            fills: PcbScene3dCopperDetailFilter.#filterMaskOpenPrimitives(
+                detail.fills
+            ),
+            polygons: PcbScene3dCopperDetailFilter.#filterMaskOpenPrimitives(
+                detail.polygons
+            ),
             copperTexts: PcbScene3dCopperDetailFilter.#filterMaskOpenPrimitives(
                 detail.copperTexts,
                 copperTextMaskMatcher
             ),
-            vias: PcbScene3dCopperDetailFilter.#filterExposedVias(detail.vias)
+            vias: PcbScene3dCopperDetailFilter.#filterExposedVias(
+                detail.vias,
+                sceneDescription
+            )
         }
     }
 
     /**
      * Resolves trace-like copper that should be visible through solder mask.
      * @param {object} sceneDescription 3D scene description.
-     * @returns {{ tracks: any[], arcs: any[], copperTexts: any[], vias: any[] }}
+     * @returns {{ tracks: any[], arcs: any[], fills: any[], polygons: any[], copperTexts: any[], vias: any[] }}
      */
     static resolveCoveredByMask(sceneDescription) {
         const detail = sceneDescription?.detail || {}
@@ -52,7 +61,14 @@ export class PcbScene3dCopperDetailFilter {
                 sceneDescription
             )
         ) {
-            return { tracks: [], arcs: [], copperTexts: [], vias: [] }
+            return {
+                tracks: [],
+                arcs: [],
+                fills: [],
+                polygons: [],
+                copperTexts: [],
+                vias: []
+            }
         }
 
         const defaultCovered =
@@ -69,6 +85,14 @@ export class PcbScene3dCopperDetailFilter {
                 detail.arcs,
                 defaultCovered
             ),
+            fills: PcbScene3dCopperDetailFilter.#filterMaskCoveredPrimitives(
+                detail.fills,
+                defaultCovered
+            ),
+            polygons: PcbScene3dCopperDetailFilter.#filterMaskCoveredPrimitives(
+                detail.polygons,
+                defaultCovered
+            ),
             copperTexts: [],
             vias: []
         }
@@ -104,7 +128,10 @@ export class PcbScene3dCopperDetailFilter {
         const vias = PcbScene3dCopperDetailFilter.#usesRealisticMasking(
             sceneDescription
         )
-            ? PcbScene3dCopperDetailFilter.#filterExposedVias(detail.vias)
+            ? PcbScene3dCopperDetailFilter.#filterExposedVias(
+                  detail.vias,
+                  sceneDescription
+              )
             : detail.vias || []
 
         return PcbScene3dCopperDetailFilter.#appendPadBarrelSpecs(
@@ -113,6 +140,28 @@ export class PcbScene3dCopperDetailFilter {
         )
     }
 
+    /**
+     * Resolves via annuli that should be visible through solder mask.
+     * @param {object} sceneDescription 3D scene description.
+     * @returns {any[]}
+     */
+    static resolveCoveredStandaloneVias(sceneDescription) {
+        const detail = sceneDescription?.detail || {}
+
+        if (
+            !PcbScene3dCopperDetailFilter.#usesRealisticMasking(
+                sceneDescription
+            )
+        ) {
+            return []
+        }
+
+        return PcbScene3dCopperDetailFilter.#filterMaskCoveredVias(
+            detail.vias,
+            sceneDescription
+        )
+    }
+
     /**
      * Checks whether one scene should use solder-mask visibility.
      * @param {object} sceneDescription 3D scene description.
@@ -163,6 +212,8 @@ export class PcbScene3dCopperDetailFilter {
         return [
             detail?.tracks,
             detail?.arcs,
+            detail?.fills,
+            detail?.polygons,
             detail?.copperTexts,
             detail?.vias,
             detail?.pads
@@ -205,14 +256,40 @@ export class PcbScene3dCopperDetailFilter {
     }
 
     /**
-     * Keeps vias only when they are explicitly not tented.
+     * Keeps vias that should expose copper annuli in the 3D view.
      * @param {any[] | undefined} vias Via list.
+     * @param {object} sceneDescription 3D scene description.
      * @returns {any[]}
      */
-    static #filterExposedVias(vias) {
-        return (vias || []).filter((via) => {
-            return via?.isTentingTop === false || via?.isTentingBottom === false
-        })
+    static #filterExposedVias(vias, sceneDescription) {
+        return (vias || []).filter((via) =>
+            PcbScene3dCopperDetailFilter.#isViaExplicitlyOpen(via)
+        )
+    }
+
+    /**
+     * Keeps KiCad via annuli that are covered by solder mask.
+     * @param {any[] | undefined} vias Via list.
+     * @param {object} sceneDescription 3D scene description.
+     * @returns {any[]}
+     */
+    static #filterMaskCoveredVias(vias, sceneDescription) {
+        if (!PcbScene3dCopperDetailFilter.#isKiCadScene(sceneDescription)) {
+            return []
+        }
+
+        return (vias || []).filter(
+            (via) => !PcbScene3dCopperDetailFilter.#isViaExplicitlyOpen(via)
+        )
+    }
+
+    /**
+     * Checks whether one via explicitly exposes copper on either side.
+     * @param {object} via Via primitive.
+     * @returns {boolean}
+     */
+    static #isViaExplicitlyOpen(via) {
+        return via?.isTentingTop === false || via?.isTentingBottom === false
     }
 
     /**

package/src/PcbScene3dCopperDetailGroupBuilder.mjs

@@ -1,6 +1,8 @@
 import { PcbScene3dBoardMaterialPalette } from './PcbScene3dBoardMaterialPalette.mjs'
 import { PcbScene3dCopperDetailFilter } from './PcbScene3dCopperDetailFilter.mjs'
+import { PcbScene3dCopperDrillCutoutBuilder } from './PcbScene3dCopperDrillCutoutBuilder.mjs'
 import { PcbScene3dCopperFactory } from './PcbScene3dCopperFactory.mjs'
+import { PcbScene3dMaskCoveredCopperMaterial } from './PcbScene3dMaskCoveredCopperMaterial.mjs'
 import { PcbScene3dPadFactory } from './PcbScene3dPadFactory.mjs'
 import { PcbScene3dViaFactory } from './PcbScene3dViaFactory.mjs'
 
@@ -9,6 +11,8 @@ import { PcbScene3dViaFactory } from './PcbScene3dViaFactory.mjs'
  */
 export class PcbScene3dCopperDetailGroupBuilder {
     static #CIRCLE_SEGMENTS = 64
+    static #COVERED_COPPER_UNDERLAP_MIL = 6
+    static #MAX_SILKSCREEN_OCCLUSION_SPAN_MIL = 500
     static #ROUNDED_CORNER_SEGMENTS = 12
 
     /**
@@ -21,11 +25,21 @@ export class PcbScene3dCopperDetailGroupBuilder {
      */
     static build(THREE, sceneDescription, topZ, normalizePoint) {
         const group = new THREE.Group()
+        const drillCutouts = PcbScene3dCopperDrillCutoutBuilder.resolve(
+            sceneDescription?.detail
+        )
         const coveredGroup =
             PcbScene3dCopperDetailGroupBuilder.#buildCoveredGroup(
                 THREE,
                 sceneDescription,
                 topZ,
+                normalizePoint,
+                drillCutouts
+            )
+        const coveredViaGroup =
+            PcbScene3dCopperDetailGroupBuilder.#buildCoveredViaGroup(
+                THREE,
+                sceneDescription,
                 normalizePoint
             )
         const exposedGroup =
@@ -33,7 +47,8 @@ export class PcbScene3dCopperDetailGroupBuilder {
                 THREE,
                 sceneDescription,
                 topZ,
-                normalizePoint
+                normalizePoint,
+                drillCutouts
             )
         const viaGroup = PcbScene3dCopperDetailGroupBuilder.#buildViaGroup(
             THREE,
@@ -41,7 +56,7 @@ export class PcbScene3dCopperDetailGroupBuilder {
             normalizePoint
         )
 
-        ;[coveredGroup, exposedGroup, viaGroup]
+        ;[coveredGroup, coveredViaGroup, exposedGroup, viaGroup]
             .filter((child) => child.children.length)
             .forEach((child) => group.add(child))
 
@@ -54,9 +69,16 @@ export class PcbScene3dCopperDetailGroupBuilder {
      * @param {object} sceneDescription Scene description.
      * @param {number} topZ Top copper center Z.
      * @param {(x: number, y: number) => { x: number, y: number }} normalizePoint
+     * @param {{ x: number, y: number }[][]} drillCutouts Board drill cutouts.
      * @returns {any}
      */
-    static #buildCoveredGroup(THREE, sceneDescription, topZ, normalizePoint) {
+    static #buildCoveredGroup(
+        THREE,
+        sceneDescription,
+        topZ,
+        normalizePoint,
+        drillCutouts
+    ) {
         return PcbScene3dCopperFactory.buildMaskCoveredGroup(
             THREE,
             PcbScene3dCopperDetailFilter.resolveCoveredByMask(sceneDescription),
@@ -64,15 +86,11 @@ export class PcbScene3dCopperDetailGroupBuilder {
             -topZ,
             normalizePoint,
             {
-                solderMaskColor:
-                    PcbScene3dBoardMaterialPalette.resolveSurfaceColor(
-                        sceneDescription?.board,
-                        {
-                            hasBoardAssemblyModel: Boolean(
-                                sceneDescription?.boardAssemblyModel
-                            )
-                        }
-                    ),
+                ...PcbScene3dCopperDetailGroupBuilder.#coveredCopperMaterialOptions(
+                    sceneDescription
+                ),
+                drillCutouts,
+                drillDetail: sceneDescription?.detail,
                 occlusionCutouts:
                     PcbScene3dCopperDetailGroupBuilder.#resolveCoveredCopperOcclusions(
                         sceneDescription?.detail
@@ -81,22 +99,65 @@ export class PcbScene3dCopperDetailGroupBuilder {
         )
     }
 
+    /**
+     * Builds solder-mask-covered via annuli.
+     * @param {any} THREE Three.js namespace.
+     * @param {object} sceneDescription Scene description.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizePoint
+     * @returns {any}
+     */
+    static #buildCoveredViaGroup(THREE, sceneDescription, normalizePoint) {
+        const vias =
+            PcbScene3dCopperDetailFilter.resolveCoveredStandaloneVias(
+                sceneDescription
+            )
+        if (!vias.length) {
+            return new THREE.Group()
+        }
+
+        return PcbScene3dViaFactory.buildGroup(
+            THREE,
+            vias,
+            sceneDescription?.board?.thicknessMil,
+            normalizePoint,
+            {
+                material: PcbScene3dMaskCoveredCopperMaterial.build(
+                    THREE,
+                    PcbScene3dCopperDetailGroupBuilder.#coveredCopperMaterialOptions(
+                        sceneDescription
+                    )
+                )
+            }
+        )
+    }
+
     /**
      * Builds exposed copper detail.
      * @param {any} THREE Three.js namespace.
      * @param {object} sceneDescription Scene description.
      * @param {number} topZ Top copper center Z.
      * @param {(x: number, y: number) => { x: number, y: number }} normalizePoint
+     * @param {{ x: number, y: number }[][]} drillCutouts Board drill cutouts.
      * @returns {any}
      */
-    static #buildExposedGroup(THREE, sceneDescription, topZ, normalizePoint) {
+    static #buildExposedGroup(
+        THREE,
+        sceneDescription,
+        topZ,
+        normalizePoint,
+        drillCutouts
+    ) {
         return PcbScene3dCopperFactory.buildGroup(
             THREE,
             PcbScene3dCopperDetailFilter.resolve(sceneDescription),
             topZ,
             -topZ,
             normalizePoint,
-            { coordinateSystem: sceneDescription?.coordinateSystem }
+            {
+                coordinateSystem: sceneDescription?.coordinateSystem,
+                drillCutouts,
+                drillDetail: sceneDescription?.detail
+            }
         )
     }
 
@@ -126,6 +187,24 @@ export class PcbScene3dCopperDetailGroupBuilder {
         )
     }
 
+    /**
+     * Resolves solder-mask material options for covered copper relief.
+     * @param {object} sceneDescription Scene description.
+     * @returns {{ solderMaskColor: number }}
+     */
+    static #coveredCopperMaterialOptions(sceneDescription) {
+        return {
+            solderMaskColor: PcbScene3dBoardMaterialPalette.resolveSurfaceColor(
+                sceneDescription?.board,
+                {
+                    hasBoardAssemblyModel: Boolean(
+                        sceneDescription?.boardAssemblyModel
+                    )
+                }
+            )
+        }
+    }
+
     /**
      * Resolves opaque silkscreen fill polygons that should hide covered copper.
      * @param {{ top?: object, bottom?: object } | undefined} silkscreen Scene silkscreen detail.
@@ -168,6 +247,11 @@ export class PcbScene3dCopperDetailGroupBuilder {
                     )
             )
             .filter((points) => points.length >= 3)
+            .filter((points) =>
+                PcbScene3dCopperDetailGroupBuilder.#isBoundedSilkscreenOcclusion(
+                    points
+                )
+            )
     }
 
     /**
@@ -198,6 +282,44 @@ export class PcbScene3dCopperDetailGroupBuilder {
         ]
     }
 
+    /**
+     * Checks whether a silkscreen fill is small enough for copper clipping.
+     * @param {{ x: number, y: number }[]} points Fill contour points.
+     * @returns {boolean}
+     */
+    static #isBoundedSilkscreenOcclusion(points) {
+        const bounds =
+            PcbScene3dCopperDetailGroupBuilder.#resolveSilkscreenBounds(points)
+        const span = Math.max(
+            bounds.maxX - bounds.minX,
+            bounds.maxY - bounds.minY
+        )
+
+        return (
+            Number.isFinite(span) &&
+            span <=
+                PcbScene3dCopperDetailGroupBuilder
+                    .#MAX_SILKSCREEN_OCCLUSION_SPAN_MIL
+        )
+    }
+
+    /**
+     * Resolves the bounds for one silkscreen fill contour.
+     * @param {{ x: number, y: number }[]} points Fill contour points.
+     * @returns {{ minX: number, maxX: number, minY: number, maxY: number }}
+     */
+    static #resolveSilkscreenBounds(points) {
+        return points.reduce(
+            (bounds, point) => ({
+                minX: Math.min(bounds.minX, point.x),
+                maxX: Math.max(bounds.maxX, point.x),
+                minY: Math.min(bounds.minY, point.y),
+                maxY: Math.max(bounds.maxY, point.y)
+            }),
+            { minX: Infinity, maxX: -Infinity, minY: Infinity, maxY: -Infinity }
+        )
+    }
+
     /**
      * Resolves opaque geometry that should hide mask-covered copper.
      * @param {object | undefined} detail Scene detail.
@@ -318,18 +440,67 @@ export class PcbScene3dCopperDetailGroupBuilder {
      */
     static #resolvePadSurfacePolygon(pad, side) {
         const spec = PcbScene3dPadFactory.resolvePadSurfaceSpec(pad, side)
+        const occlusionSpec =
+            PcbScene3dCopperDetailGroupBuilder.#insetPadSurfaceSpec(spec)
         const center = {
             x: Number(pad?.x || 0) + spec.offsetX,
             y: Number(pad?.y || 0) + spec.offsetY
         }
 
+        if (!occlusionSpec) {
+            return []
+        }
+
         return PcbScene3dCopperDetailGroupBuilder.#transformPoints(
-            PcbScene3dCopperDetailGroupBuilder.#buildPadLocalPoints(spec),
+            PcbScene3dCopperDetailGroupBuilder.#buildPadLocalPoints(
+                occlusionSpec
+            ),
             center,
             Number(pad?.rotation || 0)
         )
     }
 
+    /**
+     * Insets a pad occlusion so mask-covered traces can visually tuck below
+     * exposed copper sidewalls instead of ending at the same vertical plane.
+     * @param {{ width: number, height: number, kind: string, cornerRadius: number }} spec Pad surface spec.
+     * @returns {{ width: number, height: number, kind: string, cornerRadius: number } | null}
+     */
+    static #insetPadSurfaceSpec(spec) {
+        const inset = PcbScene3dCopperDetailGroupBuilder.#resolvePadInset(spec)
+        const width = Math.max(Number(spec?.width || 0) - inset * 2, 0)
+        const height = Math.max(Number(spec?.height || 0) - inset * 2, 0)
+
+        if (width <= 0 || height <= 0) {
+            return null
+        }
+
+        return {
+            ...spec,
+            width,
+            height,
+            radius: Math.max(width, height) / 2,
+            cornerRadius: Math.max(Number(spec?.cornerRadius || 0) - inset, 0)
+        }
+    }
+
+    /**
+     * Resolves a bounded pad occlusion inset.
+     * @param {{ width: number, height: number }} spec Pad surface spec.
+     * @returns {number}
+     */
+    static #resolvePadInset(spec) {
+        return Math.min(
+            PcbScene3dCopperDetailGroupBuilder.#COVERED_COPPER_UNDERLAP_MIL,
+            Math.max(
+                Math.min(Number(spec?.width || 0), Number(spec?.height || 0)) /
+                    2 -
+                    0.001,
+                0
+            )
+        )
+    }
+
     /**
      * Builds local points for one pad face.
      * @param {{ width: number, height: number, kind: string, cornerRadius: number }} spec Pad surface spec.