altium-toolkit 1.0.9 → 1.1.0

package/src/core/altium/PcbPadStackParser.mjs

@@ -81,6 +81,10 @@ export class PcbPadStackParser {
         const flags = PcbPadStackParser.#parseFlags(mainRecord)
         const mainRecordTail =
             PcbPadStackParser.#parseMainRecordTail(mainRecord)
+        const extension = PcbPadStackParser.#parseExtensionRecord(
+            extensionRecord,
+            padContext
+        )
 
         return {
             ...flags,
@@ -90,8 +94,10 @@ export class PcbPadStackParser {
                 mainRecordTail,
                 padContext
             ),
-            ...PcbPadStackParser.#parseExtensionRecord(
-                extensionRecord,
+            ...extension,
+            ...PcbPadStackParser.#buildLocalStack(
+                mainRecordTail,
+                extension,
                 padContext
             )
         }
@@ -722,6 +728,169 @@ export class PcbPadStackParser {
         }
     }
 
+    /**
+     * Builds a normalized local-stack geometry read model.
+     * @param {Record<string, boolean | number>} mainRecordTail Main tail fields.
+     * @param {Record<string, unknown>} extension Extension fields.
+     * @param {Record<string, unknown>} padContext Parsed pad fields.
+     * @returns {{ localStack?: object }}
+     */
+    static #buildLocalStack(mainRecordTail, extension, padContext) {
+        const mode = Number(mainRecordTail.padMode)
+        if (mode === 1) {
+            return {
+                localStack: {
+                    schema: 'altium-toolkit.pcb.pad-local-stack.a1',
+                    mode,
+                    modeName: String(mainRecordTail.padModeName || ''),
+                    source: 'main-record',
+                    layers: [
+                        PcbPadStackParser.#localStackLayer(
+                            'top',
+                            1,
+                            'L1',
+                            padContext,
+                            extension
+                        ),
+                        PcbPadStackParser.#localStackLayer(
+                            'middle',
+                            null,
+                            'INNER',
+                            padContext,
+                            extension
+                        ),
+                        PcbPadStackParser.#localStackLayer(
+                            'bottom',
+                            32,
+                            'L32',
+                            padContext,
+                            extension
+                        )
+                    ],
+                    hole: PcbPadStackParser.#localStackHole(
+                        padContext,
+                        extension
+                    )
+                }
+            }
+        }
+
+        if (
+            mode === 2 &&
+            Array.isArray(extension.fullStackLayerEntries) &&
+            extension.fullStackLayerEntries.length
+        ) {
+            return {
+                localStack: {
+                    schema: 'altium-toolkit.pcb.pad-local-stack.a1',
+                    mode,
+                    modeName: String(mainRecordTail.padModeName || ''),
+                    source: 'extension-record',
+                    layers: extension.fullStackLayerEntries.map((entry) => ({
+                        role: 'layer',
+                        layerId: Number(entry.layerCode),
+                        layerKey: 'L' + Number(entry.layerCode),
+                        enabled: entry.enabled,
+                        width: entry.sizeX,
+                        height: entry.sizeY,
+                        cornerRadius: entry.cornerRadius,
+                        modeFlags: entry.modeFlags
+                    })),
+                    hole: PcbPadStackParser.#localStackHole(
+                        padContext,
+                        extension
+                    )
+                }
+            }
+        }
+
+        return {}
+    }
+
+    /**
+     * Builds one top/middle/bottom local-stack layer entry.
+     * @param {'top' | 'middle' | 'bottom'} role Layer role.
+     * @param {number | null} layerId Layer id.
+     * @param {string} layerKey Stable layer key.
+     * @param {Record<string, unknown>} padContext Parsed pad fields.
+     * @param {Record<string, unknown>} extension Extension fields.
+     * @returns {object}
+     */
+    static #localStackLayer(role, layerId, layerKey, padContext, extension) {
+        const suffix =
+            role === 'top' ? 'Top' : role === 'bottom' ? 'Bottom' : 'Mid'
+        const offset = PcbPadStackParser.#layerOffset(role, extension)
+
+        return {
+            role,
+            layerId,
+            layerKey,
+            width: Number(padContext['size' + suffix + 'X'] || 0),
+            height: Number(padContext['size' + suffix + 'Y'] || 0),
+            shape: PcbPadStackParser.#numericOrNull(
+                padContext['shape' + suffix]
+            ),
+            shapeName: PcbPadShapeCodec.padShapeName(
+                padContext['shape' + suffix]
+            ),
+            offsetX: offset.x,
+            offsetY: offset.y
+        }
+    }
+
+    /**
+     * Resolves layer offsets from extension data when present.
+     * @param {'top' | 'middle' | 'bottom'} role Layer role.
+     * @param {Record<string, unknown>} extension Extension fields.
+     * @returns {{ x: number, y: number }}
+     */
+    static #layerOffset(role, extension) {
+        const layerNumber = role === 'top' ? 1 : role === 'bottom' ? 32 : null
+        const offset = Array.isArray(extension.layerOffsets)
+            ? extension.layerOffsets.find(
+                  (entry) => entry.layerNumber === layerNumber
+              )
+            : null
+
+        return {
+            x: Number(offset?.x || 0),
+            y: Number(offset?.y || 0)
+        }
+    }
+
+    /**
+     * Builds local-stack hole geometry.
+     * @param {Record<string, unknown>} padContext Parsed pad fields.
+     * @param {Record<string, unknown>} extension Extension fields.
+     * @returns {object}
+     */
+    static #localStackHole(padContext, extension) {
+        const shape = PcbPadStackParser.#numericOrNull(extension.holeShape)
+
+        return {
+            diameter: Number(padContext.holeDiameter || 0),
+            shape,
+            shapeName:
+                shape === null ? null : PcbPadShapeCodec.holeShapeName(shape),
+            slotLength: extension.holeSlotLength ?? null,
+            rotation: extension.holeRotation ?? null
+        }
+    }
+
+    /**
+     * Converts finite numeric values and nullish values into stable output.
+     * @param {unknown} value Candidate value.
+     * @returns {number | null}
+     */
+    static #numericOrNull(value) {
+        if (value === null || value === undefined || value === '') {
+            return null
+        }
+
+        const number = Number(value)
+        return Number.isFinite(number) ? number : null
+    }
+
     /**
      * Decodes non-empty inner-layer pad sizes.
      * @param {DataView} extensionRecord

package/src/core/altium/PcbPickPlacePositionResolver.mjs

@@ -15,10 +15,16 @@ export class PcbPickPlacePositionResolver {
      * @param {{ componentIndex: number, designator: string, pattern: string, layer: string, rotation: number, x: number, y: number }[]} components
      * @param {{ componentIndex: number, pads?: { x?: number, y?: number }[] }[]} componentPrimitiveGroups
      * @param {{ sourceComponents?: { componentIndex: number, rotation?: number }[] }} [options] Resolver options.
-     * @returns {{ positionMode: string, entries: object[], modes: { componentOrigin: { positionMode: string, entries: object[] } } }}
+     * @returns {{ units: object, positionMode: string, entries: object[], modes: { componentOrigin: { units: object, positionMode: string, entries: object[] } } }}
      */
     static buildModel(components, componentPrimitiveGroups, options = {}) {
+        const units = {
+            coordinate: 'mil',
+            angle: 'deg'
+        }
+
         return {
+            units,
             positionMode: DEFAULT_POSITION_MODE,
             entries: PcbPickPlacePositionResolver.buildEntries(
                 components,
@@ -28,6 +34,7 @@ export class PcbPickPlacePositionResolver {
             ),
             modes: {
                 componentOrigin: {
+                    units,
                     positionMode: COMPONENT_ORIGIN_MODE,
                     entries: PcbPickPlacePositionResolver.buildEntries(
                         components,
@@ -137,6 +144,9 @@ export class PcbPickPlacePositionResolver {
             designator: component.designator || '',
             pattern: component.pattern || '',
             layer: component.layer || '',
+            ...(component.componentKind
+                ? { componentKind: component.componentKind }
+                : {}),
             rotation: PcbPickPlacePositionResolver.#roundCoordinate(rotation),
             x: PcbPickPlacePositionResolver.#roundCoordinate(position.x),
             y: PcbPickPlacePositionResolver.#roundCoordinate(position.y),

package/src/core/altium/PcbPlacedFootprintManifestBuilder.mjs

@@ -0,0 +1,338 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds read-only extraction manifests for placed PCB footprints.
+ */
+export class PcbPlacedFootprintManifestBuilder {
+    static SCHEMA = 'altium-toolkit.pcb.placed-footprint-extraction.a1'
+
+    /**
+     * Builds a placed-footprint extraction manifest.
+     * @param {{ fileName?: string, components?: object[], componentPrimitiveGroups?: object[], embeddedModels?: object[] }} context Manifest context.
+     * @returns {object}
+     */
+    static build(context = {}) {
+        const outputs = (context.componentPrimitiveGroups || []).map(
+            (group, index) =>
+                PcbPlacedFootprintManifestBuilder.#output(context, group, index)
+        )
+        const embeddedAssetCount = outputs.reduce(
+            (total, output) => total + output.embeddedAssets.length,
+            0
+        )
+
+        return {
+            schema: PcbPlacedFootprintManifestBuilder.SCHEMA,
+            sourceDocument: String(context.fileName || ''),
+            summary: {
+                componentCount: (context.components || []).length,
+                extractableFootprintCount: outputs.length,
+                embeddedAssetCount
+            },
+            outputs,
+            indexes: PcbPlacedFootprintManifestBuilder.#indexes(outputs)
+        }
+    }
+
+    /**
+     * Builds one placed-footprint output descriptor.
+     * @param {object} context Manifest context.
+     * @param {object} group Component primitive group.
+     * @param {number} index Group index.
+     * @returns {object}
+     */
+    static #output(context, group, index) {
+        const component =
+            (context.components || []).find(
+                (candidate) =>
+                    Number(candidate.componentIndex) ===
+                    Number(group.componentIndex)
+            ) || {}
+        const designator = group.designator || component.designator || ''
+        const pattern = component.pattern || ''
+        const footprintKey =
+            'footprint-extract-' +
+            index +
+            '-' +
+            PcbPlacedFootprintManifestBuilder.#slug(
+                [designator, pattern].filter(Boolean).join('-') || index
+            )
+
+        return {
+            kind: 'placed-footprint',
+            footprintKey,
+            designator,
+            pattern,
+            componentIndex: Number(group.componentIndex),
+            outputLibraryKey: 'pcb-extract/' + footprintKey + '.PcbLib',
+            renderManifestKey: 'pcb-extract/' + footprintKey + '.render.json',
+            primitiveCounts:
+                PcbPlacedFootprintManifestBuilder.#primitiveCounts(group),
+            layers: PcbPlacedFootprintManifestBuilder.#layers(group),
+            embeddedAssets: PcbPlacedFootprintManifestBuilder.#embeddedAssets(
+                group,
+                context.embeddedModels || []
+            ),
+            diagnostics: PcbPlacedFootprintManifestBuilder.#diagnostics(group)
+        }
+    }
+
+    /**
+     * Counts footprint-owned primitive families.
+     * @param {object} group Component primitive group.
+     * @returns {object}
+     */
+    static #primitiveCounts(group) {
+        return {
+            pads: (group.pads || []).length,
+            tracks: (group.tracks || []).length,
+            arcs: (group.arcs || []).length,
+            fills: (group.fills || []).length,
+            vias: (group.vias || []).length,
+            regions: (group.regions || []).length,
+            shapeBasedRegions: (group.shapeBasedRegions || []).length,
+            texts: (group.texts || []).length,
+            componentBodies: (group.componentBodies || []).length
+        }
+    }
+
+    /**
+     * Builds layer descriptors touched by one footprint.
+     * @param {object} group Component primitive group.
+     * @returns {object[]}
+     */
+    static #layers(group) {
+        const layerMap = new Map()
+        for (const primitive of PcbPlacedFootprintManifestBuilder.#primitives(
+            group
+        )) {
+            const layer =
+                PcbPlacedFootprintManifestBuilder.#layerDescriptor(primitive)
+            if (layer) {
+                layerMap.set(layer.layerKey, layer)
+            }
+        }
+        return [...layerMap.values()].sort((left, right) =>
+            left.layerKey.localeCompare(right.layerKey, undefined, {
+                numeric: true
+            })
+        )
+    }
+
+    /**
+     * Collects embedded assets referenced by component bodies.
+     * @param {object} group Component primitive group.
+     * @param {object[]} embeddedModels Embedded model rows.
+     * @returns {object[]}
+     */
+    static #embeddedAssets(group, embeddedModels) {
+        return PcbPlacedFootprintManifestBuilder.#dedupe(
+            (group.componentBodies || []).flatMap((body) => {
+                const model =
+                    PcbPlacedFootprintManifestBuilder.#matchingModel(
+                        body,
+                        embeddedModels
+                    ) || body
+                return [
+                    PcbPlacedFootprintManifestBuilder.#stripUndefined({
+                        key: model.id || body.modelId || model.name,
+                        format: model.format,
+                        sourceStream: model.sourceStream,
+                        name: model.name || body.name
+                    })
+                ]
+            })
+        )
+    }
+
+    /**
+     * Builds extraction diagnostics for one group.
+     * @param {object} group Component primitive group.
+     * @returns {object[]}
+     */
+    static #diagnostics(group) {
+        const diagnostics = []
+        if (!PcbPlacedFootprintManifestBuilder.#hasOwnedGeometry(group)) {
+            diagnostics.push({
+                code: 'pcb-footprint-extract.empty-geometry',
+                severity: 'warning',
+                message: 'Placed component has no owned footprint geometry.'
+            })
+        }
+        return diagnostics
+    }
+
+    /**
+     * Builds manifest lookup indexes.
+     * @param {object[]} outputs Output descriptors.
+     * @returns {object}
+     */
+    static #indexes(outputs) {
+        const outputsByDesignator = {}
+        const outputsByPattern = {}
+
+        outputs.forEach((output, index) => {
+            if (output.designator)
+                outputsByDesignator[output.designator] = index
+            if (output.pattern) {
+                outputsByPattern[output.pattern] =
+                    outputsByPattern[output.pattern] || []
+                outputsByPattern[output.pattern].push(index)
+            }
+        })
+
+        return {
+            outputsByDesignator,
+            outputsByPattern
+        }
+    }
+
+    /**
+     * Returns all geometry primitives from a group.
+     * @param {object} group Component primitive group.
+     * @returns {object[]}
+     */
+    static #primitives(group) {
+        return [
+            ...(group.pads || []),
+            ...(group.tracks || []),
+            ...(group.arcs || []),
+            ...(group.fills || []),
+            ...(group.vias || []),
+            ...(group.regions || []),
+            ...(group.shapeBasedRegions || []),
+            ...(group.texts || [])
+        ]
+    }
+
+    /**
+     * Returns true when a component has any extractable geometry.
+     * @param {object} group Component primitive group.
+     * @returns {boolean}
+     */
+    static #hasOwnedGeometry(group) {
+        return (
+            PcbPlacedFootprintManifestBuilder.#primitives(group).length > 0 ||
+            (group.componentBodies || []).length > 0
+        )
+    }
+
+    /**
+     * Builds a normalized layer descriptor.
+     * @param {object} primitive Primitive row.
+     * @returns {object | null}
+     */
+    static #layerDescriptor(primitive) {
+        const layerId = Number.isInteger(primitive?.layerId)
+            ? primitive.layerId
+            : null
+        const displayName = String(
+            primitive?.layerName || primitive?.layer || ''
+        ).trim()
+        if (layerId === null && !displayName) {
+            return null
+        }
+        const layerKey =
+            layerId === null
+                ? 'layer-' +
+                  PcbPlacedFootprintManifestBuilder.#slug(displayName)
+                : 'L' + layerId
+
+        return PcbPlacedFootprintManifestBuilder.#stripUndefined({
+            layerKey,
+            layerId: layerId === null ? undefined : layerId,
+            displayName: displayName || layerKey
+        })
+    }
+
+    /**
+     * Resolves an embedded model row for one component body.
+     * @param {object} body Component body row.
+     * @param {object[]} embeddedModels Embedded model rows.
+     * @returns {object | null}
+     */
+    static #matchingModel(body, embeddedModels) {
+        return (
+            (embeddedModels || []).find(
+                (model) =>
+                    PcbPlacedFootprintManifestBuilder.#same(
+                        model.id,
+                        body.modelId
+                    ) ||
+                    PcbPlacedFootprintManifestBuilder.#same(
+                        model.checksum,
+                        body.checksum
+                    ) ||
+                    PcbPlacedFootprintManifestBuilder.#same(
+                        model.name,
+                        body.name
+                    )
+            ) || null
+        )
+    }
+
+    /**
+     * Compares two non-empty values.
+     * @param {unknown} left First value.
+     * @param {unknown} right Second value.
+     * @returns {boolean}
+     */
+    static #same(left, right) {
+        return (
+            left !== null &&
+            left !== undefined &&
+            left !== '' &&
+            right !== null &&
+            right !== undefined &&
+            right !== '' &&
+            String(left) === String(right)
+        )
+    }
+
+    /**
+     * Deduplicates objects by their JSON form.
+     * @param {object[]} rows Candidate rows.
+     * @returns {object[]}
+     */
+    static #dedupe(rows) {
+        const seen = new Set()
+        const deduped = []
+        for (const row of rows || []) {
+            const key = JSON.stringify(row)
+            if (seen.has(key)) continue
+            seen.add(key)
+            deduped.push(row)
+        }
+        return deduped
+    }
+
+    /**
+     * Converts a value to a deterministic lowercase key segment.
+     * @param {unknown} value Source value.
+     * @returns {string}
+     */
+    static #slug(value) {
+        return (
+            String(value || '')
+                .trim()
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/gu, '-')
+                .replace(/^-+|-+$/gu, '') || 'item'
+        )
+    }
+
+    /**
+     * Removes undefined fields from one object.
+     * @param {Record<string, unknown>} value Candidate object.
+     * @returns {Record<string, unknown>}
+     */
+    static #stripUndefined(value) {
+        return Object.fromEntries(
+            Object.entries(value || {}).filter(
+                ([, entryValue]) => entryValue !== undefined
+            )
+        )
+    }
+}

