pcb-scene3d-viewer 1.1.49 → 1.2.0

package/src/PcbScene3dFacetedModelGroupBuilder.mjs

@@ -0,0 +1,217 @@
+import { PcbScene3dBufferAttributeFactory } from './PcbScene3dBufferAttributeFactory.mjs'
+
+/**
+ * Converts normalized faceted assembly meshes into live Three.js groups.
+ */
+export class PcbScene3dFacetedModelGroupBuilder {
+    /**
+     * Builds a Three.js group from normalized mesh rows.
+     * @param {any} THREE Three.js namespace.
+     * @param {object[]} meshes Normalized faceted meshes.
+     * @returns {any}
+     */
+    static build(THREE, meshes) {
+        const group = new THREE.Group()
+        for (const mesh of Array.isArray(meshes) ? meshes : []) {
+            const threeMesh = PcbScene3dFacetedModelGroupBuilder.#buildMesh(
+                THREE,
+                mesh
+            )
+            if (threeMesh) group.add(threeMesh)
+        }
+        if (!group.children.length) {
+            throw new Error('External model contains no renderable meshes.')
+        }
+        return group
+    }
+
+    /**
+     * Builds one Three.js mesh from normalized vertices and faces.
+     * @param {any} THREE Three.js namespace.
+     * @param {object} mesh Normalized faceted mesh.
+     * @returns {any | null}
+     */
+    static #buildMesh(THREE, mesh) {
+        const vertices = Array.isArray(mesh?.vertices) ? mesh.vertices : []
+        const indices = PcbScene3dFacetedModelGroupBuilder.#indices(mesh?.faces)
+        if (!vertices.length || !indices.length) return null
+
+        const geometry = new THREE.BufferGeometry()
+        geometry.setAttribute(
+            'position',
+            PcbScene3dBufferAttributeFactory.createFloat32(
+                THREE,
+                vertices.flatMap((vertex) => [
+                    Number(vertex?.[0] || 0),
+                    Number(vertex?.[1] || 0),
+                    Number(vertex?.[2] || 0)
+                ]),
+                3
+            )
+        )
+        geometry.setIndex(
+            PcbScene3dBufferAttributeFactory.createUint32(THREE, indices, 1)
+        )
+        const colorAttribute = PcbScene3dFacetedModelGroupBuilder.#vertexColors(
+            mesh,
+            vertices
+        )
+        if (colorAttribute.values.length) {
+            geometry.setAttribute(
+                'color',
+                PcbScene3dBufferAttributeFactory.createFloat32(
+                    THREE,
+                    colorAttribute.values,
+                    colorAttribute.itemSize
+                )
+            )
+        }
+        geometry.computeVertexNormals()
+        geometry.computeBoundingSphere()
+
+        const result = new THREE.Mesh(
+            geometry,
+            PcbScene3dFacetedModelGroupBuilder.#material(
+                THREE,
+                mesh,
+                colorAttribute
+            )
+        )
+        result.name = String(mesh?.name || '')
+        return result
+    }
+
+    /**
+     * Triangulates polygon faces into a packed index array.
+     * @param {unknown} faces Polygon face rows.
+     * @returns {number[]}
+     */
+    static #indices(faces) {
+        const indices = []
+        for (const face of Array.isArray(faces) ? faces : []) {
+            if (!Array.isArray(face) || face.length < 3) continue
+            const first = Number(face[0])
+            for (let index = 1; index + 1 < face.length; index += 1) {
+                indices.push(
+                    first,
+                    Number(face[index]),
+                    Number(face[index + 1])
+                )
+            }
+        }
+        return indices.filter((index) => Number.isInteger(index) && index >= 0)
+    }
+
+    /**
+     * Flattens optional RGB or RGBA vertex colors into RGB attributes.
+     * @param {object} mesh Normalized faceted mesh.
+     * @param {unknown[]} vertices Mesh vertices.
+     * @returns {{ values: number[], itemSize: number, transparent: boolean }}
+     */
+    static #vertexColors(mesh, vertices) {
+        if (!Array.isArray(mesh?.vertexColors)) {
+            return { values: [], itemSize: 3, transparent: false }
+        }
+        const fallback = PcbScene3dFacetedModelGroupBuilder.#color(mesh)
+        const itemSize = mesh.vertexColors.some(
+            (color) => Array.isArray(color) && color.length >= 4
+        )
+            ? 4
+            : 3
+        let transparent = false
+        const values = vertices.flatMap((_vertex, index) => {
+            const color = mesh.vertexColors[index]
+            const channels = [0, 1, 2].map((channel) =>
+                PcbScene3dFacetedModelGroupBuilder.#unit(
+                    color?.[channel],
+                    fallback[channel]
+                )
+            )
+            if (itemSize === 4) {
+                const alpha = PcbScene3dFacetedModelGroupBuilder.#unit(
+                    color?.[3],
+                    1
+                )
+                transparent ||= alpha < 1
+                channels.push(alpha)
+            }
+            return channels
+        })
+        return { values, itemSize, transparent }
+    }
+
+    /**
+     * Creates a color- and opacity-preserving Three.js material.
+     * @param {any} THREE Three.js namespace.
+     * @param {object} mesh Normalized faceted mesh.
+     * @param {{ values: number[], transparent: boolean }} colorAttribute Vertex-color metadata.
+     * @returns {any}
+     */
+    static #material(THREE, mesh, colorAttribute) {
+        const color = PcbScene3dFacetedModelGroupBuilder.#color(mesh)
+        const opacity = PcbScene3dFacetedModelGroupBuilder.#opacity(mesh)
+        const options = {
+            color: new THREE.Color(color[0], color[1], color[2]),
+            opacity,
+            transparent: opacity < 1 || colorAttribute.transparent,
+            vertexColors: colorAttribute.values.length > 0
+        }
+        if (THREE.DoubleSide !== undefined) options.side = THREE.DoubleSide
+
+        const source = mesh?.material || {}
+        if (THREE.MeshPhongMaterial && Array.isArray(source.specularColor)) {
+            options.specular = new THREE.Color(
+                Number(source.specularColor[0] || 0),
+                Number(source.specularColor[1] || 0),
+                Number(source.specularColor[2] || 0)
+            )
+            options.shininess = Number(source.shininess || 30)
+            return new THREE.MeshPhongMaterial(options)
+        }
+        return new THREE.MeshStandardMaterial({
+            ...options,
+            roughness: 0.56,
+            metalness: 0.14
+        })
+    }
+
+    /**
+     * Resolves one normalized base color.
+     * @param {object} mesh Normalized faceted mesh.
+     * @returns {number[]}
+     */
+    static #color(mesh) {
+        const color = Array.isArray(mesh?.color)
+            ? mesh.color
+            : [0.78, 0.78, 0.78]
+        return [0, 1, 2].map((index) =>
+            PcbScene3dFacetedModelGroupBuilder.#unit(color[index], 0.78)
+        )
+    }
+
+    /**
+     * Resolves normalized material opacity.
+     * @param {object} mesh Normalized faceted mesh.
+     * @returns {number}
+     */
+    static #opacity(mesh) {
+        const colorAlpha = Array.isArray(mesh?.color) ? mesh.color[3] : null
+        return PcbScene3dFacetedModelGroupBuilder.#unit(
+            colorAlpha ?? mesh?.material?.alpha,
+            1
+        )
+    }
+
+    /**
+     * Clamps one material channel into the unit interval.
+     * @param {unknown} value Channel value.
+     * @param {number} fallback Fallback channel value.
+     * @returns {number}
+     */
+    static #unit(value, fallback) {
+        const number = Number(value)
+        return Number.isFinite(number)
+            ? Math.min(Math.max(number, 0), 1)
+            : fallback
+    }
+}

