altium-toolkit 0.1.1 → 0.1.16

package/src/core/altium/PcbFontMetricsParser.mjs

@@ -0,0 +1,308 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Parses minimal sfnt metric tables from recovered embedded PCB fonts.
+ */
+export class PcbFontMetricsParser {
+    /**
+     * Parses font-family metrics from a TrueType/OpenType sfnt payload.
+     * @param {Uint8Array | ArrayBuffer} bytes
+     * @returns {{ format: 'truetype' | 'opentype' | 'unknown', unitsPerEm?: number, ascent?: number, descent?: number, lineGap?: number, cellHeight?: number, emScaleFromPcbHeight?: number, capHeight?: number, averageAdvanceWidth?: number, weightClass?: number, widthClass?: number }}
+     */
+    static parse(bytes) {
+        const normalizedBytes = PcbFontMetricsParser.#toUint8Array(bytes)
+        const view = new DataView(
+            normalizedBytes.buffer,
+            normalizedBytes.byteOffset,
+            normalizedBytes.byteLength
+        )
+
+        if (normalizedBytes.byteLength < 12) {
+            return { format: 'unknown' }
+        }
+
+        const format = PcbFontMetricsParser.#parseFormat(normalizedBytes)
+        if (format === 'unknown') {
+            return { format }
+        }
+
+        const tables = PcbFontMetricsParser.#parseTableDirectory(view)
+        const head = PcbFontMetricsParser.#readHeadTable(
+            view,
+            tables.get('head')
+        )
+        const hhea = PcbFontMetricsParser.#readHheaTable(
+            view,
+            tables.get('hhea')
+        )
+        const os2 = PcbFontMetricsParser.#readOs2Table(view, tables.get('OS/2'))
+        const hmtx = PcbFontMetricsParser.#readHmtxTable(
+            view,
+            tables.get('hmtx'),
+            hhea.numberOfHMetrics
+        )
+        const cellHeight =
+            Number.isFinite(hhea.ascent) && Number.isFinite(hhea.descent)
+                ? hhea.ascent + Math.abs(hhea.descent)
+                : undefined
+        const metrics = {
+            format,
+            ...head,
+            ...hhea,
+            cellHeight,
+            emScaleFromPcbHeight:
+                head.unitsPerEm && cellHeight
+                    ? head.unitsPerEm / cellHeight
+                    : undefined,
+            ...os2,
+            averageAdvanceWidth:
+                hmtx.averageAdvanceWidth || os2.averageAdvanceWidth
+        }
+
+        return Object.fromEntries(
+            Object.entries(metrics).filter(
+                ([key, value]) =>
+                    key !== 'numberOfHMetrics' &&
+                    value !== undefined &&
+                    (typeof value === 'string' || Number.isFinite(value))
+            )
+        )
+    }
+
+    /**
+     * Resolves the sfnt flavor from the first four bytes.
+     * @param {Uint8Array} bytes
+     * @returns {'truetype' | 'opentype' | 'unknown'}
+     */
+    static #parseFormat(bytes) {
+        const signature = String.fromCharCode(...bytes.subarray(0, 4))
+
+        if (
+            bytes[0] === 0x00 &&
+            bytes[1] === 0x01 &&
+            bytes[2] === 0x00 &&
+            bytes[3] === 0x00
+        ) {
+            return 'truetype'
+        }
+
+        if (signature === 'true' || signature === 'typ1') {
+            return 'truetype'
+        }
+
+        if (signature === 'OTTO') {
+            return 'opentype'
+        }
+
+        return 'unknown'
+    }
+
+    /**
+     * Reads the sfnt table directory.
+     * @param {DataView} view
+     * @returns {Map<string, { offset: number, length: number }>}
+     */
+    static #parseTableDirectory(view) {
+        const tables = new Map()
+        const tableCount = PcbFontMetricsParser.#readUint16(view, 4)
+
+        for (let index = 0; index < tableCount; index += 1) {
+            const recordOffset = 12 + index * 16
+            if (recordOffset + 16 > view.byteLength) {
+                break
+            }
+
+            const tag = PcbFontMetricsParser.#readTag(view, recordOffset)
+            const offset = PcbFontMetricsParser.#readUint32(
+                view,
+                recordOffset + 8
+            )
+            const length = PcbFontMetricsParser.#readUint32(
+                view,
+                recordOffset + 12
+            )
+
+            if (offset + length <= view.byteLength) {
+                tables.set(tag, { offset, length })
+            }
+        }
+
+        return tables
+    }
+
+    /**
+     * Reads the units-per-em value from the `head` table.
+     * @param {DataView} view
+     * @param {{ offset: number, length: number } | undefined} table
+     * @returns {{ unitsPerEm?: number }}
+     */
+    static #readHeadTable(view, table) {
+        if (!PcbFontMetricsParser.#tableHasBytes(table, 20)) {
+            return {}
+        }
+
+        return {
+            unitsPerEm: PcbFontMetricsParser.#readUint16(
+                view,
+                table.offset + 18
+            )
+        }
+    }
+
+    /**
+     * Reads ascent, descent, and metric-count data from the `hhea` table.
+     * @param {DataView} view
+     * @param {{ offset: number, length: number } | undefined} table
+     * @returns {{ ascent?: number, descent?: number, lineGap?: number, numberOfHMetrics?: number }}
+     */
+    static #readHheaTable(view, table) {
+        if (!PcbFontMetricsParser.#tableHasBytes(table, 36)) {
+            return {}
+        }
+
+        return {
+            ascent: PcbFontMetricsParser.#readInt16(view, table.offset + 4),
+            descent: PcbFontMetricsParser.#readInt16(view, table.offset + 6),
+            lineGap: PcbFontMetricsParser.#readInt16(view, table.offset + 8),
+            numberOfHMetrics: PcbFontMetricsParser.#readUint16(
+                view,
+                table.offset + 34
+            )
+        }
+    }
+
+    /**
+     * Reads typography metadata from the `OS/2` table.
+     * @param {DataView} view
+     * @param {{ offset: number, length: number } | undefined} table
+     * @returns {{ averageAdvanceWidth?: number, weightClass?: number, widthClass?: number, capHeight?: number }}
+     */
+    static #readOs2Table(view, table) {
+        if (!PcbFontMetricsParser.#tableHasBytes(table, 8)) {
+            return {}
+        }
+
+        const version = PcbFontMetricsParser.#readUint16(view, table.offset)
+        const metrics = {
+            averageAdvanceWidth: PcbFontMetricsParser.#readInt16(
+                view,
+                table.offset + 2
+            ),
+            weightClass: PcbFontMetricsParser.#readUint16(
+                view,
+                table.offset + 4
+            ),
+            widthClass: PcbFontMetricsParser.#readUint16(view, table.offset + 6)
+        }
+
+        if (version >= 2 && PcbFontMetricsParser.#tableHasBytes(table, 90)) {
+            metrics.capHeight = PcbFontMetricsParser.#readInt16(
+                view,
+                table.offset + 88
+            )
+        }
+
+        return metrics
+    }
+
+    /**
+     * Reads horizontal advance data from the `hmtx` table.
+     * @param {DataView} view
+     * @param {{ offset: number, length: number } | undefined} table
+     * @param {number | undefined} numberOfHMetrics
+     * @returns {{ averageAdvanceWidth?: number }}
+     */
+    static #readHmtxTable(view, table, numberOfHMetrics) {
+        if (!PcbFontMetricsParser.#tableHasBytes(table, 4)) {
+            return {}
+        }
+
+        const metricCount = Math.max(Number(numberOfHMetrics) || 1, 1)
+        const maxMetricCount = Math.min(
+            metricCount,
+            Math.floor(table.length / 4)
+        )
+        let totalAdvanceWidth = 0
+
+        for (let index = 0; index < maxMetricCount; index += 1) {
+            totalAdvanceWidth += PcbFontMetricsParser.#readUint16(
+                view,
+                table.offset + index * 4
+            )
+        }
+
+        return {
+            averageAdvanceWidth: Math.round(totalAdvanceWidth / maxMetricCount)
+        }
+    }
+
+    /**
+     * Returns true when a table record contains at least the requested length.
+     * @param {{ offset: number, length: number } | undefined} table
+     * @param {number} minimumLength
+     * @returns {boolean}
+     */
+    static #tableHasBytes(table, minimumLength) {
+        return Boolean(table && table.length >= minimumLength)
+    }
+
+    /**
+     * Reads one four-character table tag.
+     * @param {DataView} view
+     * @param {number} offset
+     * @returns {string}
+     */
+    static #readTag(view, offset) {
+        return String.fromCharCode(
+            view.getUint8(offset),
+            view.getUint8(offset + 1),
+            view.getUint8(offset + 2),
+            view.getUint8(offset + 3)
+        )
+    }
+
+    /**
+     * Reads one big-endian unsigned 16-bit integer.
+     * @param {DataView} view
+     * @param {number} offset
+     * @returns {number}
+     */
+    static #readUint16(view, offset) {
+        return offset + 2 <= view.byteLength ? view.getUint16(offset, false) : 0
+    }
+
+    /**
+     * Reads one big-endian signed 16-bit integer.
+     * @param {DataView} view
+     * @param {number} offset
+     * @returns {number}
+     */
+    static #readInt16(view, offset) {
+        return offset + 2 <= view.byteLength ? view.getInt16(offset, false) : 0
+    }
+
+    /**
+     * Reads one big-endian unsigned 32-bit integer.
+     * @param {DataView} view
+     * @param {number} offset
+     * @returns {number}
+     */
+    static #readUint32(view, offset) {
+        return offset + 4 <= view.byteLength ? view.getUint32(offset, false) : 0
+    }
+
+    /**
+     * Normalizes byte-like input into a Uint8Array view.
+     * @param {Uint8Array | ArrayBuffer} bytes
+     * @returns {Uint8Array}
+     */
+    static #toUint8Array(bytes) {
+        if (bytes instanceof Uint8Array) {
+            return bytes
+        }
+
+        return new Uint8Array(bytes || new ArrayBuffer(0))
+    }
+}

