altium-toolkit 0.1.0

package/src/core/altium/PcbStreamExtractor.mjs

@@ -0,0 +1,210 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { AsciiRecordParser } from './AsciiRecordParser.mjs'
+import { PcbBinaryPrimitiveParser } from './PcbBinaryPrimitiveParser.mjs'
+import { PcbEmbeddedModelExtractor } from './PcbEmbeddedModelExtractor.mjs'
+import { OleCompoundDocument } from '../ole/OleCompoundDocument.mjs'
+import { OleConstants } from '../ole/OleConstants.mjs'
+
+/**
+ * Extracts stream-scoped printable and binary PCB content from OLE-backed
+ * PcbDoc containers.
+ */
+export class PcbStreamExtractor {
+    /**
+     * Returns true when one buffer starts with the OLE compound-document
+     * signature.
+     * @param {ArrayBuffer} arrayBuffer
+     * @returns {boolean}
+     */
+    static isCompoundDocument(arrayBuffer) {
+        const bytes = new Uint8Array(
+            arrayBuffer,
+            0,
+            Math.min(
+                arrayBuffer.byteLength,
+                OleConstants.HEADER_SIGNATURE.length
+            )
+        )
+
+        if (bytes.byteLength < OleConstants.HEADER_SIGNATURE.length) {
+            return false
+        }
+
+        return OleConstants.HEADER_SIGNATURE.every(
+            (value, index) => bytes[index] === value
+        )
+    }
+
+    /**
+     * Extracts PCB content directly from one OLE-backed PcbDoc buffer.
+     * @param {ArrayBuffer} arrayBuffer
+     * @returns {{ records: Array<{ raw: string, fields: Record<string, string | string[]>, sourceStream: string }>, streamNames: string[], binaryPrimitives: { fills: { x1: number, y1: number, x2: number, y2: number, layerCode: number }[], tracks: { x1: number, y1: number, x2: number, y2: number, width: number, layerCode: 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, sizeTopX: number, sizeTopY: number, sizeMidX: number, sizeMidY: number, sizeBottomX: number, sizeBottomY: number, holeDiameter: number, shapeTop: number, shapeMid: number, shapeBottom: number, rotation: number, isPlated: boolean }[] }, diagnostics: { printableRecordCount: number, printableStreamCount: number, binaryPrimitiveCount: number } } | null}
+     */
+    static extractFromArrayBuffer(arrayBuffer) {
+        if (!PcbStreamExtractor.isCompoundDocument(arrayBuffer)) {
+            return null
+        }
+
+        const compoundDocument =
+            OleCompoundDocument.fromArrayBuffer(arrayBuffer)
+        const streams = new Map()
+
+        for (const name of compoundDocument.listStreams()) {
+            streams.set(name, compoundDocument.getStream(name))
+        }
+
+        return PcbStreamExtractor.extractFromStreams(streams)
+    }
+
+    /**
+     * Extracts stream-scoped printable records and known binary primitives from
+     * a stream map.
+     * @param {Map<string, Uint8Array>} streams
+     * @returns {{ records: Array<{ raw: string, fields: Record<string, string | string[]>, sourceStream: string }>, streamNames: string[], binaryPrimitives: { fills: { x1: number, y1: number, x2: number, y2: number, layerCode: number }[], tracks: { x1: number, y1: number, x2: number, y2: number, width: number, layerCode: 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, sizeTopX: number, sizeTopY: number, sizeMidX: number, sizeMidY: number, sizeBottomX: number, sizeBottomY: number, holeDiameter: number, shapeTop: number, shapeMid: number, shapeBottom: number, rotation: number, isPlated: boolean }[] }, diagnostics: { printableRecordCount: number, printableStreamCount: number, binaryPrimitiveCount: number } }}
+     */
+    static extractFromStreams(streams) {
+        const records = []
+        const printableStreamNames = new Set()
+        const usedStreamNames = new Set()
+        const binaryPrimitives = {
+            fills: [],
+            tracks: [],
+            arcs: [],
+            vias: [],
+            pads: []
+        }
+
+        for (const [name, bytes] of streams.entries()) {
+            if (!name.endsWith('/Data')) {
+                continue
+            }
+
+            const recordBuffer = PcbStreamExtractor.#toArrayBuffer(bytes)
+            const streamRecords = AsciiRecordParser.parse(recordBuffer).map(
+                (record) => ({
+                    ...record,
+                    sourceStream: name
+                })
+            )
+
+            if (!streamRecords.length) {
+                continue
+            }
+
+            records.push(...streamRecords)
+            printableStreamNames.add(name)
+            usedStreamNames.add(name)
+        }
+
+        const arcHeaderBytes = streams.get('Arcs6/Header')
+        const arcDataBytes = streams.get('Arcs6/Data')
+        const trackHeaderBytes = streams.get('Tracks6/Header')
+        const trackDataBytes = streams.get('Tracks6/Data')
+        const viaHeaderBytes = streams.get('Vias6/Header')
+        const viaDataBytes = streams.get('Vias6/Data')
+        const fillHeaderBytes = streams.get('Fills6/Header')
+        const fillDataBytes = streams.get('Fills6/Data')
+        const padHeaderBytes = streams.get('Pads6/Header')
+        const padDataBytes = streams.get('Pads6/Data')
+
+        if (arcHeaderBytes && arcDataBytes) {
+            binaryPrimitives.arcs = PcbBinaryPrimitiveParser.parseArcStream(
+                arcHeaderBytes,
+                arcDataBytes
+            )
+            if (binaryPrimitives.arcs.length) {
+                usedStreamNames.add('Arcs6/Data')
+            }
+        }
+
+        if (trackHeaderBytes && trackDataBytes) {
+            binaryPrimitives.tracks = PcbBinaryPrimitiveParser.parseTrackStream(
+                trackHeaderBytes,
+                trackDataBytes
+            )
+            if (binaryPrimitives.tracks.length) {
+                usedStreamNames.add('Tracks6/Data')
+            }
+        }
+
+        if (viaHeaderBytes && viaDataBytes) {
+            binaryPrimitives.vias = PcbBinaryPrimitiveParser.parseViaStream(
+                viaHeaderBytes,
+                viaDataBytes
+            )
+            if (binaryPrimitives.vias.length) {
+                usedStreamNames.add('Vias6/Data')
+            }
+        }
+
+        if (fillHeaderBytes && fillDataBytes) {
+            binaryPrimitives.fills = PcbBinaryPrimitiveParser.parseFillStream(
+                fillHeaderBytes,
+                fillDataBytes
+            )
+            if (binaryPrimitives.fills.length) {
+                usedStreamNames.add('Fills6/Data')
+            }
+        }
+
+        if (padHeaderBytes && padDataBytes) {
+            binaryPrimitives.pads = PcbBinaryPrimitiveParser.parsePadStream(
+                padHeaderBytes,
+                padDataBytes
+            )
+            if (binaryPrimitives.pads.length) {
+                usedStreamNames.add('Pads6/Data')
+            }
+        }
+
+        const embeddedModels =
+            PcbEmbeddedModelExtractor.extractFromStreams(streams)
+
+        if (
+            embeddedModels.models.length ||
+            embeddedModels.componentBodies.length
+        ) {
+            usedStreamNames.add('Models/Data')
+            embeddedModels.models.forEach((model) =>
+                usedStreamNames.add(model.sourceStream)
+            )
+            embeddedModels.componentBodies.forEach((componentBody) =>
+                usedStreamNames.add(componentBody.sourceStream)
+            )
+        }
+
+        return {
+            records,
+            streamNames: [...usedStreamNames].sort((left, right) =>
+                left.localeCompare(right)
+            ),
+            binaryPrimitives,
+            embeddedModels,
+            diagnostics: {
+                printableRecordCount: records.length,
+                printableStreamCount: printableStreamNames.size,
+                binaryPrimitiveCount:
+                    binaryPrimitives.arcs.length +
+                    binaryPrimitives.tracks.length +
+                    binaryPrimitives.vias.length +
+                    binaryPrimitives.fills.length +
+                    binaryPrimitives.pads.length
+            }
+        }
+    }
+
+    /**
+     * Normalizes one byte view into an isolated ArrayBuffer.
+     * @param {Uint8Array} bytes
+     * @returns {ArrayBuffer}
+     */
+    static #toArrayBuffer(bytes) {
+        return bytes.buffer.slice(
+            bytes.byteOffset,
+            bytes.byteOffset + bytes.byteLength
+        )
+    }
+}

