altium-toolkit 1.1.1 → 1.1.3

package/src/core/altium/SchematicImageParser.mjs

@@ -2,6 +2,7 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+import { unzlibSync } from 'fflate'
 import { OleCompoundDocument } from '../ole/OleCompoundDocument.mjs'
 import { ParserUtils } from './ParserUtils.mjs'
 
@@ -53,11 +54,15 @@ export class SchematicImageParser {
             }
         }
 
+        const packedStorageImages = oleDocument
+            ? SchematicImageParser.#indexPackedStorageImages(oleDocument)
+            : SchematicImageParser.#createPackedStorageImageIndex()
         const images = imageRecords
             .map((record) =>
                 SchematicImageParser.#parseSchematicImageRecord(
                     record,
                     oleDocument,
+                    packedStorageImages,
                     diagnostics
                 )
             )
@@ -79,10 +84,16 @@ export class SchematicImageParser {
      * Normalizes one image placement record.
      * @param {{ fields: Record<string, string | string[]>, recordIndex: number }} record
      * @param {OleCompoundDocument | null} oleDocument
+     * @param {{ byPath: Map<string, Uint8Array>, byBaseName: Map<string, Uint8Array | null> }} packedStorageImages
      * @param {{ severity: 'info' | 'warning', message: string }[]} diagnostics
-     * @returns {{ x: number, y: number, cornerX: number, cornerY: number, fileName: string, embedded: boolean, keepAspect: boolean, mimeType: string, dataBase64: string, renderOrder: number, diagnosticState: string } | null}
+     * @returns {{ x: number, y: number, cornerX: number, cornerY: number, fileName: string, embedded: boolean, keepAspect: boolean, mimeType: string, dataBase64: string, renderOrder: number, diagnosticState: string, ownerIndex?: string } | null}
      */
-    static #parseSchematicImageRecord(record, oleDocument, diagnostics) {
+    static #parseSchematicImageRecord(
+        record,
+        oleDocument,
+        packedStorageImages,
+        diagnostics
+    ) {
         const x = parseNumericField(record.fields, 'Location.X')
         const y = parseNumericField(record.fields, 'Location.Y')
         const cornerX = parseNumericField(record.fields, 'Corner.X')
@@ -110,8 +121,13 @@ export class SchematicImageParser {
         let diagnosticState = embedded ? 'missing-embedded-payload' : 'external'
 
         if (embedded && fileName && oleDocument) {
-            try {
-                const streamBytes = oleDocument.getStream(fileName)
+            const streamBytes = SchematicImageParser.#resolveEmbeddedImageBytes(
+                fileName,
+                oleDocument,
+                packedStorageImages
+            )
+
+            if (streamBytes) {
                 const decoded =
                     SchematicImageParser.#decodeEmbeddedImagePayload(
                         streamBytes,
@@ -123,7 +139,7 @@ export class SchematicImageParser {
                 hasAlpha = decoded.hasAlpha
                 dataBase64 = SchematicImageParser.#encodeBase64(decoded.bytes)
                 diagnosticState = 'embedded'
-            } catch {
+            } else {
                 diagnostics.push({
                     severity: 'warning',
                     message:
@@ -153,7 +169,10 @@ export class SchematicImageParser {
             mimeType,
             dataBase64,
             renderOrder,
-            diagnosticState
+            diagnosticState,
+            ...(getField(record.fields, 'OwnerIndex')
+                ? { ownerIndex: getField(record.fields, 'OwnerIndex') }
+                : {})
         }
 
         if (sourceMimeType && sourceMimeType !== mimeType) {
@@ -169,6 +188,272 @@ export class SchematicImageParser {
         return image
     }
 
+    /**
+     * Resolves an embedded image payload from direct OLE streams or packed
+     * Altium icon storage.
+     * @param {string} fileName Image file name from the schematic record.
+     * @param {OleCompoundDocument} oleDocument Parsed OLE container.
+     * @param {{ byPath: Map<string, Uint8Array>, byBaseName: Map<string, Uint8Array | null> }} packedStorageImages
+     * @returns {Uint8Array | null}
+     */
+    static #resolveEmbeddedImageBytes(
+        fileName,
+        oleDocument,
+        packedStorageImages
+    ) {
+        try {
+            return oleDocument.getStream(fileName)
+        } catch {
+            return SchematicImageParser.#findPackedStorageImage(
+                fileName,
+                packedStorageImages
+            )
+        }
+    }
+
+    /**
+     * Creates an empty packed-storage image index.
+     * @returns {{ byPath: Map<string, Uint8Array>, byBaseName: Map<string, Uint8Array | null> }}
+     */
+    static #createPackedStorageImageIndex() {
+        return {
+            byPath: new Map(),
+            byBaseName: new Map()
+        }
+    }
+
+    /**
+     * Reads Altium's packed schematic image storage stream.
+     * @param {OleCompoundDocument} oleDocument Parsed OLE container.
+     * @returns {{ byPath: Map<string, Uint8Array>, byBaseName: Map<string, Uint8Array | null> }}
+     */
+    static #indexPackedStorageImages(oleDocument) {
+        try {
+            return SchematicImageParser.#parsePackedStorageImages(
+                oleDocument.getStream('Storage')
+            )
+        } catch {
+            return SchematicImageParser.#createPackedStorageImageIndex()
+        }
+    }
+
+    /**
+     * Parses Altium's compact icon-storage records into decoded image bytes.
+     * @param {Uint8Array} bytes Packed storage stream bytes.
+     * @returns {{ byPath: Map<string, Uint8Array>, byBaseName: Map<string, Uint8Array | null> }}
+     */
+    static #parsePackedStorageImages(bytes) {
+        const index = SchematicImageParser.#createPackedStorageImageIndex()
+        if (!(bytes instanceof Uint8Array) || bytes.byteLength < 16) {
+            return index
+        }
+
+        const view = new DataView(
+            bytes.buffer,
+            bytes.byteOffset,
+            bytes.byteLength
+        )
+        const headerLength = view.getUint32(0, true)
+        if (headerLength <= 0 || 4 + headerLength > bytes.byteLength) {
+            return index
+        }
+
+        const headerText = new TextDecoder('windows-1252').decode(
+            bytes.subarray(4, 4 + headerLength)
+        )
+        if (!headerText.includes('Icon storage')) {
+            return index
+        }
+
+        let offset = 4 + headerLength
+        if (bytes[offset] === 0) {
+            offset += 1
+        }
+
+        while (offset + 10 <= bytes.byteLength) {
+            while (offset < bytes.byteLength && bytes[offset] === 0) {
+                offset += 1
+            }
+            if (offset + 10 > bytes.byteLength) {
+                break
+            }
+
+            const entryLength =
+                bytes[offset] |
+                (bytes[offset + 1] << 8) |
+                (bytes[offset + 2] << 16)
+            const parsedEntry =
+                SchematicImageParser.#parsePackedStorageImageEntry(
+                    bytes,
+                    view,
+                    offset
+                )
+
+            if (parsedEntry) {
+                SchematicImageParser.#addPackedStorageImage(
+                    index,
+                    parsedEntry.fileName,
+                    parsedEntry.bytes
+                )
+                offset = parsedEntry.nextOffset
+                continue
+            }
+
+            offset += Math.max(entryLength + 3, 1)
+        }
+
+        return index
+    }
+
+    /**
+     * Parses one packed icon-storage entry.
+     * @param {Uint8Array} bytes Storage stream bytes.
+     * @param {DataView} view Storage stream view.
+     * @param {number} offset Entry offset.
+     * @returns {{ fileName: string, bytes: Uint8Array, nextOffset: number } | null}
+     */
+    static #parsePackedStorageImageEntry(bytes, view, offset) {
+        const entryStart = offset + 3
+        if (entryStart + 3 > bytes.byteLength) {
+            return null
+        }
+
+        const pathLength = bytes[entryStart + 2]
+        const pathOffset = entryStart + 3
+        const compressedLengthOffset = pathOffset + pathLength
+        const compressedOffset = compressedLengthOffset + 4
+
+        if (pathLength <= 0 || compressedLengthOffset + 4 > bytes.byteLength) {
+            return null
+        }
+
+        const compressedLength = view.getUint32(compressedLengthOffset, true)
+        const compressedEnd = compressedOffset + compressedLength
+        if (
+            compressedLength <= 0 ||
+            compressedEnd > bytes.byteLength ||
+            !SchematicImageParser.#looksLikeZlibStream(bytes, compressedOffset)
+        ) {
+            return null
+        }
+
+        try {
+            return {
+                fileName: SchematicImageParser.#decodePackedImagePath(
+                    bytes.subarray(pathOffset, compressedLengthOffset)
+                ),
+                bytes: unzlibSync(
+                    bytes.subarray(compressedOffset, compressedEnd)
+                ),
+                nextOffset: compressedEnd
+            }
+        } catch {
+            return null
+        }
+    }
+
+    /**
+     * Adds one decoded image to path and unique-basename lookup indexes.
+     * @param {{ byPath: Map<string, Uint8Array>, byBaseName: Map<string, Uint8Array | null> }} index Packed-storage index.
+     * @param {string} fileName Image path.
+     * @param {Uint8Array} bytes Image bytes.
+     */
+    static #addPackedStorageImage(index, fileName, bytes) {
+        const normalizedPath =
+            SchematicImageParser.#normalizeImageLookupPath(fileName)
+        if (!normalizedPath) {
+            return
+        }
+
+        index.byPath.set(normalizedPath, bytes)
+
+        const baseName =
+            SchematicImageParser.#imageLookupBaseName(normalizedPath)
+        if (!baseName) {
+            return
+        }
+
+        if (
+            index.byBaseName.has(baseName) &&
+            index.byBaseName.get(baseName) !== bytes
+        ) {
+            index.byBaseName.set(baseName, null)
+            return
+        }
+
+        index.byBaseName.set(baseName, bytes)
+    }
+
+    /**
+     * Finds one packed-storage image by full path or unique basename.
+     * @param {string} fileName Requested image path.
+     * @param {{ byPath: Map<string, Uint8Array>, byBaseName: Map<string, Uint8Array | null> }} index Packed-storage image index.
+     * @returns {Uint8Array | null}
+     */
+    static #findPackedStorageImage(fileName, index) {
+        const normalizedPath =
+            SchematicImageParser.#normalizeImageLookupPath(fileName)
+        if (!normalizedPath) {
+            return null
+        }
+
+        const directMatch = index.byPath.get(normalizedPath)
+        if (directMatch) {
+            return directMatch
+        }
+
+        const baseName =
+            SchematicImageParser.#imageLookupBaseName(normalizedPath)
+        return index.byBaseName.get(baseName) || null
+    }
+
+    /**
+     * Decodes a packed-storage path string.
+     * @param {Uint8Array} bytes Path bytes.
+     * @returns {string}
+     */
+    static #decodePackedImagePath(bytes) {
+        return new TextDecoder('windows-1252')
+            .decode(bytes)
+            .replace(/\0+$/u, '')
+    }
+
+    /**
+     * Checks whether bytes at an offset resemble a zlib stream.
+     * @param {Uint8Array} bytes Source bytes.
+     * @param {number} offset Candidate offset.
+     * @returns {boolean}
+     */
+    static #looksLikeZlibStream(bytes, offset) {
+        if (offset + 2 > bytes.byteLength || bytes[offset] !== 0x78) {
+            return false
+        }
+
+        return ((bytes[offset] << 8) + bytes[offset + 1]) % 31 === 0
+    }
+
+    /**
+     * Normalizes image paths for cross-platform lookup.
+     * @param {string} fileName Image path.
+     * @returns {string}
+     */
+    static #normalizeImageLookupPath(fileName) {
+        return String(fileName || '')
+            .replace(/\\+/gu, '/')
+            .replace(/\/+/gu, '/')
+            .toLowerCase()
+    }
+
+    /**
+     * Returns the final path segment from a normalized image lookup path.
+     * @param {string} normalizedPath Normalized path.
+     * @returns {string}
+     */
+    static #imageLookupBaseName(normalizedPath) {
+        const parts = normalizedPath.split('/')
+        return parts[parts.length - 1] || ''
+    }
+
     /**
      * Chooses the browser-facing image payload from one embedded stream.
      * @param {Uint8Array} bytes Embedded image stream bytes.

package/src/core/altium/SchematicImplementationParser.mjs

@@ -21,6 +21,10 @@ export class SchematicImplementationParser {
         const components = SchematicImplementationParser.#componentRows(records)
         const listsByIndex =
             SchematicImplementationParser.#implementationLists(records)
+        const childrenByOwner =
+            SchematicImplementationParser.#implementationChildrenByOwner(
+                records
+            )
         const implementations = (records || [])
             .filter(
                 (record) =>
@@ -32,9 +36,9 @@ export class SchematicImplementationParser {
             .map((record) =>
                 SchematicImplementationParser.#implementation(
                     record,
-                    records,
                     components,
-                    listsByIndex
+                    listsByIndex,
+                    childrenByOwner
                 )
             )
             .filter(Boolean)
@@ -137,12 +141,12 @@ export class SchematicImplementationParser {
     /**
      * Parses one implementation record.
      * @param {object} record Implementation record.
-     * @param {object[]} records All schematic records.
      * @param {object[]} components Component rows.
      * @param {Map<string, object>} listsByIndex Implementation lists.
+     * @param {Map<string, { recordType: string, record: object }[]>} childrenByOwner Implementation child rows by owner index.
      * @returns {object | null}
      */
