altium-toolkit 0.1.0 → 0.1.16

package/src/ui/PcbEmbeddedFontFaceRenderer.mjs

@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Renders recovered embedded PCB fonts as self-contained SVG font faces.
+ */
+export class PcbEmbeddedFontFaceRenderer {
+    /**
+     * Builds self-contained SVG @font-face rules for recovered embedded fonts.
+     * @param {{ name?: string, style?: string, format?: string, mimeType?: string, payloadBase64?: string, metrics?: { weightClass?: number } }[]} embeddedFonts
+     * @returns {string}
+     */
+    static buildMarkup(embeddedFonts) {
+        const rules = (embeddedFonts || [])
+            .filter((font) => font?.name && font?.payloadBase64)
+            .map((font) => PcbEmbeddedFontFaceRenderer.#buildRule(font))
+
+        return rules.length ? '<style>' + rules.join('') + '</style>' : ''
+    }
+
+    /**
+     * Builds one CSS @font-face rule.
+     * @param {{ name?: string, style?: string, format?: string, mimeType?: string, payloadBase64?: string, metrics?: { weightClass?: number } }} font
+     * @returns {string}
+     */
+    static #buildRule(font) {
+        const family = PcbEmbeddedFontFaceRenderer.#escapeCssString(font.name)
+        const base64 = PcbEmbeddedFontFaceRenderer.#sanitizeBase64(
+            font.payloadBase64
+        )
+
+        return (
+            "@font-face{font-family: '" +
+            family +
+            "'; font-style: " +
+            PcbEmbeddedFontFaceRenderer.#fontStyleForFont(font) +
+            '; font-weight: ' +
+            PcbEmbeddedFontFaceRenderer.#fontWeightForFont(font) +
+            "; src: url('data:" +
+            PcbEmbeddedFontFaceRenderer.#fontMimeType(font) +
+            ';base64,' +
+            base64 +
+            "') format('" +
+            PcbEmbeddedFontFaceRenderer.#fontFormat(font) +
+            "');}"
+        )
+    }
+
+    /**
+     * Resolves a CSS font-style value from embedded font metadata.
+     * @param {{ style?: string }} font
+     * @returns {'normal' | 'italic'}
+     */
+    static #fontStyleForFont(font) {
+        return /italic|oblique/iu.test(String(font.style || ''))
+            ? 'italic'
+            : 'normal'
+    }
+
+    /**
+     * Resolves a CSS font-weight value from embedded font metadata.
+     * @param {{ style?: string, metrics?: { weightClass?: number } }} font
+     * @returns {number}
+     */
+    static #fontWeightForFont(font) {
+        if (Number(font.metrics?.weightClass) >= 100) {
+            return Number(font.metrics.weightClass)
+        }
+
+        return /bold/iu.test(String(font.style || '')) ? 700 : 400
+    }
+
+    /**
+     * Resolves a CSS font source MIME type.
+     * @param {{ mimeType?: string, format?: string }} font
+     * @returns {string}
+     */
+    static #fontMimeType(font) {
+        if (font.mimeType) {
+            return PcbEmbeddedFontFaceRenderer.#escapeCssUrlToken(font.mimeType)
+        }
+
+        return font.format === 'opentype' ? 'font/otf' : 'font/ttf'
+    }
+
+    /**
+     * Resolves a CSS font source format label.
+     * @param {{ format?: string }} font
+     * @returns {'opentype' | 'truetype'}
+     */
+    static #fontFormat(font) {
+        return font.format === 'opentype' ? 'opentype' : 'truetype'
+    }
+
+    /**
+     * Escapes a string for use inside a single-quoted CSS string.
+     * @param {string | undefined} value
+     * @returns {string}
+     */
+    static #escapeCssString(value) {
+        return String(value || '')
+            .replace(/\\/gu, '\\\\')
+            .replace(/'/gu, "\\'")
+            .replace(/\r?\n/gu, ' ')
+            .replace(/</gu, '\\3C ')
+    }
+
+    /**
+     * Keeps a base64 font payload constrained to data-URI-safe characters.
+     * @param {string | undefined} value
+     * @returns {string}
+     */
+    static #sanitizeBase64(value) {
+        return String(value || '').replace(/[^A-Za-z0-9+/=]/gu, '')
+    }
+
+    /**
+     * Escapes a short CSS URL token.
+     * @param {string | undefined} value
+     * @returns {string}
+     */
+    static #escapeCssUrlToken(value) {
+        return String(value || '').replace(/[^A-Za-z0-9./+-]/gu, '')
+    }
+}

package/src/ui/PcbFootprintPrimitiveSelector.mjs

