altium-toolkit 1.0.8 → 1.0.10

package/src/core/altium/PcbExtendedPrimitiveInformationParser.mjs

@@ -0,0 +1,256 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbSidecarRecordParser } from './PcbSidecarRecordParser.mjs'
+
+/**
+ * Decodes extended primitive sidecar records such as mask-expansion overrides.
+ */
+export class PcbExtendedPrimitiveInformationParser {
+    static #SOURCE_STREAM = 'ExtendedPrimitiveInformation/Data'
+
+    static #OBJECT_ID_TO_COLLECTION = {
+        1: ['arcs', 'arc'],
+        2: ['pads', 'pad'],
+        3: ['vias', 'via'],
+        4: ['tracks', 'track'],
+        5: ['texts', 'text'],
+        6: ['fills', 'fill'],
+        11: ['regions', 'region']
+    }
+
+    /**
+     * Parses extended primitive information records.
+     * @param {Uint8Array | ArrayBuffer | undefined} dataBytes
+     * @param {string} [sourceStream]
+     * @returns {{ entries: object[], byPrimitiveIndex: Record<string, object>, byPrimitiveKey: Record<string, object> }}
+     */
+    static parse(
+        dataBytes,
+        sourceStream = PcbExtendedPrimitiveInformationParser.#SOURCE_STREAM
+    ) {
+        const entries = PcbSidecarRecordParser.parseLengthPrefixedRecords(
+            dataBytes,
+            sourceStream
+        )
+            .map((record) =>
+                PcbExtendedPrimitiveInformationParser.#normalizeRecord(record)
+            )
+            .filter(Boolean)
+
+        return PcbExtendedPrimitiveInformationParser.#buildLookups(entries)
+    }
+
+    /**
+     * Adds extended primitive information to matching decoded primitives.
+     * @param {Record<string, object[]>} binaryPrimitives
+     * @param {{ entries?: object[] }} extendedInformation
+     */
+    static attachToPrimitives(binaryPrimitives, extendedInformation) {
+        if (!binaryPrimitives || !Array.isArray(extendedInformation?.entries)) {
+            return
+        }
+
+        for (const entry of extendedInformation.entries) {
+            const collectionName =
+                PcbExtendedPrimitiveInformationParser.#collectionNameForEntry(
+                    entry
+                )
+            const collection = binaryPrimitives[collectionName]
+
+            if (!Array.isArray(collection)) {
+                continue
+            }
+
+            const primitive = collection[entry.primitiveIndex]
+            if (!primitive) {
+                continue
+            }
+
+            primitive.extendedPrimitiveInformation =
+                PcbExtendedPrimitiveInformationParser.#publicEntry(entry)
+        }
+    }
+
+    /**
+     * Normalizes one decoded sidecar record.
+     * @param {{ fields: Record<string, string>, sourceStream: string, recordIndex: number }} record
+     * @returns {object | null}
+     */
+    static #normalizeRecord(record) {
+        const primitiveIndex = PcbSidecarRecordParser.parseInteger(
+            PcbSidecarRecordParser.firstField(record.fields, [
+                'PRIMITIVEINDEX',
+                'INDEX'
+            ])
+        )
+
+        if (primitiveIndex === null) {
+            return null
+        }
+
+        const primitiveObjectId = PcbSidecarRecordParser.parseInteger(
+            PcbSidecarRecordParser.firstField(record.fields, [
+                'PRIMITIVEOBJECTID',
+                'OBJECTID'
+            ])
+        )
+        const objectInfo =
+            PcbExtendedPrimitiveInformationParser.#OBJECT_ID_TO_COLLECTION[
+                primitiveObjectId
+            ] || []
+        const type = PcbSidecarRecordParser.firstField(record.fields, ['TYPE'])
+        const primitiveType =
+            objectInfo[1] ||
+            PcbExtendedPrimitiveInformationParser.#normalizePrimitiveType(type)
+
+        return {
+            primitiveIndex,
+            primitiveObjectId,
+            primitiveType,
+            type,
+            sourceStream: record.sourceStream,
+            maskExpansion:
+                PcbExtendedPrimitiveInformationParser.#parseMaskExpansion(
+                    record.fields
+                ),
+            fields: record.fields
+        }
+    }
+
+    /**
+     * Parses paste and solder mask-expansion fields.
+     * @param {Record<string, string>} fields
+     * @returns {{ paste: object, solder: object }}
+     */
+    static #parseMaskExpansion(fields) {
+        const pasteMode = PcbSidecarRecordParser.parseInteger(
+            PcbSidecarRecordParser.firstField(fields, [
+                'PASTEMASKEXPANSIONMODE',
+                'PASTEMASKEXPANSION_MODE'
+            ])
+        )
+        const solderMode = PcbSidecarRecordParser.parseInteger(
+            PcbSidecarRecordParser.firstField(fields, [
+                'SOLDERMASKEXPANSIONMODE',
+                'SOLDERMASKEXPANSION_MODE'
+            ])
+        )
+
+        return {
+            paste: {
+                mode: pasteMode,
+                source: PcbExtendedPrimitiveInformationParser.#maskExpansionSource(
+                    pasteMode
+                ),
+                manualExpansion: PcbSidecarRecordParser.parseNumber(
+                    PcbSidecarRecordParser.firstField(fields, [
+                        'PASTEMASKEXPANSION_MANUAL',
+                        'PASTEMASKEXPANSIONMANUAL'
+                    ])
+                )
+            },
+            solder: {
+                mode: solderMode,
+                source: PcbExtendedPrimitiveInformationParser.#maskExpansionSource(
+                    solderMode
+                ),
+                manualExpansion: PcbSidecarRecordParser.parseNumber(
+                    PcbSidecarRecordParser.firstField(fields, [
+                        'SOLDERMASKEXPANSION_MANUAL',
+                        'SOLDERMASKEXPANSIONMANUAL'
+                    ])
+                )
+            }
+        }
+    }
+
+    /**
+     * Builds primitive-index lookups.
+     * @param {object[]} entries
+     * @returns {{ entries: object[], byPrimitiveIndex: Record<string, object>, byPrimitiveKey: Record<string, object> }}
+     */
+    static #buildLookups(entries) {
+        const byPrimitiveIndex = {}
+        const byPrimitiveKey = {}
+
+        for (const entry of entries) {
+            byPrimitiveIndex[String(entry.primitiveIndex)] = entry
+            if (Number.isInteger(entry.primitiveObjectId)) {
+                byPrimitiveKey[
+                    entry.primitiveObjectId + ':' + entry.primitiveIndex
+                ] = entry
+            }
+        }
+
+        return {
+            entries,
+            byPrimitiveIndex,
+            byPrimitiveKey
+        }
+    }
+
+    /**
+     * Resolves one binary primitive collection for a sidecar entry.
+     * @param {object} entry
+     * @returns {string}
+     */
+    static #collectionNameForEntry(entry) {
+        const objectInfo =
+            PcbExtendedPrimitiveInformationParser.#OBJECT_ID_TO_COLLECTION[
+                entry.primitiveObjectId
+            ]
+        if (objectInfo) {
+            return objectInfo[0]
+        }
+
+        const primitiveType = String(entry.primitiveType || '').toLowerCase()
+        return primitiveType ? primitiveType + 's' : ''
+    }
+
+    /**
+     * Builds the public primitive-attached entry.
+     * @param {object} entry
+     * @returns {object}
+     */
+    static #publicEntry(entry) {
+        return {
+            primitiveIndex: entry.primitiveIndex,
+            primitiveObjectId: entry.primitiveObjectId,
+            primitiveType: entry.primitiveType,
+            type: entry.type,
+            sourceStream: entry.sourceStream,
+            maskExpansion: entry.maskExpansion
+        }
+    }
+
+    /**
+     * Maps one mask-expansion mode to the existing source vocabulary.
+     * @param {number | null} mode
+     * @returns {string}
+     */
+    static #maskExpansionSource(mode) {
+        if (mode === 1) return 'rule'
+        if (mode === 2) return 'manual'
+        if (mode === 0) return 'default'
+        if (mode === null) return 'unknown'
+
+        return 'unknown-' + mode
+    }
+
+    /**
+     * Normalizes one textual primitive type hint.
+     * @param {string} value
+     * @returns {string}
+     */
+    static #normalizePrimitiveType(value) {
+        const normalized = String(value || '')
+            .trim()
+            .toLowerCase()
+            .replace(/^e/iu, '')
+            .replace(/object$/iu, '')
+
+        return normalized
+    }
+}

