pcb-scene3d-viewer 1.2.2 → 1.3.0

package/src/PcbScene3dCopperTextFactory.mjs

@@ -1,6 +1,7 @@
 import { PcbScene3dStrokeFont } from './PcbScene3dStrokeFont.mjs'
 import { PcbScene3dCutoutGeometryFilter } from './PcbScene3dCutoutGeometryFilter.mjs'
 import { PcbScene3dStrokeGeometryBuilder } from './PcbScene3dStrokeGeometryBuilder.mjs'
+import { PcbScene3dStrokeCutoutBuilder } from './PcbScene3dStrokeCutoutBuilder.mjs'
 
 /**
  * Builds KiCad copper text as widened stroke meshes for the 3D PCB scene.
@@ -11,6 +12,33 @@ export class PcbScene3dCopperTextFactory {
     static #FIRST_LINE_HEIGHT_RATIO = 1.17
     static #STROKE_BASELINE_FUDGE_RATIO = 0.052
 
+    /**
+     * Builds exact round-capped stroke polygons for one copper text primitive.
+     * @param {object} text Copper text primitive.
+     * @param {{ glyphYUp?: boolean, alignmentStrokeWidth?: number }} [options] Text geometry options. `alignmentStrokeWidth` keeps paired text with different stroke widths on one source-authored anchor.
+     * @returns {{ x: number, y: number }[][]}
+     */
+    static strokeCutouts(text, options = {}) {
+        const width = PcbScene3dCopperTextFactory.#textStrokeWidth(text)
+        return PcbScene3dCopperTextFactory.#textStrokes(
+            text,
+            Boolean(options?.glyphYUp),
+            options?.alignmentStrokeWidth
+        ).flatMap((stroke) => {
+            const cutouts = []
+            for (let index = 1; index < stroke.length; index += 1) {
+                const cutout = PcbScene3dStrokeCutoutBuilder.build(
+                    stroke[index - 1],
+                    stroke[index],
+                    width,
+                    { minWidth: 1 }
+                )
+                if (cutout.length >= 3) cutouts.push(cutout)
+            }
+            return cutouts
+        })
+    }
+
     /**
      * Builds one side-specific copper text group.
      * @param {any} THREE
@@ -171,9 +199,10 @@ export class PcbScene3dCopperTextFactory {
      * Builds all KiCad stroke-font point lists for one text primitive.
      * @param {object} text
      * @param {boolean} glyphYUp
+     * @param {number | undefined} alignmentStrokeWidth Stroke width used only for anchor adjustment.
      * @returns {{ x: number, y: number }[][]}
      */
-    static #textStrokes(text, glyphYUp) {
+    static #textStrokes(text, glyphYUp, alignmentStrokeWidth) {
         const lines = String(text?.value ?? text?.text ?? '').split('\n')
         const lineSpacing = PcbScene3dCopperTextFactory.#textLineSpacing(text)
 
@@ -184,7 +213,8 @@ export class PcbScene3dCopperTextFactory {
                 index,
                 lines.length,
                 lineSpacing,
-                glyphYUp
+                glyphYUp,
+                alignmentStrokeWidth
             )
         )
     }
@@ -197,6 +227,7 @@ export class PcbScene3dCopperTextFactory {
      * @param {number} lineCount
      * @param {number} lineSpacing
      * @param {boolean} glyphYUp
+     * @param {number | undefined} alignmentStrokeWidth Stroke width used only for anchor adjustment.
      * @returns {{ x: number, y: number }[][]}
      */
     static #textLineStrokes(
@@ -205,7 +236,8 @@ export class PcbScene3dCopperTextFactory {
         index,
         lineCount,
         lineSpacing,
-        glyphYUp
+        glyphYUp,
+        alignmentStrokeWidth
     ) {
         const sizeX = PcbScene3dCopperTextFactory.#textWidth(text)
         const sizeY = PcbScene3dCopperTextFactory.#textHeight(text)
@@ -215,12 +247,17 @@ export class PcbScene3dCopperTextFactory {
             sizeX,
             sizeY
         })
-        const x = PcbScene3dCopperTextFactory.#textLineX(text, layout.width)
+        const x = PcbScene3dCopperTextFactory.#textLineX(
+            text,
+            layout.width,
+            alignmentStrokeWidth
+        )
         const y = PcbScene3dCopperTextFactory.#textLineY(
             text,
             index,
             lineCount,
