altium-toolkit 1.1.2 → 1.1.22

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/PrintableTextDecoder.mjs

@@ -6,6 +6,9 @@
  * Extracts long printable runs from binary Altium documents.
  */
 export class PrintableTextDecoder {
+    static #decoderCache = new Map()
+    static #decoderConstructor = null
+
     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,
@@ -115,7 +118,7 @@ export class PrintableTextDecoder {
         if (preferredEncoding === 'utf-8') {
             return (
                 PrintableTextDecoder.#tryDecode(bytes, 'utf-8') ||
-                new TextDecoder('utf-8').decode(bytes)
+                PrintableTextDecoder.#decode(bytes, 'utf-8')
             )
         }
         if (
@@ -124,7 +127,7 @@ export class PrintableTextDecoder {
         ) {
             return (
                 PrintableTextDecoder.#tryDecodeWindows1252(bytes) ||
-                new TextDecoder('utf-8').decode(bytes)
+                PrintableTextDecoder.#decode(bytes, 'utf-8')
             )
         }
 
@@ -144,7 +147,7 @@ export class PrintableTextDecoder {
         return (
             PrintableTextDecoder.#tryDecode(bytes, 'gb18030') ||
             PrintableTextDecoder.#tryDecodeWindows1252(bytes) ||
-            new TextDecoder('utf-8').decode(bytes)
+            PrintableTextDecoder.#decode(bytes, 'utf-8')
         )
     }
 
@@ -157,18 +160,25 @@ export class PrintableTextDecoder {
      * @param {number} minLength
      */
     static #pushRunBytes(runs, bytes, start, end, minLength) {
-        const length = end - start
-        if (length < minLength) return
-
-        const slice = bytes.slice(start, end)
-        const normalized = PrintableTextDecoder.#normalizeRun(
-            PrintableTextDecoder.decodeBytes(slice)
+        const bounds = PrintableTextDecoder.#trimAsciiByteRange(
+            bytes,
+            start,
+            end
         )
+        const length = bounds.end - bounds.start
+        if (length < minLength) return
 
-        if (normalized.length < minLength) return
-        if (!normalized.includes('|') || !normalized.includes('=')) return
+        if (
+            !PrintableTextDecoder.#containsRecordDelimiterBytes(
+                bytes,
+                bounds.start,
+                bounds.end
+            )
+        ) {
+            return
+        }
 
-        runs.push(slice)
+        runs.push(bytes.slice(start, end))
     }
 
     /**
@@ -218,6 +228,72 @@ export class PrintableTextDecoder {
         return false
     }
 
+    /**
+     * Trims ASCII whitespace from one byte range.
+     * @param {Uint8Array} bytes
+     * @param {number} start
+     * @param {number} end
+     * @returns {{ start: number, end: number }}
+     */
+    static #trimAsciiByteRange(bytes, start, end) {
+        let trimmedStart = start
+        let trimmedEnd = end
+
+        while (
+            trimmedStart < trimmedEnd &&
+            PrintableTextDecoder.#isAsciiWhitespaceByte(bytes[trimmedStart])
+        ) {
+            trimmedStart += 1
+        }
+
+        while (
+            trimmedEnd > trimmedStart &&
+            PrintableTextDecoder.#isAsciiWhitespaceByte(bytes[trimmedEnd - 1])
+        ) {
+            trimmedEnd -= 1
+        }
+
+        return {
+            start: trimmedStart,
+            end: trimmedEnd
+        }
+    }
+
+    /**
+     * Returns true when one byte range contains Altium record delimiters.
+     * @param {Uint8Array} bytes
+     * @param {number} start
+     * @param {number} end
+     * @returns {boolean}
+     */
+    static #containsRecordDelimiterBytes(bytes, start, end) {
+        let hasPipe = false
+        let hasEquals = false
+
+        for (let index = start; index < end; index += 1) {
+            if (bytes[index] === 0x7c) {
+                hasPipe = true
+            } else if (bytes[index] === 0x3d) {
+                hasEquals = true
+            }
+
+            if (hasPipe && hasEquals) {
+                return true
+            }
+        }
+
+        return false
+    }
+
+    /**
+     * Returns true when a byte is ASCII whitespace normalized around runs.
+     * @param {number} byte
+     * @returns {boolean}
+     */
+    static #isAsciiWhitespaceByte(byte) {
+        return byte === 9 || byte === 10 || byte === 13 || byte === 32
+    }
+
     /**
      * Tries one strict decode and returns null when bytes are invalid for it.
      * @param {Uint8Array} bytes
@@ -226,12 +302,56 @@ export class PrintableTextDecoder {
      */
     static #tryDecode(bytes, encoding) {
         try {
-            return new TextDecoder(encoding, { fatal: true }).decode(bytes)
+            return PrintableTextDecoder.#decode(bytes, encoding, {
+                fatal: true
+            })
         } catch {
             return null
         }
     }
 
