altium-toolkit 1.0.8 → 1.0.10

package/src/core/altium/PcbOwnershipGraphBuilder.mjs

@@ -0,0 +1,245 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds a read-only PCB primitive ownership graph from normalized indexes.
+ */
+export class PcbOwnershipGraphBuilder {
+    static SCHEMA_ID = 'altium-toolkit.pcb.ownership.a1'
+
+    /**
+     * Builds primitive owner groups keyed by component, net, and polygon index.
+     * @param {{ components?: object[], nets?: object[], fills?: object[], tracks?: object[], arcs?: object[], vias?: object[], pads?: object[], regions?: object[], shapeBasedRegions?: object[], texts?: object[] }} pcb Normalized PCB model.
+     * @returns {{ schema: string, primitiveOwners: object[], componentsByIndex: Record<string, object>, netsByIndex: Record<string, object>, polygonsByIndex: Record<string, object> }}
+     */
+    static build(pcb) {
+        const componentNames = PcbOwnershipGraphBuilder.#componentNames(
+            pcb?.components || []
+        )
+        const netNames = PcbOwnershipGraphBuilder.#netNames(pcb?.nets || [])
+        const componentsByIndex =
+            PcbOwnershipGraphBuilder.#initialComponentGroups(
+                pcb?.components || []
+            )
+        const netsByIndex = {}
+        const polygonsByIndex = {}
+        const primitiveOwners = []
+
+        for (const item of PcbOwnershipGraphBuilder.#primitiveItems(pcb)) {
+            const owner = PcbOwnershipGraphBuilder.#primitiveOwner(
+                item,
+                componentNames,
+                netNames
+            )
+            if (!owner) {
+                continue
+            }
+
+            primitiveOwners.push(owner)
+            PcbOwnershipGraphBuilder.#addGroupKey(
+                componentsByIndex,
+                owner.componentIndex,
+                {
+                    componentIndex: owner.componentIndex,
+                    designator: owner.component || '',
+                    primitiveKeys: []
+                },
+                owner.primitiveKey
+            )
+            PcbOwnershipGraphBuilder.#addGroupKey(
+                netsByIndex,
+                owner.netIndex,
+                {
+                    netIndex: owner.netIndex,
+                    name: owner.net || '',
+                    primitiveKeys: []
+                },
+                owner.primitiveKey
+            )
+            PcbOwnershipGraphBuilder.#addGroupKey(
+                polygonsByIndex,
+                owner.polygonIndex,
+                {
+                    polygonIndex: owner.polygonIndex,
+                    primitiveKeys: []
+                },
+                owner.primitiveKey
+            )
+        }
+
+        return {
+            schema: PcbOwnershipGraphBuilder.SCHEMA_ID,
+            primitiveOwners,
+            componentsByIndex,
+            netsByIndex,
+            polygonsByIndex
+        }
+    }
+
+    /**
+     * Builds primitive iterable entries in stable renderer collection order.
+     * @param {object} pcb Normalized PCB model.
+     * @returns {{ primitiveKind: string, primitiveKey: string, primitive: object }[]}
+     */
+    static #primitiveItems(pcb) {
+        return [
+            ['fill', pcb?.fills || []],
+            ['track', pcb?.tracks || []],
+            ['arc', pcb?.arcs || []],
+            ['via', pcb?.vias || []],
+            ['pad', pcb?.pads || []],
+            ['region', pcb?.regions || []],
+            ['shape-based-region', pcb?.shapeBasedRegions || []],
+            ['text', pcb?.texts || []],
+            ['polygon', pcb?.polygons || []]
+        ].flatMap(([primitiveKind, primitives]) =>
+            primitives.map((primitive, index) => ({
+                primitiveKind,
+                primitiveKey: primitiveKind + '-' + index,
+                primitive
+            }))
+        )
+    }
+
+    /**
+     * Builds a compact primitive owner row.
+     * @param {{ primitiveKind: string, primitiveKey: string, primitive: object }} item Primitive item.
+     * @param {Map<number, string>} componentNames Component names by native index.
+     * @param {Map<number, string>} netNames Net names by native index.
+     * @returns {object | null}
+     */
+    static #primitiveOwner(item, componentNames, netNames) {
+        const componentIndex =
+            PcbOwnershipGraphBuilder.#optionalInteger(
+                item.primitive.componentIndex
+            ) ??
+            (item.primitiveKind === 'text'
+                ? PcbOwnershipGraphBuilder.#optionalInteger(
+                      item.primitive.ownerIndex
+                  )
+                : null)
+        const netIndex = PcbOwnershipGraphBuilder.#optionalInteger(
+            item.primitive.netIndex
+        )
+        const polygonIndex = PcbOwnershipGraphBuilder.#optionalInteger(
+            item.primitive.polygonIndex
+        )
+
+        if (
+            componentIndex === null &&
+            netIndex === null &&
+            polygonIndex === null
+        ) {
+            return null
+        }
+
+        return {
+            primitiveKey: item.primitiveKey,
+            primitiveKind: item.primitiveKind,
+            componentIndex,
+            component:
+                componentIndex === null
+                    ? ''
+                    : componentNames.get(componentIndex) || '',
+            netIndex,
+            net: netIndex === null ? '' : netNames.get(netIndex) || '',
+            polygonIndex
+        }
+    }
+
+    /**
+     * Builds component designator lookup by native component index.
+     * @param {object[]} components Component rows.
+     * @returns {Map<number, string>}
+     */
+    static #componentNames(components) {
+        const names = new Map()
+
+        for (const component of components || []) {
+            const componentIndex = PcbOwnershipGraphBuilder.#optionalInteger(
+                component?.componentIndex
+            )
+            if (componentIndex !== null) {
+                names.set(componentIndex, String(component.designator || ''))
+            }
+        }
+
+        return names
+    }
+
+    /**
+     * Builds net name lookup by native net index.
+     * @param {object[]} nets Net rows.
+     * @returns {Map<number, string>}
+     */
+    static #netNames(nets) {
+        const names = new Map()
+
+        for (const net of nets || []) {
+            const netIndex = PcbOwnershipGraphBuilder.#optionalInteger(
+                net?.netIndex
+            )
+            if (netIndex !== null) {
+                names.set(netIndex, String(net.name || ''))
+            }
+        }
+
+        return names
+    }
+
+    /**
+     * Creates empty component groups so consumers can inspect ownerless rows.
+     * @param {object[]} components Component rows.
+     * @returns {Record<string, object>}
+     */
+    static #initialComponentGroups(components) {
+        const groups = {}
+
+        for (const component of components || []) {
+            const componentIndex = PcbOwnershipGraphBuilder.#optionalInteger(
+                component?.componentIndex
+            )
+            if (componentIndex !== null) {
+                groups[String(componentIndex)] = {
+                    componentIndex,
+                    designator: String(component.designator || ''),
+                    primitiveKeys: []
+                }
+            }
+        }
+
+        return groups
+    }
+
+    /**
+     * Adds one primitive key to a numeric owner group.
+     * @param {Record<string, object>} groups Group map.
+     * @param {number | null} index Owner index.
+     * @param {object} fallbackGroup Group to create when missing.
+     * @param {string} primitiveKey Primitive key to append.
+     */
+    static #addGroupKey(groups, index, fallbackGroup, primitiveKey) {
+        if (index === null) {
+            return
+        }
+
+        const key = String(index)
+        if (!groups[key]) {
+            groups[key] = fallbackGroup
+        }
+        if (!groups[key].primitiveKeys.includes(primitiveKey)) {
+            groups[key].primitiveKeys.push(primitiveKey)
+        }
+    }
+
+    /**
+     * Parses an optional integer value.
+     * @param {unknown} value Candidate value.
+     * @returns {number | null}
+     */
+    static #optionalInteger(value) {
+        const parsed = Number(value)
+        return Number.isInteger(parsed) ? parsed : null
+    }
+}