-            lineSpacing
+            lineSpacing,
+            alignmentStrokeWidth
         )
 
         return layout.strokes.map((stroke) =>
@@ -293,11 +330,14 @@ export class PcbScene3dCopperTextFactory {
      * Resolves line origin from KiCad horizontal justification.
      * @param {object} text
      * @param {number} lineWidth
+     * @param {number | undefined} alignmentStrokeWidth Stroke width used only for anchor adjustment.
      * @returns {number}
      */
-    static #textLineX(text, lineWidth) {
-        const fudge =
-            PcbScene3dCopperTextFactory.#textStrokeHorizontalFudge(text)
+    static #textLineX(text, lineWidth, alignmentStrokeWidth) {
+        const fudge = PcbScene3dCopperTextFactory.#textStrokeHorizontalFudge(
+            text,
+            alignmentStrokeWidth
+        )
 
         if (text?.hAlign === 'left') {
             return Number(text?.x || 0) + fudge
@@ -316,9 +356,16 @@ export class PcbScene3dCopperTextFactory {
      * @param {number} index
      * @param {number} lineCount
      * @param {number} lineSpacing
+     * @param {number | undefined} alignmentStrokeWidth Stroke width used only for anchor adjustment.
      * @returns {number}
      */
-    static #textLineY(text, index, lineCount, lineSpacing) {
+    static #textLineY(
+        text,
+        index,
+        lineCount,
+        lineSpacing,
+        alignmentStrokeWidth
+    ) {
         const height = PcbScene3dCopperTextFactory.#textHeight(text)
         const blockHeight =
             height * PcbScene3dCopperTextFactory.#FIRST_LINE_HEIGHT_RATIO +
@@ -326,7 +373,10 @@ export class PcbScene3dCopperTextFactory {
         let baseline =
             Number(text?.y || 0) +
             height -
-            PcbScene3dCopperTextFactory.#textStrokeBaselineFudge(text)
+            PcbScene3dCopperTextFactory.#textStrokeBaselineFudge(
+                text,
+                alignmentStrokeWidth
+            )
 
         if (text?.vAlign === 'bottom') {
             baseline -= blockHeight
@@ -354,24 +404,46 @@ export class PcbScene3dCopperTextFactory {
     /**
      * Resolves KiCad's small horizontal text adjustment.
      * @param {object} text
+     * @param {number | undefined} alignmentStrokeWidth Stroke width used only for anchor adjustment.
      * @returns {number}
      */
-    static #textStrokeHorizontalFudge(text) {
-        return PcbScene3dCopperTextFactory.#textStrokeWidth(text) / 1.52
+    static #textStrokeHorizontalFudge(text, alignmentStrokeWidth) {
+        return (
+            PcbScene3dCopperTextFactory.#alignmentStrokeWidth(
+                text,
+                alignmentStrokeWidth
+            ) / 1.52
+        )
     }
 
     /**
      * Resolves KiCad's small baseline text adjustment.
      * @param {object} text
+     * @param {number | undefined} alignmentStrokeWidth Stroke width used only for anchor adjustment.
      * @returns {number}
      */
-    static #textStrokeBaselineFudge(text) {
+    static #textStrokeBaselineFudge(text, alignmentStrokeWidth) {
         return (
-            PcbScene3dCopperTextFactory.#textStrokeWidth(text) *
-            PcbScene3dCopperTextFactory.#STROKE_BASELINE_FUDGE_RATIO
+            PcbScene3dCopperTextFactory.#alignmentStrokeWidth(
+                text,
+                alignmentStrokeWidth
+            ) * PcbScene3dCopperTextFactory.#STROKE_BASELINE_FUDGE_RATIO
         )
     }
 
+    /**
+     * Resolves the stroke width used for source-anchor alignment adjustments.
+     * @param {object} text Copper text primitive.
+     * @param {number | undefined} alignmentStrokeWidth Optional paired-text reference width.
+     * @returns {number}
+     */
+    static #alignmentStrokeWidth(text, alignmentStrokeWidth) {
+        const candidate = Number(alignmentStrokeWidth)
+        return Number.isFinite(candidate) && candidate > 0
+            ? candidate
+            : PcbScene3dCopperTextFactory.#textStrokeWidth(text)
+    }
+
     /**
      * Applies KiCad text rotation and mirrored text transforms.
      * @param {object} text
@@ -389,15 +461,15 @@ export class PcbScene3dCopperTextFactory {
             : point
 
         if (text?.mirrored) {
-            const rotated = PcbScene3dCopperTextFactory.#rotatePoint(
+            const mirroredPoint = PcbScene3dCopperTextFactory.#mirrorPointX(
                 sourcePoint,
+                origin
+            )
+            return PcbScene3dCopperTextFactory.#rotatePoint(
+                mirroredPoint,
                 origin,
                 Number(text?.rotation || 0)
             )
-            return {
-                x: origin.x - (rotated.x - origin.x),
-                y: rotated.y
-            }
         }
 
         return PcbScene3dCopperTextFactory.#rotatePoint(
@@ -407,6 +479,19 @@ export class PcbScene3dCopperTextFactory {
         )
     }
 
+    /**
+     * Mirrors one stroke-font point across the text anchor's local Y axis.
+     * @param {{ x: number, y: number }} point
+     * @param {{ x: number, y: number }} origin
+     * @returns {{ x: number, y: number }}
+     */
+    static #mirrorPointX(point, origin) {
+        return {
+            x: origin.x - (Number(point?.x || 0) - origin.x),
+            y: Number(point?.y || 0)
+        }
+    }
+
     /**
      * Mirrors one stroke-font point across the text anchor's local X axis.
      * @param {{ x: number, y: number }} point

package/src/PcbScene3dExternalModels.mjs

@@ -84,6 +84,15 @@ export class PcbScene3dExternalModels {
                         await PcbScene3dExternalModels.#yieldToMainThread()
                     }
                 } catch (error) {
+                    if (
+                        PcbScene3dExternalModels.#isDeferredContentError(
+                            placement,
+                            error,
+                            modelLoaderOptions
+                        )
+                    ) {
+                        continue
+                    }
                     diagnostics.push(
                         'Could not load external model for ' +
                             String(placement?.designator || 'component') +
@@ -101,6 +110,23 @@ export class PcbScene3dExternalModels {
         return diagnostics
     }
 
+    /**
+     * Returns whether a failure represents an intentionally deferred model.
+     * @param {object} placement External-model placement.
+     * @param {unknown} error Model loading failure.
+     * @param {object} modelLoaderOptions Scoped model loading options.
+     * @returns {boolean}
+     */
+    static #isDeferredContentError(placement, error, modelLoaderOptions) {
+        const model = placement?.externalModel
+        return Boolean(
+            model &&
+            PcbScene3dModelContent.isUnavailableError(error) &&
+            !PcbScene3dModelContent.hasLocal(model) &&
+            !PcbScene3dModelContent.canFetch(modelLoaderOptions)
+        )
+    }
+
     /**
      * Applies the active view mirror compensation to loaded model geometry.
      * @param {any} externalModelsGroup Root group containing placed models.

package/src/PcbScene3dMaskCoveredCopperSideGroupBuilder.mjs

@@ -16,7 +16,7 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
     /**
      * Builds one side group from prepared mask-covered copper meshes.
      * @param {any} THREE Three.js namespace.
-     * @param {{ trackMesh?: any | null, arcMesh?: any | null, fillMesh?: any | null, z?: number, mirrorY?: boolean }} options
+     * @param {{ trackMesh?: any | null, arcMesh?: any | null, fillMesh?: any | null, textMesh?: any | null, z?: number, mirrorY?: boolean }} options
      * @returns {any}
      */
     static build(
@@ -25,6 +25,7 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
             trackMesh = null,
             arcMesh = null,
             fillMesh = null,
+            textMesh = null,
             z = 0,
             mirrorY = false
         } = {}
