pcb-scene3d-viewer 1.1.21 → 1.1.22

package/src/PcbScene3dFallbackBodyFactory.mjs

@@ -0,0 +1,105 @@
+import { PcbScene3dBodyColor } from './PcbScene3dBodyColor.mjs'
+import { PcbScene3dComponentAdjustment } from './PcbScene3dComponentAdjustment.mjs'
+import { PcbScene3dMountRig } from './PcbScene3dMountRig.mjs'
+
+/**
+ * Builds procedural fallback body render roots for PCB components.
+ */
+export class PcbScene3dFallbackBodyFactory {
+    /**
+     * Builds one procedural fallback body root.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ designator?: string, positionMil: { x: number, y: number, z: number }, rotationDeg: number, mountSide: string, body: { family: string, sizeMil: { width: number, depth: number, height: number } } }} component Component scene entry.
+     * @param {{ companionBase?: boolean }} [options] Rendering options.
+     * @returns {{ rootGroup: any, adjustmentGroup: any }}
+     */
+    static build(THREE, component, options = {}) {
+        const family = component.body.family
+        const size = component.body.sizeMil
+        const material = new THREE.MeshStandardMaterial({
+            color: PcbScene3dFallbackBodyFactory.#resolveColor(family, options),
+            roughness: 0.72,
+            metalness: family === 'chip' ? 0.12 : 0.08
+        })
+        const mesh = PcbScene3dFallbackBodyFactory.#buildMesh(
+            THREE,
+            family,
+            size,
+            material
+        )
+        const mountRig = PcbScene3dMountRig.create(THREE, component)
+        const adjustmentGroup =
+            PcbScene3dFallbackBodyFactory.#buildAdjustmentGroup(
+                THREE,
+                component
+            )
+
+        mountRig.rootGroup.userData.scene3dSelection = {
+            designator: String(component?.designator || 'component'),
+            sourceType: 'component'
+        }
+        adjustmentGroup.add(mesh)
+        mountRig.faceGroup.add(adjustmentGroup)
+
+        return {
+            rootGroup: mountRig.rootGroup,
+            adjustmentGroup
+        }
+    }
+
+    /**
+     * Resolves the fallback body color.
+     * @param {string} family Package family.
+     * @param {{ companionBase?: boolean }} options Rendering options.
+     * @returns {number}
+     */
+    static #resolveColor(family, options) {
+        return options?.companionBase
+            ? 0x808080
+            : PcbScene3dBodyColor.resolve(family)
+    }
+
+    /**
+     * Builds the body mesh for one package family.
+     * @param {any} THREE Three.js namespace.
+     * @param {string} family Package family.
+     * @param {{ width: number, depth: number, height: number }} size Body size.
+     * @param {any} material Mesh material.
+     * @returns {any}
+     */
+    static #buildMesh(THREE, family, size, material) {
+        if (family === 'radial-capacitor' || family === 'test-point') {
+            return new THREE.Mesh(
+                new THREE.CylinderGeometry(
+                    size.width / 2,
+                    size.width / 2,
+                    size.height,
+                    28
+                ),
+                material
+            )
+        }
+
+        return new THREE.Mesh(
+            new THREE.BoxGeometry(size.width, size.depth, size.height),
+            material
+        )
+    }
+
+    /**
+     * Builds the transform node used by live component adjustments.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ designator?: string }} component Component scene entry.
+     * @returns {any}
+     */
+    static #buildAdjustmentGroup(THREE, component) {
+        const adjustmentGroup = new THREE.Group()
+        adjustmentGroup.userData.scene3dAdjustmentTarget = true
+        adjustmentGroup.userData.scene3dAdjustmentDesignator = String(
+            component?.designator || 'component'
+        )
+        adjustmentGroup.userData.scene3dAdjustmentBaseline =
+            PcbScene3dComponentAdjustment.neutral()
+        return adjustmentGroup
+    }
+}

package/src/PcbScene3dFallbackVisibility.mjs

@@ -74,9 +74,66 @@ export class PcbScene3dFallbackVisibility {
                     return
                 }
 
+                const stitchedCompanion =
+                    PcbScene3dFallbackVisibility.shouldKeepExternalCompanion(
+                        rootObject,
+                        toggles
+                    )
                 rootObject.visible =
