pcb-scene3d-viewer 1.1.21 → 1.1.31

package/src/PcbAssemblyFillRingNormalizer.mjs

@@ -0,0 +1,209 @@
+const COORDINATE_EPSILON = 0.001
+const AREA_EPSILON = 0.001
+
+/**
+ * Normalizes saved copper fill rings before triangulation and export.
+ */
+export class PcbAssemblyFillRingNormalizer {
+    /**
+     * Normalizes one ring into a clean, optionally oriented loop.
+     * @param {unknown[]} points Candidate point rows.
+     * @param {{ role?: string, shapeIndex?: number, ringIndex?: number, winding?: 'positive' | 'negative' }} options Normalization options.
+     * @returns {{ loop: number[][], diagnostic: object | null, area: number }}
+     */
+    static normalize(points, options = {}) {
+        const rows = PcbAssemblyFillRingNormalizer.#pointRows(points)
+        const hasNonFinitePoint = rows.some((row) => !row.isFinite)
+        if (hasNonFinitePoint) {
+            return PcbAssemblyFillRingNormalizer.#result(
+                [],
+                'non-finite-point',
+                options,
+                rows.length,
+                0
+            )
+        }
+
+        const loop = PcbAssemblyFillRingNormalizer.#cleanLoop(
+            rows.map((row) => [row.x, row.y])
+        )
+        const signedArea = PcbAssemblyFillRingNormalizer.signedArea(loop)
+        const area = Math.abs(signedArea)
+        if (loop.length < 3) {
+            return PcbAssemblyFillRingNormalizer.#result(
+                loop,
+                'too-few-points',
+                options,
+                loop.length,
+                area
+            )
+        }
+        if (area <= AREA_EPSILON) {
+            return PcbAssemblyFillRingNormalizer.#result(
+                loop,
+                'near-zero-area',
+                options,
+                loop.length,
+                area
+            )
+        }
+
+        return {
+            loop: PcbAssemblyFillRingNormalizer.#orientLoop(
+                loop,
+                signedArea,
+                options.winding
+            ),
+            diagnostic: null,
+            area
+        }
+    }
+
+    /**
+     * Checks whether one loop has enough non-collinear area.
+     * @param {number[][]} loop Candidate loop.
+     * @returns {boolean}
+     */
+    static isValidLoop(loop) {
+        return (
+            Array.isArray(loop) &&
+            loop.length >= 3 &&
+            Math.abs(PcbAssemblyFillRingNormalizer.signedArea(loop)) >
+                AREA_EPSILON
+        )
+    }
+
+    /**
+     * Computes signed polygon area in source units.
+     * @param {number[][]} loop Candidate loop.
+     * @returns {number}
+     */
+    static signedArea(loop) {
+        let area = 0
+        for (let index = 0; index < (loop || []).length; index += 1) {
+            const current = loop[index]
+            const next = loop[(index + 1) % loop.length]
+            area += current[0] * next[1] - next[0] * current[1]
+        }
+        return area / 2
+    }
+
+    /**
+     * Normalizes candidate point rows into numeric values.
+     * @param {unknown[]} points Candidate point rows.
+     * @returns {{ x: number, y: number, isFinite: boolean }[]}
+     */
+    static #pointRows(points) {
+        return (Array.isArray(points) ? points : []).map((point) => {
+            const x = Number(Array.isArray(point) ? point[0] : point?.x)
+            const y = Number(Array.isArray(point) ? point[1] : point?.y)
+            return {
+                x,
+                y,
+                isFinite: Number.isFinite(x) && Number.isFinite(y)
+            }
+        })
+    }
+
+    /**
+     * Removes invalid, repeated, and closing points from one loop.
+     * @param {number[][]} points Candidate numeric points.
+     * @returns {number[][]}
+     */
+    static #cleanLoop(points) {
+        const loop = []
+        for (const point of points || []) {
+            const x = Number(point?.[0])
+            const y = Number(point?.[1])
+            if (!Number.isFinite(x) || !Number.isFinite(y)) {
+                continue
+            }
+
+            const previous = loop[loop.length - 1]
+            if (
+                previous &&
+                Math.abs(previous[0] - x) < COORDINATE_EPSILON &&
+                Math.abs(previous[1] - y) < COORDINATE_EPSILON
+            ) {
+                continue
+            }
+            loop.push([x, y])
+        }
+
+        const first = loop[0]
+        const last = loop[loop.length - 1]
+        if (
+            first &&
+            last &&
+            Math.abs(first[0] - last[0]) < COORDINATE_EPSILON &&
+            Math.abs(first[1] - last[1]) < COORDINATE_EPSILON
+        ) {
+            loop.pop()
+        }
+
+        return loop
+    }
+
+    /**
+     * Orients one loop to the requested signed-area winding.
+     * @param {number[][]} loop Candidate loop.
+     * @param {number} signedArea Signed loop area.
+     * @param {'positive' | 'negative' | undefined} winding Requested winding.
+     * @returns {number[][]}
+     */
+    static #orientLoop(loop, signedArea, winding) {
+        if (winding === 'positive' && signedArea < 0) {
+            return [...loop].reverse()
+        }
+        if (winding === 'negative' && signedArea > 0) {
+            return [...loop].reverse()
+        }
+        return loop
+    }
+
+    /**
+     * Builds a normalization result.
+     * @param {number[][]} loop Normalized loop.
+     * @param {string} reason Drop reason.
+     * @param {{ role?: string, shapeIndex?: number, ringIndex?: number }} options Normalization options.
+     * @param {number} pointCount Clean point count.
+     * @param {number} area Absolute loop area.
+     * @returns {{ loop: number[][], diagnostic: object, area: number }}
+     */
+    static #result(loop, reason, options, pointCount, area) {
+        return {
+            loop,
+            diagnostic: PcbAssemblyFillRingNormalizer.#diagnostic(
+                reason,
+                options,
+                pointCount,
+                area
+            ),
+            area
+        }
+    }
+
+    /**
+     * Builds one dropped-ring diagnostic row.
+     * @param {string} reason Drop reason.
+     * @param {{ role?: string, shapeIndex?: number, ringIndex?: number }} options Normalization options.
+     * @param {number} pointCount Clean point count.
+     * @param {number} area Absolute loop area.
+     * @returns {object}
+     */
+    static #diagnostic(reason, options, pointCount, area) {
+        const diagnostic = {
+            reason,
+            role: String(options.role || 'ring'),
+            pointCount,
+            area
+        }
+        if (Number.isInteger(options.shapeIndex)) {
+            diagnostic.shapeIndex = options.shapeIndex
+        }
+        if (Number.isInteger(options.ringIndex)) {
+            diagnostic.ringIndex = options.ringIndex
+        }
+        return diagnostic
+    }
+}