-    static #implementation(record, records, components, listsByIndex) {
+    static #implementation(record, components, listsByIndex, childrenByOwner) {
         const indexInSheet =
             parseNumericField(record.fields, 'IndexInSheet') ??
             record.recordIndex ??
@@ -184,11 +188,11 @@ export class SchematicImplementationParser {
                 record.fields
             ),
             mapDefiners: SchematicImplementationParser.#mapDefiners(
-                records,
+                childrenByOwner,
                 indexInSheet
             ),
             parameters: SchematicImplementationParser.#parameters(
-                records,
+                childrenByOwner,
                 indexInSheet
             )
         })
@@ -326,23 +330,17 @@ export class SchematicImplementationParser {
 
     /**
      * Parses map-definer child records for one implementation.
-     * @param {object[]} records All schematic records.
+     * @param {Map<string, { recordType: string, record: object }[]>} childrenByOwner Implementation child rows by owner index.
      * @param {number} implementationIndex Implementation index.
      * @returns {object[]}
      */
-    static #mapDefiners(records, implementationIndex) {
-        return (records || [])
-            .filter(
-                (record) =>
-                    SchematicImplementationParser.#field(
-                        record.fields,
-                        'RECORD'
-                    ) === '47' &&
-                    SchematicImplementationParser.#field(
-                        record.fields,
-                        'OwnerIndex'
-                    ) === String(implementationIndex)
-            )
+    static #mapDefiners(childrenByOwner, implementationIndex) {
+        return SchematicImplementationParser.#ownedImplementationChildren(
+            childrenByOwner,
+            implementationIndex
+        )
+            .filter((row) => row.recordType === '47')
+            .map((row) => row.record)
             .map((record) =>
                 SchematicImplementationParser.#stripEmpty({
                     recordKey: SchematicImplementationParser.#recordKey(record),
@@ -360,25 +358,17 @@ export class SchematicImplementationParser {
 
     /**
      * Parses implementation parameter child records.
-     * @param {object[]} records All schematic records.
+     * @param {Map<string, { recordType: string, record: object }[]>} childrenByOwner Implementation child rows by owner index.
      * @param {number} implementationIndex Implementation index.
      * @returns {object[]}
      */
-    static #parameters(records, implementationIndex) {
-        return (records || [])
-            .filter((record) => {
-                const recordType = SchematicImplementationParser.#field(
-                    record.fields,
-                    'RECORD'
-                )
-                return (
-                    (recordType === '48' || recordType === '41') &&
-                    SchematicImplementationParser.#field(
-                        record.fields,
-                        'OwnerIndex'
-                    ) === String(implementationIndex)
-                )
-            })
+    static #parameters(childrenByOwner, implementationIndex) {
+        return SchematicImplementationParser.#ownedImplementationChildren(
+            childrenByOwner,
+            implementationIndex
+        )
+            .filter((row) => row.recordType === '48' || row.recordType === '41')
+            .map((row) => row.record)
             .map((record) =>
                 SchematicImplementationParser.#stripEmpty({
                     recordKey: SchematicImplementationParser.#recordKey(record),
@@ -396,6 +386,55 @@ export class SchematicImplementationParser {
             )
     }
 
