altium-toolkit 1.0.1 → 1.0.7

package/src/styles/altium-renderers.css

@@ -141,6 +141,7 @@
     --pcb-via-hole-fill: #0f746c;
     --pcb-footprint-fill: rgba(247, 230, 117, 0.14);
     --pcb-footprint-track-color: rgba(237, 172, 36, 1);
+    --pcb-text-knockout-fill: rgba(248, 246, 239, 0.96);
     --pcb-component-top-fill: rgba(244, 219, 198, 0.92);
     --pcb-component-bottom-fill: rgba(15, 116, 108, 0.84);
     --pcb-component-stroke: rgba(110, 64, 38, 0.28);
@@ -178,6 +179,8 @@
     fill: var(--pcb-board-fill);
     stroke: var(--pcb-board-stroke);
     stroke-width: 18;
+    stroke-linecap: round;
+    stroke-linejoin: round;
 }
 
 .board-outline--stroke {
@@ -252,7 +255,7 @@
 }
 
 .pcb-footprint-region {
-    fill: var(--pcb-footprint-track-color);
+    fill: var(--pcb-footprint-region-fill, var(--pcb-footprint-track-color));
 }
 
 .pcb-footprint-track,
@@ -278,6 +281,14 @@
     pointer-events: none;
 }
 
+.pcb-text__knockout-fill {
+    fill: var(--pcb-text-knockout-fill);
+}
+
+.pcb-text__knockout-glyphs {
+    fill: #000;
+}
+
 .bom-panel {
     display: grid;
     gap: 1rem;

package/src/ui/PcbNativeTextKnockoutDetector.mjs

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Detects native overlay artwork that already contains text knockout holes.
+ */
+export class PcbNativeTextKnockoutDetector {
+    static #DENSE_OVERLAY_MIN_REGION_AREA_RATIO = 0.2
+    static #DENSE_OVERLAY_MIN_TRACK_COUNT = 250
+
+    /**
+     * Returns true when side-resolved overlay primitives carry native text
+     * knockouts, so source inverted TrueType labels would duplicate artwork.
+     * @param {{ fills?: object[], regions?: object[], tracks?: object[], arcs?: object[] }} primitives Side-resolved overlay primitives.
+     * @param {{ widthMil?: number, heightMil?: number }} board Board bounds.
+     * @returns {boolean}
+     */
+    static hasNativeTextKnockouts(primitives, board) {
+        const fills = [
+            ...(Array.isArray(primitives?.fills) ? primitives.fills : []),
+            ...(Array.isArray(primitives?.regions) ? primitives.regions : [])
+        ]
+
+        return (
+            PcbNativeTextKnockoutDetector.#isDenseOverlayArtwork(
+                {
+                    fills,
+                    tracks: primitives?.tracks,
+                    arcs: primitives?.arcs
+                },
+                board
+            ) &&
+            fills.some(
+                (fill) => Array.isArray(fill?.holes) && fill.holes.length > 0
+            )
+        )
+    }
+
+    /**
+     * Detects dense overlay artwork from structural density.
+     * @param {{ fills?: object[], tracks?: object[], arcs?: object[] }} side Side primitives.
+     * @param {{ widthMil?: number, heightMil?: number }} board Board bounds.
+     * @returns {boolean}
+     */
+    static #isDenseOverlayArtwork(side, board) {
+        const strokeCount =
+            (Array.isArray(side?.tracks) ? side.tracks.length : 0) +
+            (Array.isArray(side?.arcs) ? side.arcs.length : 0)
+
+        return (
+            strokeCount >=
+                PcbNativeTextKnockoutDetector.#DENSE_OVERLAY_MIN_TRACK_COUNT &&
+            PcbNativeTextKnockoutDetector.#maxFillAreaRatio(
+                side?.fills,
+                board
+            ) >=
+                PcbNativeTextKnockoutDetector
+                    .#DENSE_OVERLAY_MIN_REGION_AREA_RATIO
+        )
+    }
+
+    /**
+     * Resolves the largest fill-to-board bounding-box area ratio.
+     * @param {object[] | undefined} fills Fill primitives.
+     * @param {{ widthMil?: number, heightMil?: number }} board Board bounds.
+     * @returns {number}
+     */
+    static #maxFillAreaRatio(fills, board) {
+        const boardArea =
+            Math.max(Number(board?.widthMil || 0), 0) *
+            Math.max(Number(board?.heightMil || 0), 0)
+        if (!boardArea) {
+            return 0
+        }
+
+        return (Array.isArray(fills) ? fills : []).reduce((maxRatio, fill) => {
+            const bounds =
+                PcbNativeTextKnockoutDetector.#resolveFillBounds(fill)
+            if (!bounds) {
+                return maxRatio
+            }
+
+            const fillArea =
+                Math.max(bounds.maxX - bounds.minX, 0) *
+                Math.max(bounds.maxY - bounds.minY, 0)
+
+            return Math.max(maxRatio, fillArea / boardArea)
+        }, 0)
+    }
+
+    /**
+     * Resolves rough authored bounds for one rectangular or polygon fill.
+     * @param {{ x1?: number, y1?: number, x2?: number, y2?: number, points?: { x?: number, y?: number }[] }} fill Fill primitive.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number } | null}
+     */
+    static #resolveFillBounds(fill) {
+        const points = Array.isArray(fill?.points)
+            ? fill.points
+                  .map((point) => ({
+                      x: Number(point?.x),
+                      y: Number(point?.y)
+                  }))
+                  .filter(
+                      (point) =>
+                          Number.isFinite(point.x) && Number.isFinite(point.y)
+                  )
+            : [
+                  { x: Number(fill?.x1), y: Number(fill?.y1) },
+                  { x: Number(fill?.x2), y: Number(fill?.y2) }
+              ].filter(
+                  (point) =>
+                      Number.isFinite(point.x) && Number.isFinite(point.y)
+              )
+
+        if (points.length < 2) {
+            return null
+        }
+
+        const xs = points.map((point) => point.x)
+        const ys = points.map((point) => point.y)
+
+        return {
+            minX: Math.min(...xs),
+            minY: Math.min(...ys),
+            maxX: Math.max(...xs),
+            maxY: Math.max(...ys)
+        }
+    }
+}