package/src/core/altium/PrintableTextDecoder.mjs

@@ -0,0 +1,156 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Extracts long printable runs from binary Altium documents.
+ */
+export class PrintableTextDecoder {
+    /**
+     * Returns printable ASCII-like runs from a binary buffer.
+     * @param {ArrayBuffer} arrayBuffer
+     * @param {{ minLength?: number }} [options]
+     * @returns {string[]}
+     */
+    static extractRuns(arrayBuffer, options = {}) {
+        return PrintableTextDecoder.extractRunBytes(arrayBuffer, options).map(
+            (runBytes) =>
+                PrintableTextDecoder.#normalizeRun(
+                    PrintableTextDecoder.decodeBytes(runBytes)
+                )
+        )
+    }
+
+    /**
+     * Returns printable byte runs from a binary buffer.
+     * @param {ArrayBuffer} arrayBuffer
+     * @param {{ minLength?: number }} [options]
+     * @returns {Uint8Array[]}
+     */
+    static extractRunBytes(arrayBuffer, options = {}) {
+        const minLength = Number(options.minLength) || 24
+        const bytes = new Uint8Array(arrayBuffer)
+        const runs = []
+        let start = -1
+
+        for (let index = 0; index < bytes.length; index += 1) {
+            if (PrintableTextDecoder.#isPrintableByte(bytes[index])) {
+                if (start === -1) {
+                    start = index
+                }
+                continue
+            }
+
+            if (start !== -1) {
+                PrintableTextDecoder.#pushRunBytes(
+                    runs,
+                    bytes,
+                    start,
+                    index,
+                    minLength
+                )
+                start = -1
+            }
+        }
+
+        if (start !== -1) {
+            PrintableTextDecoder.#pushRunBytes(
+                runs,
+                bytes,
+                start,
+                bytes.length,
+                minLength
+            )
+        }
+
+        return runs
+    }
+
+    /**
+     * Decodes one byte slice using UTF-8 first, then GB18030 for non-UTF-8
+     * payloads such as legacy PCB library text.
+     * @param {Uint8Array} bytes
+     * @param {{ encoding?: string }} [options]
+     * @returns {string}
+     */
+    static decodeBytes(bytes, options = {}) {
+        const preferredEncoding = String(options.encoding || '').toLowerCase()
+
+        if (preferredEncoding === 'utf-8') {
+            return (
+                PrintableTextDecoder.#tryDecode(bytes, 'utf-8') ||
+                new TextDecoder('utf-8').decode(bytes)
+            )
+        }
+
+        return (
+            PrintableTextDecoder.#tryDecode(bytes, 'utf-8') ||
+            PrintableTextDecoder.#tryDecode(bytes, 'gb18030') ||
+            new TextDecoder('utf-8').decode(bytes)
+        )
+    }
+
+    /**
+     * Normalizes one printable byte slice and appends it if meaningful.
+     * @param {string[]} runs
+     * @param {Uint8Array} bytes
+     * @param {number} start
+     * @param {number} end
+     * @param {number} minLength
+     */
+    static #pushRunBytes(runs, bytes, start, end, minLength) {
+        const length = end - start
+        if (length < minLength) return
+
+        const slice = bytes.slice(start, end)
+        const normalized = PrintableTextDecoder.#normalizeRun(
+            PrintableTextDecoder.decodeBytes(slice)
+        )
+
+        if (normalized.length < minLength) return
+        if (!normalized.includes('|') || !normalized.includes('=')) return
+
+        runs.push(slice)
+    }
+
+    /**
+     * Returns true for bytes commonly preserved in printable record runs.
+     * @param {number} value
+     * @returns {boolean}
+     */
+    static #isPrintableByte(value) {
+        return (
+            value === 9 ||
+            value === 10 ||
+            value === 13 ||
+            (value >= 32 && value <= 126) ||
+            value >= 128
+        )
+    }
+
+    /**
+     * Returns one normalized printable run.
+     * @param {string} raw
+     * @returns {string}
+     */
+    static #normalizeRun(raw) {
+        return raw
+            .replace(/\r/g, '\n')
+            .replace(/\n{2,}/g, '\n')
+            .trim()
+    }
+
+    /**
+     * Tries one strict decode and returns null when bytes are invalid for it.
+     * @param {Uint8Array} bytes
+     * @param {string} encoding
+     * @returns {string | null}
+     */
+    static #tryDecode(bytes, encoding) {
+        try {
+            return new TextDecoder(encoding, { fatal: true }).decode(bytes)
+        } catch {
+            return null
+        }
+    }
+}

