altium-toolkit 1.0.8 → 1.0.9

package/src/core/altium/PcbViaStackParser.mjs

@@ -56,6 +56,12 @@ export class PcbViaStackParser {
 
     static #DRILL_LAYER_PAIR_TYPE_OFFSET = 317
 
+    static #PROPAGATION_DELAY_OFFSET = 321
+
+    static #HOLE_TOLERANCE_UNSET = 0x7fffffff
+
+    static #PICOSECONDS_PER_SECOND = 1_000_000_000_000
+
     static #PHYSICAL_LAYER_COUNT = 32
 
     /**
@@ -417,14 +423,21 @@ export class PcbViaStackParser {
             PcbViaStackParser.#TAIL_SIGNATURE_OFFSET + offsetShift,
             16
         )
-        const positiveTolerance = PcbViaStackParser.#readMilIfAvailable(
-            view,
-            PcbViaStackParser.#POSITIVE_TOLERANCE_OFFSET + offsetShift
-        )
-        const negativeTolerance = PcbViaStackParser.#readMilIfAvailable(
-            view,
-            PcbViaStackParser.#NEGATIVE_TOLERANCE_OFFSET + offsetShift
-        )
+        const positiveTolerance =
+            PcbViaStackParser.#readHoleToleranceIfAvailable(
+                view,
+                PcbViaStackParser.#POSITIVE_TOLERANCE_OFFSET + offsetShift
+            )
+        const negativeTolerance =
+            PcbViaStackParser.#readHoleToleranceIfAvailable(
+                view,
+                PcbViaStackParser.#NEGATIVE_TOLERANCE_OFFSET + offsetShift
+            )
+        const propagationDelayPs =
+            PcbViaStackParser.#readPropagationDelayIfAvailable(
+                view,
+                PcbViaStackParser.#PROPAGATION_DELAY_OFFSET + offsetShift
+            )
         const drillLayerPairType = PcbViaStackParser.#readByteIfAvailable(
             view,
             PcbViaStackParser.#DRILL_LAYER_PAIR_TYPE_OFFSET + offsetShift
@@ -439,12 +452,20 @@ export class PcbViaStackParser {
         if (tailSignature) {
             result.tailSignature = tailSignature
         }
-        if (positiveTolerance) {
+        if (positiveTolerance !== null) {
             result.positiveTolerance = positiveTolerance
         }
-        if (negativeTolerance) {
+        if (negativeTolerance !== null) {
             result.negativeTolerance = negativeTolerance
         }
+        PcbViaStackParser.#assignHoleTolerance(
+            result,
+            positiveTolerance,
+            negativeTolerance
+        )
+        if (propagationDelayPs !== null) {
+            result.propagationDelayPs = propagationDelayPs
+        }
         if (drillLayerPairType) {
             result.drillLayerPairType = drillLayerPairType
         }
@@ -494,6 +515,73 @@ export class PcbViaStackParser {
         return view.getInt32(offset, true) / 10000
     }
 
+    /**
+     * Reads one optional hole tolerance and suppresses unset sentinel values.
+     * @param {DataView} view
+     * @param {number} offset
+     * @returns {number | null}
+     */
+    static #readHoleToleranceIfAvailable(view, offset) {
+        if (!view || offset + 4 > view.byteLength) {
+            return null
+        }
+
+        const rawValue = view.getInt32(offset, true)
+        if (
+            rawValue === 0 ||
+            rawValue === PcbViaStackParser.#HOLE_TOLERANCE_UNSET
+        ) {
+            return null
+        }
+
+        return rawValue / 10000
+    }
+
+    /**
+     * Adds grouped semantic hole tolerance fields when tolerances are present.
+     * @param {Record<string, unknown>} result
+     * @param {number | null} positiveTolerance
+     * @param {number | null} negativeTolerance
+     */
+    static #assignHoleTolerance(result, positiveTolerance, negativeTolerance) {
+        const holeTolerance = {}
+
+        if (positiveTolerance !== null) {
+            holeTolerance.positive = positiveTolerance
+        }
+        if (negativeTolerance !== null) {
+            holeTolerance.negative = negativeTolerance
+        }
+        if (Object.keys(holeTolerance).length) {
+            result.holeTolerance = holeTolerance
+        }
+    }
+
+    /**
+     * Reads one optional via propagation delay stored as seconds.
+     * @param {DataView} view
+     * @param {number} offset
+     * @returns {number | null}
+     */
+    static #readPropagationDelayIfAvailable(view, offset) {
+        if (!view || offset + 4 > view.byteLength) {
+            return null
+        }
+
+        const seconds = view.getFloat32(offset, true)
+        const picoseconds = seconds * PcbViaStackParser.#PICOSECONDS_PER_SECOND
+
+        if (
+            !Number.isFinite(picoseconds) ||
+            Math.abs(picoseconds) < 0.001 ||
+            Math.abs(picoseconds) > 1_000_000
+        ) {
+            return null
+        }
+
+        return Number(picoseconds.toFixed(4))
+    }
+
     /**
      * Reads one byte when available.
      * @param {DataView} view

package/src/core/altium/PcbViaStructureParser.mjs

@@ -0,0 +1,335 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PrintableTextDecoder } from './PrintableTextDecoder.mjs'
+
+/**
+ * Decodes via-protection sidecar records and links them to via primitives.
+ */
+export class PcbViaStructureParser {
+    static #STRUCTURE_STREAM_NAMES = [
+        'ViaStructures/Data',
+        'ViaStructureManager/Data'
+    ]
+
+    /**
+     * Extracts via-protection structures and primitive links from stream data.
+     * @param {Map<string, Uint8Array>} streams
+     * @returns {{ structures: object[], links: object[], byPrimitiveIndex: Record<string, object> }}
+     */
+    static extractFromStreams(streams) {
+        const structures = []
+        const links = []
+
+        for (const streamName of PcbViaStructureParser
+            .#STRUCTURE_STREAM_NAMES) {
+            const records = PcbViaStructureParser.#parseLengthPrefixedRecords(
+                streams.get(streamName),
+                streamName
+            )
+
+            for (const record of records) {
+                const structure =
+                    PcbViaStructureParser.#parseStructureRecord(record)
+                const link = PcbViaStructureParser.#parseLinkRecord(record)
+
+                if (structure) {
+                    structures.push(structure)
+                }
+                if (link) {
+                    links.push(link)
+                }
+            }
+        }
+
+        return PcbViaStructureParser.#buildLookup(structures, links)
+    }
+
+    /**
+     * Adds via-protection metadata to parsed via primitives in place.
+     * @param {object[]} vias
+     * @param {{ byPrimitiveIndex?: Record<string, object> }} viaStructures
+     */
+    static attachToVias(vias, viaStructures) {
+        if (!Array.isArray(vias) || !viaStructures?.byPrimitiveIndex) {
+            return
+        }
+
+        for (let index = 0; index < vias.length; index += 1) {
+            const viaProtection = viaStructures.byPrimitiveIndex[String(index)]
+            if (!viaProtection) {
+                continue
+            }
+
+            vias[index].viaStructureIndex = viaProtection.viaStructureIndex
+            if (viaProtection.ipc4761Type !== undefined) {
+                vias[index].ipc4761Type = viaProtection.ipc4761Type
+            }
+            vias[index].viaProtection = {
+                ipc4761Type: viaProtection.ipc4761Type,
+                structureType: viaProtection.structureType,
+                features: viaProtection.features
+            }
+            vias[index].drill = {
+                holeKind: 'via',
+                plating:
+                    vias[index].isPlated === false ? 'non-plated' : 'plated',
+                renderState:
+                    PcbViaStructureParser.#resolveDrillRenderState(
+                        viaProtection
+                    ),
+                ipc4761Type: viaProtection.ipc4761Type
+            }
+        }
+    }
+
+    /**
+     * Resolves a display drill state from via-protection metadata.
+     * @param {{ ipc4761Type?: number | string, features?: object[] }} viaProtection Via-protection metadata.
+     * @returns {'open' | 'covered' | 'filled' | 'capped'}
+     */
+    static #resolveDrillRenderState(viaProtection) {
+        const featureText = (viaProtection?.features || [])
+            .flatMap((feature) => [feature.type, feature.material])
+            .join(' ')
+            .toLowerCase()
+
+        if (/cap/u.test(featureText)) return 'capped'
+        if (/fill|plug/u.test(featureText)) return 'filled'
+        if (/cover|tent|mask/u.test(featureText)) return 'covered'
+
+        const ipcType = Number(viaProtection?.ipc4761Type)
+        if (ipcType === 6 || ipcType === 7) return 'capped'
+        if (ipcType === 3 || ipcType === 4 || ipcType === 5) return 'filled'
+        if (ipcType === 1 || ipcType === 2) return 'covered'
+        return 'open'
+    }
+
+    /**
+     * Parses one sidecar stream into field records.
+     * @param {Uint8Array | undefined} dataBytes
+     * @param {string} sourceStream
+     * @returns {{ fields: Record<string, string>, sourceStream: string, recordIndex: number }[]}
+     */
+    static #parseLengthPrefixedRecords(dataBytes, sourceStream) {
+        const bytes = PcbViaStructureParser.#toUint8Array(dataBytes)
+        const records = []
+        let offset = 0
+
+        while (offset + 4 <= bytes.byteLength) {
+            const recordLength = PcbViaStructureParser.#readUint32(
+                bytes,
+                offset
+            )
+            offset += 4
+
+            if (recordLength <= 0 || offset + recordLength > bytes.byteLength) {
+                break
+            }
+
+            const recordBytes = bytes.subarray(offset, offset + recordLength)
+            offset += recordLength
+
+            records.push({
+                fields: PcbViaStructureParser.#parseRecordFields(recordBytes),
+                sourceStream,
+                recordIndex: records.length
+            })
+        }
+
+        return records
+    }
+
+    /**
+     * Parses one pipe-delimited sidecar record.
+     * @param {Uint8Array} bytes
+     * @returns {Record<string, string>}
+     */
+    static #parseRecordFields(bytes) {
+        const text = PrintableTextDecoder.decodeBytes(bytes)
+            .replace(/\u0000/gu, '')
+            .trim()
+        const fields = {}
+
+        for (const segment of text.split('|')) {
+            const candidate = segment.trim()
+            const separatorIndex = candidate.indexOf('=')
+            if (separatorIndex <= 0) {
+                continue
+            }
+
+            const key = candidate.slice(0, separatorIndex).trim().toUpperCase()
+            if (!key) {
+                continue
+            }
+
+            fields[key] = candidate.slice(separatorIndex + 1).trim()
+        }
+
+        return fields
+    }
+
+    /**
+     * Parses one via structure definition record.
+     * @param {{ fields: Record<string, string>, sourceStream: string, recordIndex: number }} record
+     * @returns {object | null}
+     */
+    static #parseStructureRecord(record) {
+        if (!('STRUCTURETYPE' in record.fields)) {
+            return null
+        }
+
+        const index =
+            PcbViaStructureParser.#parseInteger(
+                record.fields.VIASTRUCTUREINDEX
+            ) ?? record.recordIndex
+        const structureType = PcbViaStructureParser.#parseIntegerOrString(
+            record.fields.STRUCTURETYPE
+        )
+
+        return {
+            index,
+            ipc4761Type: structureType,
+            structureType,
+            sourceStream: record.sourceStream,
+            features: PcbViaStructureParser.#parseFeatures(record.fields)
+        }
+    }
+
+    /**
+     * Parses one primitive-to-structure link record.
+     * @param {{ fields: Record<string, string>, sourceStream: string }} record
+     * @returns {{ primitiveIndex: number, viaStructureIndex: number, sourceStream: string } | null}
+     */
+    static #parseLinkRecord(record) {
+        const primitiveIndex = PcbViaStructureParser.#parseInteger(
+            record.fields.PRIMITIVEINDEX ?? record.fields.VIAINDEX
+        )
+        const viaStructureIndex = PcbViaStructureParser.#parseInteger(
+            record.fields.VIASTRUCTUREINDEX ?? record.fields.STRUCTUREINDEX
+        )
+
+        if (primitiveIndex === null || viaStructureIndex === null) {
+            return null
+        }
+
+        return {
+            primitiveIndex,
+            viaStructureIndex,
+            sourceStream: record.sourceStream
+        }
+    }
+
+    /**
+     * Parses repeated via-protection feature fields.
+     * @param {Record<string, string>} fields
+     * @returns {{ index: number, type: string, side: string, material: string }[]}
+     */
+    static #parseFeatures(fields) {
+        const features = []
+
+        for (let index = 0; index < 16; index += 1) {
+            const type = fields[`FEATURETYPE${index}`]
+            const side = fields[`FEATURESIDE${index}`]
+            const material = fields[`FEATUREMATERIAL${index}`]
+
+            if (!type && !side && !material) {
+                continue
+            }
+
+            features.push({
+                index,
+                type: type || '',
+                side: side || '',
+                material: material || ''
+            })
+        }
+
+        return features
+    }
+
+    /**
+     * Builds link lookups keyed by via primitive index.
+     * @param {object[]} structures
+     * @param {{ primitiveIndex: number, viaStructureIndex: number }[]} links
+     * @returns {{ structures: object[], links: object[], byPrimitiveIndex: Record<string, object> }}
+     */
+    static #buildLookup(structures, links) {
+        const structuresByIndex = new Map(
+            structures.map((structure) => [structure.index, structure])
+        )
+        const byPrimitiveIndex = {}
+
+        for (const link of links) {
+            const structure = structuresByIndex.get(link.viaStructureIndex)
+            if (!structure) {
+                continue
+            }
+
+            byPrimitiveIndex[String(link.primitiveIndex)] = {
+                viaStructureIndex: link.viaStructureIndex,
+                ipc4761Type: structure.ipc4761Type,
+                structureType: structure.structureType,
+                features: structure.features
+            }
+        }
+
+        return {
+            structures,
+            links,
+            byPrimitiveIndex
+        }
+    }
+
+    /**
+     * Parses a finite integer from a field value.
+     * @param {string | undefined} value
+     * @returns {number | null}
+     */
+    static #parseInteger(value) {
+        const number = Number(value)
+        return Number.isInteger(number) ? number : null
+    }
+
+    /**
+     * Parses a number when possible and otherwise preserves the string value.
+     * @param {string | undefined} value
+     * @returns {number | string}
+     */
+    static #parseIntegerOrString(value) {
+        const parsed = PcbViaStructureParser.#parseInteger(value)
+        return parsed === null ? String(value || '') : parsed
+    }
+
+    /**
+     * Reads one little-endian unsigned integer from a byte view.
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @returns {number}
+     */
+    static #readUint32(bytes, offset) {
+        return new DataView(
+            bytes.buffer,
+            bytes.byteOffset + offset,
+            4
+        ).getUint32(0, true)
+    }
+
+    /**
+     * Normalizes one byte-like input into a Uint8Array view.
+     * @param {Uint8Array | ArrayBuffer | undefined} bytes
+     * @returns {Uint8Array}
+     */
+    static #toUint8Array(bytes) {
+        if (!bytes) {
+            return new Uint8Array(0)
+        }
+
+        if (bytes instanceof Uint8Array) {
+            return bytes
+        }
+
+        return new Uint8Array(bytes)
+    }
+}