+    /**
+     * Indexes implementation child rows by owner index once per parse.
+     * @param {object[]} records Schematic records.
+     * @returns {Map<string, { recordType: string, record: object }[]>}
+     */
+    static #implementationChildrenByOwner(records) {
+        const rowsByOwner = new Map()
+
+        for (const record of records || []) {
+            const recordType = SchematicImplementationParser.#field(
+                record.fields,
+                'RECORD'
+            )
+            if (
+                recordType !== '47' &&
+                recordType !== '48' &&
+                recordType !== '41'
+            ) {
+                continue
+            }
+
+            const ownerIndex = SchematicImplementationParser.#field(
+                record.fields,
+                'OwnerIndex'
+            )
+            if (!ownerIndex) {
+                continue
+            }
+
+            if (!rowsByOwner.has(ownerIndex)) {
+                rowsByOwner.set(ownerIndex, [])
+            }
+
+            rowsByOwner.get(ownerIndex).push({ recordType, record })
+        }
+
+        return rowsByOwner
+    }
+
+    /**
+     * Returns pre-indexed child rows for one implementation.
+     * @param {Map<string, { recordType: string, record: object }[]>} childrenByOwner Implementation child rows by owner index.
+     * @param {number} implementationIndex Implementation index.
+     * @returns {{ recordType: string, record: object }[]}
+     */
+    static #ownedImplementationChildren(childrenByOwner, implementationIndex) {
+        return childrenByOwner.get(String(implementationIndex)) || []
+    }
+
     /**
      * Parses indexed implementation designator fields from a map definer.
      * @param {Record<string, string | string[]>} fields Record fields.

package/src/core/altium/SchematicMultipartDesignatorNormalizer.mjs

@@ -0,0 +1,164 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Normalizes visible designator labels for repeated multipart schematic units.
+ */
+export class SchematicMultipartDesignatorNormalizer {
+    /**
+     * Rewrites multipart designator labels from the active Altium part id.
+     * @param {{ text: string, name?: string, ownerIndex?: string, recordType?: string }[]} texts
+     * @param {Map<string, string>} activeMultipartOwnerParts
+     * @returns {{ text: string, name?: string, ownerIndex?: string, recordType?: string }[]}
+     */
+    static normalize(texts, activeMultipartOwnerParts) {
+        const repeatedStems =
+            SchematicMultipartDesignatorNormalizer.#collectRepeatedStems(
+                texts,
+                activeMultipartOwnerParts
+            )
+
+        return texts.map((text) =>
+            SchematicMultipartDesignatorNormalizer.#normalizeText(
+                text,
+                activeMultipartOwnerParts,
+                repeatedStems
+            )
+        )
+    }
+
+    /**
+     * Collects designator stems used by multiple active multipart owners.
+     * @param {{ text: string, name?: string, ownerIndex?: string, recordType?: string }[]} texts
+     * @param {Map<string, string>} activeMultipartOwnerParts
+     * @returns {Set<string>}
+     */
+    static #collectRepeatedStems(texts, activeMultipartOwnerParts) {
+        const counts = new Map()
+
+        for (const text of texts) {
+            if (
+                !SchematicMultipartDesignatorNormalizer.#isActiveDesignator(
+                    text,
+                    activeMultipartOwnerParts
+                )
+            ) {
+                continue
+            }
+
+            const parsed =
+                SchematicMultipartDesignatorNormalizer.#parseDesignatorStem(
+                    text.text
+                )
+            if (!parsed) {
+                continue
+            }
+
+            counts.set(parsed.stem, (counts.get(parsed.stem) || 0) + 1)
+        }
+
+        return new Set(
+            [...counts.entries()]
+                .filter(([, count]) => count > 1)
+                .map(([stem]) => stem)
+        )
+    }
+
+    /**
+     * Normalizes one designator text row.
+     * @param {{ text: string, name?: string, ownerIndex?: string, recordType?: string }} text
+     * @param {Map<string, string>} activeMultipartOwnerParts
+     * @param {Set<string>} repeatedStems
+     * @returns {{ text: string, name?: string, ownerIndex?: string, recordType?: string }}
+     */
+    static #normalizeText(text, activeMultipartOwnerParts, repeatedStems) {
+        if (
+            !SchematicMultipartDesignatorNormalizer.#isActiveDesignator(
+                text,
+                activeMultipartOwnerParts
+            )
+        ) {
+            return text
+        }
+
+        const parsed =
+            SchematicMultipartDesignatorNormalizer.#parseDesignatorStem(
+                text.text
+            )
+        if (!parsed || !repeatedStems.has(parsed.stem)) {
+            return text
+        }
+
+        const suffix = SchematicMultipartDesignatorNormalizer.#formatPartSuffix(
+            activeMultipartOwnerParts.get(String(text.ownerIndex || ''))
+        )
+        const normalizedText = parsed.stem + suffix
+
+        return normalizedText === text.text
+            ? text
+            : {
+                  ...text,
+                  text: normalizedText
+              }
+    }
+
+    /**
+     * Returns true when a text row is an active multipart designator.
+     * @param {{ name?: string, ownerIndex?: string, recordType?: string }} text
+     * @param {Map<string, string>} activeMultipartOwnerParts
+     * @returns {boolean}
+     */
+    static #isActiveDesignator(text, activeMultipartOwnerParts) {
+        const ownerIndex = String(text?.ownerIndex || '')
+
+        return (
+            activeMultipartOwnerParts.has(ownerIndex) &&
+            text?.recordType === '34' &&
+            String(text?.name || '')
+                .trim()
+                .toLowerCase() === 'designator'
+        )
+    }
+
+    /**
+     * Parses a component stem before an optional multipart suffix.
+     * @param {string} text Designator text.
+     * @returns {{ stem: string, suffix: string } | null}
+     */
+    static #parseDesignatorStem(text) {
+        const match = /^(?<stem>.*\d)(?<suffix>[A-Z]+)?$/u.exec(
+            String(text || '').trim()
+        )
+
+        return match?.groups
+            ? {
+                  stem: match.groups.stem,
+                  suffix: match.groups.suffix || ''
+              }
+            : null
+    }
+
+    /**
+     * Converts one numeric multipart part id into an alphabetic suffix.
+     * @param {string | undefined} partId
+     * @returns {string}
+     */
+    static #formatPartSuffix(partId) {
+        const numericPartId = Number.parseInt(String(partId || ''), 10)
+        if (!Number.isInteger(numericPartId) || numericPartId <= 0) {
+            return ''
+        }
+
+        let suffix = ''
+        let remaining = numericPartId
+
+        while (remaining > 0) {
+            remaining -= 1
+            suffix = String.fromCharCode(65 + (remaining % 26)) + suffix
+            remaining = Math.floor(remaining / 26)
+        }
+
+        return suffix
+    }
+}

package/src/core/altium/SchematicMultipartOwnerMatcher.mjs

@@ -542,10 +542,12 @@ export class SchematicMultipartOwnerMatcher {
     static #inferSchematicPinOrientation(conglomerate) {
         switch (conglomerate) {
             case 34:
+            case 42:
             case 50:
             case 58:
                 return 'left'
             case 32:
+            case 40:
             case 48:
             case 56:
                 return 'right'