package/src/PcbAssemblyGeometryBuilder.mjs

@@ -1,12 +1,14 @@
 import { PcbAssemblyBoardSubstrateBuilder } from './PcbAssemblyBoardSubstrateBuilder.mjs'
+import { PcbAssemblyComponentMeshBuilder } from './PcbAssemblyComponentMeshBuilder.mjs'
+import { PcbAssemblyFillGeometryResolver } from './PcbAssemblyFillGeometryResolver.mjs'
 import { PcbAssemblyMeshUtils } from './PcbAssemblyMeshUtils.mjs'
+import { PcbAssemblyPadMeshBuilder } from './PcbAssemblyPadMeshBuilder.mjs'
 
 const COPPER_THICKNESS_MIL = 2.2
 const SILKSCREEN_THICKNESS_MIL = 0.8
 const BOARD_COLOR = [0.05, 0.32, 0.18]
 const COPPER_COLOR = [0.85, 0.62, 0.12]
 const SILKSCREEN_COLOR = [0.96, 0.95, 0.9]
-const COMPONENT_COLOR = [0.55, 0.56, 0.58]
 
 /**
  * Converts a prepared 3D scene description into exportable faceted meshes.
@@ -15,7 +17,7 @@ export class PcbAssemblyGeometryBuilder {
     /**
      * Builds assembly meshes and diagnostics.
      * @param {{ board?: object, detail?: object, components?: object[], externalPlacements?: object[] }} sceneDescription Prepared scene description.
-     * @param {{ modelMeshLoader?: (placement: object) => Promise<object | object[]>, progress?: { advance?: (units: number, message: string) => Promise<void>, finish?: (message: string) => Promise<void> } }} [options] Build options.
+     * @param {{ modelMeshLoader?: (placement: object) => Promise<object | object[]>, includeModels?: boolean, renderFallbackBodies?: boolean, progress?: { advance?: (units: number, message: string) => Promise<void>, finish?: (message: string) => Promise<void> } }} [options] Build options.
      * @returns {Promise<{ meshes: object[], diagnostics: object[] }>}
      */
     static async build(sceneDescription, options = {}) {
@@ -35,23 +37,20 @@ export class PcbAssemblyGeometryBuilder {
                 progress
             )
         const pcbMeshes = [...boardMeshes, ...copperMeshes, ...silkscreenMeshes]
+        const componentResult = await PcbAssemblyComponentMeshBuilder.build(
+            sceneDescription,
+            options,
+            progress
+        )
+        diagnostics.push(...componentResult.diagnostics)
         const meshes = [
             ...PcbAssemblyGeometryBuilder.#translateMeshes(
                 pcbMeshes,
                 PcbAssemblyGeometryBuilder.#boardLocalOffset(sceneDescription)
             ),
-            ...(await PcbAssemblyGeometryBuilder.#buildComponentMeshes(
-                sceneDescription,
-                options,
-                diagnostics,
-                progress
-            ))
+            ...componentResult.meshes
         ]
 