package/src/ui/PcbSvgRenderer.mjs

@@ -7,7 +7,9 @@ import { PcbEdgeFacingGlyphNormalizer } from './PcbEdgeFacingGlyphNormalizer.mjs
 import { PcbEmbeddedFontFaceRenderer } from './PcbEmbeddedFontFaceRenderer.mjs'
 import { PcbFootprintPrimitiveSelector } from './PcbFootprintPrimitiveSelector.mjs'
 import { PcbCopperPrimitiveSplitter } from './PcbCopperPrimitiveSplitter.mjs'
+import { PcbNativeTextKnockoutDetector } from './PcbNativeTextKnockoutDetector.mjs'
 import { PcbRegionPrimitiveRenderer } from './PcbRegionPrimitiveRenderer.mjs'
+import { PcbScene3dBoardOutlineRefiner } from './PcbScene3dBoardOutlineRefiner.mjs'
 import { PcbTextPrimitiveRenderer } from './PcbTextPrimitiveRenderer.mjs'
 import { SchematicSvgUtils } from './SchematicSvgUtils.mjs'
 /**
@@ -27,7 +29,10 @@ export class PcbSvgRenderer {
         if (!pcb) {
             return '<section class="altium-renderer-empty">No PCB entities were recovered from this file.</section>'
         }
-        const outline = pcb.boardOutline
+        const outline = PcbScene3dBoardOutlineRefiner.refine(
+            { board: pcb.boardOutline },
+            documentModel
+        ).board
         const polygons = pcb.polygons || []
         const fills = pcb.fills || []
         const tracks = pcb.tracks || []
@@ -43,11 +48,6 @@ export class PcbSvgRenderer {
         const stackLayers = Array.isArray(pcb.layers) ? pcb.layers : []
         const primitiveLayers = pcb.primitiveLayers || []
         const displayLayers = stackLayers.length ? stackLayers : primitiveLayers
-        const texts = PcbTextPrimitiveRenderer.select(
-            primitiveLayers,
-            pcb.texts || [],
-            'top'
-        )
         const copperGroups = PcbCopperPrimitiveSplitter.split(
             polygons,
             fills,
@@ -66,6 +66,18 @@ export class PcbSvgRenderer {
             ),
             outline
         )
+        const texts = PcbTextPrimitiveRenderer.select(
+            primitiveLayers,
+            pcb.texts || [],
+            'top',
+            {
+                nativeTextKnockouts:
+                    PcbNativeTextKnockoutDetector.hasNativeTextKnockouts(
+                        footprintPrimitives,
+                        outline
+                    )
+            }
+        )
         const path = PcbSvgRenderer.#buildBoardPath(outline.segments)
         const clipPathId = 'pcb-board-clip'
         const viewBox = PcbSvgRenderer.#buildViewBox(
@@ -256,6 +268,9 @@ export class PcbSvgRenderer {
             'pcb-footprint-region'
         )
         const textMarkup = PcbTextPrimitiveRenderer.render(texts)
+        const textGroupTransform = PcbSvgRenderer.#renderTextGroupTransform(
+            pcb.textGroupTransform
+        )
         const fontFaceMarkup = PcbEmbeddedFontFaceRenderer.buildMarkup(
             pcb.embeddedFonts || []
         )
@@ -355,17 +370,19 @@ export class PcbSvgRenderer {
             footprintArcMarkup +
             footprintRegionMarkup +
             '</g>' +
+            '<g class="pcb-components">' +
+            componentMarkup +
+            '</g>' +
             '<g class="pcb-texts" clip-path="url(#' +
             clipPathId +
-            ')">' +
+            ')"' +
+            textGroupTransform +
+            '>' +
             textMarkup +
             '</g>' +
             '<path class="board-outline board-outline--stroke" d="' +
             SchematicSvgUtils.escapeHtml(path) +
             '" />' +
-            '<g class="pcb-components">' +
-            componentMarkup +
-            '</g>' +
             '</svg></div></section>'
         )
     }
@@ -415,6 +432,62 @@ export class PcbSvgRenderer {
         return path + ' Z'
     }
 
+    /**
+     * Renders an optional transform for the whole PCB text layer.
+     * @param {{ translateX?: number, translateY?: number, scaleX?: number, scaleY?: number } | undefined} transform Text group transform.
+     * @returns {string}
+     */
+    static #renderTextGroupTransform(transform) {
+        if (!transform || typeof transform !== 'object') {
+            return ''
+        }
+
+        const translateX = Number(transform.translateX || 0)
+        const translateY = Number(transform.translateY || 0)
+        const scaleX =
+            transform.scaleX === null || transform.scaleX === undefined
+                ? 1
+                : Number(transform.scaleX)
+        const scaleY =
+            transform.scaleY === null || transform.scaleY === undefined
+                ? 1
+                : Number(transform.scaleY)
+        if (
+            !Number.isFinite(translateX) ||
+            !Number.isFinite(translateY) ||
+            !Number.isFinite(scaleX) ||
+            !Number.isFinite(scaleY) ||
+            (translateX === 0 &&
+                translateY === 0 &&
+                scaleX === 1 &&
+                scaleY === 1)
+        ) {
+            return ''
+        }
+
+        const parts = []
+        if (translateX !== 0 || translateY !== 0) {
+            parts.push(
+                'translate(' +
+                    SchematicSvgUtils.formatNumber(translateX) +
+                    ' ' +
+                    SchematicSvgUtils.formatNumber(translateY) +
+                    ')'
+            )
+        }
+        if (scaleX !== 1 || scaleY !== 1) {
+            parts.push(
+                'scale(' +
+                    SchematicSvgUtils.formatNumber(scaleX) +
+                    ' ' +
+                    SchematicSvgUtils.formatNumber(scaleY) +
+                    ')'
+            )
+        }
+
+        return ' transform="' + parts.join(' ') + '"'
+    }
+
     /**
      * Computes a reasonable viewBox.
      * @param {{ minX: number, minY: number, widthMil: number, heightMil: number, segments: Array<Record<string, number | string>> }} outline