altium-toolkit 1.1.3 → 1.1.23

package/src/core/altium/PcbNetMembershipReportBuilder.mjs

@@ -0,0 +1,270 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds deterministic per-net primitive ownership summaries for PCB models.
+ */
+export class PcbNetMembershipReportBuilder {
+    static SCHEMA = 'altium-toolkit.pcb.net-membership.a1'
+
+    /**
+     * Builds a PCB net-membership report from normalized PCB primitives.
+     * @param {object} pcb Normalized PCB model.
+     * @returns {object}
+     */
+    static build(pcb = {}) {
+        const declaredNetNames =
+            PcbNetMembershipReportBuilder.#declaredNetNames(pcb)
+        const rowsByNet = new Map()
+        const unownedPrimitives = []
+        let primitiveCount = 0
+
+        for (const family of PcbNetMembershipReportBuilder.#families()) {
+            const rows = Array.isArray(pcb?.[family]) ? pcb[family] : []
+            primitiveCount += rows.length
+
+            rows.forEach((primitive, index) => {
+                const row = PcbNetMembershipReportBuilder.#primitiveRow(
+                    family,
+                    primitive,
+                    index
+                )
+
+                if (!row.netName) {
+                    unownedPrimitives.push(
+                        PcbNetMembershipReportBuilder.#stripEmpty({
+                            primitiveKey: row.primitiveKey,
+                            family,
+                            index,
+                            layerId: row.layerId
+                        })
+                    )
+                    return
+                }
+
+                if (!rowsByNet.has(row.netName)) {
+                    rowsByNet.set(row.netName, [])
+                }
+                rowsByNet.get(row.netName).push(row)
+            })
+        }
+
+        const observedNetNames = new Set(rowsByNet.keys())
+        const byNet = [...rowsByNet.entries()]
+            .map(([netName, rows]) =>
+                PcbNetMembershipReportBuilder.#netRow(
+                    netName,
+                    rows,
+                    declaredNetNames.has(netName)
+                )
+            )
+            .sort((left, right) =>
+                PcbNetMembershipReportBuilder.#naturalCompare(
+                    left.netName,
+                    right.netName
+                )
+            )
+        const emptyDeclaredNets = [...declaredNetNames]
+            .filter((netName) => !observedNetNames.has(netName))
+            .sort(PcbNetMembershipReportBuilder.#naturalCompare)
+        const undeclaredNets = [...observedNetNames]
+            .filter((netName) => !declaredNetNames.has(netName))
+            .sort(PcbNetMembershipReportBuilder.#naturalCompare)
+        const possibleUnroutedNets = byNet
+            .filter(
+                (net) =>
+                    net.declared &&
+                    net.padCount >= 2 &&
+                    net.trackCount + net.arcCount + net.viaCount === 0
+            )
+            .map((net) => net.netName)
+
+        return {
+            schema: PcbNetMembershipReportBuilder.SCHEMA,
+            summary: {
+                declaredNetCount: declaredNetNames.size,
+                observedNetCount: observedNetNames.size,
+                matchedNetCount: [...observedNetNames].filter((netName) =>
+                    declaredNetNames.has(netName)
+                ).length,
+                undeclaredNetCount: undeclaredNets.length,
+                emptyDeclaredNetCount: emptyDeclaredNets.length,
+                netCount: new Set([...declaredNetNames, ...observedNetNames])
+                    .size,
+                primitiveCount,
+                ownedPrimitiveCount: primitiveCount - unownedPrimitives.length,
+                unownedPrimitiveCount: unownedPrimitives.length,
+                possibleUnroutedNetCount: possibleUnroutedNets.length
+            },
+            byNet,
+            emptyDeclaredNets,
+            undeclaredNets,
+            possibleUnroutedNets,
+            unownedPrimitives
+        }
+    }
+
+    /**
+     * Returns primitive families that can carry net ownership.
+     * @returns {string[]}
+     */
+    static #families() {
+        return [
+            'pads',
+            'tracks',
+            'arcs',
+            'vias',
+            'fills',
+            'regions',
+            'shapeBasedRegions',
+            'polygons'
+        ]
+    }
+
+    /**
+     * Collects declared net names from the normalized net table.
+     * @param {object} pcb Normalized PCB model.
+     * @returns {Set<string>}
+     */
+    static #declaredNetNames(pcb) {
+        return new Set(
+            (Array.isArray(pcb?.nets) ? pcb.nets : [])
+                .map((net) => String(net?.name || '').trim())
+                .filter(Boolean)
+        )
+    }
+
+    /**
+     * Builds one normalized primitive membership row.
+     * @param {string} family Primitive family name.
+     * @param {object} primitive Primitive row.
+     * @param {number} index Primitive index within its family.
+     * @returns {object}
+     */
+    static #primitiveRow(family, primitive, index) {
+        return PcbNetMembershipReportBuilder.#stripEmpty({
+            primitiveKey: family + '-' + index,
+            family,
+            index,
+            netName: PcbNetMembershipReportBuilder.#netName(primitive),
+            layerId: PcbNetMembershipReportBuilder.#layerId(primitive),
+            padDesignator:
+                family === 'pads'
+                    ? PcbNetMembershipReportBuilder.#padDesignator(primitive)
+                    : undefined
+        })
+    }
+
+    /**
+     * Builds one per-net aggregate row.
+     * @param {string} netName Net name.
+     * @param {object[]} rows Primitive rows owned by the net.
+     * @param {boolean} declared Whether the net is declared in the net table.
+     * @returns {object}
+     */
+    static #netRow(netName, rows, declared) {
+        const counts = Object.fromEntries(
+            PcbNetMembershipReportBuilder.#families().map((family) => [
+                family,
+                0
+            ])
+        )
+        const layerIds = new Set()
+        const padDesignators = new Set()
+        const memberKeys = []
+
+        for (const row of rows) {
+            counts[row.family] = Number(counts[row.family] || 0) + 1
+            memberKeys.push(row.primitiveKey)
+            if (Number.isInteger(row.layerId)) {
+                layerIds.add(row.layerId)
+            }
+            if (row.padDesignator) {
+                padDesignators.add(row.padDesignator)
+            }
+        }
+
+        return {
+            netName,
+            declared,
+            totalPrimitiveCount: rows.length,
+            padCount: counts.pads,
+            trackCount: counts.tracks,
+            arcCount: counts.arcs,
+            viaCount: counts.vias,
+            fillCount: counts.fills,
+            regionCount: counts.regions,
+            shapeBasedRegionCount: counts.shapeBasedRegions,
+            polygonCount: counts.polygons,
+            layers: [...layerIds].sort((left, right) => left - right),
+            padDesignators: [...padDesignators].sort(
+                PcbNetMembershipReportBuilder.#naturalCompare
+            ),
+            memberKeys
+        }
+    }
+
+    /**
+     * Resolves a primitive net name from normalized field spellings.
+     * @param {object} primitive Primitive row.
+     * @returns {string}
+     */
+    static #netName(primitive) {
+        return String(
+            primitive?.netName || primitive?.net || primitive?.netLabel || ''
+        ).trim()
+    }
+
+    /**
+     * Resolves a primitive layer id from normalized field spellings.
+     * @param {object} primitive Primitive row.
+     * @returns {number | undefined}
+     */
+    static #layerId(primitive) {
+        for (const key of ['layerId', 'layerCode', 'id', 'index']) {
+            const number = Number(primitive?.[key])
+            if (Number.isInteger(number)) {
+                return number
+            }
+        }
+
+        return undefined
+    }
+
+    /**
+     * Resolves a pad designator from normalized field spellings.
+     * @param {object} pad Pad row.
+     * @returns {string}
+     */
+    static #padDesignator(pad) {
+        return String(
+            pad?.designator || pad?.padNumber || pad?.pinName || pad?.name || ''
+        ).trim()
+    }
+
+    /**
+     * Sorts strings with numeric chunks in human order.
+     * @param {string} left Left value.
+     * @param {string} right Right value.
+     * @returns {number}
+     */
+    static #naturalCompare(left, right) {
+        return String(left).localeCompare(String(right), undefined, {
+            numeric: true
+        })
+    }
+
+    /**
+     * Removes undefined and blank-string values from a shallow object.
+     * @param {Record<string, unknown>} row Input row.
+     * @returns {Record<string, unknown>}
+     */
+    static #stripEmpty(row) {
+        return Object.fromEntries(
+            Object.entries(row).filter(
+                ([, value]) => value !== undefined && value !== ''
+            )
+        )
+    }
+}