package/src/PcbScene3dGeometryZCompressor.mjs

@@ -9,7 +9,7 @@ export class PcbScene3dGeometryZCompressor {
      * Rewrites mask-covered copper relief below exposed copper height.
      * @param {any | null} mesh Mesh with a position attribute.
      * @param {number} sourceCenterZ Original geometry center Z.
-     * @param {{ centerOffsetMil?: number }} [options] Compression options.
+     * @param {{ centerOffsetMil?: number, thicknessMil?: number }} [options] Compression options.
      * @returns {void}
      */
     static compressMaskCoveredCopperMesh(mesh, sourceCenterZ, options = {}) {
@@ -19,7 +19,9 @@ export class PcbScene3dGeometryZCompressor {
             sourceCenterZ +
                 MASK_COVERED_CENTER_OFFSET_MIL +
                 Number(options?.centerOffsetMil || 0),
-            MASK_COVERED_THICKNESS_MIL
+            Number.isFinite(Number(options?.thicknessMil))
+                ? Math.max(Number(options.thicknessMil), 0)
+                : MASK_COVERED_THICKNESS_MIL
         )
     }
 

package/src/PcbScene3dMaskCoveredCopperSideGroupBuilder.mjs

@@ -10,7 +10,8 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
     static #TRACK_COPPER_BLEND = 0.7
     static #FILL_RENDER_ORDER = 10
     static #TRACK_RENDER_ORDER = 12
-    static #TRACK_CENTER_OFFSET_MIL = 0.16
+    static #TRACK_CENTER_OFFSET_MIL = 0.25
+    static #TRACK_THICKNESS_MIL = 1.05
 
     /**
      * Builds one side group from prepared mask-covered copper meshes.
@@ -39,6 +40,10 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
                 centerOffsetMil:
                     PcbScene3dMaskCoveredCopperSideGroupBuilder
                         .#TRACK_CENTER_OFFSET_MIL,
+                thicknessMil:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#TRACK_THICKNESS_MIL,
+                keepSideWalls: true,
                 copperBlend:
                     PcbScene3dMaskCoveredCopperSideGroupBuilder
                         .#TRACK_COPPER_BLEND,
@@ -56,6 +61,10 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
                 centerOffsetMil:
                     PcbScene3dMaskCoveredCopperSideGroupBuilder
                         .#TRACK_CENTER_OFFSET_MIL,
+                thicknessMil:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#TRACK_THICKNESS_MIL,
+                keepSideWalls: true,
                 copperBlend:
                     PcbScene3dMaskCoveredCopperSideGroupBuilder
                         .#TRACK_COPPER_BLEND,
@@ -92,7 +101,7 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
      * @param {any | null} mesh Mesh to add.
      * @param {string} name Scene object name.
      * @param {number} z Source center Z.
-     * @param {{ centerOffsetMil?: number, copperBlend?: number, renderOrder?: number }} [options] Presentation options.
+     * @param {{ centerOffsetMil?: number, thicknessMil?: number, keepSideWalls?: boolean, copperBlend?: number, renderOrder?: number }} [options] Presentation options.
      * @returns {void}
      */
     static #addCompressedMesh(group, mesh, name, z, options = {}) {
@@ -100,9 +109,14 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
             return
         }
         PcbScene3dGeometryZCompressor.compressMaskCoveredCopperMesh(mesh, z, {
-            centerOffsetMil: options.centerOffsetMil
+            centerOffsetMil: options.centerOffsetMil,
+            thicknessMil: options.thicknessMil
         })
