pcb-scene3d-viewer 1.1.44 → 1.1.48

package/src/PcbAssemblyGltfWriter.mjs

@@ -1,4 +1,6 @@
 import { PcbAssemblyExportCoordinateFrame } from './PcbAssemblyExportCoordinateFrame.mjs'
+import { PcbAssemblyGltfImageDataUri } from './PcbAssemblyGltfImageDataUri.mjs'
+import { PcbAssemblyGltfSceneCamera } from './PcbAssemblyGltfSceneCamera.mjs'
 import { PcbAssemblyPolygonTriangulator } from './PcbAssemblyPolygonTriangulator.mjs'
 
 const FLOAT_COMPONENT = 5126
@@ -17,7 +19,7 @@ const BIN_CHUNK_TYPE = 0x004e4942
 export class PcbAssemblyGltfWriter {
     /**
      * Writes a GLTF or GLB assembly document.
-     * @param {{ name?: string, meshes?: object[], format?: string, binary?: boolean, includeSceneMetadata?: boolean }} assembly Assembly data.
+     * @param {{ name?: string, meshes?: object[], format?: string, binary?: boolean, includeSceneMetadata?: boolean, sceneCameraPreset?: string, sceneCameraAspectRatio?: number, sceneCameraFovDegrees?: number }} assembly Assembly data.
      * @returns {object | Uint8Array}
      */
     static write(assembly = {}) {
@@ -32,7 +34,7 @@ export class PcbAssemblyGltfWriter {
 
     /**
      * Builds the GLTF JSON tree and shared binary buffer.
-     * @param {{ name?: string, meshes?: object[], includeSceneMetadata?: boolean }} assembly Assembly data.
+     * @param {{ name?: string, meshes?: object[], includeSceneMetadata?: boolean, sceneCameraPreset?: string, sceneCameraAspectRatio?: number, sceneCameraFovDegrees?: number }} assembly Assembly data.
      * @param {boolean} binary Whether the document will be embedded in GLB.
      * @returns {{ gltf: object, buffer: Uint8Array }}
      */
@@ -46,7 +48,22 @@ export class PcbAssemblyGltfWriter {
             PcbAssemblyGltfWriter.#appendMesh(state, mesh)
         })
         if (assembly?.includeSceneMetadata === true) {
-            PcbAssemblyGltfWriter.#appendSceneMetadata(state, sourceMeshes)
+            PcbAssemblyGltfWriter.#appendSceneMetadata(
+                state,
+                sourceMeshes,
+                assembly
+            )
+        }
+        if (binary) {
+            state.images = PcbAssemblyGltfImageDataUri.pack(
+                state.images,
+                (bytes) =>
+                    PcbAssemblyGltfWriter.#appendBufferView(
+                        state,
+                        bytes,
+                        undefined
+                    )
+            )
         }
 
         const buffer = PcbAssemblyGltfWriter.#concatBuffer(state.bufferParts)