package/src/core/altium/SchematicAnnotationParser.mjs

@@ -0,0 +1,220 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+/**
+ * Helpers for synthesized schematic annotations recovered from source metadata.
+ */
+export class SchematicAnnotationParser {
+    /**
+     * Builds synthesized schematic text annotations from non-visible component
+     * metadata that is still recoverable from the source file.
+     * @param {{ fields: Record<string, string | string[]> }[]} records
+     * @param {{ x: number, y: number, length: number, name: string, designator: string, orientation: 'left' | 'right' | 'top' | 'bottom', color: string, labelColor?: string, labelMode?: 'hidden' | 'number-only' | 'name-only' | 'name-and-number', ownerIndex: string }[]} pins
+     * @param {Record<string, { size: number, family: string, bold: boolean, rotation: number }>} fonts
+     * @returns {{ x: number, y: number, text: string, color: string, hidden: boolean, name: string, recordType: string, style: number, fontSize: number, fontFamily: string, fontWeight: number, rotation: number, anchor: 'start' | 'middle' | 'end' }[]}
+     */
+    static buildSchematicSyntheticTexts(records, pins, fonts) {
+        const connectorGroups =
+            SchematicAnnotationParser.#buildConnectorPinGroups(pins)
+        const connectorComponents = records
+            .filter(
+                (record) =>
+                    ParserUtils.getField(record.fields, 'RECORD') === '1'
+            )
+            .map((record) =>
+                SchematicAnnotationParser.#normalizeConnectorComponent(
+                    record.fields
+                )
+            )
+            .filter(Boolean)
+
+        if (!connectorGroups.length || !connectorComponents.length) {
+            return []
+        }
+
+        const font =
+            fonts['1'] || SchematicAnnotationParser.#defaultAnnotationFont()
+        const availableGroups = connectorGroups.slice()
+        const texts = []
+
+        for (const component of connectorComponents) {
+            const closestIndex =
+                SchematicAnnotationParser.#findClosestConnectorGroupIndex(
+                    component,
+                    availableGroups
+                )
+            if (closestIndex === -1) continue
+
+            const [group] = availableGroups.splice(closestIndex, 1)
+
+            texts.push({
+                x: group.centerX,
+                y: group.minY - 20,
+                text: component.annotation,
+                color: '#000080',
+                hidden: false,
+                name: 'Comment',
+                recordType: 'annotation',
+                style: 0,
+                fontSize: SchematicAnnotationParser.#toSvgFontSize(font.size),
+                fontFamily: font.family,
+                fontWeight: 400,
+                rotation: 0,
+                anchor: 'middle'
+            })
+        }
+
+        return texts
+    }
+
+    /**
+     * Collects the number-only dual-row connector pin groups used by J6/J8.
+     * @param {{ x: number, y: number, length: number, name: string, designator: string, orientation: 'left' | 'right' | 'top' | 'bottom', color: string, labelColor?: string, labelMode?: 'hidden' | 'number-only' | 'name-only' | 'name-and-number', ownerIndex: string }[]} pins
+     * @returns {{ ownerIndex: string, centerX: number, centerY: number, minY: number }[]}
+     */
+    static #buildConnectorPinGroups(pins) {
+        const groups = new Map()
+
+        for (const pin of pins) {
+            if (!groups.has(pin.ownerIndex)) {
+                groups.set(pin.ownerIndex, [])
+            }
+
+            groups.get(pin.ownerIndex).push(pin)
+        }
+
+        return [...groups.values()]
+            .filter(
+                (group) =>
+                    group.length === 6 &&
+                    group[0].labelMode === 'number-only' &&
+                    group.every((pin) => /^\d+$/.test(pin.name))
+            )
+            .map((group) => {
+                const xs = group.map((pin) => pin.x)
+                const ys = group.map((pin) => pin.y)
+
+                return {
+                    ownerIndex: group[0].ownerIndex,
+                    centerX: (Math.min(...xs) + Math.max(...xs)) / 2,
+                    centerY: (Math.min(...ys) + Math.max(...ys)) / 2,
+                    minY: Math.min(...ys)
+                }
+            })
+            .sort((left, right) => right.centerY - left.centerY)
+    }
+
+    /**
+     * Normalizes one connector component record when it should emit a
+     * synthesized schematic annotation.
+     * @param {Record<string, string | string[]>} fields
+     * @returns {{ x: number, y: number, annotation: string } | null}
+     */
+    static #normalizeConnectorComponent(fields) {
+        const libReference = ParserUtils.getField(fields, 'LibReference')
+        const x = ParserUtils.parseNumericField(fields, 'Location.X')
+        const y = ParserUtils.parseNumericField(fields, 'Location.Y')
+        const annotation =
+            SchematicAnnotationParser.#formatConnectorAnnotation(libReference)
+
+        if (!annotation || x === null || y === null) {
+            return null
+        }
+
+        return { x, y, annotation }
+    }
+
+    /**
+     * Formats a closer-to-Altium connector note from the library reference.
+     * @param {string} libReference
+     * @returns {string}
+     */
+    static #formatConnectorAnnotation(libReference) {
+        const normalized = String(libReference || '').trim()
+        const upper = normalized.toUpperCase()
+        const hasConnectorKeyword =
+            /\b(CON|CONN|CONNECTOR|HDR|HEADER)\b/.test(upper) ||
+            /\b\d+X\d+P\b/.test(upper)
+
+        if (!hasConnectorKeyword) {
+            return ''
+        }
+
+        const notes = ['HEADER']
+        const pitch =
+            /PH\s*([0-9.]+)/i.exec(normalized)?.[1] ||
+            /PITCH[_ =-]*([0-9.]+)/i.exec(normalized)?.[1]
+        const pinFormat = /\b(\d+X\d+P)\b/i.exec(upper)?.[1]
+        const length = /L=([0-9.]+)/i.exec(normalized)?.[1] || ''
+
+        if (pitch) {
+            notes.push('P' + pitch)
+        }
+
+        if (pinFormat) {
+            notes.push(pinFormat)
+        }
+
+        if (/\b(straight|vertical)\b/i.test(normalized)) {
+            notes.push('VERTICAL')
+        } else if (/\b(right angle|horizontal)\b/i.test(normalized)) {
+            notes.push('RIGHT-ANGLE')
+        }
+
+        if (length) {
+            notes.push('L=' + length)
+        }
+
+        return notes.join(' ')
+    }
+
+    /**
+     * Finds the nearest available connector pin group for one component record.
+     * @param {{ x: number, y: number, annotation: string }} component
+     * @param {{ ownerIndex: string, centerX: number, centerY: number, minY: number }[]} groups
+     * @returns {number}
+     */
+    static #findClosestConnectorGroupIndex(component, groups) {
+        let closestIndex = -1
+        let closestDistance = Number.POSITIVE_INFINITY
+
+        for (let index = 0; index < groups.length; index += 1) {
+            const group = groups[index]
+            const distance =
+                Math.abs(group.centerX - component.x) +
+                Math.abs(group.centerY - component.y)
+
+            if (distance < closestDistance) {
+                closestDistance = distance
+                closestIndex = index
+            }
+        }
+
+        return closestIndex
+    }
+
+    /**
+     * Returns the default sheet font used for synthetic annotations.
+     * @returns {{ size: number, family: string, bold: boolean, rotation: number }}
+     */
+    static #defaultAnnotationFont() {
+        return {
+            size: 10,
+            family: 'Times New Roman',
+            bold: false,
+            rotation: 0
+        }
+    }
+
+    /**
+     * Converts Altium point sizes into SVG font units.
+     * @param {number} size
+     * @returns {number}
+     */
+    static #toSvgFontSize(size) {
+        return Number(size || 10)
+    }
+}