-                    showFallbackBodies && !hideForLoadedExternal
+                    stitchedCompanion ||
+                    (showFallbackBodies && !hideForLoadedExternal)
             })
         })
     }
+
+    /**
+     * Checks whether any fallback root should keep the fallback group visible
+     * as part of a stitched external-model package.
+     * @param {Map<string, Set<any>>} fallbackRoots Fallback root registry.
+     * @param {{ 'external-models'?: boolean }} toggles Detail toggles.
+     * @returns {boolean}
+     */
+    static hasVisibleExternalCompanion(fallbackRoots, toggles) {
+        if (
+            !(fallbackRoots instanceof Map) ||
+            !Boolean(toggles?.['external-models'])
+        ) {
+            return false
+        }
+
+        let hasCompanion = false
+        fallbackRoots.forEach((roots) => {
+            roots?.forEach?.((rootObject) => {
+                hasCompanion =
+                    hasCompanion ||
+                    PcbScene3dFallbackVisibility.#isExternalCompanion(
+                        rootObject
+                    )
+            })
+        })
+        return hasCompanion
+    }
+
+    /**
+     * Checks whether one fallback body should stay visible as a stitched
+     * external-model companion under the active toggles.
+     * @param {any} rootObject Fallback root object.
+     * @param {{ 'external-models'?: boolean }} toggles Detail toggles.
+     * @returns {boolean}
+     */
+    static shouldKeepExternalCompanion(rootObject, toggles) {
+        return (
+            Boolean(toggles?.['external-models']) &&
+            PcbScene3dFallbackVisibility.#isExternalCompanion(rootObject)
+        )
+    }
+
+    /**
+     * Checks whether a fallback body is part of a stitched external model.
+     * @param {any} rootObject Fallback root object.
+     * @returns {boolean}
+     */
+    static #isExternalCompanion(rootObject) {
+        return Boolean(rootObject?.userData?.scene3dFallbackExternalCompanion)
+    }
 }

package/src/PcbScene3dRenderGroupVisibility.mjs

@@ -37,9 +37,16 @@ export class PcbScene3dRenderGroupVisibility {
             state?.groups?.get('copper'),
             boardAssemblyActive
         )
+        const showFallbackBodies =
+            !boardAssemblyActive &&
+            (Boolean(state?.toggles?.['fallback-bodies']) ||
+                PcbScene3dFallbackVisibility.hasVisibleExternalCompanion(
+                    state?.fallbackBodyRoots,
+                    state?.toggles
+                ))
         PcbScene3dRenderGroupVisibility.#setVisible(
             state?.groups?.get('fallback-bodies'),