package/src/core/altium/PcbPadPrimitiveParser.mjs

@@ -35,19 +35,18 @@ export class PcbPadPrimitiveParser {
             return []
         }
 
-        let offset = 0
+        const records = PcbPadPrimitiveParser.#readPadRecordSequence(
+            normalizedData,
+            0,
+            count
+        )
         const pads = []
 
-        for (let index = 0; index < count; index += 1) {
-            const record = PcbPadPrimitiveParser.#readPadRecordAt(
-                normalizedData,
-                offset
-            )
-
-            if (!record) {
-                return []
-            }
+        if (!records) {
+            return []
+        }
 
+        for (const record of records) {
             const pad = PcbPadPrimitiveParser.#parsePadSubrecords(
                 record.subrecords
             )
@@ -57,25 +56,69 @@ export class PcbPadPrimitiveParser {
             }
 
             pads.push(pad)
-            offset = record.nextOffset
-
-            if (index < count - 1) {
-                const nextOffset =
-                    PcbPadPrimitiveParser.#findNextPadRecordOffset(
-                        normalizedData,
-                        offset,
-                        count - index - 1
-                    )
-
-                if (nextOffset === null) {
-                    return []
+        }
+
+        return pads
+    }
+
+    /**
+     * Reads all expected pad records without recursive suffix validation.
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @param {number} count
+     * @returns {{ subrecords: DataView[], nextOffset: number }[] | null}
+     */
+    static #readPadRecordSequence(bytes, offset, count) {
+        const firstRecord = PcbPadPrimitiveParser.#readPadRecordAt(
+            bytes,
+            offset
+        )
+
+        if (!firstRecord) {
+            return null
+        }
+
+        const records = [firstRecord]
+        const alternativeScanOffsets = [null]
+        let depth = 1
+        let scanOffset = firstRecord.nextOffset
+
+        while (depth < count) {
+            const candidate = PcbPadPrimitiveParser.#findNextPadRecordCandidate(
+                bytes,
+                scanOffset
+            )
+
+            if (!candidate) {
+                let foundAlternative = false
+
+                while (depth > 1 && !foundAlternative) {
+                    depth -= 1
+                    records.length = depth
+
+                    const alternativeOffset = alternativeScanOffsets[depth]
+                    alternativeScanOffsets.length = depth
+
+                    if (alternativeOffset !== null) {
+                        scanOffset = alternativeOffset
+                        foundAlternative = true
+                    }
                 }
 
-                offset = nextOffset
+                if (!foundAlternative) {
+                    return null
+                }
+
+                continue
             }