package/src/core/altium/PcbLibModelParser.mjs

@@ -4,6 +4,11 @@
 
 import { NormalizedModelSchema } from './NormalizedModelSchema.mjs'
 import { ParserUtils } from './ParserUtils.mjs'
+import { LibraryRenderManifestBuilder } from './LibraryRenderManifestBuilder.mjs'
+import { PcbCustomPadShapeParser } from './PcbCustomPadShapeParser.mjs'
+import { PcbDefaultsParser } from './PcbDefaultsParser.mjs'
+import { PcbExtendedPrimitiveInformationParser } from './PcbExtendedPrimitiveInformationParser.mjs'
+import { PcbMaskPasteResolver } from './PcbMaskPasteResolver.mjs'
 
 const { stripExtension } = ParserUtils
 
@@ -19,24 +24,56 @@ export class PcbLibModelParser {
      */
     static parse(fileName, extraction) {
         const safeExtraction = extraction || {}
+        const embeddedModels = Array.isArray(
+            safeExtraction.embeddedModels?.models
+        )
+            ? safeExtraction.embeddedModels.models
+            : []
+        const componentBodies = Array.isArray(
+            safeExtraction.embeddedModels?.componentBodies
+        )
+            ? safeExtraction.embeddedModels.componentBodies
+            : []
         const footprints = Array.isArray(safeExtraction.footprints)
             ? safeExtraction.footprints.map((footprint) =>
-                  PcbLibModelParser.#normalizeFootprint(footprint)
+                  PcbLibModelParser.#normalizeFootprint(
+                      footprint,
+                      embeddedModels
+                  )
               )
             : []
         const embeddedFonts = Array.isArray(safeExtraction.embeddedFonts?.fonts)
             ? safeExtraction.embeddedFonts.fonts
             : []
+        const defaults = PcbDefaultsParser.parse(
+            safeExtraction.libraryHeader || {},
+            'pcb-library'
+        )
         const summary = PcbLibModelParser.#buildSummary(
             fileName,
             footprints,
-            embeddedFonts
+            embeddedFonts,
+            embeddedModels
         )
         const diagnostics = PcbLibModelParser.#buildDiagnostics(
             footprints,
             embeddedFonts,
