altium-toolkit 0.1.23 → 1.0.2

package/src/ui/PcbScene3dBoardOutlineRefiner.mjs

@@ -0,0 +1,402 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Refines Altium 3D board outlines when parser recovery emitted a rasterized
+ * stair-step contour even though the document still carries a smoother board
+ * region contour.
+ */
+export class PcbScene3dBoardOutlineRefiner {
+    static #MIN_RASTERIZED_SEGMENTS = 16
+    static #MIN_SHORT_SEGMENT_RATIO = 0.35
+    static #MIN_AXIS_ALIGNED_RATIO = 0.9
+    static #SHORT_SEGMENT_MAX_MIL = 24
+    static #POINT_EPSILON_MIL = 0.25
+    static #AREA_RATIO_MIN = 0.75
+    static #AREA_RATIO_MAX = 1.25
+
+    /**
+     * Returns a scene description with a refined board outline when a better
+     * board-region contour is available.
+     * @param {object} sceneDescription Built scene description.
+     * @param {object} documentModel Source PCB document model.
+     * @returns {object}
+     */
+    static refine(sceneDescription, documentModel) {
+        const board = sceneDescription?.board
+        const segments = Array.isArray(board?.segments) ? board.segments : []
+
+        if (
+            !PcbScene3dBoardOutlineRefiner.#isRasterizedManhattanOutline(
+                segments
+            )
+        ) {
+            return sceneDescription
+        }
+
+        const currentOutline =
+            documentModel?.pcb?.boardOutline || sceneDescription?.board || {}
+        const candidate = PcbScene3dBoardOutlineRefiner.#selectCandidate(
+            documentModel?.pcb?.boardRegions,
+            currentOutline
+        )
+
+        if (!candidate) {
+            return sceneDescription
+        }
+
+        return {
+            ...sceneDescription,
+            board: {
+                ...board,
+                minX: candidate.minX,
+                minY: candidate.minY,
+                widthMil: candidate.widthMil,
+                heightMil: candidate.heightMil,
+                centerX: candidate.minX + candidate.widthMil / 2,
+                centerY: candidate.minY + candidate.heightMil / 2,
+                segments: candidate.segments
+            }
+        }
+    }
+
+    /**
+     * Returns true when an outline looks like a raster-grid recovery of a
+     * curved board route instead of authored geometric segments.
+     * @param {Array<Record<string, number | string>>} segments Outline segments.
+     * @returns {boolean}
+     */
+    static #isRasterizedManhattanOutline(segments) {
+        if (
+            segments.length <
+            PcbScene3dBoardOutlineRefiner.#MIN_RASTERIZED_SEGMENTS
+        ) {
+            return false
+        }
+
+        if (segments.some((segment) => segment.type === 'arc')) {
+            return false
+        }
+
+        let axisAlignedCount = 0
+        let shortSegmentCount = 0
+
+        for (const segment of segments) {
+            const dx = Math.abs(
+                Number(segment.x2 || 0) - Number(segment.x1 || 0)
+            )
+            const dy = Math.abs(
+                Number(segment.y2 || 0) - Number(segment.y1 || 0)
+            )
+            const length = Math.hypot(dx, dy)
+
+            if (dx <= 0.001 || dy <= 0.001) {
+                axisAlignedCount += 1
+            }
+            if (
+                length <= PcbScene3dBoardOutlineRefiner.#SHORT_SEGMENT_MAX_MIL
+            ) {
+                shortSegmentCount += 1
+            }
+        }
+
+        return (
+            axisAlignedCount / segments.length >=
+                PcbScene3dBoardOutlineRefiner.#MIN_AXIS_ALIGNED_RATIO &&
+            shortSegmentCount / segments.length >=
+                PcbScene3dBoardOutlineRefiner.#MIN_SHORT_SEGMENT_RATIO
+        )
+    }
+
+    /**
+     * Chooses the best compatible board-region contour.
+     * @param {object[] | undefined} regions Candidate board regions.
+     * @param {object} currentOutline Current outline bounds and segments.
+     * @returns {object | null}
+     */
+    static #selectCandidate(regions, currentOutline) {
+        const currentBounds =
+            PcbScene3dBoardOutlineRefiner.#resolveOutlineBounds(currentOutline)
+        if (!currentBounds) {
+            return null
+        }
+
+        const currentArea = Math.abs(
+            PcbScene3dBoardOutlineRefiner.#computeAreaFromSegments(
+                currentOutline?.segments || []
+            )
+        )
+        const candidates = (Array.isArray(regions) ? regions : [])
+            .filter((region) =>
+                PcbScene3dBoardOutlineRefiner.#isBoardRegionCandidate(region)
+            )
+            .map((region) =>
+                PcbScene3dBoardOutlineRefiner.#buildOutlineFromPoints(
+                    region.points
+                )
+            )
+            .filter(Boolean)
+            .filter((outline) =>
+                PcbScene3dBoardOutlineRefiner.#boundsAreCompatible(
+                    currentBounds,
+                    outline
+                )
+            )
+            .filter((outline) =>
+                PcbScene3dBoardOutlineRefiner.#areaIsCompatible(
+                    currentArea,
+                    outline
+                )
+            )
+            .map((outline) => ({
+                outline,
+                score: PcbScene3dBoardOutlineRefiner.#scoreBounds(
+                    currentBounds,
+                    outline
+                )
+            }))
+            .sort((left, right) => left.score - right.score)
+
+        return candidates[0]?.outline || null
+    }
+
+    /**
+     * Returns true when a region can represent the board body boundary.
+     * @param {object} region Source board region.
+     * @returns {boolean}
+     */
+    static #isBoardRegionCandidate(region) {
+        return (
+            Array.isArray(region?.points) &&
+            region.points.length >= 3 &&
+            (region?.objectKind === 'BoardRegion' ||
+                region?.isBoardCutout === true ||
+                Number.isInteger(region?.boardRegionIndex))
+        )
+    }
+
+    /**
+     * Converts one point loop into outline bounds and line segments.
+     * @param {{ x?: number, y?: number }[] | undefined} points Source points.
+     * @returns {object | null}
+     */
+    static #buildOutlineFromPoints(points) {
+        const normalizedPoints =
+            PcbScene3dBoardOutlineRefiner.#normalizePointLoop(points)
+
+        if (normalizedPoints.length < 3) {
+            return null
+        }
+
+        let minX = Number.POSITIVE_INFINITY
+        let minY = Number.POSITIVE_INFINITY
+        let maxX = Number.NEGATIVE_INFINITY
+        let maxY = Number.NEGATIVE_INFINITY
+
+        for (const point of normalizedPoints) {
+            minX = Math.min(minX, point.x)
+            minY = Math.min(minY, point.y)
+            maxX = Math.max(maxX, point.x)
+            maxY = Math.max(maxY, point.y)
+        }
+
+        const segments = normalizedPoints.map((point, index) => {
+            const next = normalizedPoints[(index + 1) % normalizedPoints.length]
+
+            return {
+                type: 'line',
+                x1: point.x,
+                y1: point.y,
+                x2: next.x,
+                y2: next.y
+            }
+        })
+
+        return {
+            minX,
+            minY,
+            widthMil: maxX - minX,
+            heightMil: maxY - minY,
+            segments
+        }
+    }
+
+    /**
+     * Normalizes finite points and drops duplicated adjacent points.
+     * @param {{ x?: number, y?: number }[] | undefined} points Source points.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #normalizePointLoop(points) {
+        const output = []
+
+        for (const point of Array.isArray(points) ? points : []) {
+            const nextPoint = {
+                x: Number(point?.x),
+                y: Number(point?.y)
+            }
+
+            if (
+                !Number.isFinite(nextPoint.x) ||
+                !Number.isFinite(nextPoint.y)
+            ) {
+                continue
+            }
+
+            if (
+                output.length &&
+                PcbScene3dBoardOutlineRefiner.#distanceBetween(
+                    output[output.length - 1],
+                    nextPoint
+                ) <= PcbScene3dBoardOutlineRefiner.#POINT_EPSILON_MIL
+            ) {
+                continue
+            }
+
+            output.push(nextPoint)
+        }
+
+        if (
+            output.length > 1 &&
+            PcbScene3dBoardOutlineRefiner.#distanceBetween(
+                output[0],
+                output[output.length - 1]
+            ) <= PcbScene3dBoardOutlineRefiner.#POINT_EPSILON_MIL
+        ) {
+            output.pop()
+        }
+
+        return output
+    }
+
+    /**
+     * Resolves bounds from an outline object.
+     * @param {object} outline Outline-like object.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number, widthMil: number, heightMil: number } | null}
+     */
+    static #resolveOutlineBounds(outline) {
+        const minX = Number(outline?.minX)
+        const minY = Number(outline?.minY)
+        const widthMil = Number(outline?.widthMil)
+        const heightMil = Number(outline?.heightMil)
+
+        if (
+            !Number.isFinite(minX) ||
+            !Number.isFinite(minY) ||
+            !Number.isFinite(widthMil) ||
+            !Number.isFinite(heightMil) ||
+            widthMil <= 0 ||
+            heightMil <= 0
+        ) {
+            return null
+        }
+
+        return {
+            minX,
+            minY,
+            maxX: minX + widthMil,
+            maxY: minY + heightMil,
+            widthMil,
+            heightMil
+        }
+    }
+
+    /**
+     * Returns true when a candidate's envelope matches the current board.
+     * @param {object} current Current outline bounds.
+     * @param {object} candidate Candidate outline bounds.
+     * @returns {boolean}
+     */
+    static #boundsAreCompatible(current, candidate) {
+        const tolerance = Math.max(
+            Math.max(current.widthMil, current.heightMil) * 0.06,
+            40
+        )
+        const candidateBounds =
+            PcbScene3dBoardOutlineRefiner.#resolveOutlineBounds(candidate)
+
+        if (!candidateBounds) {
+            return false
+        }
+
+        return (
+            Math.abs(current.minX - candidateBounds.minX) <= tolerance &&
+            Math.abs(current.minY - candidateBounds.minY) <= tolerance &&
+            Math.abs(current.maxX - candidateBounds.maxX) <= tolerance &&
+            Math.abs(current.maxY - candidateBounds.maxY) <= tolerance
+        )
+    }
+
+    /**
+     * Returns true when the candidate area is close enough to the fallback.
+     * @param {number} currentArea Current outline area.
+     * @param {object} candidate Candidate outline.
+     * @returns {boolean}
+     */
+    static #areaIsCompatible(currentArea, candidate) {
+        if (!currentArea) {
+            return true
+        }
+
+        const candidateArea = Math.abs(
+            PcbScene3dBoardOutlineRefiner.#computeAreaFromSegments(
+                candidate?.segments || []
+            )
+        )
+        const ratio = candidateArea / currentArea
+
+        return (
+            ratio >= PcbScene3dBoardOutlineRefiner.#AREA_RATIO_MIN &&
+            ratio <= PcbScene3dBoardOutlineRefiner.#AREA_RATIO_MAX
+        )
+    }
+
+    /**
+     * Scores how closely candidate bounds match current bounds.
+     * @param {object} current Current outline bounds.
+     * @param {object} candidate Candidate outline bounds.
+     * @returns {number}
+     */
+    static #scoreBounds(current, candidate) {
+        const candidateBounds =
+            PcbScene3dBoardOutlineRefiner.#resolveOutlineBounds(candidate)
+
+        if (!candidateBounds) {
+            return Number.POSITIVE_INFINITY
+        }
+
+        return (
+            Math.abs(current.minX - candidateBounds.minX) +
+            Math.abs(current.minY - candidateBounds.minY) +
+            Math.abs(current.maxX - candidateBounds.maxX) +
+            Math.abs(current.maxY - candidateBounds.maxY)
+        )
+    }
+
+    /**
+     * Computes signed area from line segments.
+     * @param {Array<Record<string, number | string>>} segments Outline segments.
+     * @returns {number}
+     */
+    static #computeAreaFromSegments(segments) {
+        let area = 0
+
+        for (const segment of segments) {
+            area +=
+                Number(segment.x1 || 0) * Number(segment.y2 || 0) -
+                Number(segment.x2 || 0) * Number(segment.y1 || 0)
+        }
+
+        return area / 2
+    }
+
+    /**
+     * Measures the distance between two points.
+     * @param {{ x: number, y: number }} left First point.
+     * @param {{ x: number, y: number }} right Second point.
+     * @returns {number}
+     */
+    static #distanceBetween(left, right) {
+        return Math.hypot(right.x - left.x, right.y - left.y)
+    }
+}