-            Boolean(state?.toggles?.['fallback-bodies']) && !boardAssemblyActive
+            showFallbackBodies
         )
 
         PcbScene3dFallbackVisibility.applyVisibility(

package/src/PcbScene3dRuntime.mjs

@@ -1,18 +1,19 @@
 import { PcbScene3dBoardSolderMaskFactory } from './PcbScene3dBoardSolderMaskFactory.mjs'
-import { PcbScene3dBodyColor } from './PcbScene3dBodyColor.mjs'
 import { PcbScene3dCameraRig } from './PcbScene3dCameraRig.mjs'
 import { PcbScene3dCircuitJsonAdapter } from './PcbScene3dCircuitJsonAdapter.mjs'
 import { PcbScene3dComponentVisibility } from './PcbScene3dComponentVisibility.mjs'
 import { PcbScene3dComponentAdjustment } from './PcbScene3dComponentAdjustment.mjs'
 import { PcbScene3dComponentAdjustmentRegistry } from './PcbScene3dComponentAdjustmentRegistry.mjs'
+import { PcbScene3dCompanionBasePlacementAdjuster } from './PcbScene3dCompanionBasePlacementAdjuster.mjs'
 import { PcbScene3dCopperDetailGroupBuilder } from './PcbScene3dCopperDetailGroupBuilder.mjs'
 import { PcbScene3dCopperFactory } from './PcbScene3dCopperFactory.mjs'
 import { PcbScene3dDetailCoordinateNormalizer } from './PcbScene3dDetailCoordinateNormalizer.mjs'
 import { PcbScene3dDrillVoidFactory } from './PcbScene3dDrillVoidFactory.mjs'
+import { PcbScene3dExternalCompanionFallback } from './PcbScene3dExternalCompanionFallback.mjs'
 import { PcbScene3dExternalModels } from './PcbScene3dExternalModels.mjs'
+import { PcbScene3dFallbackBodyFactory } from './PcbScene3dFallbackBodyFactory.mjs'
 import { PcbScene3dFallbackVisibility } from './PcbScene3dFallbackVisibility.mjs'
 import { PcbScene3dInteractionHints } from './PcbScene3dInteractionHints.mjs'
-import { PcbScene3dMountRig } from './PcbScene3dMountRig.mjs'
 import { PcbScene3dModelSearchPlacement } from './PcbScene3dModelSearchPlacement.mjs'
 import { PcbScene3dPresetState } from './PcbScene3dPresetState.mjs'
 import { PcbScene3dRenderGroupVisibility } from './PcbScene3dRenderGroupVisibility.mjs'
@@ -22,6 +23,7 @@ import { PcbScene3dSilkscreenChunkedFactory } from './PcbScene3dSilkscreenChunke
 import { PcbScene3dTrueTypeTextFactory } from './PcbScene3dTrueTypeTextFactory.mjs'
 import { PcbScene3dSelectionResolver } from './PcbScene3dSelectionResolver.mjs'
 import { PcbScene3dSelectionStyler } from './PcbScene3dSelectionStyler.mjs'
+import { PcbScene3dStaticBodyFactory } from './PcbScene3dStaticBodyFactory.mjs'
 import { PcbScene3dViewportResize } from './PcbScene3dViewportResize.mjs'
 import { PcbScene3dViewScale } from './PcbScene3dViewScale.mjs'
 const SILKSCREEN_COPPER_CLEARANCE_MIL = 0.12
@@ -37,6 +39,7 @@ const Z_MIL = {
 export class PcbScene3dRuntime {
     #viewportNode
     #sceneDescription
+    #placementSceneDescription
     #hooks
     #toggles
     #groups
@@ -78,6 +81,8 @@ export class PcbScene3dRuntime {
             PcbScene3dRuntime.#normalizeSceneDescription(sceneDescription)
         this.#viewportNode = viewportNode
         this.#sceneDescription = renderModel
+        this.#placementSceneDescription =
+            PcbScene3dCompanionBasePlacementAdjuster.adjust(renderModel)
         this.#hooks = hooks
         this.#toggles = {
             'external-models': true,
@@ -385,19 +390,60 @@ export class PcbScene3dRuntime {
         this.#groups.set('copper', copperGroup)
         this.#rootGroup.add(copperGroup)
         const fallbackBodiesGroup = new THREE.Group()
+        const staticBodiesGroup = new THREE.Group()
         const externalModelsGroup = new THREE.Group()
         this.#sceneDescription.components.forEach((component) => {
-            const fallbackBody = this.#buildFallbackBody(component)
-            fallbackBodiesGroup.add(fallbackBody)
+            if (component?.renderFallbackBody === false) {
+                return
+            }
+
+            const isCompanionBase =
+                PcbScene3dExternalCompanionFallback.shouldKeepFallback(
+                    this.#sceneDescription,
+                    component
+                )
+            const fallbackBody = PcbScene3dFallbackBodyFactory.build(
+                THREE,
+                component,
+                { companionBase: isCompanionBase }
+            )
+            if (isCompanionBase) {
+                fallbackBody.rootGroup.userData.scene3dFallbackExternalCompanion = true
+            }
+            fallbackBodiesGroup.add(fallbackBody.rootGroup)
             PcbScene3dFallbackVisibility.registerFallbackRoot(
                 this.#fallbackBodyRoots,
                 component?.designator,
-                fallbackBody
+                fallbackBody.rootGroup
+            )
+            this.#registerSelectionRoot(
+                component?.designator,
+                fallbackBody.rootGroup
+            )
+            this.#componentAdjustmentRegistry.register(
+                component?.designator,
+                fallbackBody.adjustmentGroup
+            )
+        })
+        PcbScene3dStaticBodyFactory.buildMany(
+            THREE,
+            this.#placementSceneDescription.staticBodyPlacements
+        ).forEach((staticBody) => {
+            staticBodiesGroup.add(staticBody.rootGroup)
+            this.#registerSelectionRoot(
+                staticBody.placement?.designator,
+                staticBody.rootGroup
+            )
+            this.#componentAdjustmentRegistry.register(
+                staticBody.placement?.designator,
+                staticBody.adjustmentGroup
             )
         })
         this.#groups.set('fallback-bodies', fallbackBodiesGroup)