-        PcbScene3dMaskCoveredCopperSurfaceFilter.keepOuterSurface(mesh)
+        if (options.keepSideWalls === true) {
+            PcbScene3dMaskCoveredCopperSurfaceFilter.keepOuterRelief(mesh)
+        } else {
+            PcbScene3dMaskCoveredCopperSurfaceFilter.keepOuterSurface(mesh)
+        }
         mesh.name = name
         mesh.renderOrder = Number(options.renderOrder || 0)
         PcbScene3dMaskCoveredCopperSideGroupBuilder.#applyCopperTint(

package/src/PcbScene3dMaskCoveredCopperSurfaceFilter.mjs

@@ -10,6 +10,29 @@ export class PcbScene3dMaskCoveredCopperSurfaceFilter {
      * @returns {void}
      */
     static keepOuterSurface(mesh) {
+        PcbScene3dMaskCoveredCopperSurfaceFilter.#filterOuterTriangles(mesh, {
+            keepSideWalls: false
+        })
+    }
+
+    /**
+     * Removes the hidden underside while keeping shallow edge walls.
+     * @param {any | null} mesh Copper relief mesh.
+     * @returns {void}
+     */
+    static keepOuterRelief(mesh) {
+        PcbScene3dMaskCoveredCopperSurfaceFilter.#filterOuterTriangles(mesh, {
+            keepSideWalls: true
+        })
+    }
+
+    /**
+     * Keeps only triangles that are visible above the solder mask.
+     * @param {any | null} mesh Copper relief mesh.
+     * @param {{ keepSideWalls?: boolean }} options Filter options.
+     * @returns {void}
+     */
+    static #filterOuterTriangles(mesh, options) {
         const geometry = mesh?.geometry
         const position = geometry?.getAttribute?.('position')
         const source = position?.array