+
+            records[depth] = candidate.record
+            alternativeScanOffsets[depth] = candidate.alternativeOffset
+            depth += 1
+            scanOffset = candidate.record.nextOffset
         }
 
-        return pads
+        return records
     }
 
     /**
@@ -149,31 +192,28 @@ export class PcbPadPrimitiveParser {
     }
 
     /**
-     * Finds the next pad record boundary after optional unknown subrecords.
+     * Finds the next readable pad record after optional unknown subrecords.
      * @param {Uint8Array} bytes
      * @param {number} offset
-     * @param {number} remainingCount
-     * @returns {number | null}
+     * @returns {{ record: { subrecords: DataView[], nextOffset: number }, alternativeOffset: number | null } | null}
      */
-    static #findNextPadRecordOffset(bytes, offset, remainingCount) {
+    static #findNextPadRecordCandidate(bytes, offset) {
         let cursor = offset
 
         while (cursor < bytes.byteLength) {
-            if (
-                PcbPadPrimitiveParser.#canReadPadRecordSequence(
-                    bytes,
-                    cursor,
-                    remainingCount
-                )
-            ) {
-                return cursor
-            }
-
+            const record = PcbPadPrimitiveParser.#readPadRecordAt(bytes, cursor)
             const unknownSubrecord = PcbPadPrimitiveParser.#readSubrecordAt(
                 bytes,
                 cursor
             )
 
+            if (record) {
+                return {
+                    record,
+                    alternativeOffset: unknownSubrecord?.nextOffset ?? null
+                }
+            }
+
             if (!unknownSubrecord) {
                 return null
             }
@@ -184,33 +224,6 @@ export class PcbPadPrimitiveParser {
         return null
     }
 