@@ -136,41 +153,23 @@ export class PcbAssemblyGltfWriter {
      * Appends default camera and light nodes from scene bounds.
      * @param {object} state Writer state.
      * @param {object[]} meshes Source meshes.
+     * @param {{ sceneCameraPreset?: string, sceneCameraAspectRatio?: number, sceneCameraFovDegrees?: number }} options Scene metadata options.
      * @returns {void}
      */
-    static #appendSceneMetadata(state, meshes) {
+    static #appendSceneMetadata(state, meshes, options) {
         const bounds = PcbAssemblyGltfWriter.#sceneBounds(meshes)
-        const center = [
-            (bounds.min[0] + bounds.max[0]) / 2,
-            (bounds.min[1] + bounds.max[1]) / 2,
-            (bounds.min[2] + bounds.max[2]) / 2
-        ]
-        const span = Math.max(
-            bounds.max[0] - bounds.min[0],
-            bounds.max[1] - bounds.min[1],
-            bounds.max[2] - bounds.min[2],
-            1
-        )
-        const distance = span * 2.2
+        const camera = PcbAssemblyGltfSceneCamera.resolve(bounds, options)
         const cameraIndex = state.cameras.length
         state.cameras.push({
             name: 'Default Camera',
             type: 'perspective',
-            perspective: {
-                yfov: 0.7,
-                znear: Math.max(distance / 1000, 0.01),
-                zfar: distance * 10
-            }
+            perspective: camera.perspective
         })
         state.nodes.push({
             name: 'Default Camera',
             camera: cameraIndex,
-            translation: [
-                center[0] + distance * 0.65,
-                center[1] + distance * 0.45,
-                center[2] + distance
-            ],
-            rotation: [-0.260009, 0.279848, 0.076342, 0.920364]
+            translation: camera.position,
+            rotation: camera.rotation
         })
 
         const lightIndex = state.lights.length
@@ -182,9 +181,9 @@ export class PcbAssemblyGltfWriter {
         state.nodes.push({
             name: 'Key Light',
             translation: [
-                center[0] - distance * 0.35,
-                center[1] + distance,
-                center[2] + distance
+                camera.center[0] - camera.distance * 0.35,
+                camera.center[1] + camera.distance,
+                camera.center[2] + camera.distance
             ],
             extensions: {
                 KHR_lights_punctual: {
@@ -513,7 +512,7 @@ export class PcbAssemblyGltfWriter {
      * Adds one aligned buffer view to the document.
      * @param {object} state Writer state.
      * @param {Uint8Array} bytes Binary data.
-     * @param {number} target Buffer target.
+     * @param {number | undefined} target Buffer target.
      * @returns {number}
      */
     static #appendBufferView(state, bytes, target) {
@@ -526,8 +525,10 @@ export class PcbAssemblyGltfWriter {
         const bufferView = {
             buffer: 0,
             byteOffset: state.byteLength,
-            byteLength: bytes.byteLength,
-            target
+            byteLength: bytes.byteLength
+        }
+        if (Number.isInteger(target)) {
+            bufferView.target = target
         }
         state.bufferViews.push(bufferView)
         state.bufferParts.push(bytes)

package/src/PcbScene3dBoardAssemblyPresentation.mjs

@@ -19,9 +19,10 @@ export class PcbScene3dBoardAssemblyPresentation {
      * PCB-derived substrate, copper, and silkscreen remain the visual source.
      * @param {any} modelGroup Loaded board assembly group.
      * @param {{ widthMil?: number, heightMil?: number, thicknessMil?: number } | null | undefined} board Board dimensions.
+     * @param {{ sourceFormat?: string }} [options] Presentation options.
      * @returns {void}
      */
-    static apply(modelGroup, board) {
+    static apply(modelGroup, board, options = {}) {
         const meshRecords =
             PcbScene3dBoardAssemblyPresentation.#collectMeshRecords(modelGroup)
         const boardBounds =
@@ -30,7 +31,10 @@ export class PcbScene3dBoardAssemblyPresentation {
                 board
             )
         const surfaceColor =
-            PcbScene3dBoardAssemblyPresentation.#resolveSurfaceColor(board)
+            PcbScene3dBoardAssemblyPresentation.#resolveSurfaceColor(
+                board,
+                options
+            )
         const edgeColor =
             PcbScene3dBoardAssemblyPresentation.#resolveEdgeColor(board)
         const importedSurfaceColor =
@@ -412,11 +416,13 @@ export class PcbScene3dBoardAssemblyPresentation {
     /**
      * Resolves the app-level substrate color for board assembly meshes.
      * @param {{ surfaceColor?: number } | null | undefined} board Board dimensions.
+     * @param {{ sourceFormat?: string }} options Presentation options.
      * @returns {number}
      */
-    static #resolveSurfaceColor(board) {
+    static #resolveSurfaceColor(board, options) {
         return PcbScene3dBoardMaterialPalette.resolveSurfaceColor(board, {
-            hasBoardAssemblyModel: true
+            hasBoardAssemblyModel: true,
+            sourceFormat: options?.sourceFormat
         })
     }
 

package/src/PcbScene3dBoardCutoutPathFactory.mjs

@@ -0,0 +1,83 @@
+/**
+ * Builds normalized Three.js paths for explicit board cutouts.
+ */
+export class PcbScene3dBoardCutoutPathFactory {
+    /**
+     * Resolves explicit board cutout paths.
+     * @param {any} THREE Three.js namespace.
+     * @param {{ cutouts?: any[] }} board Board metadata.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @returns {{ path: any, points: { x: number, y: number }[] }[]}
+     */
+    static resolve(THREE, board, normalizeBoardPoint) {
+        return (Array.isArray(board?.cutouts) ? board.cutouts : [])
+            .map((cutout) =>
+                PcbScene3dBoardCutoutPathFactory.#buildPath(
+                    THREE,
+                    cutout,
+                    normalizeBoardPoint
+                )
+            )
+            .filter(Boolean)
+    }
+
+    /**
+     * Builds one explicit board cutout path.
+     * @param {any} THREE Three.js namespace.
+     * @param {any} cutout Source cutout.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @returns {{ path: any, points: { x: number, y: number }[] } | null}
+     */
+    static #buildPath(THREE, cutout, normalizeBoardPoint) {
+        const points = PcbScene3dBoardCutoutPathFactory.#sourcePoints(cutout)
+            .map((point) =>
+                PcbScene3dBoardCutoutPathFactory.#normalizePoint(
+                    point,
+                    normalizeBoardPoint
+                )
+            )
+            .filter(Boolean)
+
+        if (points.length < 3) {
+            return null
+        }
+
+        const path = new THREE.Path()
+        path.moveTo(points[0].x, points[0].y)
+        for (let index = 1; index < points.length; index += 1) {
+            path.lineTo(points[index].x, points[index].y)
+        }
+        path.closePath()
+
+        return { path, points }
+    }
+
+    /**
+     * Resolves one cutout's point list.
+     * @param {any} cutout Source cutout.
+     * @returns {any[]}
+     */
+    static #sourcePoints(cutout) {
+        if (Array.isArray(cutout?.points)) {
+            return cutout.points
+        }
+
+        if (Array.isArray(cutout?.vertices)) {
+            return cutout.vertices
+        }
+
+        return Array.isArray(cutout) ? cutout : []
+    }
+
+    /**
+     * Normalizes one source point into local board shape coordinates.
+     * @param {any} point Source point.
+     * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
+     * @returns {{ x: number, y: number } | null}
+     */
+    static #normalizePoint(point, normalizeBoardPoint) {
+        const x = Number(point?.x ?? point?.[0])
+        const y = Number(point?.y ?? point?.[1])
+        return Number.isFinite(x + y) ? normalizeBoardPoint(x, y) : null
+    }
+}

package/src/PcbScene3dBoardMaterialPalette.mjs

@@ -7,11 +7,16 @@ export class PcbScene3dBoardMaterialPalette {
     /**
      * Resolves the solder-mask face color for the generated board shell.
      * @param {{ surfaceColor?: number } | undefined} board Board metadata.
-     * @param {{ hasBoardAssemblyModel?: boolean }} [options] Scene options.
+     * @param {{ hasBoardAssemblyModel?: boolean, sourceFormat?: string }} [options] Scene options.
      * @returns {number}
      */
     static resolveSurfaceColor(board, options = {}) {
-        if (options.hasBoardAssemblyModel) {
+        if (
+            options.hasBoardAssemblyModel &&
+            !PcbScene3dBoardMaterialPalette.#shouldPreserveAuthoredSurfaceColor(
+                options
+            )
+        ) {
             return PcbScene3dBoardMaterialPalette.#DEFAULT_SURFACE_COLOR
         }
 
@@ -20,6 +25,16 @@ export class PcbScene3dBoardMaterialPalette {
             : PcbScene3dBoardMaterialPalette.#DEFAULT_SURFACE_COLOR
     }
 
+    /**
+     * Returns true when the source format supplies display-stable board colors.
+     * @param {{ sourceFormat?: string }} options Scene options.
+     * @returns {boolean}
+     */
+    static #shouldPreserveAuthoredSurfaceColor(options) {
+        const sourceFormat = String(options?.sourceFormat || '').toLowerCase()
+        return sourceFormat === 'altium' || sourceFormat.startsWith('altium-')
+    }
+
     /**
      * Resolves whether the generated board face should render.
      * @param {{ hasBoardAssemblyModel?: boolean }} [options] Scene options.

package/src/PcbScene3dBoardShapeFactory.mjs

@@ -1,4 +1,5 @@
 import { PcbScene3dBoardEdgeCutoutBuilder } from './PcbScene3dBoardEdgeCutoutBuilder.mjs'
+import { PcbScene3dBoardCutoutPathFactory } from './PcbScene3dBoardCutoutPathFactory.mjs'
 import { PcbScene3dDrillPathFactory } from './PcbScene3dDrillPathFactory.mjs'
 import { PcbScene3dOutlineBuilder } from './PcbScene3dOutlineBuilder.mjs'
 
@@ -36,6 +37,11 @@ export class PcbScene3dBoardShapeFactory {
         )
         const contourPoints =
             PcbScene3dBoardEdgeCutoutBuilder.resolveShapePoints(baseShape)
+        const boardCutouts = PcbScene3dBoardCutoutPathFactory.resolve(
+            THREE,
+            board,
+            normalizeBoardPoint
+        )
         const drillCutouts = PcbScene3dBoardShapeFactory.#resolveDrillCutouts(
             THREE,
             detail,
@@ -61,12 +67,20 @@ export class PcbScene3dBoardShapeFactory {
         const finalContourPoints = edgeCutouts.length
             ? PcbScene3dBoardEdgeCutoutBuilder.resolveShapePoints(shape)
             : contourPoints
-
+        for (const cutout of boardCutouts) {
+            if (
+                PcbScene3dBoardEdgeCutoutBuilder.isHoleInsideContour(
+                    cutout.points,
+                    finalContourPoints
+                )
+            ) {
+                shape.holes.push(cutout.path)
+            }
+        }
         for (const cutout of drillCutouts) {
             if (edgeCutouts.includes(cutout)) {
                 continue
             }
-
             if (
                 !cutout.isCircular ||
                 PcbScene3dBoardEdgeCutoutBuilder.isHoleInsideContour(
@@ -77,7 +91,6 @@ export class PcbScene3dBoardShapeFactory {
                 shape.holes.push(cutout.path)
             }
         }
-
         return shape
     }
 

package/src/PcbScene3dBoardSolderMaskFactory.mjs

@@ -1,4 +1,5 @@
 import { PcbScene3dBoardMaterialPalette } from './PcbScene3dBoardMaterialPalette.mjs'
+import { PcbScene3dBoardCutoutPathFactory } from './PcbScene3dBoardCutoutPathFactory.mjs'
 import { PcbScene3dCutoutGeometryFilter } from './PcbScene3dCutoutGeometryFilter.mjs'
 import { PcbScene3dDrillPathFactory } from './PcbScene3dDrillPathFactory.mjs'
 import { PcbScene3dMaterialFinish } from './PcbScene3dMaterialFinish.mjs'
@@ -51,12 +52,14 @@ export class PcbScene3dBoardSolderMaskFactory {
         const topMaterial = PcbScene3dBoardSolderMaskFactory.#buildMaterial(
             THREE,
             board,
-            THREE.FrontSide
+            THREE.FrontSide,
+            sceneDescription?.sourceFormat
         )
         const bottomMaterial = PcbScene3dBoardSolderMaskFactory.#buildMaterial(
             THREE,
             board,
-            THREE.BackSide
+            THREE.BackSide,
+            sceneDescription?.sourceFormat
         )
         const z = Number(board?.thicknessMil || 0) / 2
 
@@ -148,6 +151,11 @@ export class PcbScene3dBoardSolderMaskFactory {
         )
         const contourPoints =
             PcbScene3dBoardSolderMaskFactory.#resolveShapePoints(shape)
+        const boardCutouts = PcbScene3dBoardCutoutPathFactory.resolve(
+            THREE,
+            board,
+            normalizeBoardPoint
+        )
         const drillCutouts =
             PcbScene3dBoardSolderMaskFactory.#resolveDrillCutouts(
                 THREE,
@@ -155,8 +163,8 @@ export class PcbScene3dBoardSolderMaskFactory {
                 normalizeBoardPoint
             )
         const { shapeHoles, clippingCutouts } =
-            PcbScene3dBoardSolderMaskFactory.#partitionDrillCutouts(
-                drillCutouts,
+            PcbScene3dBoardSolderMaskFactory.#partitionCutouts(
+                [...boardCutouts, ...drillCutouts],
                 contourPoints
             )
 
@@ -395,16 +403,16 @@ export class PcbScene3dBoardSolderMaskFactory {
     }
 
     /**
-     * Splits drill cutouts into safe shape holes and fallback clip polygons.
-     * @param {{ path: any, points: { x: number, y: number }[] }[]} drillCutouts
+     * Splits cutouts into safe shape holes and fallback clip polygons.
+     * @param {{ path: any, points: { x: number, y: number }[] }[]} cutouts
      * @param {{ x: number, y: number }[]} contourPoints
      * @returns {{ shapeHoles: { path: any, points: { x: number, y: number }[] }[], clippingCutouts: { path: any, points: { x: number, y: number }[] }[] }}
      */
-    static #partitionDrillCutouts(drillCutouts, contourPoints) {
+    static #partitionCutouts(cutouts, contourPoints) {
         const shapeHoles = []
         const clippingCutouts = []
 
-        for (const cutout of Array.isArray(drillCutouts) ? drillCutouts : []) {
+        for (const cutout of Array.isArray(cutouts) ? cutouts : []) {
             if (
                 PcbScene3dBoardSolderMaskFactory.#isHoleInsideContour(
                     cutout.points,
@@ -596,12 +604,14 @@ export class PcbScene3dBoardSolderMaskFactory {
      * @param {any} THREE
      * @param {{ surfaceColor?: number }} board Board metadata.
      * @param {number} side Rendered material side.
+     * @param {string | undefined} sourceFormat Scene source format.
      * @returns {any}
      */
-    static #buildMaterial(THREE, board, side) {
+    static #buildMaterial(THREE, board, side, sourceFormat) {
         return new THREE.MeshStandardMaterial({
             color: PcbScene3dBoardMaterialPalette.resolveSurfaceColor(board, {
-                hasBoardAssemblyModel: true
+                hasBoardAssemblyModel: true,
+                sourceFormat
             }),
             ...PcbScene3dMaterialFinish.semiMatteSolderMaskProperties(),
             polygonOffset: true,

package/src/PcbScene3dCompanionBasePlacementAdjuster.mjs

@@ -74,6 +74,14 @@ export class PcbScene3dCompanionBasePlacementAdjuster {
             return null
         }
 
+        if (
+            PcbScene3dCompanionBasePlacementAdjuster.#isBottomSide(
+                component?.mountSide
+            )
+        ) {
+            return null
+        }
+
         return {
             designator: String(component?.designator || '').trim(),
             mountSide: String(component?.mountSide || 'top').toLowerCase(),

package/src/PcbScene3dController.mjs

@@ -1,6 +1,7 @@
 import { PcbModelArchiveExporter } from './PcbModelArchiveExporter.mjs'
 import { PcbScene3dAdjustmentControlBinder } from './PcbScene3dAdjustmentControlBinder.mjs'
 import { PcbScene3dCircuitJsonAdapter } from './PcbScene3dCircuitJsonAdapter.mjs'
+import { PcbScene3dExternalPlacementDefaults } from './PcbScene3dExternalPlacementDefaults.mjs'
 import { PcbScene3dInteractionHints } from './PcbScene3dInteractionHints.mjs'
 import { PcbScene3dRuntime } from './PcbScene3dRuntime.mjs'
 import { PcbScene3dSelectionInspectorRenderer } from './PcbScene3dSelectionInspectorRenderer.mjs'
@@ -473,6 +474,7 @@ export class PcbScene3dController {
                 this.#handleRuntimeSelection(selection),
             translate: this.#translate
         })
+        this.#applyInitialToggles()
         if (!this.#autoSearchMissingModels) {
             this.#runtime?.setToggle?.('model-search-models', false)
         }
@@ -561,6 +563,25 @@ export class PcbScene3dController {
         })
     }
 
+    /**
+     * Synchronizes runtime visibility with the shell's initial checkbox state.
+     * @returns {void}
+     */
+    #applyInitialToggles() {
+        const toggles =
+            this.#rootNode?.querySelectorAll('[data-scene-3d-toggle]') || []
+
+        toggles.forEach((toggle) => {
+            const toggleName =
+                toggle?.getAttribute?.('data-scene-3d-toggle') || ''
+            if (!toggleName) {
+                return
+            }
+
+            this.#runtime?.setToggle?.(toggleName, Boolean(toggle.checked))
+        })
+    }
+
     /**
      * Binds the model archive export action.
      * @returns {void}
@@ -903,11 +924,14 @@ export class PcbScene3dController {
      * @returns {any}
      */
     static #normalizeSceneDescription(sceneDescription) {
-        return PcbScene3dCircuitJsonAdapter.isDirectCircuitJsonModel(
-            sceneDescription
-        )
-            ? PcbScene3dCircuitJsonAdapter.build(sceneDescription)
-            : sceneDescription
+        const normalizedScene =
+            PcbScene3dCircuitJsonAdapter.isDirectCircuitJsonModel(
+                sceneDescription
+            )
+                ? PcbScene3dCircuitJsonAdapter.build(sceneDescription)
+                : sceneDescription
+
+        return PcbScene3dExternalPlacementDefaults.apply(normalizedScene)
     }
 
     /**

package/src/PcbScene3dCopperDetailGroupBuilder.mjs

@@ -25,9 +25,14 @@ export class PcbScene3dCopperDetailGroupBuilder {
      */
     static build(THREE, sceneDescription, topZ, normalizePoint) {
         const group = new THREE.Group()
-        const drillCutouts = PcbScene3dCopperDrillCutoutBuilder.resolve(
-            sceneDescription?.detail
-        )
+        const drillCutouts = [
+            ...PcbScene3dCopperDrillCutoutBuilder.resolve(
+                sceneDescription?.detail
+            ),
+            ...PcbScene3dCopperDetailGroupBuilder.#resolveBoardCutouts(
+                sceneDescription?.board
+            )
+        ]
         const coveredGroup =
             PcbScene3dCopperDetailGroupBuilder.#buildCoveredGroup(
                 THREE,
@@ -187,6 +192,43 @@ export class PcbScene3dCopperDetailGroupBuilder {
         )
     }
 
+    /**
+     * Resolves explicit through-board cutouts that copper detail must not cover.
+     * @param {{ cutouts?: any[] } | undefined} board Board metadata.
+     * @returns {{ x: number, y: number }[][]}
+     */
+    static #resolveBoardCutouts(board) {
+        return (Array.isArray(board?.cutouts) ? board.cutouts : [])
+            .map((cutout) =>
+                PcbScene3dCopperDetailGroupBuilder.#resolveBoardCutoutPoints(
+                    cutout
+                )
+            )
+            .filter((points) => points.length >= 3)
+    }
+
+    /**
+     * Resolves one explicit board cutout loop in source board coordinates.
+     * @param {any} cutout Cutout source.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #resolveBoardCutoutPoints(cutout) {
+        const points = Array.isArray(cutout?.points)
+            ? cutout.points
+            : Array.isArray(cutout?.vertices)
+              ? cutout.vertices
+              : Array.isArray(cutout)
+                ? cutout
+                : []
+
+        return points
+            .map((point) => ({
+                x: Number(point?.x ?? point?.[0]),
+                y: Number(point?.y ?? point?.[1])
+            }))
+            .filter((point) => Number.isFinite(point.x + point.y))
+    }
+
     /**
      * Resolves solder-mask material options for covered copper relief.
      * @param {object} sceneDescription Scene description.
@@ -199,7 +241,8 @@ export class PcbScene3dCopperDetailGroupBuilder {
                 {
                     hasBoardAssemblyModel: Boolean(
                         sceneDescription?.boardAssemblyModel
-                    )
+                    ),
+                    sourceFormat: sceneDescription?.sourceFormat
                 }
             )
         }