altium-toolkit 1.0.8 → 1.0.10

package/src/core/altium/PcbStreamExtractor.mjs

@@ -3,11 +3,16 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { AsciiRecordParser } from './AsciiRecordParser.mjs'
+import { EmbeddedFileInventoryBuilder } from './EmbeddedFileInventoryBuilder.mjs'
 import { PcbBinaryPrimitiveParser } from './PcbBinaryPrimitiveParser.mjs'
+import { PcbCustomPadShapeParser } from './PcbCustomPadShapeParser.mjs'
 import { PcbEmbeddedFontExtractor } from './PcbEmbeddedFontExtractor.mjs'
 import { PcbEmbeddedModelExtractor } from './PcbEmbeddedModelExtractor.mjs'
+import { PcbExtendedPrimitiveInformationParser } from './PcbExtendedPrimitiveInformationParser.mjs'
 import { PcbPrimitiveParameterParser } from './PcbPrimitiveParameterParser.mjs'
 import { PcbRawRecordRegistry } from './PcbRawRecordRegistry.mjs'
+import { PcbUnionParser } from './PcbUnionParser.mjs'
+import { PcbViaStructureParser } from './PcbViaStructureParser.mjs'
 import { PcbWideStringTableParser } from './PcbWideStringTableParser.mjs'
 import { OleCompoundDocument } from '../ole/OleCompoundDocument.mjs'
 import { OleConstants } from '../ole/OleConstants.mjs'
