altium-toolkit 0.1.0 → 0.1.16

package/src/core/altium/PcbPrimitiveOwnershipIndexParser.mjs

@@ -0,0 +1,60 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Decodes nullable owner indexes shared by binary PCB primitive records.
+ */
+export class PcbPrimitiveOwnershipIndexParser {
+    /**
+     * Reads component, net, and polygon ownership indexes from one record.
+     * @param {DataView} view
+     * @param {{ component: number, net: number, polygon: number }} offsets
+     * @returns {{ componentIndex: number | null, netIndex: number | null, polygonIndex: number | null }}
+     */
+    static readOwnershipIndexes(view, offsets) {
+        return {
+            componentIndex: PcbPrimitiveOwnershipIndexParser.readComponentIndex(
+                view,
+                offsets.component
+            ),
+            netIndex: PcbPrimitiveOwnershipIndexParser.readLinkIndex(
+                view,
+                offsets.net
+            ),
+            polygonIndex: PcbPrimitiveOwnershipIndexParser.readLinkIndex(
+                view,
+                offsets.polygon
+            )
+        }
+    }
+
+    /**
+     * Reads one nullable component index.
+     * @param {DataView} view
+     * @param {number} offset
+     * @returns {number | null}
+     */
+    static readComponentIndex(view, offset) {
+        return PcbPrimitiveOwnershipIndexParser.readLinkIndex(view, offset)
+    }
+
+    /**
+     * Reads one nullable two-byte Altium object link index.
+     * @param {DataView} view
+     * @param {number} offset
+     * @returns {number | null}
+     */
+    static readLinkIndex(view, offset) {
+        if (
+            !Number.isInteger(offset) ||
+            offset < 0 ||
+            offset + 2 > view.byteLength
+        ) {
+            return null
+        }
+
+        const value = view.getUint16(offset, true)
+        return value === 0xffff ? null : value
+    }
+}

package/src/core/altium/PcbPrimitiveParameterParser.mjs