package/src/ui/PcbScene3dBuilder.mjs

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { PcbEdgeFacingGlyphNormalizer } from './PcbEdgeFacingGlyphNormalizer.mjs'
+import { PcbScene3dBoardOutlineRefiner } from './PcbScene3dBoardOutlineRefiner.mjs'
 import { PcbScene3dDrillCutoutBuilder } from './PcbScene3dDrillCutoutBuilder.mjs'
 import { PcbFootprintPrimitiveSelector } from './PcbFootprintPrimitiveSelector.mjs'
 import { PcbScene3dPackages } from './PcbScene3dPackages.mjs'
@@ -99,7 +100,7 @@ export class PcbScene3dBuilder {
             appearance3d
         )
 
-        return {
+        const sceneDescription = {
             sourceFormat: 'altium',
             board,
             components: components.map((component) =>
@@ -139,6 +140,11 @@ export class PcbScene3dBuilder {
                 }
             }
         }
+
+        return PcbScene3dBoardOutlineRefiner.refine(
+            sceneDescription,
+            documentModel
+        )
     }
 
     /**
@@ -729,6 +735,11 @@ export class PcbScene3dBuilder {
             boardOutline
         )
 
+        const drillCutouts = PcbScene3dDrillCutoutBuilder.buildCutouts(
+            pads,
+            vias
+        )
+
         return {
             ...normalized,
             denseOverlayArtwork,
@@ -743,11 +754,11 @@ export class PcbScene3dBuilder {
                 side
             ),
             tracks: normalized.tracks,
-            fills: PcbScene3dDrillCutoutBuilder.clipFills(
+            fills: PcbScene3dDrillCutoutBuilder.clipFillsWithCutouts(
                 fillsWithRegions,
-                pads,
-                vias
-            )
+                drillCutouts
+            ),
+            drillCutouts: drillCutouts.map((cutout) => cutout.points)
         }
     }
 

package/src/ui/PcbScene3dDrillCutoutBuilder.mjs

@@ -10,6 +10,19 @@ export class PcbScene3dDrillCutoutBuilder {
     static #SLOT_CAP_SEGMENTS = 12
     static #EPSILON = 0.001
 
+    /**
+     * Builds all known drill cutout contours.
+     * @param {{ x?: number, y?: number, holeDiameter?: number, drillDiameter?: number, holeSlotLength?: number, slotLength?: number, rotation?: number, holeRotation?: number }[]} pads
+     * @param {{ x?: number, y?: number, holeDiameter?: number, drillDiameter?: number }[]} vias
+     * @returns {{ x: number, y: number, bounds: { minX: number, minY: number, maxX: number, maxY: number }, points: { x: number, y: number }[] }[]}
+     */
+    static buildCutouts(pads, vias) {
+        return [
+            ...PcbScene3dDrillCutoutBuilder.#buildPadCutouts(pads),
+            ...PcbScene3dDrillCutoutBuilder.#buildViaCutouts(vias)
+        ]
+    }
+
     /**
      * Adds drill-shaped holes to every fill intersected by a pad or via drill.
      * @param {{ points?: { x: number, y: number }[], holes?: { x: number, y: number }[][], x1?: number, y1?: number, x2?: number, y2?: number }[]} fills
@@ -18,9 +31,20 @@ export class PcbScene3dDrillCutoutBuilder {
      * @returns {{ points?: { x: number, y: number }[], holes?: { x: number, y: number }[][], x1?: number, y1?: number, x2?: number, y2?: number }[]}
      */
     static clipFills(fills, pads, vias) {
-        const cutouts = PcbScene3dDrillCutoutBuilder.#buildCutouts(pads, vias)
+        return PcbScene3dDrillCutoutBuilder.clipFillsWithCutouts(
+            fills,
+            PcbScene3dDrillCutoutBuilder.buildCutouts(pads, vias)
+        )
+    }
 