package/src/core/altium/PrintableTextDecoder.mjs

@@ -6,6 +6,12 @@
  * Extracts long printable runs from binary Altium documents.
  */
 export class PrintableTextDecoder {
+    static #WINDOWS_1252_PRINTABLE_CONTROL_BYTES = new Set([
+        0x80, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8a, 0x8b, 0x8c,
+        0x8e, 0x91, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9a, 0x9b,
+        0x9c, 0x9e, 0x9f
+    ])
+
     /**
      * Returns printable ASCII-like runs from a binary buffer.
      * @param {ArrayBuffer} arrayBuffer
@@ -67,8 +73,8 @@ export class PrintableTextDecoder {
     }
 
     /**
-     * Decodes one byte slice using UTF-8 first, then GB18030 for non-UTF-8
-     * payloads such as legacy PCB library text.
+     * Decodes one byte slice using UTF-8 first, then Windows-1252 or GB18030
+     * for non-UTF-8 payloads such as legacy PCB library text.
      * @param {Uint8Array} bytes
      * @param {{ encoding?: string }} [options]
      * @returns {string}
@@ -82,10 +88,34 @@ export class PrintableTextDecoder {
                 new TextDecoder('utf-8').decode(bytes)
             )
         }
+        if (
+            preferredEncoding === 'windows-1252' ||
+            preferredEncoding === 'cp1252'
+        ) {
+            return (
+                PrintableTextDecoder.#tryDecode(bytes, 'windows-1252') ||
+                new TextDecoder('utf-8').decode(bytes)
+            )
+        }
+
+        const utf8 = PrintableTextDecoder.#tryDecode(bytes, 'utf-8')
+        if (utf8 !== null) {
+            return utf8
+        }
+
+        if (PrintableTextDecoder.#hasWindows1252PreferredBytes(bytes)) {
+            const windows1252 = PrintableTextDecoder.#tryDecode(
+                bytes,
+                'windows-1252'
+            )
+            if (windows1252 !== null) {
+                return windows1252
+            }
+        }
 
         return (
-            PrintableTextDecoder.#tryDecode(bytes, 'utf-8') ||
             PrintableTextDecoder.#tryDecode(bytes, 'gb18030') ||
+            PrintableTextDecoder.#tryDecode(bytes, 'windows-1252') ||
             new TextDecoder('utf-8').decode(bytes)
         )
     }
@@ -140,6 +170,26 @@ export class PrintableTextDecoder {
             .trim()
     }
 
+    /**
+     * Returns true when bytes contain printable Windows-1252 control-range
+     * punctuation that can otherwise be misread as GB18030 pairs.
+     * @param {Uint8Array} bytes
+     * @returns {boolean}
+     */
+    static #hasWindows1252PreferredBytes(bytes) {
+        for (const byte of bytes) {
+            if (
+                PrintableTextDecoder.#WINDOWS_1252_PRINTABLE_CONTROL_BYTES.has(
+                    byte
+                )
+            ) {
+                return true
+            }
+        }
+
+        return false
+    }
+
     /**
      * Tries one strict decode and returns null when bytes are invalid for it.
      * @param {Uint8Array} bytes