+    /**
+     * Decodes one byte slice with a cached runtime decoder.
+     * @param {Uint8Array} bytes
+     * @param {string} encoding
+     * @param {{ fatal?: boolean }} [options]
+     * @returns {string}
+     */
+    static #decode(bytes, encoding, options = {}) {
+        return PrintableTextDecoder.#getTextDecoder(encoding, options).decode(
+            bytes
+        )
+    }
+
+    /**
+     * Resolves a cached TextDecoder for one encoding and fatal mode.
+     * @param {string} encoding
+     * @param {{ fatal?: boolean }} options
+     * @returns {TextDecoder}
+     */
+    static #getTextDecoder(encoding, options) {
+        const Decoder = globalThis.TextDecoder
+        if (PrintableTextDecoder.#decoderConstructor !== Decoder) {
+            PrintableTextDecoder.#decoderCache = new Map()
+            PrintableTextDecoder.#decoderConstructor = Decoder
+        }
+
+        const normalizedEncoding = String(encoding || 'utf-8').toLowerCase()
+        const fatal = Boolean(options?.fatal)
+        const cacheKey = `${normalizedEncoding}:${fatal ? 'fatal' : 'replace'}`
+        const cached = PrintableTextDecoder.#decoderCache.get(cacheKey)
+        if (cached) {
+            return cached
+        }
+
+        const decoder = new Decoder(
+            normalizedEncoding,
+            fatal ? { fatal: true } : {}
+        )
+        PrintableTextDecoder.#decoderCache.set(cacheKey, decoder)
+        return decoder
+    }
+
     /**
      * Tries a Windows-1252 decode and normalizes runtimes that expose C1 bytes
      * as control characters instead of punctuation.

package/src/core/altium/SchematicComponentOwnerTextResolver.mjs

@@ -66,6 +66,19 @@ export class SchematicComponentOwnerTextResolver {
         )
     }
 
+    /**
+     * Resolves candidate owner indexes for one schematic component record.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }} componentRecord Component placement record.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }[]} records Indexed schematic records.
+     * @returns {string[]}
+     */
+    static resolveOwnerIndexes(componentRecord, records) {
+        return SchematicComponentOwnerTextResolver.#resolveOwnerIndexes(
+            componentRecord,
+            records
+        )
+    }
+
     /**
      * Resolves candidate owner indexes for one schematic component record.
      * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }} componentRecord Component placement record.

package/src/core/altium/SchematicComponentTextResolver.mjs

@@ -56,7 +56,7 @@ export class SchematicComponentTextResolver {
      */
     static resolveValue(ownerTexts, texts, component) {
         const ownerValue =
-            SchematicComponentTextResolver.#findFirstRelatedTextRecord(
+            SchematicComponentTextResolver.#findFirstUsableRelatedTextRecord(
                 ownerTexts,
                 ['Comment', 'VALUE']
             )
@@ -128,6 +128,45 @@ export class SchematicComponentTextResolver {
         return { found: false, text: '' }
     }
 
+    /**
+     * Finds the first owner text that is resolved or explicitly empty, while
+     * allowing unresolved templates to fall through to later owner parameters.
+     * @param {{ fields: Record<string, string | string[]> }[]} records
+     * @param {string[]} logicalNames Logical text names.
+     * @returns {{ found: boolean, text: string }}
+     */
+    static #findFirstUsableRelatedTextRecord(records, logicalNames) {
+        let unresolvedMatch = { found: false, text: '' }
+
+        for (const logicalName of logicalNames) {
+            const match = SchematicComponentTextResolver.#findRelatedTextRecord(
+                records,
+                logicalName
+            )
+
+            if (!match.found) {
+                continue
+            }
+
+            if (
+                SchematicComponentTextResolver.#isExplicitEmptyText(
+                    match.text
+                ) ||
+                SchematicComponentTextResolver.#isResolvedComponentText(
+                    match.text
+                )
+            ) {
+                return match
+            }
+
+            if (!unresolvedMatch.found) {
+                unresolvedMatch = match
+            }
+        }
+
+        return unresolvedMatch
+    }
+
     /**
      * Finds the closest nearby designator text for one component.
      * @param {{ x: number, y: number, text: string, name: string }[]} texts

package/src/core/altium/SchematicDirectiveParser.mjs

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { ParserUtils } from './ParserUtils.mjs'
+import { SchematicNoErcSymbolResolver } from './SchematicNoErcSymbolResolver.mjs'
 
 /**
  * Helpers for normalized schematic directive primitives.
@@ -144,6 +145,7 @@ export class SchematicDirectiveParser {
         const x = ParserUtils.parseNumericField(record.fields, 'Location.X')
         const y = ParserUtils.parseNumericField(record.fields, 'Location.Y')
         if (x === null || y === null) return null
+        const rawSymbol = ParserUtils.getField(record.fields, 'Symbol')
         const symbol = ParserUtils.parseNumericField(record.fields, 'Symbol')
 
         return {
@@ -160,7 +162,9 @@ export class SchematicDirectiveParser {
                 ParserUtils.parseNumericField(record.fields, 'Orientation') ||
                 0,
             symbol,
-            symbolName: SchematicDirectiveParser.#noErcSymbolName(symbol)
+            symbolName: SchematicNoErcSymbolResolver.resolveSymbolName(
+                rawSymbol || symbol
+            )
         }
     }
 
@@ -332,22 +336,6 @@ export class SchematicDirectiveParser {
         return 'record-' + String(record.recordIndex ?? 0)
     }
 
-    /**
-     * Converts common No ERC symbol ids into public labels.
-     * @param {number | null} symbol Symbol id.
-     * @returns {string}
-     */
-    static #noErcSymbolName(symbol) {
-        return (
-            {
-                0: 'generic',
-                1: 'box',
-                2: 'cross',
-                3: 'triangle'
-            }[Number(symbol)] || 'unknown'
-        )
-    }
-
     /**
      * Parses one boolean-ish directive parameter value.
      * @param {unknown} value Raw parameter value.