package/src/core/altium/PcbGeometryFlipper.mjs

@@ -0,0 +1,244 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Mirrors normalized PCB primitive coordinates into SVG top-view space.
+ */
+export class PcbGeometryFlipper {
+    /**
+     * Mirrors one normalized PCB model vertically.
+     * @param {{ boardOutline: { minX: number, minY: number, widthMil: number, heightMil: number, segments: Array<Record<string, number | string>> }, polygons?: { layer?: string, segments: Array<Record<string, number | string>> }[], 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 }[], vias?: { x: number, y: number, diameter: number, holeDiameter: number }[], pads?: { x: number, y: number, rotation?: number, holeRotation?: number | null }[], regions?: { points?: object[], holes?: object[][] }[], shapeBasedRegions?: { points?: object[], holes?: object[][] }[], boardRegions?: { points?: object[], holes?: object[][] }[], texts?: { x: number, y: number, rotation?: number }[], components?: { designator: string, x: number, y: number, rotation: number, layer: string, pattern: string }[] }} pcb
+     * @returns {object}
+     */
+    static flipGeometryVertically(pcb) {
+        const outline = pcb?.boardOutline
+        const maxY =
+            Number(outline?.minY || 0) + Number(outline?.heightMil || 0)
+        const mirrorY = (value) =>
+            Number(outline?.minY || 0) + maxY - Number(value || 0)
+
+        return {
+            ...pcb,
+            boardOutline: {
+                ...outline,
+                segments: (outline?.segments || []).map((segment) =>
+                    PcbGeometryFlipper.#flipSegment(segment, mirrorY)
+                )
+            },
+            polygons: (pcb?.polygons || []).map((polygon) => ({
+                ...polygon,
+                segments: (polygon.segments || []).map((segment) =>
+                    PcbGeometryFlipper.#flipSegment(segment, mirrorY)
+                )
+            })),
+            fills: PcbGeometryFlipper.#flipFills(pcb?.fills || [], mirrorY),
+            tracks: (pcb?.tracks || []).map((track) => ({
+                ...track,
+                y1: mirrorY(track.y1),
+                y2: mirrorY(track.y2)
+            })),
+            arcs: (pcb?.arcs || []).map((arc) => ({
+                ...arc,
+                y: mirrorY(arc.y),
+                startAngle: PcbGeometryFlipper.#normalizeAngle(
+                    360 - Number(arc.startAngle || 0)
+                ),
+                endAngle: PcbGeometryFlipper.#normalizeAngle(
+                    360 - Number(arc.endAngle || 0)
+                )
+            })),
+            vias: (pcb?.vias || []).map((via) => ({
+                ...via,
+                y: mirrorY(via.y)
+            })),
+            pads: (pcb?.pads || []).map((pad) =>
+                PcbGeometryFlipper.#flipPad(pad, mirrorY)
+            ),
+            regions: PcbGeometryFlipper.#flipRegions(
+                pcb?.regions || [],
+                mirrorY
+            ),
+            shapeBasedRegions: PcbGeometryFlipper.#flipRegions(
+                pcb?.shapeBasedRegions || [],
+                mirrorY
+            ),
+            boardRegions: PcbGeometryFlipper.#flipRegions(
+                pcb?.boardRegions || [],
+                mirrorY
+            ),
+            texts: (pcb?.texts || []).map((text) => ({
+                ...text,
+                y: mirrorY(text.y),
+                rotation: PcbGeometryFlipper.#normalizeAngle(
+                    360 - Number(text.rotation || 0)
+                )
+            })),
+            components: (pcb?.components || []).map((component) => ({
+                ...component,
+                y: mirrorY(component.y),
+                rotation: PcbGeometryFlipper.#normalizeAngle(
+                    360 - Number(component.rotation || 0)
+                )
+            }))
+        }
+    }
+
+    /**
+     * Mirrors rectangular fill extents across the board Y axis.
+     * @param {{ y1: number, y2: number }[]} fills
+     * @param {(value: number) => number} mirrorY
+     * @returns {object[]}
+     */
+    static #flipFills(fills, mirrorY) {
+        return fills.map((fill) => {
+            const y1 = mirrorY(fill.y1)
+            const y2 = mirrorY(fill.y2)
+
+            return {
+                ...fill,
+                y1: Math.min(y1, y2),
+                y2: Math.max(y1, y2)
+            }
+        })
+    }
+
+    /**
+     * Mirrors one pad center and rotation across the board Y axis.
+     * @param {{ y: number, rotation?: number, holeRotation?: number | null }} pad
+     * @param {(value: number) => number} mirrorY
+     * @returns {object}
+     */
+    static #flipPad(pad, mirrorY) {
+        return {
+            ...pad,
+            y: mirrorY(pad.y),
+            rotation: PcbGeometryFlipper.#normalizeAngle(
+                360 - Number(pad.rotation || 0)
+            ),
+            holeRotation:
+                pad?.holeRotation === null || pad?.holeRotation === undefined
+                    ? (pad?.holeRotation ?? null)
+                    : PcbGeometryFlipper.#normalizeAngle(
+                          360 - Number(pad.holeRotation || 0)
+                      )
+        }
+    }
+
+    /**
+     * Mirrors one outline or polygon segment across the board Y axis.
+     * @param {Record<string, number | string>} segment
+     * @param {(value: number) => number} mirrorY
+     * @returns {Record<string, number | string>}
+     */
+    static #flipSegment(segment, mirrorY) {
+        if (segment.type !== 'arc') {
+            return {
+                ...segment,
+                y1: mirrorY(Number(segment.y1 || 0)),
+                y2: mirrorY(Number(segment.y2 || 0))
+            }
+        }
+
+        const startAngle = Number(segment.startAngle || 0)
+        const endAngle = Number(segment.endAngle || 0)
+
+        return {
+            ...segment,
+            y1: mirrorY(Number(segment.y1 || 0)),
+            y2: mirrorY(Number(segment.y2 || 0)),
+            cy: mirrorY(Number(segment.cy || 0)),
+            startAngle: PcbGeometryFlipper.#normalizeAngle(360 - startAngle),
+            endAngle: PcbGeometryFlipper.#normalizeAngle(360 - endAngle)
+        }
+    }
+
+    /**
+     * Mirrors filled region contours and holes across the board Y axis.
+     * @param {{ points?: object[], holes?: object[][] }[]} regions
+     * @param {(value: number) => number} mirrorY
+     * @returns {object[]}
+     */
+    static #flipRegions(regions, mirrorY) {
+        return regions.map((region) => ({
+            ...region,
+            points: PcbGeometryFlipper.#flipRegionPoints(
+                region.points || [],
+                mirrorY
+            ),
+            holes: (region.holes || []).map((hole) =>
+                PcbGeometryFlipper.#flipRegionPoints(hole, mirrorY)
+            ),
+            ...(Array.isArray(region.bendingLines)
+                ? {
+                      bendingLines: PcbGeometryFlipper.#flipBendingLines(
+                          region.bendingLines,
+                          mirrorY
+                      )
+                  }
+                : {})
+        }))
+    }
+
+    /**
+     * Mirrors board-region bending-line endpoints across the board Y axis.
+     * @param {{ y1?: number | null, y2?: number | null }[]} bendingLines
+     * @param {(value: number) => number} mirrorY
+     * @returns {object[]}
+     */
+    static #flipBendingLines(bendingLines, mirrorY) {
+        return bendingLines.map((line) => ({
+            ...line,
+            y1:
+                line.y1 === null || line.y1 === undefined
+                    ? (line.y1 ?? null)
+                    : mirrorY(line.y1),
+            y2:
+                line.y2 === null || line.y2 === undefined
+                    ? (line.y2 ?? null)
+                    : mirrorY(line.y2)
+        }))
+    }
+
+    /**
+     * Mirrors one region point list across the board Y axis.
+     * @param {object[]} points
+     * @param {(value: number) => number} mirrorY
+     * @returns {object[]}
+     */
+    static #flipRegionPoints(points, mirrorY) {
+        return points.map((point) => {
+            const nextPoint = {
+                ...point,
+                y: mirrorY(point.y)
+            }
+
+            if (point.centerY !== null && point.centerY !== undefined) {
+                nextPoint.centerY = mirrorY(point.centerY)
+            }
+            if (point.startAngle !== null && point.startAngle !== undefined) {
+                nextPoint.startAngle = PcbGeometryFlipper.#normalizeAngle(
+                    360 - Number(point.startAngle || 0)
+                )
+            }
+            if (point.endAngle !== null && point.endAngle !== undefined) {
+                nextPoint.endAngle = PcbGeometryFlipper.#normalizeAngle(
+                    360 - Number(point.endAngle || 0)
+                )
+            }
+
+            return nextPoint
+        })
+    }
+
+    /**
+     * Normalizes one circular angle into the [0, 360) range.
+     * @param {number} angle
+     * @returns {number}
+     */
+    static #normalizeAngle(angle) {
+        const normalized = Number(angle || 0) % 360
+
+        return normalized < 0 ? normalized + 360 : normalized
+    }
+}