-    /**
-     * Checks whether the remaining pad records can be read from an offset.
-     * @param {Uint8Array} bytes
-     * @param {number} offset
-     * @param {number} remainingCount
-     * @returns {boolean}
-     */
-    static #canReadPadRecordSequence(bytes, offset, remainingCount) {
-        const record = PcbPadPrimitiveParser.#readPadRecordAt(bytes, offset)
-
-        if (!record) {
-            return false
-        }
-
-        if (remainingCount <= 1) {
-            return true
-        }
-
-        return (
-            PcbPadPrimitiveParser.#findNextPadRecordOffset(
-                bytes,
-                record.nextOffset,
-                remainingCount - 1
-            ) !== null
-        )
-    }
-
     /**
      * Decodes one pad payload from its subrecords.
      * @param {DataView[]} subrecords

package/src/core/altium/PcbPadStackParser.mjs

@@ -48,6 +48,12 @@ export class PcbPadStackParser {
 
     static #SOLDER_MASK_CACHE_VALID_OFFSET = 104
 
+    static #POSITIVE_TOLERANCE_OFFSET = 162
+
+    static #NEGATIVE_TOLERANCE_OFFSET = 166
+
+    static #HOLE_TOLERANCE_UNSET = 0x7fffffff
+
     static #EXTENSION_MIN_BYTE_LENGTH = 596
 
     static #INNER_LAYER_COUNT = 29
@@ -75,6 +81,10 @@ export class PcbPadStackParser {
         const flags = PcbPadStackParser.#parseFlags(mainRecord)
         const mainRecordTail =
             PcbPadStackParser.#parseMainRecordTail(mainRecord)
+        const extension = PcbPadStackParser.#parseExtensionRecord(
+            extensionRecord,
+            padContext
+        )
 
         return {
             ...flags,
@@ -84,8 +94,10 @@ export class PcbPadStackParser {
                 mainRecordTail,
                 padContext
             ),
-            ...PcbPadStackParser.#parseExtensionRecord(
-                extensionRecord,
+            ...extension,
+            ...PcbPadStackParser.#buildLocalStack(
+                mainRecordTail,
+                extension,
                 padContext
             )
         }
@@ -178,6 +190,7 @@ export class PcbPadStackParser {
 
         PcbPadStackParser.#assignPadCacheFields(result, mainRecord)
         PcbPadStackParser.#assignMaskCacheFields(result, mainRecord)
+        PcbPadStackParser.#assignHoleToleranceFields(result, mainRecord)
 
         return result
     }
@@ -292,6 +305,35 @@ export class PcbPadStackParser {
         }
     }
 
+    /**
+     * Adds optional hole tolerance fields to an output object.
+     * @param {Record<string, unknown>} result
+     * @param {DataView} mainRecord
+     */
+    static #assignHoleToleranceFields(result, mainRecord) {
+        const positiveTolerance = PcbPadStackParser.#readHoleTolerance(
+            mainRecord,
+            PcbPadStackParser.#POSITIVE_TOLERANCE_OFFSET
+        )
+        const negativeTolerance = PcbPadStackParser.#readHoleTolerance(
+            mainRecord,
+            PcbPadStackParser.#NEGATIVE_TOLERANCE_OFFSET
+        )
+        const holeTolerance = {}
+
+        if (positiveTolerance !== null) {
+            result.positiveTolerance = positiveTolerance
+            holeTolerance.positive = positiveTolerance
+        }
+        if (negativeTolerance !== null) {
+            result.negativeTolerance = negativeTolerance
+            holeTolerance.negative = negativeTolerance
+        }
+        if (Object.keys(holeTolerance).length) {
+            result.holeTolerance = holeTolerance
+        }
+    }
+
     /**
      * Returns whether one decoded pad cache contains meaningful data.
      * @param {{ planeConnectionStyle: number, thermalReliefConductorWidth: number, thermalReliefConductorCount: number, thermalReliefAirGap: number, powerPlaneReliefExpansion: number, powerPlaneClearance: number, validity: Record<string, number> }} padCache
@@ -311,6 +353,28 @@ export class PcbPadStackParser {
         return values.some((value) => value !== 0)
     }
 
+    /**
+     * Reads one optional hole tolerance from a pad main record.
+     * @param {DataView} mainRecord
+     * @param {number} offset
+     * @returns {number | null}
+     */
+    static #readHoleTolerance(mainRecord, offset) {
+        if (!mainRecord || offset + 4 > mainRecord.byteLength) {
+            return null
+        }
+
+        const rawValue = mainRecord.getInt32(offset, true)
+        if (
+            rawValue === 0 ||
+            rawValue === PcbPadStackParser.#HOLE_TOLERANCE_UNSET
+        ) {
+            return null
+        }
+
+        return rawValue / 10000
+    }
+
     /**
      * Adds derived mask-expansion and layer-opening semantics.
      * @param {Record<string, boolean | number>} flags
@@ -664,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