+            embeddedModels,
             safeExtraction
         )
+        const pcbLibrary = {
+            libraryHeader: safeExtraction.libraryHeader || {},
+            componentParamsToc: safeExtraction.componentParamsToc || {},
+            sectionKeys: safeExtraction.sectionKeys || {},
+            footprints,
+            indexes: PcbLibModelParser.#buildIndexes(footprints),
+            embeddedFonts,
+            embeddedModels,
+            componentBodies,
+            ...(defaults ? { defaults } : {})
+        }
+        pcbLibrary.renderManifest =
+            LibraryRenderManifestBuilder.buildPcbLibraryManifest(pcbLibrary)
 
         return NormalizedModelSchema.attach({
             kind: 'pcb-library',
@@ -44,13 +81,7 @@ export class PcbLibModelParser {
             fileName,
             summary,
             diagnostics,
-            pcbLibrary: {
-                libraryHeader: safeExtraction.libraryHeader || {},
-                componentParamsToc: safeExtraction.componentParamsToc || {},
-                sectionKeys: safeExtraction.sectionKeys || {},
-                footprints,
-                embeddedFonts
-            },
+            pcbLibrary,
             bom: []
         })
     }
@@ -60,9 +91,10 @@ export class PcbLibModelParser {
      * @param {string} fileName
      * @param {object[]} footprints
      * @param {object[]} embeddedFonts
+     * @param {object[]} embeddedModels
      * @returns {Record<string, number | string>}
      */
-    static #buildSummary(fileName, footprints, embeddedFonts) {
+    static #buildSummary(fileName, footprints, embeddedFonts, embeddedModels) {
         return {
             title: stripExtension(fileName),
             footprintCount: footprints.length,
@@ -81,7 +113,8 @@ export class PcbLibModelParser {
                 footprints,
                 'rawRecords'
             ),
-            embeddedFontCount: embeddedFonts.length
+            embeddedFontCount: embeddedFonts.length,
+            embeddedModelCount: embeddedModels.length
         }
     }
 