@@ -87,6 +88,20 @@ export class PcbScene3dMaskCoveredCopperSideGroupBuilder {
                         .#FILL_RENDER_ORDER
             }
         )
+        PcbScene3dMaskCoveredCopperSideGroupBuilder.#addCompressedMesh(
+            group,
+            textMesh,
+            'mask-covered-copper-text',
+            z,
+            {
+                copperBlend:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#TRACK_COPPER_BLEND,
+                renderOrder:
+                    PcbScene3dMaskCoveredCopperSideGroupBuilder
+                        .#TRACK_RENDER_ORDER
+            }
+        )
 
         if (mirrorY && group.children.length) {
             group.rotation.x = Math.PI

package/src/PcbScene3dModelContent.mjs

@@ -1,6 +1,8 @@
 import { PcbScene3dModelIdentity } from './PcbScene3dModelIdentity.mjs'
 import { PcbScene3dModelFetchPolicy } from './PcbScene3dModelFetchPolicy.mjs'
 
+const CONTENT_UNAVAILABLE_ERROR = 'ERR_MODEL_CONTENT_UNAVAILABLE'
+
 /**
  * Reads external-model payloads through one explicit local/network policy.
  */
@@ -23,6 +25,35 @@ export class PcbScene3dModelContent {
         return PcbScene3dModelFetchPolicy.canFetch(options)
     }
 
+    /**
+     * Creates a typed missing-content error for deferred model references.
+     * @param {string} [label] Human-readable format label.
+     * @returns {Error}
+     */
+    static unavailableError(label = 'Model') {
+        const error = new Error(label + ' model content is not available.')
+        Object.defineProperty(error, 'code', {
+            configurable: false,
+            enumerable: true,
+            value: CONTENT_UNAVAILABLE_ERROR,
+            writable: false
+        })
+        return error
+    }
+
+    /**
+     * Returns whether a failure is the typed missing-content condition.
+     * @param {unknown} error Candidate failure.
+     * @returns {boolean}
+     */
+    static isUnavailableError(error) {
+        try {
+            return error?.code === CONTENT_UNAVAILABLE_ERROR
+        } catch {
+            return false
+        }
+    }
+
     /**
      * Reads one model as bytes from text, binary data, files, or opted-in URLs.
      * @param {unknown} model External model metadata.
@@ -155,7 +186,7 @@ export class PcbScene3dModelContent {
                 ''
         ).trim()
         if (!url || !PcbScene3dModelFetchPolicy.canFetch(options)) {
-            throw new Error(label + ' model content is not available.')
+            throw PcbScene3dModelContent.unavailableError(label)
         }
 
         const cache =

package/src/PcbScene3dRuntimeBoardMeshes.mjs

@@ -124,10 +124,8 @@ export class PcbScene3dRuntimeBoardMeshes {
             metalness: 0.08,
             visible: generatedBodyVisible
         }
-        const edgeColor = Number(board.edgeColor)
-        const resolvedEdgeColor = Number.isInteger(edgeColor)
-            ? edgeColor
-            : 0xc9ca78
+        const resolvedEdgeColor =
+            PcbScene3dBoardMaterialPalette.resolveEdgeColor(board)
         const surfaceColor = hasBoardAssemblyModel
             ? resolvedEdgeColor
             : PcbScene3dBoardMaterialPalette.resolveBoardSurfaceColor(board, {