@@ -13,12 +13,23 @@ export class PcbFootprintPrimitiveSelector {
      * @param {{ x1: number, y1: number, x2: number, y2: number, layerCode?: number, layerId?: number }[]} fills
      * @param {{ x1: number, y1: number, x2: number, y2: number, width: number, layerCode?: number, layerId?: number }[]} tracks
      * @param {{ x: number, y: number, radius: number, startAngle: number, endAngle: number, width: number, layerCode?: number, layerId?: number }[]} arcs
+     * @param {{ points?: object[], holes?: object[][], layerCode?: number, layerId?: number }[] | 'top' | 'bottom'} [regionsOrSide]
      * @param {'top' | 'bottom'} [side]
-     * @returns {{ fills: { x1: number, y1: number, x2: number, y2: number, layerCode?: number, layerId?: number }[], tracks: { x1: number, y1: number, x2: number, y2: number, width: number, layerCode?: number, layerId?: number }[], arcs: { x: number, y: number, radius: number, startAngle: number, endAngle: number, width: number, layerCode?: number, layerId?: number }[] }}
+     * @returns {{ fills: { x1: number, y1: number, x2: number, y2: number, layerCode?: number, layerId?: number }[], tracks: { x1: number, y1: number, x2: number, y2: number, width: number, layerCode?: number, layerId?: number }[], arcs: { x: number, y: number, radius: number, startAngle: number, endAngle: number, width: number, layerCode?: number, layerId?: number }[], regions: { points?: object[], holes?: object[][], layerCode?: number, layerId?: number }[] }}
      */
-    static select(primitiveLayers, fills, tracks, arcs, side = 'top') {
+    static select(
+        primitiveLayers,
+        fills,
+        tracks,
+        arcs,
+        regionsOrSide = [],
+        side = 'top'
+    ) {
+        const requestedSide =
+            typeof regionsOrSide === 'string' ? regionsOrSide : side
+        const regions = Array.isArray(regionsOrSide) ? regionsOrSide : []
         const prioritizedLayerMatchers =
-            PcbFootprintPrimitiveSelector.#resolveLayerMatchers(side)
+            PcbFootprintPrimitiveSelector.#resolveLayerMatchers(requestedSide)
 
         for (const matchesLayerName of prioritizedLayerMatchers) {
             const layerIds = new Set(
@@ -41,12 +52,21 @@ export class PcbFootprintPrimitiveSelector {
             const layerArcs = (arcs || []).filter((arc) =>
                 layerIds.has(arc.layerId)
             )
+            const layerRegions = regions.filter((region) =>
+                layerIds.has(region.layerId)
+            )
 
-            if (layerFills.length || layerTracks.length || layerArcs.length) {
+            if (
+                layerFills.length ||
+                layerTracks.length ||
+                layerArcs.length ||
+                layerRegions.length
+            ) {
                 return {
                     fills: layerFills,
                     tracks: layerTracks,
-                    arcs: layerArcs
+                    arcs: layerArcs,
+                    regions: layerRegions
                 }
             }
         }
@@ -54,7 +74,8 @@ export class PcbFootprintPrimitiveSelector {
         return {
             fills: [],
             tracks: [],
-            arcs: []
+            arcs: [],
+            regions: []
         }
     }
 

package/src/ui/PcbRegionPrimitiveRenderer.mjs

@@ -0,0 +1,243 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { SchematicSvgUtils } from './SchematicSvgUtils.mjs'
+
+/**
+ * Renders filled PCB region contours into SVG path markup.
+ */
+export class PcbRegionPrimitiveRenderer {
+    /**
+     * Builds SVG path markup for filled PCB regions.
+     * @param {{ points?: object[], holes?: object[][] }[]} regions
+     * @param {string} className
+     * @returns {string}
+     */
+    static buildMarkup(regions, className) {
+        return (regions || [])
+            .map((region) =>
+                PcbRegionPrimitiveRenderer.#renderRegion(region, className)
+            )
+            .join('')
+    }
+
+    /**
+     * Returns true when one region intersects a bounds object.
+     * @param {{ points?: { x: number, y: number }[], holes?: { x: number, y: number }[][] }} region
+     * @param {{ minX: number, minY: number, maxX: number, maxY: number }} bounds
+     * @returns {boolean}
+     */
+    static intersectsBounds(region, bounds) {
+        const regionBounds = PcbRegionPrimitiveRenderer.bounds(region)
+        if (!regionBounds) {
+            return false
+        }
+
+        return !(
+            regionBounds.maxX < bounds.minX ||
+            regionBounds.minX > bounds.maxX ||
+            regionBounds.maxY < bounds.minY ||
+            regionBounds.minY > bounds.maxY
+        )
+    }
+
+    /**
+     * Computes a bounding box for one filled region.
+     * @param {{ points?: { x: number, y: number }[], holes?: { x: number, y: number }[][] }} region
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number } | null}
+     */
+    static bounds(region) {
+        const points = [
+            ...(region?.points || []),
+            ...(region?.holes || []).flat()
+        ].filter(
+            (point) => Number.isFinite(point?.x) && Number.isFinite(point?.y)
+        )
+
+        if (!points.length) {
+            return null
+        }
+
+        return {
+            minX: Math.min(...points.map((point) => Number(point.x))),
+            minY: Math.min(...points.map((point) => Number(point.y))),
+            maxX: Math.max(...points.map((point) => Number(point.x))),
+            maxY: Math.max(...points.map((point) => Number(point.y)))
+        }
+    }
+
+    /**
+     * Pushes one region's extent into viewBox coordinate arrays.
+     * @param {number[]} xs
+     * @param {number[]} ys
+     * @param {{ points?: { x: number, y: number }[], holes?: { x: number, y: number }[][] }} region
+     */
+    static pushExtents(xs, ys, region) {
+        const bounds = PcbRegionPrimitiveRenderer.bounds(region)
+        if (!bounds) {
+            return
+        }
+
+        xs.push(bounds.minX, bounds.maxX)
+        ys.push(bounds.minY, bounds.maxY)
+    }
+
+    /**
+     * Renders one filled region path.
+     * @param {{ points?: object[], holes?: object[][] }} region
+     * @param {string} className
+     * @returns {string}
+     */
+    static #renderRegion(region, className) {
+        const path = PcbRegionPrimitiveRenderer.#buildRegionPath(region)
+        if (!path) {
+            return ''
+        }
+
+        return (
+            '<path class="' +
+            SchematicSvgUtils.escapeHtml(className) +
+            '" d="' +
+            SchematicSvgUtils.escapeHtml(path) +
+            '" fill-rule="evenodd" />'
+        )
+    }
+
+    /**
+     * Builds one SVG path containing the outline and holes.
+     * @param {{ points?: object[], holes?: object[][] }} region
+     * @returns {string}
+     */
+    static #buildRegionPath(region) {
+        const paths = [
+            PcbRegionPrimitiveRenderer.#buildPointPath(region?.points || [])
+        ]
+
+        for (const hole of region?.holes || []) {
+            paths.push(PcbRegionPrimitiveRenderer.#buildPointPath(hole))
+        }
+
+        return paths.filter(Boolean).join(' ')
+    }
+
+    /**
+     * Builds one closed contour path from region points.
+     * @param {object[]} points
+     * @returns {string}
+     */
+    static #buildPointPath(points) {
+        const contour =
+            PcbRegionPrimitiveRenderer.#withoutClosingDuplicate(points)
+        if (contour.length < 3) {
+            return ''
+        }
+
+        const [first] = contour
+        const commands = [
+            'M ' +
+                SchematicSvgUtils.formatNumber(first.x) +
+                ' ' +
+                SchematicSvgUtils.formatNumber(first.y)
+        ]
+
+        for (let index = 0; index < contour.length - 1; index += 1) {
+            const current = contour[index]
+            const next = contour[index + 1]
+            commands.push(
+                PcbRegionPrimitiveRenderer.#segmentCommand(current, next)
+            )
+        }
+
+        const last = contour[contour.length - 1]
+        if (PcbRegionPrimitiveRenderer.#isArcPoint(last)) {
+            commands.push(
+                PcbRegionPrimitiveRenderer.#segmentCommand(last, first)
+            )
+        }
+
+        commands.push('Z')
+        return commands.join(' ')
+    }
+
+    /**
+     * Builds one line or arc segment command.
+     * @param {object} current
+     * @param {object} next
+     * @returns {string}
+     */
+    static #segmentCommand(current, next) {
+        if (PcbRegionPrimitiveRenderer.#isArcPoint(current)) {
+            const delta =
+                PcbRegionPrimitiveRenderer.#normalizeAngle(
+                    Number(current.endAngle || 0) -
+                        Number(current.startAngle || 0)
+                ) || 360
+            return (
+                'A ' +
+                SchematicSvgUtils.formatNumber(current.radius) +
+                ' ' +
+                SchematicSvgUtils.formatNumber(current.radius) +
+                ' 0 ' +
+                (delta > 180 ? '1' : '0') +
+                ' ' +
+                (Number(current.endAngle || 0) >=
+                Number(current.startAngle || 0)
+                    ? '1'
+                    : '0') +
+                ' ' +
+                SchematicSvgUtils.formatNumber(next.x) +
+                ' ' +
+                SchematicSvgUtils.formatNumber(next.y)
+            )
+        }
+
+        return (
+            'L ' +
+            SchematicSvgUtils.formatNumber(next.x) +
+            ' ' +
+            SchematicSvgUtils.formatNumber(next.y)
+        )
+    }
+
+    /**
+     * Removes an explicit duplicate closing vertex when present.
+     * @param {object[]} points
+     * @returns {object[]}
+     */
+    static #withoutClosingDuplicate(points) {
+        if ((points || []).length < 2) {
+            return points || []
+        }
+
+        const first = points[0]
+        const last = points[points.length - 1]
+        if (
+            Math.abs(Number(first.x) - Number(last.x)) < 1e-6 &&
+            Math.abs(Number(first.y) - Number(last.y)) < 1e-6
+        ) {
+            return points.slice(0, -1)
+        }
+
+        return points
+    }
+
+    /**
+     * Checks whether one region point represents an arc segment.
+     * @param {object | undefined} point
+     * @returns {boolean}
+     */
+    static #isArcPoint(point) {
+        return Boolean(point?.isArc && Number(point.radius || 0) > 0)
+    }
+
+    /**
+     * Normalizes one angle delta into [0, 360).
+     * @param {number} angle
+     * @returns {number}
+     */
+    static #normalizeAngle(angle) {
+        const normalized = Number(angle || 0) % 360
+        return normalized < 0 ? normalized + 360 : normalized
+    }
+}