@@ -0,0 +1,212 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Decodes Altium PrimitiveParameters/Data sidecar records.
+ */
+export class PcbPrimitiveParameterParser {
+    /**
+     * Parses length-prefixed primitive parameter records.
+     * @param {Uint8Array | ArrayBuffer | undefined} dataBytes
+     * @returns {{ groups: { primitiveId: string, id: string, appurtenance: string, variantGuid: string, declaredCount: number | null, parameters: Record<string, string>, records: Record<string, string>[] }[], byPrimitiveId: Record<string, Record<string, string>> }}
+     */
+    static parse(dataBytes) {
+        const bytes = PcbPrimitiveParameterParser.#toUint8Array(dataBytes)
+        const groups = []
+        const groupsByPrimitiveId = new Map()
+        let currentGroup = null
+        let offset = 0
+
+        while (offset + 4 <= bytes.byteLength) {
+            const recordLength = PcbPrimitiveParameterParser.#readUint32(
+                bytes,
+                offset
+            )
+            offset += 4
+
+            if (recordLength < 0 || offset + recordLength > bytes.byteLength) {
+                break
+            }
+
+            const recordBytes = bytes.subarray(offset, offset + recordLength)
+            offset += recordLength
+
+            const fields =
+                PcbPrimitiveParameterParser.#parseRecordFields(recordBytes)
+            if (!Object.keys(fields).length) {
+                continue
+            }
+
+            const primitiveId = fields.PRIMITIVEID || ''
+            if (primitiveId) {
+                currentGroup = PcbPrimitiveParameterParser.#groupForPrimitiveId(
+                    primitiveId,
+                    fields,
+                    groups,
+                    groupsByPrimitiveId
+                )
+                currentGroup.records.push(fields)
+                continue
+            }
+
+            if (currentGroup) {
+                PcbPrimitiveParameterParser.#appendParameterRecord(
+                    currentGroup,
+                    fields
+                )
+            }
+        }
+
+        return {
+            groups,
+            byPrimitiveId:
+                PcbPrimitiveParameterParser.#buildPrimitiveParameterLookup(
+                    groups
+                )
+        }
+    }
+
+    /**
+     * Returns an existing group or creates one for a primitive unique ID.
+     * @param {string} primitiveId
+     * @param {Record<string, string>} fields
+     * @param {{ primitiveId: string, id: string, appurtenance: string, variantGuid: string, declaredCount: number | null, parameters: Record<string, string>, records: Record<string, string>[] }[]} groups
+     * @param {Map<string, { primitiveId: string, id: string, appurtenance: string, variantGuid: string, declaredCount: number | null, parameters: Record<string, string>, records: Record<string, string>[] }>} groupsByPrimitiveId
+     * @returns {{ primitiveId: string, id: string, appurtenance: string, variantGuid: string, declaredCount: number | null, parameters: Record<string, string>, records: Record<string, string>[] }}
+     */
+    static #groupForPrimitiveId(
+        primitiveId,
+        fields,
+        groups,
+        groupsByPrimitiveId
+    ) {
+        if (!groupsByPrimitiveId.has(primitiveId)) {
+            const group = {
+                primitiveId,
+                id: '',
+                appurtenance: '',
+                variantGuid: '',
+                declaredCount: null,
+                parameters: {},
+                records: []
+            }
+            groupsByPrimitiveId.set(primitiveId, group)
+            groups.push(group)
+        }
+
+        const group = groupsByPrimitiveId.get(primitiveId)
+        PcbPrimitiveParameterParser.#mergeGroupFields(group, fields)
+
+        return group
+    }
+
+    /**
+     * Merges group-level metadata fields into one primitive parameter group.
+     * @param {{ id: string, appurtenance: string, variantGuid: string, declaredCount: number | null }} group
+     * @param {Record<string, string>} fields
+     */
+    static #mergeGroupFields(group, fields) {
+        group.id = fields.ID || group.id
+        group.appurtenance = fields.APPURTENANCE || group.appurtenance
+        group.variantGuid = fields.VARIANTGUID || group.variantGuid
+
+        const declaredCount = Number(fields.COUNT)
+        if (Number.isInteger(declaredCount) && declaredCount > 0) {
+            group.declaredCount = declaredCount
+        }
+    }
+
+    /**
+     * Appends one name/value parameter record to a group.
+     * @param {{ parameters: Record<string, string>, records: Record<string, string>[] }} group
+     * @param {Record<string, string>} fields
+     */
+    static #appendParameterRecord(group, fields) {
+        const name = fields.NAME || ''
+
+        if (name) {
+            group.parameters[name] = fields.VALUE || ''
+        }
+
+        group.records.push(fields)
+    }
+
+    /**
+     * Builds a plain-object lookup keyed by primitive unique ID.
+     * @param {{ primitiveId: string, parameters: Record<string, string> }[]} groups
+     * @returns {Record<string, Record<string, string>>}
+     */
+    static #buildPrimitiveParameterLookup(groups) {
+        const byPrimitiveId = {}
+
+        for (const group of groups) {
+            byPrimitiveId[group.primitiveId] = { ...group.parameters }
+        }
+
+        return byPrimitiveId
+    }
+
+    /**
+     * Parses one pipe-delimited primitive parameter record.
+     * @param {Uint8Array} bytes
+     * @returns {Record<string, string>}
+     */
+    static #parseRecordFields(bytes) {
+        const text = new TextDecoder()
+            .decode(bytes)
+            .replace(/\u0000/gu, '')
+            .replace(/\r\n?/gu, '\n')
+            .trim()
+        const fields = {}
+
+        for (const segment of text.split('|')) {
+            const candidate = segment.trim()
+            const separatorIndex = candidate.indexOf('=')
+
+            if (separatorIndex <= 0) {
+                continue
+            }
+
+            const key = candidate.slice(0, separatorIndex).trim()
+            if (!key) {
+                continue
+            }
+
+            fields[key] = candidate.slice(separatorIndex + 1).trim()
+        }
+
+        return fields
+    }
+
+    /**
+     * Reads one little-endian unsigned integer from a byte view.
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @returns {number}
+     */
+    static #readUint32(bytes, offset) {
+        return new DataView(
+            bytes.buffer,
+            bytes.byteOffset + offset,
+            4
+        ).getUint32(0, true)
+    }
+
+    /**
+     * Normalizes one byte-like input into a Uint8Array view.
+     * @param {Uint8Array | ArrayBuffer | undefined} bytes
+     * @returns {Uint8Array}
+     */
+    static #toUint8Array(bytes) {
+        if (!bytes) {
+            return new Uint8Array(0)
+        }
+
+        if (bytes instanceof Uint8Array) {
+            return bytes
+        }
+
+        return new Uint8Array(bytes)
+    }
+}