package/src/core/altium/SchematicBusEntryParser.mjs

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+const { getField, parseNumericField, toColor } = ParserUtils
+
+/**
+ * Normalizes authored schematic bus-entry records.
+ */
+export class SchematicBusEntryParser {
+    /**
+     * Parses schematic bus-entry markers from `RECORD=37`.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex: number }[]} records
+     * @returns {{ x1: number, y1: number, x2: number, y2: number, color: string, width: number, renderOrder: number }[]}
+     */
+    static parseSchematicBusEntries(records) {
+        return records
+            .map((record) => {
+                if (getField(record.fields, 'RECORD') !== '37') {
+                    return null
+                }
+
+                const x1 = parseNumericField(record.fields, 'Location.X')
+                const y1 = parseNumericField(record.fields, 'Location.Y')
+                const x2 = parseNumericField(record.fields, 'Corner.X')
+                const y2 = parseNumericField(record.fields, 'Corner.Y')
+
+                if (x1 === null || y1 === null || x2 === null || y2 === null) {
+                    return null
+                }
+
+                return {
+                    x1,
+                    y1,
+                    x2,
+                    y2,
+                    color: toColor(record.fields.Color, '#000080'),
+                    width: parseNumericField(record.fields, 'LineWidth') || 1,
+                    renderOrder:
+                        parseNumericField(record.fields, 'IndexInSheet') ??
+                        record.recordIndex
+                }
+            })
+            .filter(Boolean)
+    }
+}

package/src/core/altium/SchematicDirectiveParser.mjs

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+/**
+ * Helpers for normalized schematic directive primitives.
+ */
+export class SchematicDirectiveParser {
+    /**
+     * Normalizes schematic directive records into drawable directive metadata.
+     * @param {{ fields: Record<string, string | string[]> }[]} records
+     * @returns {{ x: number, y: number, color: string, name: string, orientation: number }[]}
+     */
+    static parseSchematicDirectives(records) {
+        return records
+            .map((record) => {
+                const x = ParserUtils.parseNumericField(
+                    record.fields,
+                    'Location.X'
+                )
+                const y = ParserUtils.parseNumericField(
+                    record.fields,
+                    'Location.Y'
+                )
+                const name = ParserUtils.getField(record.fields, 'Name')
+
+                if (x === null || y === null || !name) {
+                    return null
+                }
+
+                return {
+                    x,
+                    y,
+                    color: ParserUtils.toColor(record.fields.Color, '#ff0000'),
+                    name,
+                    orientation:
+                        ParserUtils.parseNumericField(
+                            record.fields,
+                            'Orientation'
+                        ) || 0
+                }
+            })
+            .filter(Boolean)
+    }
+}