-        PcbAssemblyGeometryBuilder.#appendMissingModelDiagnostics(
-            sceneDescription,
-            diagnostics
-        )
         await progress?.finish?.('Geometry meshes ready')
         return {
             meshes: meshes.filter((mesh) => mesh?.vertices?.length),
@@ -149,14 +148,14 @@ export class PcbAssemblyGeometryBuilder {
         for (let index = 0; index < fills.length; index += 1) {
             const fill = fills[index]
             const side = PcbAssemblyGeometryBuilder.#resolveSide(fill)
-            const mesh = PcbAssemblyMeshUtils.prism(
+            const fillMeshes = PcbAssemblyGeometryBuilder.#fillMeshes(
                 'copper-' + side + '-fill-' + (index + 1),
-                PcbAssemblyGeometryBuilder.#points(fill),
+                fill,
                 side === 'bottom' ? bottomZ : topZ,
                 COPPER_THICKNESS_MIL,
                 COPPER_COLOR
             )
-            if (mesh) meshes.push(mesh)
+            meshes.push(...fillMeshes)
             await progress?.advance?.(
                 1,
                 'Building copper fills ' + (index + 1) + '/' + fills.length
@@ -166,19 +165,21 @@ export class PcbAssemblyGeometryBuilder {
         const pads = PcbAssemblyGeometryBuilder.#array(detail.pads)
         for (let index = 0; index < pads.length; index += 1) {
             const pad = pads[index]
-            const topMesh = PcbAssemblyGeometryBuilder.#padMesh(
+            const topMesh = PcbAssemblyPadMeshBuilder.build(
                 'pad-top-' + (index + 1),
                 pad,
                 'top',
                 topZ,
-                COPPER_THICKNESS_MIL
+                COPPER_THICKNESS_MIL,
+                COPPER_COLOR
             )
-            const bottomMesh = PcbAssemblyGeometryBuilder.#padMesh(
+            const bottomMesh = PcbAssemblyPadMeshBuilder.build(
                 'pad-bottom-' + (index + 1),
                 pad,
                 'bottom',
                 bottomZ,
-                COPPER_THICKNESS_MIL
+                COPPER_THICKNESS_MIL,
+                COPPER_COLOR
             )
             if (topMesh) meshes.push(topMesh)
             await progress?.advance?.(
@@ -389,164 +390,6 @@ export class PcbAssemblyGeometryBuilder {
         }
     }
 
-    /**
-     * Builds component model meshes.
-     * @param {{ externalPlacements?: object[] }} sceneDescription Prepared scene description.
-     * @param {{ modelMeshLoader?: (placement: object) => Promise<object | object[]> }} options Build options.
-     * @param {object[]} diagnostics Mutable diagnostics list.
-     * @param {{ advance?: (units: number, message: string) => Promise<void> } | null} progress Progress tracker.
-     * @returns {Promise<object[]>}
-     */
-    static async #buildComponentMeshes(
-        sceneDescription,
-        options,
-        diagnostics,
-        progress = null
-    ) {
-        const loader =
-            typeof options.modelMeshLoader === 'function'
-                ? options.modelMeshLoader
-                : null
-        if (!loader) {
-            return []
-        }
-
-        const meshes = []
-        const placements = PcbAssemblyGeometryBuilder.#array(
-            sceneDescription?.externalPlacements
-        ).filter((placement) => placement?.externalModel)
-        for (
-            let placementIndex = 0;
-            placementIndex < placements.length;
-            placementIndex += 1
-        ) {
-            const placement = placements[placementIndex]
-
-            try {
-                const loaded = await loader(placement)
-                const loadedMeshes = Array.isArray(loaded) ? loaded : [loaded]
-                loadedMeshes.filter(Boolean).forEach((mesh, index) => {
-                    const designator = PcbAssemblyMeshUtils.safeName(
-                        placement?.designator || 'component'
-                    )
-                    const transformed = PcbAssemblyMeshUtils.transformMesh(
-                        {
-                            ...mesh,
-                            name:
-                                'component-' +
-                                designator +
-                                (loadedMeshes.length > 1
-                                    ? '-' + (index + 1)
-                                    : ''),
-                            color: mesh.color || COMPONENT_COLOR
-                        },
-                        placement
-                    )
-                    meshes.push(transformed)
-                })
-                PcbAssemblyGeometryBuilder.#appendModelDiagnostic(
-                    placement,
-                    diagnostics
-                )
-            } catch (error) {
-                diagnostics.push(
-                    PcbAssemblyGeometryBuilder.#diagnostic(
-                        'warning',
-                        'component_model_conversion_failed',
-                        'Could not convert 3D model for ' +
-                            String(placement?.designator || 'component') +
-                            ': ' +
-                            String(error?.message || error)
-                    )
-                )
-            }
-            await progress?.advance?.(
-                1,
-                'Loading component models ' +
-                    (placementIndex + 1) +
-                    '/' +
-                    placements.length
-            )
-        }
-
-        return meshes
-    }
-
-    /**
-     * Adds a format-specific component model diagnostic.
-     * @param {object} placement Component placement.
-     * @param {object[]} diagnostics Mutable diagnostics list.
-     * @returns {void}
-     */
-    static #appendModelDiagnostic(placement, diagnostics) {
-        const format = String(
-            placement?.externalModel?.format || ''
-        ).toLowerCase()
-        if (format === 'wrl' || format === 'vrml') {
-            diagnostics.push(
-                PcbAssemblyGeometryBuilder.#diagnostic(
-                    'info',
-                    'component_wrl_faceted_step',
-                    'Converted WRL model for ' +
-                        String(placement?.designator || 'component') +
-                        ' as faceted geometry.'
-                )
-            )
-            return
-        }
-
-        if (format === 'step' || format === 'stp') {
-            diagnostics.push(
-                PcbAssemblyGeometryBuilder.#diagnostic(
-                    'info',
-                    'component_step_faceted_export',
-                    'Included STEP model for ' +
-                        String(placement?.designator || 'component') +
-                        ' through export mesh geometry.'
-                )
-            )
-        }
-    }
-
-    /**
-     * Adds diagnostics for components without resolved external models.
-     * @param {{ components?: object[], externalPlacements?: object[] }} sceneDescription Scene description.
-     * @param {object[]} diagnostics Mutable diagnostics list.
-     * @returns {void}
-     */
-    static #appendMissingModelDiagnostics(sceneDescription, diagnostics) {
-        const placementDesignators = new Set(
-            PcbAssemblyGeometryBuilder.#array(
-                sceneDescription?.externalPlacements
-            )
-                .map((placement) => String(placement?.designator || '').trim())
-                .filter(Boolean)
-        )
-
-        PcbAssemblyGeometryBuilder.#array(sceneDescription?.components).forEach(
-            (component) => {
-                const designator = String(component?.designator || '').trim()
-                if (
-                    !designator ||
-                    component?.externalModel ||
-                    placementDesignators.has(designator)
-                ) {
-                    return
-                }
-
-                diagnostics.push(
-                    PcbAssemblyGeometryBuilder.#diagnostic(
-                        'warning',
-                        'component_model_missing',
-                        'No resolved 3D model was available for ' +
-                            designator +
-                            '.'
-                    )
-                )
-            }
-        )
-    }
-
     /**
      * Builds one widened track mesh.
      * @param {string} name Mesh name.
@@ -584,133 +427,30 @@ export class PcbAssemblyGeometryBuilder {
     }
 
     /**
-     * Builds one pad mesh.
+     * Builds filled polygon meshes.
      * @param {string} name Mesh name.
-     * @param {object} pad Pad primitive.
-     * @param {'top' | 'bottom'} side Pad side.
+     * @param {object} fill Filled primitive.
      * @param {number} z Center Z.
-     * @param {number} thickness Extrusion thickness.
-     * @returns {object | null}
-     */
-    static #padMesh(name, pad, side, z, thickness) {
-        const size = PcbAssemblyGeometryBuilder.#padSize(pad, side)
-        if (!size) {
-            return null
-        }
-
-        const offset = PcbAssemblyGeometryBuilder.#padOffset(pad, side)
-        const x = Number(pad?.x || 0) + offset.x
-        const y = Number(pad?.y || 0) + offset.y
-        const shape = PcbAssemblyGeometryBuilder.#padShape(pad, side)
-        const isCircle =
-            Math.abs(size.width - size.height) < 0.001 && shape !== 2
-        const mesh = isCircle
-            ? PcbAssemblyMeshUtils.cylinder(name, {
-                  x,
-                  y,
-                  z,
-                  radius: size.width / 2,
-                  height: thickness,
-                  color: COPPER_COLOR
-              })
-            : PcbAssemblyMeshUtils.box(name, {
-                  x,
-                  y,
-                  z,
-                  width: size.width,
-                  depth: size.height,
-                  height: thickness,
-                  color: COPPER_COLOR
-              })
-
-        return PcbAssemblyGeometryBuilder.#rotateMeshAroundZ(
-            mesh,
-            Number(pad?.rotation || 0),
-            x,
-            y
-        )
-    }
-
-    /**
-     * Resolves side-specific pad dimensions.
-     * @param {object} pad Pad primitive.
-     * @param {'top' | 'bottom'} side Pad side.
-     * @returns {{ width: number, height: number } | null}
-     */
-    static #padSize(pad, side) {
-        const prefix = side === 'bottom' ? 'Bottom' : 'Top'
-        let width = PcbAssemblyGeometryBuilder.#firstPositive([
-            pad?.['size' + prefix + 'X']
-        ])
-        let height = PcbAssemblyGeometryBuilder.#firstPositive([
-            pad?.['size' + prefix + 'Y']
-        ])
-
-        if (side === 'top' && !width) {
-            width = PcbAssemblyGeometryBuilder.#firstPositive([
-                pad?.width,
-                pad?.sizeX,
-                pad?.diameter,
-                pad?.sizeMidX,
-                pad?.sizeBottomX
-            ])
-        }
-        if (side === 'top' && !height) {
-            height = PcbAssemblyGeometryBuilder.#firstPositive([
-                pad?.height,
-                pad?.sizeY,
-                pad?.diameter,
-                pad?.sizeMidY,
-                pad?.sizeBottomY,
-                width
-            ])
-        }
-        if (width && !height) {
-            height = width
-        }
-
-        return width && height
-            ? {
-                  width: Math.max(width, 1),
-                  height: Math.max(height, 1)
-              }
-            : null
-    }
-
-    /**
-     * Resolves side-specific pad center offset.
-     * @param {object} pad Pad primitive.
-     * @param {'top' | 'bottom'} side Pad side.
-     * @returns {{ x: number, y: number }}
-     */
-    static #padOffset(pad, side) {
-        const prefix = side === 'bottom' ? 'Bottom' : 'Top'
-
-        return {
-            x: Number(pad?.['offset' + prefix + 'X'] || 0),
-            y: Number(pad?.['offset' + prefix + 'Y'] || 0)
-        }
-    }
-
-    /**
-     * Resolves the renderer pad shape code for one side.
-     * @param {object} pad Pad primitive.
-     * @param {'top' | 'bottom'} side Pad side.
-     * @returns {number}
+     * @param {number} thickness Mesh thickness.
+     * @param {number[]} color Mesh color.
+     * @returns {object[]}
      */
-    static #padShape(pad, side) {
-        const prefix = side === 'bottom' ? 'Bottom' : 'Top'
-        const rounded = pad?.['roundedRectShape' + prefix]
-        if (Number.isInteger(Number(rounded))) {
-            return Number(rounded)
-        }
-
-        return Number(
-            pad?.['shape' + prefix] ||
-                pad?.shapeMid ||
-                (side === 'top' ? pad?.shapeBottom : pad?.shapeTop) ||
-                0
-        )
+    static #fillMeshes(name, fill, z, thickness, color) {
+        const loopSets = PcbAssemblyFillGeometryResolver.resolveAll(fill)
+        return loopSets
+            .map((loops, index) =>
+                PcbAssemblyMeshUtils.prismWithHoles(
+                    loopSets.length > 1
+                        ? name + '-island-' + (index + 1)
+                        : name,
+                    loops.outer,
+                    loops.holes,
+                    z,
+                    thickness,
+                    color
+                )
+            )
+            .filter(Boolean)
     }
 
     /**