+        this.#groups.set('static-bodies', staticBodiesGroup)
         this.#groups.set('external-models', externalModelsGroup)
         this.#rootGroup.add(fallbackBodiesGroup)
+        this.#rootGroup.add(staticBodiesGroup)
         this.#rootGroup.add(externalModelsGroup)
         const boardSpan = Math.max(board.widthMil, board.heightMil, 1)
         this.#scene.fog = new THREE.Fog(
@@ -536,63 +582,6 @@ export class PcbScene3dRuntime {
         }
     }
 
-    /**
-     * Builds one procedural fallback body mesh.
-     * @param {{ positionMil: { x: number, y: number, z: number }, rotationDeg: number, mountSide: string, body: { family: string, sizeMil: { width: number, depth: number, height: number } } }} component
-     * @returns {any}
-     */
-    #buildFallbackBody(component) {
-        const THREE = this.#three
-        const family = component.body.family
-        const size = component.body.sizeMil
-        const material = new THREE.MeshStandardMaterial({
-            color: PcbScene3dBodyColor.resolve(family),
-            roughness: 0.72,
-            metalness: family === 'chip' ? 0.12 : 0.08
-        })
-
-        let mesh
-        if (family === 'radial-capacitor' || family === 'test-point') {
-            mesh = new THREE.Mesh(
-                new THREE.CylinderGeometry(
-                    size.width / 2,
-                    size.width / 2,
-                    size.height,
-                    28
-                ),
-                material
-            )
-        } else {
-            mesh = new THREE.Mesh(
-                new THREE.BoxGeometry(size.width, size.depth, size.height),
-                material
-            )
-        }
-
-        const mountRig = PcbScene3dMountRig.create(THREE, component)
-        const rootGroup = mountRig.rootGroup
-        const adjustmentGroup = new THREE.Group()
-
-        rootGroup.userData.scene3dSelection = {
-            designator: String(component?.designator || 'component'),
-            sourceType: 'component'
-        }
-        adjustmentGroup.userData.scene3dAdjustmentTarget = true
-        adjustmentGroup.userData.scene3dAdjustmentDesignator = String(
-            component?.designator || 'component'
-        )
-        adjustmentGroup.userData.scene3dAdjustmentBaseline =
-            PcbScene3dComponentAdjustment.neutral()
-        this.#registerSelectionRoot(component?.designator, rootGroup)
-        this.#componentAdjustmentRegistry.register(
-            component?.designator,
-            adjustmentGroup
-        )
-        adjustmentGroup.add(mesh)
-        mountRig.faceGroup.add(adjustmentGroup)
-        return rootGroup
-    }
-
     /**
      * Attempts to load any resolved external 3D models.
      * @returns {Promise<void>}
@@ -605,7 +594,7 @@ export class PcbScene3dRuntime {
 
         const diagnostics = await PcbScene3dExternalModels.loadIntoScene({
             three: this.#three,
-            sceneDescription: this.#sceneDescription,
+            sceneDescription: this.#placementSceneDescription,
             externalModelsGroup,
             modelViewScale: PcbScene3dRuntime.resolveViewScale(
                 this.#presetState.get(),
@@ -770,6 +759,7 @@ export class PcbScene3dRuntime {
         })
         PcbScene3dComponentVisibility.apply({
             selectionRoots: this.#selectionRoots,
+            selectedDesignator: this.#selectedDesignator,
             hiddenDesignators: this.#hiddenComponentDesignators,
             fallbackBodyRoots: this.#fallbackBodyRoots,
             loadedExternalModelDesignators:
@@ -891,6 +881,7 @@ export class PcbScene3dRuntime {
 
         const selectableRoots = [
             this.#groups.get('external-models'),
+            this.#groups.get('static-bodies'),
             this.#groups.get('fallback-bodies')
         ].filter((group) => group && group.visible !== false)
         const intersections = this.#raycaster.intersectObjects(

package/src/PcbScene3dStaticBodyFactory.mjs

@@ -0,0 +1,241 @@
+import { PcbScene3dComponentAdjustment } from './PcbScene3dComponentAdjustment.mjs'
+import { PcbScene3dMountRig } from './PcbScene3dMountRig.mjs'
+
+/**
+ * Builds authored static component-body render roots.
+ */
+export class PcbScene3dStaticBodyFactory {
+    static #DEFAULT_COLOR = 0x808080
+
+    /**
+     * Builds all renderable static body roots.
+     * @param {any} THREE Three.js namespace.
+     * @param {object[]} placements Static body placements.
+     * @returns {{ rootGroup: any, adjustmentGroup: any, placement: object }[]}
+     */
+    static buildMany(THREE, placements) {
+        return (Array.isArray(placements) ? placements : [])
+            .map((placement) =>
+                PcbScene3dStaticBodyFactory.build(THREE, placement)
+            )
+            .filter(Boolean)
+    }
+
+    /**
+     * Builds one authored static body root.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ designator?: string, mountSide?: string, rotationDeg?: number, positionMil?: { x?: number, y?: number, z?: number }, geometry?: object, bodyColor?: object, bodyOpacity?: number }} placement Static body placement.
+     * @returns {{ rootGroup: any, adjustmentGroup: any, placement: object } | null}
+     */
+    static build(THREE, placement) {
+        const geometry = PcbScene3dStaticBodyFactory.#buildGeometry(
+            THREE,
+            placement?.geometry
+        )
+        if (!geometry) {
+            return null
+        }
+
+        const material = new THREE.MeshStandardMaterial({
+            color: PcbScene3dStaticBodyFactory.#resolveColor(placement),
+            roughness: 0.7,
+            metalness: 0.08,
+            transparent:
+                PcbScene3dStaticBodyFactory.#resolveOpacity(placement) < 1,
+            opacity: PcbScene3dStaticBodyFactory.#resolveOpacity(placement)
+        })
+        const mesh = new THREE.Mesh(geometry, material)
+        const mountRig = PcbScene3dMountRig.create(THREE, placement)
+        const adjustmentGroup =
+            PcbScene3dStaticBodyFactory.#buildAdjustmentGroup(THREE, placement)
+
+        mountRig.rootGroup.userData.scene3dSelection = {
+            designator: String(placement?.designator || 'static-body'),
+            sourceType: 'static-body'
+        }
+        PcbScene3dStaticBodyFactory.#applyVariantMetadata(
+            mountRig.rootGroup,
+            placement
+        )
+        adjustmentGroup.add(mesh)
+        mountRig.faceGroup.add(adjustmentGroup)
+
+        return {
+            rootGroup: mountRig.rootGroup,
+            adjustmentGroup,
+            placement
+        }
+    }
+
+    /**
+     * Builds the geometry for one supported static body.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ kind?: string, verticesMil?: { x?: number, y?: number }[], heightMil?: number, radiusMil?: number }} geometry Static body geometry.
+     * @returns {any | null}
+     */
+    static #buildGeometry(THREE, geometry) {
+        const kind = String(geometry?.kind || '').toLowerCase()
+        if (kind === 'extruded-polygon') {
+            return PcbScene3dStaticBodyFactory.#buildExtrudedPolygon(
+                THREE,
+                geometry
+            )
+        }
+        if (kind === 'cylinder') {
+            return PcbScene3dStaticBodyFactory.#buildCylinder(THREE, geometry)
+        }
+        if (kind === 'cone') {
+            return PcbScene3dStaticBodyFactory.#buildCone(THREE, geometry)
+        }
+        if (kind === 'sphere') {
+            return PcbScene3dStaticBodyFactory.#buildSphere(THREE, geometry)
+        }
+
+        return null
+    }
+
+    /**
+     * Builds an extruded polygon geometry centered on its authored Z midpoint.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ verticesMil?: { x?: number, y?: number }[], heightMil?: number }} geometry Static body geometry.
+     * @returns {any | null}
+     */
+    static #buildExtrudedPolygon(THREE, geometry) {
+        const vertices = Array.isArray(geometry?.verticesMil)
+            ? geometry.verticesMil
+            : []
+        const heightMil = Number(geometry?.heightMil || 0)
+        if (vertices.length < 3 || !(heightMil > 0)) {
+            return null
+        }
+
+        const shape = new THREE.Shape()
+        shape.moveTo(Number(vertices[0].x || 0), Number(vertices[0].y || 0))
+        vertices.slice(1).forEach((vertex) => {
+            shape.lineTo(Number(vertex.x || 0), Number(vertex.y || 0))
+        })
+        shape.closePath()
+
+        const extrudedGeometry = new THREE.ExtrudeGeometry(shape, {
+            depth: heightMil,
+            bevelEnabled: false
+        })
+        extrudedGeometry.translate?.(0, 0, -heightMil / 2)
+        return extrudedGeometry
+    }
+
+    /**
+     * Builds a cylinder body geometry.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ radiusMil?: number, heightMil?: number }} geometry Static body geometry.
+     * @returns {any | null}
+     */
+    static #buildCylinder(THREE, geometry) {
+        const radiusMil = Number(geometry?.radiusMil || 0)
+        const heightMil = Number(geometry?.heightMil || 0)
+        if (!(radiusMil > 0) || !(heightMil > 0)) {
+            return null
+        }
+
+        return new THREE.CylinderGeometry(radiusMil, radiusMil, heightMil, 32)
+    }
+
+    /**
+     * Builds a cone body geometry.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ radiusMil?: number, heightMil?: number }} geometry Static body geometry.
+     * @returns {any | null}
+     */
+    static #buildCone(THREE, geometry) {
+        const radiusMil = Number(geometry?.radiusMil || 0)
+        const heightMil = Number(geometry?.heightMil || 0)
+        if (!(radiusMil > 0) || !(heightMil > 0)) {
+            return null
+        }
+
+        if (typeof THREE.ConeGeometry === 'function') {
+            return new THREE.ConeGeometry(radiusMil, heightMil, 32)
+        }
+
+        return new THREE.CylinderGeometry(0, radiusMil, heightMil, 32)
+    }
+
+    /**
+     * Builds a sphere body geometry.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ radiusMil?: number }} geometry Static body geometry.
+     * @returns {any | null}
+     */
+    static #buildSphere(THREE, geometry) {
+        const radiusMil = Number(geometry?.radiusMil || 0)
+        if (!(radiusMil > 0) || typeof THREE.SphereGeometry !== 'function') {
+            return null
+        }
+
+        return new THREE.SphereGeometry(radiusMil, 32, 16)
+    }
+
+    /**
+     * Builds the transform node used by live component adjustments.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ designator?: string }} placement Static body placement.
+     * @returns {any}
+     */
+    static #buildAdjustmentGroup(THREE, placement) {
+        const adjustmentGroup = new THREE.Group()
+        adjustmentGroup.userData.scene3dAdjustmentTarget = true
+        adjustmentGroup.userData.scene3dAdjustmentDesignator = String(
+            placement?.designator || 'static-body'
+        )
+        adjustmentGroup.userData.scene3dAdjustmentBaseline =
+            PcbScene3dComponentAdjustment.neutral()
+        return adjustmentGroup
+    }
+
+    /**
+     * Copies authored variant grouping metadata onto the selectable root.
+     * @param {any} rootGroup Static body root group.
+     * @param {{ coLocatedVariantGroupKey?: string }} placement Static body placement.
+     * @returns {void}
+     */
+    static #applyVariantMetadata(rootGroup, placement) {
+        const groupKey = String(
+            placement?.coLocatedVariantGroupKey || ''
+        ).trim()
+        if (groupKey) {
+            rootGroup.userData.scene3dVariantGroupKey = groupKey
+        }
+    }
+
+    /**
+     * Resolves static body display color.
+     * @param {{ bodyColor?: object, geometry?: object }} placement Static body placement.
+     * @returns {number}
+     */
+    static #resolveColor(placement) {
+        const rawColor = Number(
+            placement?.bodyColor?.raw ??
+                placement?.geometry?.bodyColor?.raw ??
+                placement?.geometry?.color
+        )
+        return Number.isInteger(rawColor)
+            ? rawColor
+            : PcbScene3dStaticBodyFactory.#DEFAULT_COLOR
+    }
+
+    /**
+     * Resolves static body opacity.
+     * @param {{ bodyOpacity?: number, geometry?: object }} placement Static body placement.
+     * @returns {number}
+     */
+    static #resolveOpacity(placement) {
+        const opacity = Number(
+            placement?.bodyOpacity ?? placement?.geometry?.bodyOpacity
+        )
+        if (!Number.isFinite(opacity)) {
+            return 1
+        }
+
+        return Math.min(1, Math.max(0, opacity))
+    }
+}