package/src/core/altium/PcbPrimitiveRecordSlicer.mjs

@@ -0,0 +1,243 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Splits mixed-format PCB primitive streams.
+ */
+export class PcbPrimitiveRecordSlicer {
+    /**
+     * Splits a primitive stream, preferring object-id/length-prefixed records
+     * and falling back to legacy fixed-layout records.
+     * @param {{ headerBytes: Uint8Array | ArrayBuffer, dataBytes: Uint8Array | ArrayBuffer, objectId: number, fixedRecordByteLength: number, minimumPayloadByteLength: number, lengthPrefixedView?: 'payload' | 'record' }} options
+     * @returns {{ view: DataView, viewBytes: Uint8Array, recordBytes: Uint8Array, offset: number, byteLength: number, payloadByteLength: number | null, encoding: 'length-prefixed' | 'fixed', objectId: number | null, recordIndex: number }[]}
+     */
+    static slicePrimitiveRecords(options) {
+        const lengthPrefixedRecords =
+            PcbPrimitiveRecordSlicer.#sliceLengthPrefixedRecords(options)
+
+        if (lengthPrefixedRecords.length) {
+            return lengthPrefixedRecords
+        }
+
+        return PcbPrimitiveRecordSlicer.#sliceFixedRecords(
+            options.headerBytes,
+            options.dataBytes,
+            options.fixedRecordByteLength
+        )
+    }
+
+    /**
+     * Splits object-id/length-prefixed records when the full stream matches
+     * the expected object id, count, payload lengths, and byte length exactly.
+     * @param {{ headerBytes: Uint8Array | ArrayBuffer, dataBytes: Uint8Array | ArrayBuffer, objectId: number, minimumPayloadByteLength: number, lengthPrefixedView?: 'payload' | 'record' }} options
+     * @returns {{ view: DataView, viewBytes: Uint8Array, recordBytes: Uint8Array, offset: number, byteLength: number, payloadByteLength: number | null, encoding: 'length-prefixed' | 'fixed', objectId: number | null, recordIndex: number }[]}
+     */
+    static #sliceLengthPrefixedRecords(options) {
+        const normalizedData = PcbPrimitiveRecordSlicer.#toUint8Array(
+            options.dataBytes
+        )
+        const count = PcbPrimitiveRecordSlicer.#readRecordCount(
+            options.headerBytes
+        )
+
+        if (!count) {
+            return []
+        }
+
+        let offset = 0
+        const records = []
+
+        for (let index = 0; index < count; index += 1) {
+            const record = PcbPrimitiveRecordSlicer.#readLengthPrefixedRecordAt(
+                normalizedData,
+                offset,
+                options
+            )
+
+            if (!record) {
+                return []
+            }
+
+            records.push({ ...record, recordIndex: index })
+            offset += record.byteLength
+        }
+
+        return offset === normalizedData.byteLength ? records : []
+    }
+
+    /**
+     * Reads one length-prefixed record at a byte offset.
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @param {{ objectId: number, minimumPayloadByteLength: number, lengthPrefixedView?: 'payload' | 'record' }} options
+     * @returns {{ view: DataView, viewBytes: Uint8Array, recordBytes: Uint8Array, offset: number, byteLength: number, payloadByteLength: number | null, encoding: 'length-prefixed', objectId: number, recordIndex: number } | null}
+     */
+    static #readLengthPrefixedRecordAt(bytes, offset, options) {
+        if (
+            offset + 5 > bytes.byteLength ||
+            bytes[offset] !== options.objectId
+        ) {
+            return null
+        }
+
+        const payloadLength = PcbPrimitiveRecordSlicer.#readUint32FromBytes(
+            bytes,
+            offset + 1
+        )
+        const byteLength = 5 + payloadLength
+
+        if (
+            payloadLength < options.minimumPayloadByteLength ||
+            offset + byteLength > bytes.byteLength
+        ) {
+            return null
+        }
+
+        const viewOffset =
+            options.lengthPrefixedView === 'record' ? offset : offset + 5
+        const viewByteLength =
+            options.lengthPrefixedView === 'record' ? byteLength : payloadLength
+
+        return PcbPrimitiveRecordSlicer.#createRecord(
+            bytes,
+            offset,
+            viewOffset,
+            viewByteLength,
+            byteLength,
+            {
+                encoding: 'length-prefixed',
+                objectId: options.objectId,
+                payloadByteLength: payloadLength
+            }
+        )
+    }
+
+    /**
+     * Splits one legacy fixed-layout primitive stream into record views.
+     * @param {Uint8Array | ArrayBuffer} headerBytes
+     * @param {Uint8Array | ArrayBuffer} dataBytes
+     * @param {number} recordByteLength
+     * @returns {{ view: DataView, viewBytes: Uint8Array, recordBytes: Uint8Array, offset: number, byteLength: number, payloadByteLength: number | null, encoding: 'fixed', objectId: null, recordIndex: number }[]}
+     */
+    static #sliceFixedRecords(headerBytes, dataBytes, recordByteLength) {
+        const normalizedData = PcbPrimitiveRecordSlicer.#toUint8Array(dataBytes)
+        const count = PcbPrimitiveRecordSlicer.#readRecordCount(headerBytes)
+
+        if (!count) {
+            return []
+        }
+
+        if (normalizedData.byteLength < count * recordByteLength) {
+            return []
+        }
+
+        const records = []
+
+        for (let index = 0; index < count; index += 1) {
+            records.push(
+                PcbPrimitiveRecordSlicer.#createRecord(
+                    normalizedData,
+                    index * recordByteLength,
+                    index * recordByteLength,
+                    recordByteLength,
+                    recordByteLength,
+                    {
+                        encoding: 'fixed',
+                        objectId: null,
+                        payloadByteLength: null,
+                        recordIndex: index
+                    }
+                )
+            )
+        }
+
+        return records
+    }
+
+    /**
+     * Creates one record view tuple over a source byte array.
+     * @param {Uint8Array} bytes
+     * @param {number} recordOffset
+     * @param {number} viewOffset
+     * @param {number} viewByteLength
+     * @param {number} byteLength
+     * @param {{ encoding: 'length-prefixed' | 'fixed', objectId: number | null, payloadByteLength: number | null, recordIndex?: number }} metadata
+     * @returns {{ view: DataView, viewBytes: Uint8Array, recordBytes: Uint8Array, offset: number, byteLength: number, payloadByteLength: number | null, encoding: 'length-prefixed' | 'fixed', objectId: number | null, recordIndex: number }}
+     */
+    static #createRecord(
+        bytes,
+        recordOffset,
+        viewOffset,
+        viewByteLength,
+        byteLength,
+        metadata
+    ) {
+        return {
+            view: new DataView(
+                bytes.buffer,
+                bytes.byteOffset + viewOffset,
+                viewByteLength
+            ),
+            viewBytes: new Uint8Array(
+                bytes.buffer,
+                bytes.byteOffset + viewOffset,
+                viewByteLength
+            ),
+            recordBytes: new Uint8Array(
+                bytes.buffer,
+                bytes.byteOffset + recordOffset,
+                byteLength
+            ),
+            offset: recordOffset,
+            byteLength,
+            payloadByteLength: metadata.payloadByteLength,
+            encoding: metadata.encoding,
+            objectId: metadata.objectId,
+            recordIndex: metadata.recordIndex ?? 0
+        }
+    }
+
+    /**
+     * Reads one primitive record count from a stream header.
+     * @param {Uint8Array | ArrayBuffer} headerBytes
+     * @returns {number}
+     */
+    static #readRecordCount(headerBytes) {
+        const normalizedHeader =
+            PcbPrimitiveRecordSlicer.#toUint8Array(headerBytes)
+
+        if (normalizedHeader.byteLength < 4) {
+            return 0
+        }
+
+        return new DataView(
+            normalizedHeader.buffer,
+            normalizedHeader.byteOffset,
+            4
+        ).getUint32(0, true)
+    }
+
+    /**
+     * Reads one little-endian unsigned 32-bit value from a byte array.
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @returns {number}
+     */
+    static #readUint32FromBytes(bytes, offset) {
+        return new DataView(
+            bytes.buffer,
+            bytes.byteOffset + offset,
+            4
+        ).getUint32(0, true)
+    }
+
+    /**
+     * Normalizes a byte source to Uint8Array.
+     * @param {Uint8Array | ArrayBuffer} bytes
+     * @returns {Uint8Array}
+     */
+    static #toUint8Array(bytes) {
+        return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
+    }
+}