package/src/core/altium/PcbOutlineRecovery.mjs

@@ -24,6 +24,8 @@ export class PcbOutlineRecovery {
 
     static #MAX_DIRECT_RENDER_ARC_SWEEP_DEGREES = 120
 
+    static #MAX_MECHANICAL_FRAME_TO_AUTHORED_AREA_RATIO = 16
+
     /**
      * Selects a recoverable board outline from mechanical track layers.
      * @param {{ fallbackOutline: { minX: number, minY: number, widthMil: number, heightMil: number, segments: Array<Record<string, number | string>> }, components: { x: number, y: number }[], tracks: { x1: number, y1: number, x2: number, y2: number, width: number, layerId?: number }[] }} options
@@ -76,6 +78,20 @@ export class PcbOutlineRecovery {
             }
         }
 
+        if (
+            PcbOutlineRecovery.#shouldKeepAuthoredOutline(
+                fallbackOutline,
+                boundaryLayer.bounds,
+                componentBounds
+            )
+        ) {
+            return {
+                source: 'fallback',
+                layerId: null,
+                outline: fallbackOutline
+            }
+        }
+
         const recoveredOutline =
             PcbOutlineRecovery.#traceTrackOutline(
                 boundaryLayer.tracks,
@@ -166,6 +182,84 @@ export class PcbOutlineRecovery {
         return candidates[0] || null
     }
 
+    /**
+     * Returns true when the mechanical candidate is likely a drawing frame
+     * around an otherwise plausible authored board route.
+     * @param {{ minX: number, minY: number, widthMil: number, heightMil: number, segments?: Array<Record<string, number | string>> }} authoredOutline Authored board-route outline.
+     * @param {{ widthMil: number, heightMil: number }} mechanicalBounds Mechanical track-layer bounds.
+     * @param {{ centerX: number, centerY: number }} componentBounds Component placement envelope.
+     * @returns {boolean}
+     */
+    static #shouldKeepAuthoredOutline(
+        authoredOutline,
+        mechanicalBounds,
+        componentBounds
+    ) {
+        if (
+            !PcbOutlineRecovery.#isClosedOutlinePath(
+                authoredOutline?.segments || []
+            )
+        ) {
+            return false
+        }
+
+        const authoredArea =
+            Number(authoredOutline?.widthMil || 0) *
+            Number(authoredOutline?.heightMil || 0)
+        const mechanicalArea =
+            Number(mechanicalBounds?.widthMil || 0) *
+            Number(mechanicalBounds?.heightMil || 0)
+
+        if (!authoredArea || !mechanicalArea) {
+            return false
+        }
+
+        if (
+            mechanicalArea / authoredArea <=
+            PcbOutlineRecovery.#MAX_MECHANICAL_FRAME_TO_AUTHORED_AREA_RATIO
+        ) {
+            return false
+        }
+
+        return PcbOutlineRecovery.#outlineEnvelopeContainsPoint(
+            authoredOutline,
+            componentBounds?.centerX,
+            componentBounds?.centerY
+        )
+    }
+
+    /**
+     * Returns true when one point falls within an outline's bounding envelope.
+     * @param {{ minX?: number, minY?: number, widthMil?: number, heightMil?: number }} outline Outline bounds.
+     * @param {number} x Point X coordinate.
+     * @param {number} y Point Y coordinate.
+     * @returns {boolean}
+     */
+    static #outlineEnvelopeContainsPoint(outline, x, y) {
+        const minX = Number(outline?.minX)
+        const minY = Number(outline?.minY)
+        const widthMil = Number(outline?.widthMil)
+        const heightMil = Number(outline?.heightMil)
+
+        if (
+            !Number.isFinite(minX) ||
+            !Number.isFinite(minY) ||
+            !Number.isFinite(widthMil) ||
+            !Number.isFinite(heightMil) ||
+            !Number.isFinite(x) ||
+            !Number.isFinite(y)
+        ) {
+            return false
+        }
+
+        return (
+            x >= minX &&
+            x <= minX + widthMil &&
+            y >= minY &&
+            y <= minY + heightMil
+        )
+    }
+
     /**
      * Builds one track-bounds envelope.
      * @param {{ x1: number, y1: number, x2: number, y2: number }[]} tracks

package/src/core/altium/PcbStreamExtractor.mjs

@@ -4,6 +4,7 @@
 
 import { AsciiRecordParser } from './AsciiRecordParser.mjs'
 import { EmbeddedFileInventoryBuilder } from './EmbeddedFileInventoryBuilder.mjs'
+import { NativeStreamInventoryBuilder } from './NativeStreamInventoryBuilder.mjs'
 import { PcbBinaryPrimitiveParser } from './PcbBinaryPrimitiveParser.mjs'
 import { PcbCustomPadShapeParser } from './PcbCustomPadShapeParser.mjs'
 import { PcbEmbeddedFontExtractor } from './PcbEmbeddedFontExtractor.mjs'
@@ -11,12 +12,45 @@ import { PcbEmbeddedModelExtractor } from './PcbEmbeddedModelExtractor.mjs'
 import { PcbExtendedPrimitiveInformationParser } from './PcbExtendedPrimitiveInformationParser.mjs'
 import { PcbPrimitiveParameterParser } from './PcbPrimitiveParameterParser.mjs'
 import { PcbRawRecordRegistry } from './PcbRawRecordRegistry.mjs'
+import { PcbSidecarRecordParser } from './PcbSidecarRecordParser.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'
 
+const KNOWN_PCB_STREAM_STORAGES = new Set([
+    'Board6',
+    'Nets6',
+    'Arcs6',
+    'Pads6',
+    'Vias6',
+    'Tracks6',
+    'Texts',
+    'Texts6',
+    'Fills6',
+    'Regions6',
+    'ShapeBasedRegions6',
+    'BoardRegions',
+    'ComponentBodies6',
+    'Polygons6',
+    'Components6',
+    'Classes6',
+    'DifferentialPairs6',
+    'EmbeddedBoards6',
+    'Rooms6',
+    'Rules6',
+    'WideStrings6',
+    'PrimitiveParameters',
+    'ViaStructures',
+    'ViaStructureManager',
+    'ExtendedPrimitiveInformation',
+    'CustomShapes',
+    'UnionNames',
+    'SmartUnions',
+    'Models'
+])
+
 /**
  * Extracts stream-scoped printable and binary PCB content from OLE-backed
  * PcbDoc containers.
@@ -99,12 +133,15 @@ export class PcbStreamExtractor {
                 continue
             }
 
-            const recordBuffer = PcbStreamExtractor.#toArrayBuffer(bytes)
-            const streamRecords = AsciiRecordParser.parse(recordBuffer).map(
-                (record) => ({
-                    ...record,
-                    sourceStream: name
-                })
+            if (
+                PcbStreamExtractor.#isSupersededLegacyDataStream(name, streams)
+            ) {
+                continue
+            }
+
+            const streamRecords = PcbStreamExtractor.#parseDataStreamRecords(
+                name,
+                bytes
             )
 
             if (!streamRecords.length) {
@@ -335,11 +372,23 @@ export class PcbStreamExtractor {
             usedStreamNames.add(diagnostic.sourceStream)
         )
 
+        const nativeStreams = NativeStreamInventoryBuilder.buildFromStreams(
+            streams,
+            {
+                source: 'pcbdoc',
+                consumedStreamNames: usedStreamNames,
+                knownStreamNames: [...streams.keys()].filter((streamName) =>
+                    PcbStreamExtractor.#isKnownNativeStream(streamName)
+                )
+            }
+        )
+
         return {
             records,
             streamNames: [...usedStreamNames].sort((left, right) =>
                 left.localeCompare(right)
             ),
+            nativeStreams,
             binaryPrimitives,
             primitiveParameters,
             wideStrings,
@@ -395,6 +444,38 @@ export class PcbStreamExtractor {
         )
     }
 
+    /**
+     * Parses a data stream as length-prefixed sidecar records when needed, with
+     * printable-record fallback for regular pipe-delimited streams.
+     * @param {string} name Stream path.
+     * @param {Uint8Array} bytes Stream bytes.
+     * @returns {Array<{ raw?: string, fields: Record<string, string | string[]>, sourceStream: string, recordIndex?: number }>}
+     */
+    static #parseDataStreamRecords(name, bytes) {
+        if (PcbStreamExtractor.#isLengthPrefixedPrintableStream(name)) {
+            const sidecarRecords =
+                PcbSidecarRecordParser.parseLengthPrefixedRecords(bytes, name)
+            if (sidecarRecords.length) {
+                return sidecarRecords
+            }
+        }
+
+        const recordBuffer = PcbStreamExtractor.#toArrayBuffer(bytes)
+        return AsciiRecordParser.parse(recordBuffer).map((record) => ({
+            ...record,
+            sourceStream: name
+        }))
+    }
+
+    /**
+     * Returns true for printable sidecar streams that may use length prefixes.
+     * @param {string} name Stream path.
+     * @returns {boolean}
+     */
+    static #isLengthPrefixedPrintableStream(name) {
+        return name === 'EmbeddedBoards6/Data' || name === 'Rooms6/Data'
+    }
+
     /**
      * Returns true for binary sidecar streams with printable-looking payloads.
      * @param {string} name
@@ -413,6 +494,34 @@ export class PcbStreamExtractor {
         )
     }
 
+    /**
+     * Returns true when a legacy printable stream has a versioned companion.
+     * @param {string} name Stream path.
+     * @param {Map<string, Uint8Array>} streams Source stream map.
+     * @returns {boolean}
+     */
+    static #isSupersededLegacyDataStream(name, streams) {
+        const suffix = '/Data'
+        if (!name.endsWith(suffix)) {
+            return false
+        }
+
+        const storagePath = name.slice(0, -suffix.length)
+        const separatorIndex = storagePath.lastIndexOf('/')
+        const parentPath =
+            separatorIndex >= 0 ? storagePath.slice(0, separatorIndex + 1) : ''
+        const storageName =
+            separatorIndex >= 0
+                ? storagePath.slice(separatorIndex + 1)
+                : storagePath
+
+        if (!storageName || /\d$/u.test(storageName)) {
+            return false
+        }
+
+        return streams.has(parentPath + storageName + '6' + suffix)
+    }
+
     /**
      * Collects sidecar source stream names that produced via-structure data.
      * @param {{ structures?: { sourceStream?: string }[], links?: { sourceStream?: string }[] }} viaStructures
@@ -437,4 +546,19 @@ export class PcbStreamExtractor {
             .map((record) => record.sourceStream)
             .filter(Boolean)
     }
+
+    /**
+     * Returns true when a native stream name belongs to a recognized PCB
+     * storage.
+     * @param {string} streamName Native stream name.
+     * @returns {boolean}
+     */
+    static #isKnownNativeStream(streamName) {
+        if (streamName === 'FileHeader') {
+            return true
+        }
+
+        const storageName = String(streamName || '').split('/')[0]
+        return KNOWN_PCB_STREAM_STORAGES.has(storageName)
+    }
 }