@@ -17,14 +40,16 @@ export class PcbScene3dMaskCoveredCopperSurfaceFilter {
             return
         }
 
-        const maxZ = PcbScene3dMaskCoveredCopperSurfaceFilter.#maxZ(source)
+        const zBounds =
+            PcbScene3dMaskCoveredCopperSurfaceFilter.#zBounds(source)
         const filtered = []
         for (let index = 0; index + 8 < source.length; index += 9) {
             if (
-                [2, 5, 8].every(
-                    (offset) =>
-                        Math.abs(source[index + offset] - maxZ) <=
-                        PcbScene3dMaskCoveredCopperSurfaceFilter.#Z_EPSILON
+                PcbScene3dMaskCoveredCopperSurfaceFilter.#keepsTriangle(
+                    source,
+                    index,
+                    zBounds,
+                    options
                 )
             ) {
                 filtered.push(...source.slice(index, index + 9))
@@ -50,15 +75,55 @@ export class PcbScene3dMaskCoveredCopperSurfaceFilter {
     }
 
     /**
-     * Resolves the highest Z plane in one packed XYZ buffer.
+     * Checks whether one triangle should stay in the visible relief mesh.
+     * @param {ArrayLike<number>} source Position buffer.
+     * @param {number} index Triangle start index.
+     * @param {{ minZ: number, maxZ: number }} zBounds Geometry Z bounds.
+     * @param {{ keepSideWalls?: boolean }} options Filter options.
+     * @returns {boolean}
+     */
+    static #keepsTriangle(source, index, zBounds, options) {
+        const zValues = [2, 5, 8].map((offset) => source[index + offset])
+        const hasTop = zValues.some((z) =>
+            PcbScene3dMaskCoveredCopperSurfaceFilter.#matchesZ(z, zBounds.maxZ)
+        )
+        const hasBottom = zValues.some((z) =>
+            PcbScene3dMaskCoveredCopperSurfaceFilter.#matchesZ(z, zBounds.minZ)
+        )
+
+        if (hasTop && !hasBottom) {
+            return true
+        }
+
+        return options?.keepSideWalls === true && hasTop && hasBottom
+    }
+
+    /**
+     * Checks whether a Z value matches one target plane.
+     * @param {number} value Candidate Z.
+     * @param {number} target Target Z.
+     * @returns {boolean}
+     */
+    static #matchesZ(value, target) {
+        return (
+            Math.abs(Number(value) - Number(target)) <=
+            PcbScene3dMaskCoveredCopperSurfaceFilter.#Z_EPSILON
+        )
+    }
+
+    /**
+     * Resolves the lowest and highest Z planes in one packed XYZ buffer.
      * @param {ArrayLike<number>} source Position buffer.
-     * @returns {number}
+     * @returns {{ minZ: number, maxZ: number }}
      */
-    static #maxZ(source) {
+    static #zBounds(source) {
+        let minZ = Infinity
         let maxZ = -Infinity
         for (let index = 2; index < source.length; index += 3) {
-            maxZ = Math.max(maxZ, Number(source[index]))
+            const z = Number(source[index])
+            minZ = Math.min(minZ, z)
+            maxZ = Math.max(maxZ, z)
         }