@@ -45,7 +50,7 @@ export class PcbStreamExtractor {
     /**
      * 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: Record<string, object[]>, primitiveParameters: object, wideStrings: object, diagnostics: { printableRecordCount: number, printableStreamCount: number, binaryPrimitiveCount: number, primitiveParameterGroupCount: number, wideStringCount: number } } | null}
+     * @returns {{ records: Array<{ raw: string, fields: Record<string, string | string[]>, sourceStream: string }>, streamNames: string[], binaryPrimitives: Record<string, object[]>, primitiveParameters: object, wideStrings: object, viaStructures: object, extendedPrimitiveInformation: object, customPadShapes: object, unions: object, diagnostics: { printableRecordCount: number, printableStreamCount: number, binaryPrimitiveCount: number, primitiveParameterGroupCount: number, wideStringCount: number, viaStructureCount: number } } | null}
      */
     static extractFromArrayBuffer(arrayBuffer) {
         if (!PcbStreamExtractor.isCompoundDocument(arrayBuffer)) {
@@ -67,7 +72,7 @@ export class PcbStreamExtractor {
      * 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: Record<string, object[]>, primitiveParameters: object, wideStrings: object, diagnostics: { printableRecordCount: number, printableStreamCount: number, binaryPrimitiveCount: number, primitiveParameterGroupCount: number, wideStringCount: number } }}
+     * @returns {{ records: Array<{ raw: string, fields: Record<string, string | string[]>, sourceStream: string }>, streamNames: string[], binaryPrimitives: Record<string, object[]>, primitiveParameters: object, wideStrings: object, viaStructures: object, extendedPrimitiveInformation: object, customPadShapes: object, unions: object, diagnostics: { printableRecordCount: number, printableStreamCount: number, binaryPrimitiveCount: number, primitiveParameterGroupCount: number, wideStringCount: number, viaStructureCount: number } }}
      */
     static extractFromStreams(streams) {
         const records = []
@@ -106,7 +111,9 @@ export class PcbStreamExtractor {
                 continue
             }
 
-            records.push(...streamRecords)
+            for (const record of streamRecords) {
+                records.push(record)
+            }
             printableStreamNames.add(name)
             usedStreamNames.add(name)
         }
@@ -142,6 +149,15 @@ export class PcbStreamExtractor {
         const wideStrings = PcbWideStringTableParser.parse(
             streams.get('WideStrings6/Data')
         )
+        const viaStructures = PcbViaStructureParser.extractFromStreams(streams)
+        const extendedPrimitiveInformation =
+            PcbExtendedPrimitiveInformationParser.parse(
+                streams.get('ExtendedPrimitiveInformation/Data')
+            )
+        const customPadShapes = PcbCustomPadShapeParser.parse(
+            streams.get('CustomShapes/Data')
+        )
+        const unions = PcbUnionParser.extractFromStreams(streams)
 
         if (primitiveParameters.groups.length) {
             usedStreamNames.add('PrimitiveParameters/Data')
@@ -151,6 +167,26 @@ export class PcbStreamExtractor {
             usedStreamNames.add('WideStrings6/Data')
         }
 
+        for (const sourceStream of PcbStreamExtractor.#viaStructureStreamNames(
+            viaStructures
+        )) {
+            usedStreamNames.add(sourceStream)
+        }
+
+        if (extendedPrimitiveInformation.entries.length) {
+            usedStreamNames.add('ExtendedPrimitiveInformation/Data')
+        }
+
+        if (customPadShapes.entries.length) {
+            usedStreamNames.add('CustomShapes/Data')
+        }
+
+        for (const sourceStream of PcbStreamExtractor.#unionStreamNames(
+            unions
+        )) {
+            usedStreamNames.add(sourceStream)
+        }
+
         if (arcHeaderBytes && arcDataBytes) {
             binaryPrimitives.arcs = PcbBinaryPrimitiveParser.parseArcStream(
                 arcHeaderBytes,
@@ -176,6 +212,10 @@ export class PcbStreamExtractor {
                 viaHeaderBytes,
                 viaDataBytes
             )
+            PcbViaStructureParser.attachToVias(
+                binaryPrimitives.vias,
+                viaStructures
+            )
             if (binaryPrimitives.vias.length) {
                 usedStreamNames.add('Vias6/Data')
             }
@@ -246,6 +286,12 @@ export class PcbStreamExtractor {
             }
         }
 
+        PcbExtendedPrimitiveInformationParser.attachToPrimitives(
+            binaryPrimitives,
+            extendedPrimitiveInformation
+        )
+        PcbUnionParser.attachToPrimitives(binaryPrimitives, unions)
+
         const embeddedModels =
             PcbEmbeddedModelExtractor.extractFromStreams(streams)
         const embeddedFonts =
@@ -276,6 +322,19 @@ export class PcbStreamExtractor {
             )
         }
 
+        const embeddedFiles = EmbeddedFileInventoryBuilder.buildFromStreams(
+            streams,
+            {
+                skipStreamNames: usedStreamNames
+            }
+        )
+        embeddedFiles.files.forEach((file) =>
+            usedStreamNames.add(file.sourceStream)
+        )
+        embeddedFiles.diagnostics.forEach((diagnostic) =>
+            usedStreamNames.add(diagnostic.sourceStream)
+        )
+
         return {
             records,
             streamNames: [...usedStreamNames].sort((left, right) =>
@@ -284,16 +343,32 @@ export class PcbStreamExtractor {
             binaryPrimitives,
             primitiveParameters,
             wideStrings,
+            viaStructures,
+            extendedPrimitiveInformation,
+            customPadShapes,
+            unions,
             embeddedModels,
             embeddedFonts,
+            embeddedFiles,
             rawRecords,
             diagnostics: {
                 printableRecordCount: records.length,
                 printableStreamCount: printableStreamNames.size,
                 embeddedFontCount: embeddedFonts.fonts.length,
+                embeddedFileCount: embeddedFiles.files.length,
+                embeddedFileIssueCount: embeddedFiles.diagnostics.length,
+                embeddedModelIssueCount:
+                    embeddedModels.integrity?.issues?.length || 0,
                 rawRecordCount: rawRecords.length,
                 primitiveParameterGroupCount: primitiveParameters.groups.length,
                 wideStringCount: wideStrings.entries.length,
+                viaStructureCount: viaStructures.structures.length,
+                viaStructureLinkCount: viaStructures.links.length,
+                extendedPrimitiveInformationCount:
+                    extendedPrimitiveInformation.entries.length,
+                customPadShapeCount: customPadShapes.entries.length,
+                userUnionCount: unions.userUnions.length,
+                smartUnionCount: unions.smartUnions.length,
                 binaryPrimitiveCount:
                     binaryPrimitives.arcs.length +
                     binaryPrimitives.tracks.length +
@@ -327,7 +402,39 @@ export class PcbStreamExtractor {
      */
     static #isBinarySidecarDataStream(name) {
         return (
-            name === 'PrimitiveParameters/Data' || name === 'WideStrings6/Data'
+            name === 'PrimitiveParameters/Data' ||
+            name === 'WideStrings6/Data' ||
+            name === 'ViaStructures/Data' ||
+            name === 'ViaStructureManager/Data' ||
+            name === 'ExtendedPrimitiveInformation/Data' ||
+            name === 'CustomShapes/Data' ||
+            name === 'UnionNames/Data' ||
+            name === 'SmartUnions/Data'
         )
     }
+
+    /**
+     * Collects sidecar source stream names that produced via-structure data.
+     * @param {{ structures?: { sourceStream?: string }[], links?: { sourceStream?: string }[] }} viaStructures
+     * @returns {string[]}
+     */
+    static #viaStructureStreamNames(viaStructures) {
+        return [
+            ...(viaStructures.structures || []),
+            ...(viaStructures.links || [])
+        ]
+            .map((record) => record.sourceStream)
+            .filter(Boolean)
+    }
+
+    /**
+     * Collects sidecar source stream names that produced union metadata.
+     * @param {{ userUnions?: { sourceStream?: string }[], smartUnions?: { sourceStream?: string }[] }} unions
+     * @returns {string[]}
+     */
+    static #unionStreamNames(unions) {
+        return [...(unions.userUnions || []), ...(unions.smartUnions || [])]
+            .map((record) => record.sourceStream)
+            .filter(Boolean)
+    }
 }

package/src/core/altium/PcbTextPrimitiveParser.mjs

@@ -235,10 +235,70 @@ export class PcbTextPrimitiveParser {
         if (payload.byteLength >= 133) {
             extendedFields.textboxRectJustification = payload.getUint8(132)
         }
+        if (fontType === 2 && payload.byteLength >= 157) {
+            extendedFields.barcode =
+                PcbTextPrimitiveParser.#parseBarcodeFields(payload)
+        }
 
         return extendedFields
     }
 
+    /**
+     * Parses barcode-specific fields from modern barcode text records.
+     * @param {DataView} payload Text payload.
+     * @returns {{ kind: number, kindName: string, renderMode: number, renderModeName: string, fullWidth: number, fullHeight: number, marginX: number, marginY: number, minBarWidth: number, showText: boolean, inverted: boolean }}
+     */
+    static #parseBarcodeFields(payload) {
+        const kind = payload.getUint8(133)
+        const renderMode = payload.getUint8(134)
+
+        return {
+            kind,
+            kindName: PcbTextPrimitiveParser.#barcodeKindName(kind),
+            renderMode,
+            renderModeName:
+                PcbTextPrimitiveParser.#barcodeRenderModeName(renderMode),
+            fullWidth: PcbTextPrimitiveParser.#readMil(payload, 135),
+            fullHeight: PcbTextPrimitiveParser.#readMil(payload, 139),
+            marginX: PcbTextPrimitiveParser.#readMil(payload, 143),
+            marginY: PcbTextPrimitiveParser.#readMil(payload, 147),
+            minBarWidth: PcbTextPrimitiveParser.#readMil(payload, 151),
+            showText: payload.getUint8(155) !== 0,
+            inverted: payload.getUint8(156) !== 0
+        }
+    }
+
+    /**
+     * Resolves a barcode kind label.
+     * @param {number} kind Barcode kind id.
+     * @returns {string}
+     */
+    static #barcodeKindName(kind) {
+        return (
+            {
+                0: 'code39',
+                1: 'code128',
+                2: 'ean13',
+                3: 'qr'
+            }[Number(kind)] || 'unknown'
+        )
+    }
+
+    /**
+     * Resolves a barcode render-mode label.
+     * @param {number} mode Barcode render mode id.
+     * @returns {string}
+     */
+    static #barcodeRenderModeName(mode) {
+        return (
+            {
+                0: 'minimum',
+                1: 'fit-text',
+                2: 'full-size'
+            }[Number(mode)] || 'unknown'
+        )
+    }
+
     /**
      * Decodes one fixed-length UTF-16LE field from a payload view.
      * @param {DataView} payload

package/src/core/altium/PcbUnionParser.mjs

@@ -0,0 +1,307 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbSidecarRecordParser } from './PcbSidecarRecordParser.mjs'
+
+/**
+ * Decodes PCB user-union and smart-union sidecar streams.
+ */
+export class PcbUnionParser {
+    static #OBJECT_ID_TO_COLLECTION = {
+        1: 'arcs',
+        2: 'pads',
+        3: 'vias',
+        4: 'tracks',
+        5: 'texts',
+        6: 'fills',
+        11: 'regions'
+    }
+
+    /**
+     * Extracts user and smart union records from a stream map.
+     * @param {Map<string, Uint8Array>} streams
+     * @returns {{ userUnions: object[], smartUnions: object[], byIndex: Record<string, object>, smartByIndex: Record<string, object>, membersByPrimitiveKey: Record<string, object[]> }}
+     */
+    static extractFromStreams(streams) {
+        const userUnions = PcbUnionParser.#parseUserUnions(
+            streams.get('UnionNames/Data')
+        )
+        const smartUnions = PcbUnionParser.#parseSmartUnions(
+            streams.get('SmartUnions/Data')
+        )
+
+        return PcbUnionParser.#buildLookups(userUnions, smartUnions)
+    }
+
+    /**
+     * Adds smart-union memberships to decoded primitives in place.
+     * @param {Record<string, object[]>} binaryPrimitives
+     * @param {{ smartUnions?: object[] }} unions
+     */
+    static attachToPrimitives(binaryPrimitives, unions) {
+        if (!binaryPrimitives || !Array.isArray(unions?.smartUnions)) {
+            return
+        }
+
+        for (const smartUnion of unions.smartUnions) {
+            for (const member of smartUnion.members || []) {
+                const collectionName =
+                    PcbUnionParser.#OBJECT_ID_TO_COLLECTION[
+                        member.primitiveObjectId
+                    ]
+                const collection = binaryPrimitives[collectionName]
+                const primitive = Array.isArray(collection)
+                    ? collection[member.primitiveIndex]
+                    : null
+
+                if (!primitive) {
+                    continue
+                }
+
+                primitive.unionMemberships = primitive.unionMemberships || []
+                primitive.unionMemberships.push(
+                    PcbUnionParser.#publicMembership(smartUnion)
+                )
+            }
+        }
+    }
+
+    /**
+     * Parses UnionNames/Data entries.
+     * @param {Uint8Array | undefined} bytes
+     * @returns {object[]}
+     */
+    static #parseUserUnions(bytes) {
+        return PcbSidecarRecordParser.parseLengthPrefixedRecords(
+            bytes,
+            'UnionNames/Data'
+        )
+            .map((record) => PcbUnionParser.#normalizeUserUnion(record))
+            .filter(Boolean)
+    }
+
+    /**
+     * Parses SmartUnions/Data entries.
+     * @param {Uint8Array | undefined} bytes
+     * @returns {object[]}
+     */
+    static #parseSmartUnions(bytes) {
+        return PcbSidecarRecordParser.parseLengthPrefixedRecords(
+            bytes,
+            'SmartUnions/Data'
+        )
+            .map((record) => PcbUnionParser.#normalizeSmartUnion(record))
+            .filter(Boolean)
+    }
+
+    /**
+     * Normalizes one user-union record.
+     * @param {{ fields: Record<string, string>, sourceStream: string, recordIndex: number }} record
+     * @returns {object}
+     */
+    static #normalizeUserUnion(record) {
+        const index =
+            PcbSidecarRecordParser.parseInteger(
+                PcbSidecarRecordParser.firstField(record.fields, [
+                    'UNIONINDEX',
+                    'INDEX'
+                ])
+            ) ?? record.recordIndex
+
+        return {
+            index,
+            name: PcbSidecarRecordParser.firstField(record.fields, ['NAME']),
+            sourceStream: record.sourceStream,
+            fields: record.fields
+        }
+    }
+
+    /**
+     * Normalizes one smart-union record.
+     * @param {{ fields: Record<string, string>, sourceStream: string, recordIndex: number }} record
+     * @returns {object}
+     */
+    static #normalizeSmartUnion(record) {
+        const index =
+            PcbSidecarRecordParser.parseInteger(
+                PcbSidecarRecordParser.firstField(record.fields, [
+                    'UNIONINDEX',
+                    'SMARTUNIONINDEX',
+                    'INDEX'
+                ])
+            ) ?? record.recordIndex
+        const type = PcbUnionParser.#parseType(record.fields)
+
+        return {
+            index,
+            name: PcbSidecarRecordParser.firstField(record.fields, ['NAME']),
+            type,
+            typeName: PcbUnionParser.#smartUnionTypeName(type),
+            sourceStream: record.sourceStream,
+            members: PcbUnionParser.#parseMembers(record.fields),
+            fields: record.fields
+        }
+    }
+
+    /**
+     * Parses a smart-union type value.
+     * @param {Record<string, string>} fields
+     * @returns {number | string}
+     */
+    static #parseType(fields) {
+        const value = PcbSidecarRecordParser.firstField(fields, [
+            'UNIONTYPE',
+            'TYPE',
+            'SMARTUNIONTYPE'
+        ])
+        const parsed = PcbSidecarRecordParser.parseInteger(value)
+
+        return parsed === null ? value : parsed
+    }
+
+    /**
+     * Parses member primitive references from numbered sidecar fields.
+     * @param {Record<string, string>} fields
+     * @returns {{ primitiveObjectId: number, primitiveIndex: number }[]}
+     */
+    static #parseMembers(fields) {
+        const members = []
+        const memberNumbers = new Set()
+
+        for (const key of Object.keys(fields)) {
+            const match = key.match(/^PRIMITIVEOBJECTID(\d+)$/u)
+            if (match) {
+                memberNumbers.add(match[1])
+            }
+        }
+
+        for (const memberNumber of [...memberNumbers].sort(
+            (left, right) => Number(left) - Number(right)
+        )) {
+            const primitiveObjectId = PcbSidecarRecordParser.parseInteger(
+                fields['PRIMITIVEOBJECTID' + memberNumber]
+            )
+            const primitiveIndex = PcbSidecarRecordParser.parseInteger(
+                fields['PRIMITIVEINDEX' + memberNumber]
+            )
+
+            if (
+                Number.isInteger(primitiveObjectId) &&
+                Number.isInteger(primitiveIndex)
+            ) {
+                members.push({ primitiveObjectId, primitiveIndex })
+            }
+        }
+
+        if (!members.length) {
+            members.push(...PcbUnionParser.#parseFlatMembers(fields))
+        }
+
+        return members
+    }
+
+    /**
+     * Parses flat primitive member fields used by compact fake fixtures.
+     * @param {Record<string, string>} fields
+     * @returns {{ primitiveObjectId: number, primitiveIndex: number }[]}
+     */
+    static #parseFlatMembers(fields) {
+        const primitiveObjectId = PcbSidecarRecordParser.parseInteger(
+            PcbSidecarRecordParser.firstField(fields, [
+                'PRIMITIVEOBJECTID',
+                'OBJECTID'
+            ])
+        )
+        const primitiveIndexes = String(
+            PcbSidecarRecordParser.firstField(fields, [
+                'PRIMITIVEINDEXES',
+                'PRIMITIVEINDEX'
+            ])
+        )
+            .split(/[;,\s]+/u)
+            .map((value) => PcbSidecarRecordParser.parseInteger(value))
+            .filter(Number.isInteger)
+
+        if (!Number.isInteger(primitiveObjectId)) {
+            return []
+        }
+
+        return primitiveIndexes.map((primitiveIndex) => ({
+            primitiveObjectId,
+            primitiveIndex
+        }))
+    }
+
+    /**
+     * Builds union lookups.
+     * @param {object[]} userUnions
+     * @param {object[]} smartUnions
+     * @returns {{ userUnions: object[], smartUnions: object[], byIndex: Record<string, object>, smartByIndex: Record<string, object>, membersByPrimitiveKey: Record<string, object[]> }}
+     */
+    static #buildLookups(userUnions, smartUnions) {
+        const byIndex = {}
+        const smartByIndex = {}
+        const membersByPrimitiveKey = {}
+
+        for (const union of userUnions) {
+            byIndex[String(union.index)] = union
+        }
+
+        for (const smartUnion of smartUnions) {
+            smartByIndex[String(smartUnion.index)] = smartUnion
+            for (const member of smartUnion.members || []) {
+                const key =
+                    member.primitiveObjectId + ':' + member.primitiveIndex
+                membersByPrimitiveKey[key] = membersByPrimitiveKey[key] || []
+                membersByPrimitiveKey[key].push(smartUnion)
+            }
+        }
+
+        return {
+            userUnions,
+            smartUnions,
+            byIndex,
+            smartByIndex,
+            membersByPrimitiveKey
+        }
+    }
+
+    /**
+     * Returns the public membership shape attached to primitives.
+     * @param {object} smartUnion
+     * @returns {object}
+     */
+    static #publicMembership(smartUnion) {
+        return {
+            index: smartUnion.index,
+            name: smartUnion.name,
+            type: smartUnion.type,
+            typeName: smartUnion.typeName,
+            sourceStream: smartUnion.sourceStream
+        }
+    }
+
+    /**
+     * Maps known smart-union type ids to stable labels.
+     * @param {number | string} type
+     * @returns {string}
+     */
+    static #smartUnionTypeName(type) {
+        if (typeof type === 'string' && type) {
+            return type
+        }
+
+        return (
+            {
+                1: 'drill-table',
+                2: 'via-stitching',
+                3: 'layer-stack-table',
+                4: 'length-tuning',
+                5: 'metadata-ole-object',
+                6: 'via-shielding',
+                9: 'rectangle'
+            }[Number(type)] || 'unknown'
+        )
+    }
+}