package/src/core/altium/PcbTrackPrimitiveParser.mjs

@@ -19,7 +19,7 @@ export class PcbTrackPrimitiveParser {
      * Decodes one track stream.
      * @param {Uint8Array | ArrayBuffer} headerBytes
      * @param {Uint8Array | ArrayBuffer} dataBytes
-     * @returns {{ x1: number, y1: number, x2: number, y2: number, width: number, componentIndex: number | null, netIndex: number | null, polygonIndex: number | null, layerCode: number, layerId: number }[]}
+     * @returns {{ x1: number, y1: number, x2: number, y2: number, width: number, componentIndex: number | null, netIndex: number | null, polygonIndex: number | null, layerCode: number, layerId: number, [key: string]: unknown }[]}
      */
     static parseTrackStream(headerBytes, dataBytes) {
         return PcbTrackPrimitiveParser.#sliceTrackRecords(
@@ -31,7 +31,7 @@ export class PcbTrackPrimitiveParser {
     /**
      * Decodes one track record view into a normalized primitive.
      * @param {DataView} view
-     * @returns {{ x1: number, y1: number, x2: number, y2: number, width: number, componentIndex: number | null, netIndex: number | null, polygonIndex: number | null, layerCode: number, layerId: number }}
+     * @returns {{ x1: number, y1: number, x2: number, y2: number, width: number, componentIndex: number | null, netIndex: number | null, polygonIndex: number | null, layerCode: number, layerId: number, [key: string]: unknown }}
      */
     static #parseTrackRecord(view) {
         const layerId = view.getUint8(0)
@@ -49,11 +49,61 @@ export class PcbTrackPrimitiveParser {
             y2: PcbTrackPrimitiveParser.#readMil(view, 25),
             width: PcbTrackPrimitiveParser.#readMil(view, 29),
             ...ownershipIndexes,
+            ...PcbTrackPrimitiveParser.#parseTrackMetadata(view),
             layerCode: layerId,
             layerId
         }
     }
 
+    /**
+     * Decodes optional route-state metadata from one track record.
+     * @param {DataView} view Track record view.
+     * @returns {{ trackFlags?: number, isSelected?: boolean, isLocked?: boolean, isPartOfComponent?: boolean, isKeepout?: boolean, unionIndex?: number, isLengthTuning?: boolean, isUserRouted?: boolean }}
+     */
+    static #parseTrackMetadata(view) {
+        const flags = PcbTrackPrimitiveParser.#readByteIfAvailable(view, 1)
+        const keepout = PcbTrackPrimitiveParser.#readByteIfAvailable(view, 2)
+        const unionIndex = PcbTrackPrimitiveParser.#readByteIfAvailable(
+            view,
+            36
+        )
+        const lengthTuning = PcbTrackPrimitiveParser.#readByteIfAvailable(
+            view,
+            37
+        )
+        const userRouted = PcbTrackPrimitiveParser.#readByteIfAvailable(
+            view,
+            44
+        )
+
+        if (!flags && !keepout && !unionIndex && !lengthTuning && !userRouted) {
+            return {}
+        }
+
+        const result = {}
+
+        if (flags) {
+            result.trackFlags = flags
+            result.isSelected = (flags & 0x01) !== 0
+            result.isLocked = (flags & 0x04) === 0
+            result.isPartOfComponent = (flags & 0x10) !== 0
+        }
+        if (keepout) {
+            result.isKeepout = true
+        }
+        if (unionIndex) {
+            result.unionIndex = unionIndex
+        }
+        if (lengthTuning) {
+            result.isLengthTuning = true
+        }
+        if (userRouted) {
+            result.isUserRouted = true
+        }
+
+        return result
+    }
+
     /**
      * Splits a track stream into record views, preserving variable payload
      * lengths when tracks are stored with object-id and payload-length
@@ -84,4 +134,18 @@ export class PcbTrackPrimitiveParser {
     static #readMil(view, offset) {
         return view.getInt32(offset, true) / 10000
     }
+
+    /**
+     * Reads one byte when it is present in a variable-length record.
+     * @param {DataView} view Record view.
+     * @param {number} offset Byte offset.
+     * @returns {number}
+     */
+    static #readByteIfAvailable(view, offset) {
+        if (!view || offset >= view.byteLength) {
+            return 0
+        }
+
+        return view.getUint8(offset)
+    }
 }