-        if (!cutouts.length) {
+    /**
+     * Adds drill-shaped holes from precomputed cutouts.
+     * @param {{ points?: { x: number, y: number }[], holes?: { x: number, y: number }[][], x1?: number, y1?: number, x2?: number, y2?: number }[]} fills
+     * @param {{ x: number, y: number, bounds: { minX: number, minY: number, maxX: number, maxY: number }, points: { x: number, y: number }[] }[]} cutouts
+     * @returns {{ points?: { x: number, y: number }[], holes?: { x: number, y: number }[][], x1?: number, y1?: number, x2?: number, y2?: number }[]}
+     */
+    static clipFillsWithCutouts(fills, cutouts) {
+        if (!Array.isArray(cutouts) || !cutouts.length) {
             return fills
         }
 
@@ -48,19 +72,6 @@ export class PcbScene3dDrillCutoutBuilder {
         })
     }
 
-    /**
-     * Builds all known drill cutout contours.
-     * @param {{ x?: number, y?: number, holeDiameter?: number, drillDiameter?: number, holeSlotLength?: number, slotLength?: number, rotation?: number, holeRotation?: number }[]} pads
-     * @param {{ x?: number, y?: number, holeDiameter?: number, drillDiameter?: number }[]} vias
-     * @returns {{ x: number, y: number, bounds: { minX: number, minY: number, maxX: number, maxY: number }, points: { x: number, y: number }[] }[]}
-     */
-    static #buildCutouts(pads, vias) {
-        return [
-            ...PcbScene3dDrillCutoutBuilder.#buildPadCutouts(pads),
-            ...PcbScene3dDrillCutoutBuilder.#buildViaCutouts(vias)
-        ]
-    }
-
     /**
      * Builds drill contours for drilled pads.
      * @param {{ x?: number, y?: number, holeDiameter?: number, drillDiameter?: number, holeSlotLength?: number, slotLength?: number, rotation?: number, holeRotation?: number }[]} pads

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