-        return maxZ
+        return { minZ, maxZ }
     }
 }

package/src/PcbScene3dModelContent.mjs

@@ -0,0 +1,236 @@
+import { PcbScene3dModelIdentity } from './PcbScene3dModelIdentity.mjs'
+import { PcbScene3dModelFetchPolicy } from './PcbScene3dModelFetchPolicy.mjs'
+
+/**
+ * Reads external-model payloads through one explicit local/network policy.
+ */
+export class PcbScene3dModelContent {
+    /**
+     * Creates or reuses one bounded model fetch scope.
+     * @param {object} [options] Model loading options.
+     * @returns {object} Scoped options.
+     */
+    static createFetchScope(options = {}) {
+        return PcbScene3dModelFetchPolicy.scope(options)
+    }
+
+    /**
+     * Returns whether model URL fetching is explicitly available.
+     * @param {object} options Model loading options.
+     * @returns {boolean}
+     */
+    static canFetch(options) {
+        return PcbScene3dModelFetchPolicy.canFetch(options)
+    }
+
+    /**
+     * Reads one model as bytes from text, binary data, files, or opted-in URLs.
+     * @param {unknown} model External model metadata.
+     * @param {object} [options] Model loading policy.
+     * @param {string} [label] Human-readable format label.
+     * @returns {Promise<Uint8Array>}
+     */
+    static async bytes(model, options = {}, label = 'Model') {
+        for (const key of ['payloadText', 'text']) {
+            const value = PcbScene3dModelContent.#data(model, key)
+            if (typeof value === 'string') {
+                return new TextEncoder().encode(value)
+            }
+        }
+        for (const key of ['payloadBytes', 'bytes', 'data', 'file']) {
+            const value = PcbScene3dModelContent.#data(model, key)
+            if (typeof value === 'string') {
+                return new TextEncoder().encode(value)
+            }
+            const bytes = await PcbScene3dModelContent.#bytesFromValue(value)
+            if (bytes) return bytes
+        }
+        return PcbScene3dModelContent.#fetchBytes(model, options, label)
+    }
+
+    /**
+     * Reads one text-capable model without losing canonical string data.
+     * @param {unknown} model External model metadata.
+     * @param {object} [options] Model loading policy.
+     * @param {string} [label] Human-readable format label.
+     * @returns {Promise<string>}
+     */
+    static async text(model, options = {}, label = 'Model') {
+        for (const key of ['payloadText', 'text', 'data']) {
+            const value = PcbScene3dModelContent.#data(model, key)
+            if (typeof value === 'string') return value
+        }
+        const file = PcbScene3dModelContent.#data(model, 'file')
+        if (typeof file?.text === 'function') return file.text()
+        return new TextDecoder().decode(
+            await PcbScene3dModelContent.bytes(model, options, label)
+        )
+    }
+
+    /**
+     * Returns whether a model already carries local payload content.
+     * @param {unknown} model External model metadata.
+     * @returns {boolean}
+     */
+    static hasLocal(model) {
+        return [
+            'payloadText',
+            'text',
+            'payloadBytes',
+            'bytes',
+            'data',
+            'file'
+        ].some((key) => {
+            const value = PcbScene3dModelContent.#data(model, key)
+            return value !== null && value !== undefined
+        })
+    }
+
+    /**
+     * Resolves a relative resource URL against absolute or project-relative bases.
+     * @param {string} uri Relative resource URI.
+     * @param {string} modelUrl Main model URL or path.
+     * @returns {string}
+     */
+    static resolveRelativeUrl(uri, modelUrl) {
+        const resource = String(uri || '').trim()
+        const base = String(modelUrl || '').trim()
+        if (!resource) return ''
+        try {
+            return new URL(resource, base).toString()
+        } catch {
+            if (/^(?:[a-z][a-z\d+.-]*:|\/)/iu.test(resource)) {
+                return resource
+            }
+            const basePath = base.split(/[?#]/u)[0]
+            const directory = basePath.includes('/')
+                ? basePath.slice(0, basePath.lastIndexOf('/') + 1)
+                : ''
+            return PcbScene3dModelContent.safeProjectPath(resource, directory)
+        }
+    }
+
+    /**
+     * Resolves a safe project-relative resource path without root traversal.
+     * @param {string} uri Resource URI.
+     * @param {string} [baseDirectory] Project-relative base directory.
+     * @returns {string}
+     */
+    static safeProjectPath(uri, baseDirectory = '') {
+        const value = String(uri || '')
+            .trim()
+            .replaceAll('\\', '/')
+        if (
+            !value ||
+            /^(?:[a-z][a-z\d+.-]*:|\/|#)/iu.test(value) ||
+            value.includes('\0')
+        ) {
+            return ''
+        }
+        const parts = []
+        const combined = String(baseDirectory || '') + value
+        for (const part of combined.split('/')) {
+            if (!part || part === '.') continue
+            if (part === '..') {
+                if (!parts.length) return ''
+                parts.pop()
+                continue
+            }
+            parts.push(part)
+        }
+        return parts.join('/')
+    }
+
+    /**
+     * Fetches and caches one model URL with rejection eviction.
+     * @param {unknown} model External model metadata.
+     * @param {object} options Model loading policy.
+     * @param {string} label Human-readable format label.
+     * @returns {Promise<Uint8Array>}
+     */
+    static async #fetchBytes(model, options, label) {
+        const url = String(
+            PcbScene3dModelContent.#data(model, 'resolvedUrl') ||
+                PcbScene3dModelContent.#data(model, 'sourceUrl') ||
+                ''
+        ).trim()
+        if (!url || !PcbScene3dModelFetchPolicy.canFetch(options)) {
+            throw new Error(label + ' model content is not available.')
+        }
+
+        const cache =
+            options?.modelCache instanceof Map ? options.modelCache : null
+        const cacheKey = 'model:' + PcbScene3dModelIdentity.resolve(model)
+        const cached = cache?.get(cacheKey)
+        if (cached) return cached
+
+        const pending = PcbScene3dModelContent.#fetchUncached(
+            url,
+            options,
+            label,
+            String(PcbScene3dModelContent.#data(model, 'mainModelUrl') || url)
+        )
+        cache?.set(cacheKey, pending)
+        try {
+            return await pending
+        } catch (error) {
+            if (cache?.get(cacheKey) === pending) cache.delete(cacheKey)
+            throw error
+        }
+    }
+
+    /**
+     * Fetches one uncached model payload.
+     * @param {string} url Model URL.
+     * @param {object} options Fetch policy.
+     * @param {string} label Human-readable resource label.
+     * @param {string} mainUrl Main model URL for origin policy.
+     * @returns {Promise<Uint8Array>}
+     */
+    static async #fetchUncached(url, options, label, mainUrl) {
+        return PcbScene3dModelFetchPolicy.fetchBytes(url, options, {
+            label,
+            mainUrl
+        })
+    }
+
+    /**
+     * Converts one byte-like or blob value into bytes.
+     * @param {unknown} value Payload candidate.
+     * @returns {Promise<Uint8Array | null>}
+     */
+    static async #bytesFromValue(value) {
+        if (!value) return null
+        if (value instanceof Uint8Array) return value
+        if (value instanceof ArrayBuffer) return new Uint8Array(value)
+        if (ArrayBuffer.isView(value)) {
+            return new Uint8Array(
+                value.buffer,
+                value.byteOffset,
+                value.byteLength
+            )
+        }
+        if (typeof value.arrayBuffer === 'function') {
+            return new Uint8Array(await value.arrayBuffer())
+        }
+        return null
+    }
+
+    /**
+     * Reads one own data property without invoking accessors.
+     * @param {unknown} value Record candidate.
+     * @param {PropertyKey} key Property key.
+     * @returns {unknown}
+     */
+    static #data(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
+        }
+    }
+}