@@ -89,10 +122,16 @@ export class PcbLibModelParser {
      * Builds parser diagnostics from extraction metadata.
      * @param {object[]} footprints
      * @param {object[]} embeddedFonts
+     * @param {object[]} embeddedModels
      * @param {{ streamNames?: string[], diagnostics?: Record<string, number> }} extraction
      * @returns {{ severity: 'info' | 'warning', message: string }[]}
      */
-    static #buildDiagnostics(footprints, embeddedFonts, extraction) {
+    static #buildDiagnostics(
+        footprints,
+        embeddedFonts,
+        embeddedModels,
+        extraction
+    ) {
         const diagnostics = [
             {
                 severity: 'info',
@@ -123,6 +162,16 @@ export class PcbLibModelParser {
             })
         }
 
+        if (embeddedModels.length) {
+            diagnostics.push({
+                severity: 'info',
+                message:
+                    'Recovered ' +
+                    embeddedModels.length +
+                    ' embedded PcbLib model payloads.'
+            })
+        }
+
         if (extraction.diagnostics?.missingFootprintCount) {
             diagnostics.push({
                 severity: 'warning',
@@ -139,9 +188,10 @@ export class PcbLibModelParser {
     /**
      * Normalizes one extracted footprint object with stable primitive arrays.
      * @param {object} footprint
+     * @param {object[]} libraryEmbeddedModels Library-level embedded models.
      * @returns {object}
      */
-    static #normalizeFootprint(footprint) {
+    static #normalizeFootprint(footprint, libraryEmbeddedModels = []) {
         const normalized = {
             name: String(footprint.name || ''),
             dataName: String(footprint.dataName || footprint.name || ''),
@@ -158,6 +208,13 @@ export class PcbLibModelParser {
             unknownRecords: Array.isArray(footprint.unknownRecords)
                 ? footprint.unknownRecords
                 : [],
+            implementations: PcbLibModelParser.#array(
+                footprint.implementations
+            ),
+            componentModels: PcbLibModelParser.#array(
+                footprint.componentModels
+            ),
+            pinDisplayModes: footprint.pinDisplayModes || {},
             rawRecords: PcbLibModelParser.#array(footprint.rawRecords),
             pads: PcbLibModelParser.#array(footprint.pads),
             tracks: PcbLibModelParser.#array(footprint.tracks),
@@ -165,8 +222,51 @@ export class PcbLibModelParser {
             vias: PcbLibModelParser.#array(footprint.vias),
             fills: PcbLibModelParser.#array(footprint.fills),
             texts: PcbLibModelParser.#array(footprint.texts),
-            regions: PcbLibModelParser.#array(footprint.regions)
+            regions: PcbLibModelParser.#array(footprint.regions),
+            shapeBasedRegions: PcbLibModelParser.#array(
+                footprint.shapeBasedRegions
+            ),
+            extendedPrimitiveInformation:
+                footprint.extendedPrimitiveInformation || {
+                    entries: [],
+                    byPrimitiveIndex: {},
+                    byPrimitiveKey: {}
+                },
+            customPadShapes: footprint.customPadShapes || {
+                entries: [],
+                byPrimitiveIndex: {}
+            },
+            embeddedModels: PcbLibModelParser.#array(footprint.embeddedModels),
+            componentBodies: PcbLibModelParser.#array(footprint.componentBodies)
         }
+        normalized.defaults = PcbDefaultsParser.parse(
+            {
+                ...(footprint.defaults || {}),
+                ...(footprint.parameters || {})
+            },
+            'pcb-library-footprint'
+        )
+        PcbExtendedPrimitiveInformationParser.attachToPrimitives(
+            normalized,
+            normalized.extendedPrimitiveInformation
+        )
+        PcbCustomPadShapeParser.attachToPads(
+            normalized.pads,
+            normalized.customPadShapes,
+            normalized
+        )
+        normalized.componentBodies = PcbLibModelParser.#annotateComponentBodies(
+            normalized.componentBodies,
+            normalized.embeddedModels.length
+                ? normalized.embeddedModels
+                : libraryEmbeddedModels
+        )
+        normalized.maskPaste = PcbMaskPasteResolver.build({
+            pads: normalized.pads,
+            vias: normalized.vias,
+            rules: footprint.rules || [],
+            defaults: normalized.defaults
+        })
 
         return {
             ...normalized,
@@ -176,6 +276,127 @@ export class PcbLibModelParser {
         }
     }
 
+    /**
+     * Adds deterministic projection diagnostics to footprint body records.
+     * @param {object[]} componentBodies Component body records.
+     * @param {object[]} embeddedModels Embedded model records.
+     * @returns {object[]}
+     */
+    static #annotateComponentBodies(componentBodies, embeddedModels) {
+        return componentBodies.map((componentBody) => ({
+            ...componentBody,
+            projectionDiagnostics: PcbLibModelParser.#projectionDiagnostics(
+                componentBody,
+                embeddedModels
+            )
+        }))
+    }
+
+    /**
+     * Resolves one component-body projection diagnostic.
+     * @param {object} componentBody Component body record.
+     * @param {object[]} embeddedModels Embedded model records.
+     * @returns {{ source: string, reason: string }}
+     */
+    static #projectionDiagnostics(componentBody, embeddedModels) {
+        const matchedModel = (embeddedModels || []).find(
+            (model) =>
+                PcbLibModelParser.#sameNonEmptyValue(
+                    model?.id,
+                    componentBody?.modelId
+                ) ||
+                PcbLibModelParser.#sameNonEmptyValue(
+                    model?.checksum,
+                    componentBody?.checksum
+                ) ||
+                PcbLibModelParser.#sameNonEmptyValue(
+                    model?.name,
+                    componentBody?.name
+                )
+        )
+
+        if (matchedModel) {
+            return {
+                source: 'embedded-model',
+                reason: 'matched embedded model payload'
+            }
+        }
+
+        return {
+            source: 'fallback',
+            reason: 'no embedded model payload matched this body'
+        }
+    }
+
+    /**
+     * Compares two values only when both are present.
+     * @param {unknown} left First value.
+     * @param {unknown} right Second value.
+     * @returns {boolean}
+     */
+    static #sameNonEmptyValue(left, right) {
+        return (
+            left !== null &&
+            left !== undefined &&
+            left !== '' &&
+            right !== null &&
+            right !== undefined &&
+            right !== '' &&
+            String(left) === String(right)
+        )
+    }
+
+    /**
+     * Builds footprint lookup indexes for library consumers.
+     * @param {object[]} footprints Normalized footprints.
+     * @returns {object}
+     */
+    static #buildIndexes(footprints) {
+        const footprintsByName = {}
+
+        for (const [index, footprint] of footprints.entries()) {
+            footprintsByName[footprint.name] =
+                PcbLibModelParser.#footprintIndexEntry(footprint, index)
+        }
+
+        return { footprintsByName }
+    }
+
+    /**
+     * Builds one footprint index entry.
+     * @param {object} footprint Normalized footprint.
+     * @param {number} index Footprint index.
+     * @returns {object}
+     */
+    static #footprintIndexEntry(footprint, index) {
+        return {
+            index,
+            name: footprint.name,
+            dataName: footprint.dataName,
+            sourceStorage: footprint.sourceStorage,
+            primitiveCount: footprint.primitiveCount,
+            padCount: footprint.pads.length,
+            textCount: footprint.texts.length,
+            keywords: PcbLibModelParser.#buildFootprintKeywords(footprint)
+        }
+    }
+
+    /**
+     * Builds searchable metadata tokens for one footprint.
+     * @param {object} footprint Normalized footprint.
+     * @returns {string[]}
+     */
+    static #buildFootprintKeywords(footprint) {
+        return [
+            footprint.name,
+            footprint.dataName,
+            ...Object.values(footprint.parameters || {}),
+            ...Object.values(footprint.componentParams || {})
+        ]
+            .map((value) => String(value || '').trim())
+            .filter(Boolean)
+    }
+
     /**
      * Counts either a scalar footprint field or an array-valued family.
      * @param {object[]} footprints