package/src/core/altium/PcbLayerIdCodec.mjs

@@ -0,0 +1,136 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Converts Altium legacy and V7 saved layer identifiers into stable layer IDs.
+ */
+export class PcbLayerIdCodec {
+    static #TOP_SIGNAL_LAYER_ID = 1
+
+    static #BOTTOM_SIGNAL_LAYER_ID = 32
+
+    static #INTERNAL_PLANE_1_LAYER_ID = 39
+
+    static #MECHANICAL_1_LAYER_ID = 57
+
+    static #SIGNAL_LAYER_PREFIX = 0x01000000
+
+    static #INTERNAL_PLANE_PREFIX = 0x01010000
+
+    static #MECHANICAL_LAYER_PREFIX = 0x01020000
+
+    static #SYSTEM_LAYER_PREFIX = 0x01030000
+
+    /**
+     * Decodes a V7 saved layer id into the corresponding legacy layer id.
+     * @param {unknown} savedLayerId
+     * @returns {number | null}
+     */
+    static legacyLayerIdFromV7SaveId(savedLayerId) {
+        const saved = Number(savedLayerId)
+        if (!Number.isInteger(saved) || saved === 0) {
+            return null
+        }
+
+        if (saved >= 0x01000001 && saved <= 0x0100001f) {
+            return saved - PcbLayerIdCodec.#SIGNAL_LAYER_PREFIX
+        }
+        if (saved === 0x0100ffff) {
+            return PcbLayerIdCodec.#BOTTOM_SIGNAL_LAYER_ID
+        }
+        if (saved >= 0x01010001 && saved <= 0x01010010) {
+            return (
+                PcbLayerIdCodec.#INTERNAL_PLANE_1_LAYER_ID +
+                (saved - 0x01010001)
+            )
+        }
+        if (saved >= 0x01020001 && saved <= 0x01020010) {
+            return PcbLayerIdCodec.#MECHANICAL_1_LAYER_ID + (saved - 0x01020001)
+        }
+        if ((saved & 0xffff0000) === PcbLayerIdCodec.#SYSTEM_LAYER_PREFIX) {
+            return PcbLayerIdCodec.#systemLayerIdFromPartition(saved & 0xffff)
+        }
+
+        return null
+    }
+
+    /**
+     * Builds the V7 saved-layer id for a known legacy layer id.
+     * @param {unknown} layerId
+     * @returns {number | null}
+     */
+    static v7SaveIdFromLegacyLayerId(layerId) {
+        const legacy = Number(layerId)
+        if (!Number.isInteger(legacy) || legacy <= 0) {
+            return null
+        }
+
+        if (
+            legacy >= PcbLayerIdCodec.#TOP_SIGNAL_LAYER_ID &&
+            legacy < PcbLayerIdCodec.#BOTTOM_SIGNAL_LAYER_ID
+        ) {
+            return PcbLayerIdCodec.#SIGNAL_LAYER_PREFIX + legacy
+        }
+        if (legacy === PcbLayerIdCodec.#BOTTOM_SIGNAL_LAYER_ID) {
+            return 0x0100ffff
+        }
+        if (legacy >= 39 && legacy <= 54) {
+            return PcbLayerIdCodec.#INTERNAL_PLANE_PREFIX + (legacy - 38)
+        }
+        if (legacy >= 57 && legacy <= 72) {
+            return PcbLayerIdCodec.#MECHANICAL_LAYER_PREFIX + (legacy - 56)
+        }
+
+        return PcbLayerIdCodec.#systemPartitionFromLayerId(legacy)
+    }
+
+    /**
+     * Converts one fixed V7 system-layer partition into a legacy layer id.
+     * @param {number} partition
+     * @returns {number | null}
+     */
+    static #systemLayerIdFromPartition(partition) {
+        return (
+            {
+                6: 33,
+                7: 34,
+                8: 35,
+                9: 36,
+                10: 37,
+                11: 38,
+                12: 55,
+                13: 56,
+                14: 73,
+                15: 74,
+                16: 75
+            }[partition] || null
+        )
+    }
+
+    /**
+     * Converts one fixed legacy system layer into a V7 saved-layer id.
+     * @param {number} layerId
+     * @returns {number | null}
+     */
+    static #systemPartitionFromLayerId(layerId) {
+        const partition =
+            {
+                33: 6,
+                34: 7,
+                35: 8,
+                36: 9,
+                37: 10,
+                38: 11,
+                55: 12,
+                56: 13,
+                73: 14,
+                74: 15,
+                75: 16
+            }[layerId] || null
+
+        return partition === null
+            ? null
+            : PcbLayerIdCodec.#SYSTEM_LAYER_PREFIX + partition
+    }
+}