package/src/core/altium/PcbPolygonRecordParser.mjs

@@ -0,0 +1,120 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { AltiumLayoutParser } from './AltiumLayoutParser.mjs'
+import { ParserUtils } from './ParserUtils.mjs'
+
+const { getField, parseBoolean, parseNumericField } = ParserUtils
+
+/**
+ * Normalizes printable PCB polygon records into renderable polygon rows.
+ */
+export class PcbPolygonRecordParser {
+    /**
+     * Parses polygon rows from printable records.
+     * @param {{ fields: Record<string, string | string[]>, sourceStream?: string }[]} records Printable records.
+     * @returns {object[]}
+     */
+    static parse(records) {
+        return (records || [])
+            .filter(
+                (record) =>
+                    record.sourceStream === 'Polygons6/Data' &&
+                    getField(record.fields, 'KIND0')
+            )
+            .map((record, index) =>
+                PcbPolygonRecordParser.#normalize(record.fields, index)
+            )
+            .filter((polygon) => polygon.segments.length > 0)
+    }
+
+    /**
+     * Normalizes one printable polygon row.
+     * @param {Record<string, string | string[]>} fields Record fields.
+     * @param {number} index Fallback row index.
+     * @returns {object}
+     */
+    static #normalize(fields, index) {
+        const outline = AltiumLayoutParser.parseBoardOutline(fields)
+        return PcbPolygonRecordParser.#stripEmpty({
+            layer: getField(fields, 'LAYER') || 'UNKNOWN',
+            polygonIndex: PcbPolygonRecordParser.#firstNumber(fields, [
+                'POLYGONINDEX',
+                'POLYGON_INDEX',
+                'INDEX'
+            ]),
+            subpolygonIndex: PcbPolygonRecordParser.#firstNumber(fields, [
+                'SUBPOLYINDEX',
+                'SUBPOLYGONINDEX',
+                'SUB_POLYGON_INDEX'
+            ]),
+            unionIndex: PcbPolygonRecordParser.#firstNumber(fields, [
+                'UNIONINDEX',
+                'UNION_INDEX'
+            ]),
+            isCutout: PcbPolygonRecordParser.#firstBoolean(fields, [
+                'ISCUTOUT',
+                'IS_CUTOUT',
+                'CUTOUT'
+            ]),
+            realizationKind:
+                getField(fields, 'POLYGONKIND') ||
+                getField(fields, 'POURKIND') ||
+                '',
+            sourceRecordIndex: index,
+            segments: outline.segments
+        })
+    }
+
+    /**
+     * Reads the first numeric field from a list of native aliases.
+     * @param {Record<string, string | string[]>} fields Record fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {number | undefined}
+     */
+    static #firstNumber(fields, keys) {
+        for (const key of keys) {
+            const value = parseNumericField(fields, key)
+            if (value !== null) {
+                return value
+            }
+        }
+
+        return undefined
+    }
+
+    /**
+     * Reads the first boolean field from a list of native aliases.
+     * @param {Record<string, string | string[]>} fields Record fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {boolean | undefined}
+     */
+    static #firstBoolean(fields, keys) {
+        for (const key of keys) {
+            if (getField(fields, key)) {
+                return parseBoolean(fields[key])
+            }
+        }
+
+        return undefined
+    }
+
+    /**
+     * Removes empty optional fields while preserving zero and false.
+     * @param {Record<string, unknown>} value Candidate object.
+     * @returns {Record<string, unknown>}
+     */
+    static #stripEmpty(value) {
+        return Object.fromEntries(
+            Object.entries(value || {}).filter(([, entryValue]) => {
+                if (Array.isArray(entryValue)) return entryValue.length > 0
+                return (
+                    entryValue !== null &&
+                    entryValue !== undefined &&
+                    entryValue !== ''
+                )
+            })
+        )
+    }
+}