altium-toolkit 1.1.2 → 1.1.22

package/src/core/altium/SchematicStreamExtractor.mjs

@@ -12,6 +12,8 @@ import { OleConstants } from '../ole/OleConstants.mjs'
  * containers.
  */
 export class SchematicStreamExtractor {
+    static #AUXILIARY_PRINTABLE_STREAMS = new Set(['Additional'])
+
     /**
      * Returns true when one buffer starts with the OLE compound-document
      * signature.
@@ -38,9 +40,10 @@ export class SchematicStreamExtractor {
     }
 
     /**
-     * Extracts schematic records from the logical `FileHeader` stream.
+     * Extracts schematic records from the logical `FileHeader` stream and
+     * Altium's auxiliary printable schematic streams.
      * @param {ArrayBuffer} arrayBuffer
-     * @returns {{ records: Array<{ raw: string, fields: Record<string, string | string[]>, sourceStream: string }>, streamNames: string[] } | null}
+     * @returns {{ records: Array<{ raw: string, fields: Record<string, string | string[]>, sourceStream: string }>, streamNames: string[], embeddedFiles?: object } | null}
      */
     static extractFromArrayBuffer(arrayBuffer) {
         if (!SchematicStreamExtractor.isCompoundDocument(arrayBuffer)) {
@@ -55,20 +58,28 @@ export class SchematicStreamExtractor {
             return null
         }
 
-        let fileHeaderBytes
+        let fileHeaderRecords
 
         try {
-            fileHeaderBytes = compoundDocument.getStream('FileHeader')
+            fileHeaderRecords = SchematicStreamExtractor.#parseStreamRecords(
+                compoundDocument,
+                'FileHeader'
+            )
         } catch {
             return null
         }
 
-        const records = AsciiRecordParser.parse(
-            SchematicStreamExtractor.#toArrayBuffer(fileHeaderBytes)
-        ).map((record) => ({
-            ...record,
-            sourceStream: 'FileHeader'
-        }))
+        const streamNames = compoundDocument.listStreams()
+        const auxiliaryStreamNames = streamNames.filter((streamName) =>
+            SchematicStreamExtractor.#isAuxiliaryPrintableStream(streamName)
+        )
+        const auxiliaryRecords = auxiliaryStreamNames.flatMap((streamName) =>
+            SchematicStreamExtractor.#parseStreamRecords(
+                compoundDocument,
+                streamName
+            )
+        )
+        const records = [...fileHeaderRecords, ...auxiliaryRecords]
 
         if (!records.length) {
             return null
@@ -76,18 +87,54 @@ export class SchematicStreamExtractor {
 
         return {
             records,
-            streamNames: compoundDocument.listStreams(),
+            streamNames,
             embeddedFiles: EmbeddedFileInventoryBuilder.buildFromStreams(
                 new Map(
-                    compoundDocument
-                        .listStreams()
-                        .map((name) => [name, compoundDocument.getStream(name)])
+                    streamNames.map((name) => [
+                        name,
+                        compoundDocument.getStream(name)
+                    ])
                 ),
-                { skipStreamNames: ['FileHeader'] }
+                {
+                    skipStreamNames: ['FileHeader', ...auxiliaryStreamNames]
+                }
             )
         }
     }
 
+    /**
+     * Parses printable records from one compound-document stream.
+     * @param {OleCompoundDocument} compoundDocument
+     * @param {string} streamName
+     * @returns {Array<{ raw: string, fields: Record<string, string | string[]>, sourceStream: string }>}
+     */
+    static #parseStreamRecords(compoundDocument, streamName) {
+        return AsciiRecordParser.parse(
+            SchematicStreamExtractor.#toArrayBuffer(
+                compoundDocument.getStream(streamName)
+            )
+        ).map((record) => ({
+            ...record,
+            sourceStream: streamName
+        }))
+    }
+
+    /**
+     * Returns true for known non-embedded schematic streams with printable
+     * primitive records.
+     * @param {string} streamName
+     * @returns {boolean}
+     */
+    static #isAuxiliaryPrintableStream(streamName) {
+        const leafName = String(streamName || '')
+            .split('/')
+            .at(-1)
+
+        return SchematicStreamExtractor.#AUXILIARY_PRINTABLE_STREAMS.has(
+            leafName
+        )
+    }
+
     /**
      * Returns an ArrayBuffer view over one byte slice.
      * @param {Uint8Array} bytes

package/src/core/altium/SchematicTextParser.mjs

@@ -17,6 +17,10 @@ export class SchematicTextParser {
         const metadata = {}
 
         for (const record of records) {
+            if (ParserUtils.getField(record.fields, 'OwnerIndex')) {
+                continue
+            }
+
             const name = ParserUtils.getField(record.fields, 'Name').trim()
             const value = ParserUtils.getDisplayText(record.fields)
 
@@ -30,6 +34,39 @@ export class SchematicTextParser {
         return metadata
     }
 
+    /**
+     * Extracts owner-local parameter values used by component text templates.
+     * @param {{ fields: Record<string, string | string[]> }[]} records
+     * @returns {Map<string, Record<string, string>>}
+     */
+    static extractSchematicOwnerMetadata(records) {
+        const ownerMetadata = new Map()
+
+        for (const record of records) {
+            const ownerIndex = ParserUtils.getField(record.fields, 'OwnerIndex')
+            const name = ParserUtils.getField(record.fields, 'Name').trim()
+            const value = ParserUtils.getDisplayText(record.fields)
+
+            if (
+                !ownerIndex ||
+                !name ||
+                !value ||
+                value === '*' ||
+                String(value).trim().startsWith('=')
+            ) {
+                continue
+            }
+
+            if (!ownerMetadata.has(ownerIndex)) {
+                ownerMetadata.set(ownerIndex, {})
+            }
+
+            ownerMetadata.get(ownerIndex)[name.toLowerCase()] = value
+        }
+
+        return ownerMetadata
+    }
+
     /**
      * Builds a font table from the sheet header.
      * @param {Record<string, string | string[]> | undefined} fields
@@ -96,18 +133,30 @@ export class SchematicTextParser {
      * @param {Record<string, string>} metadata
      * @param {{ width: number, marginWidth: number, titleBlockOn?: boolean }} sheet
      * @param {Record<string, { size: number, family: string, bold: boolean, italic?: boolean, rotation: number }>} fonts
+     * @param {Map<string, Record<string, string>>} [ownerMetadata]
      * @returns {{ x: number, y: number, text: string, color: string, hidden: boolean, name: string, ownerIndex?: string, recordType: string, style: number, fontSize: number, fontFamily: string, fontWeight: number, fontStyle?: string, rotation: number, sourceOrientation?: number, isMirrored?: boolean, anchor: 'start' | 'middle' | 'end', powerPortDirection?: 'up' | 'down' | 'left' | 'right', cornerX?: number, cornerY?: number, fill?: string, borderColor?: string, isSolid?: boolean, showBorder?: boolean, textMargin?: number, noteLines?: string[] } | null}
      */
-    static normalizeSchematicTextRecord(fields, metadata, sheet, fonts) {
+    static normalizeSchematicTextRecord(
+        fields,
+        metadata,
+        sheet,
+        fonts,
+        ownerMetadata = new Map()
+    ) {
         const x = ParserUtils.parseNumericField(fields, 'Location.X')
         const y = ParserUtils.parseNumericField(fields, 'Location.Y')
         const hidden = ParserUtils.parseBoolean(fields.IsHidden)
         const name = ParserUtils.getField(fields, 'Name')
         const rawText = ParserUtils.getDisplayText(fields)
         const recordType = ParserUtils.getField(fields, 'RECORD')
+        const ownerIndex = ParserUtils.getField(fields, 'OwnerIndex')
         const text = SchematicTextParser.#resolveSchematicTemplateText(
             rawText,
-            metadata
+            SchematicTextParser.#resolveSchematicTextMetadata(
+                ownerIndex,
+                metadata,
+                ownerMetadata
+            )
         )
 
         if (hidden || x === null || y === null || !text) {
@@ -149,7 +198,7 @@ export class SchematicTextParser {
             ),
             hidden,
             name,
-            ownerIndex: ParserUtils.getField(fields, 'OwnerIndex') || undefined,
+            ownerIndex: ownerIndex || undefined,
             recordType,
             style: ParserUtils.parseNumericField(fields, 'Style') || 0,
             renderOrder:
@@ -476,6 +525,21 @@ export class SchematicTextParser {
         return replacement ? replacement : normalized
     }
 
+    /**
+     * Chooses the parameter map for one text record.
+     * @param {string} ownerIndex
+     * @param {Record<string, string>} metadata
+     * @param {Map<string, Record<string, string>>} ownerMetadata
+     * @returns {Record<string, string>}
+     */
+    static #resolveSchematicTextMetadata(ownerIndex, metadata, ownerMetadata) {
+        if (!ownerIndex) {
+            return metadata
+        }
+
+        return ownerMetadata.get(ownerIndex) || {}
+    }
+
     /**
      * Returns true when a text record is metadata rather than sheet content.
      * @param {Record<string, string | string[]>} fields
@@ -510,7 +574,6 @@ export class SchematicTextParser {
         if (nonDrawableNames.has(normalizedName)) return true
         if (/uniqueid$/i.test(normalizedName)) return true
         if (!normalizedText || normalizedText === '*') return true
-        if (/^=/.test(normalizedText)) return true
         if (
             sheet.titleBlockOn &&
             SchematicTextParser.isTitleBlockFooterRecord(fields, sheet.width)
@@ -537,10 +600,47 @@ export class SchematicTextParser {
 
         if (recordType === '17') return 'middle'
         if (explicitAnchor) return explicitAnchor
+        if (
+            SchematicTextParser.#shouldCenterSchematicNoteByDefault(
+                fields,
+                recordType,
+                text
+            )
+        ) {
+            return 'middle'
+        }
 
         return 'start'
     }
 
+    /**
+     * Returns true for Altium text frames that encode centered one-line labels
+     * without carrying an explicit justification field.
+     * @param {Record<string, string | string[]>} fields
+     * @param {string} recordType
+     * @param {string} text
+     * @returns {boolean}
+     */
+    static #shouldCenterSchematicNoteByDefault(fields, recordType, text) {
+        if (recordType !== '209' && recordType !== '28') return false
+        if (String(text || '').includes('~1')) return false
+        if (
+            ParserUtils.parseNumericField(fields, 'Corner.X') === null ||
+            ParserUtils.parseNumericField(fields, 'Corner.Y') === null
+        ) {
+            return false
+        }
+
+        if (recordType === '28') {
+            return ParserUtils.parseBoolean(fields.WordWrap)
+        }
+
+        return (
+            ParserUtils.parseBoolean(fields.WordWrap) &&
+            ParserUtils.parseBoolean(fields.ClipToRect)
+        )
+    }
+
     /**
      * Decodes Altium's three-column text justification grid into one
      * horizontal SVG text anchor.
@@ -548,23 +648,37 @@ export class SchematicTextParser {
      * @returns {'start' | 'middle' | 'end' | null}
      */
     static #resolveSchematicTextJustificationAnchor(fields) {
-        const justification = ParserUtils.parseNumericField(
-            fields,
-            'Justification'
-        )
+        const justification =
+            ParserUtils.parseNumericField(fields, 'Justification') ??
+            ParserUtils.parseNumericField(fields, 'Alignment')
 
         if (justification === null) {
             return null
         }
 
+        let anchor = 'start'
         switch (((justification % 3) + 3) % 3) {
             case 1:
-                return 'middle'
+                anchor = 'middle'
+                break
             case 2:
-                return 'end'
+                anchor = 'end'
+                break
             default:
-                return 'start'
+                anchor = 'start'
         }
+
+        if (
+            anchor !== 'middle' &&
+            ParserUtils.getField(fields, 'RECORD') === '4' &&
+            ParserUtils.getField(fields, 'OwnerIndex') &&
+            ParserUtils.parseBoolean(fields.IsMirrored) &&
+            ParserUtils.parseNumericField(fields, 'Orientation') === 2
+        ) {
+            return anchor === 'start' ? 'end' : 'start'
+        }
+
+        return anchor
     }
 
     /**

package/src/core/altium/SchematicTextPostProcessor.mjs

@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+import { SchematicMultipartDesignatorNormalizer } from './SchematicMultipartDesignatorNormalizer.mjs'
+
 /**
  * Applies placement-oriented cleanup passes to normalized schematic text.
  */
@@ -47,84 +49,17 @@ export class SchematicTextPostProcessor {
     }
 
     /**
-     * Adds multipart section suffixes like A/B/J to visible designator texts
-     * when the active Altium part id is stored separately from the base
+     * Normalizes multipart section suffixes like A/B/J on visible designator
+     * texts when the active Altium part id is stored separately from the
      * designator string.
      * @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 decorateMultipartDesignators(texts, activeMultipartOwnerParts) {
-        const duplicatedActiveBaseDesignators =
-            SchematicTextPostProcessor.#collectDuplicatedActiveMultipartDesignators(
-                texts,
-                activeMultipartOwnerParts
-            )
-
-        return texts.map((text) => {
-            const ownerIndex = String(text.ownerIndex || '')
-            const suffix =
-                SchematicTextPostProcessor.#formatMultipartPartSuffix(
-                    activeMultipartOwnerParts.get(ownerIndex)
-                )
-
-            if (
-                !suffix ||
-                text.recordType !== '34' ||
-                String(text.name || '')
-                    .trim()
-                    .toLowerCase() !== 'designator' ||
-                !duplicatedActiveBaseDesignators.has(text.text)
-            ) {
-                return text
-            }
-
-            if (!/\d$/i.test(text.text) || text.text.endsWith(suffix)) {
-                return text
-            }
-
-            return {
-                ...text,
-                text: text.text + suffix
-            }
-        })
-    }
-
-    /**
-     * Collects base multipart designators that belong to more than one active
-     * visible owner on the current sheet.
-     * @param {{ text: string, name?: string, ownerIndex?: string, recordType?: string }[]} texts
-     * @param {Map<string, string>} activeMultipartOwnerParts
-     * @returns {Set<string>}
-     */
-    static #collectDuplicatedActiveMultipartDesignators(
-        texts,
-        activeMultipartOwnerParts
-    ) {
-        const counts = new Map()
-
-        for (const text of texts) {
-            const ownerIndex = String(text.ownerIndex || '')
-
-            if (
-                !activeMultipartOwnerParts.has(ownerIndex) ||
-                text.recordType !== '34' ||
-                String(text.name || '')
-                    .trim()
-                    .toLowerCase() !== 'designator' ||
-                !/\d$/i.test(String(text.text || '').trim())
-            ) {
-                continue
-            }
-
-            const baseDesignator = String(text.text || '').trim()
-            counts.set(baseDesignator, (counts.get(baseDesignator) || 0) + 1)
-        }
-
-        return new Set(
-            [...counts.entries()]
-                .filter(([, count]) => count > 1)
-                .map(([baseDesignator]) => baseDesignator)
+        return SchematicMultipartDesignatorNormalizer.normalize(
+            texts,
+            activeMultipartOwnerParts
         )
     }
 
@@ -136,7 +71,7 @@ export class SchematicTextPostProcessor {
      * @param {{ x1: number, y1: number, x2: number, y2: number, ownerIndex?: string }[]} lines
      * @param {{ x: number, y: number, ownerIndex: string, length: number, orientation: 'left' | 'right' | 'top' | 'bottom' }[]} pins
      * @param {{ x: number, y: number, width: number, direction?: 'left' | 'right' | 'up' | 'down' }[]} ports
-     * @param {{ x: number, y: number, width: number, height: number, ownerIndex?: string }[]} rectangles
+     * @param {{ x: number, y: number, width: number, height: number, ownerIndex?: string }[] | { rectangles?: { x: number, y: number, width: number, height: number, ownerIndex?: string }[], roundedRectangles?: { x: number, y: number, width: number, height: number, ownerIndex?: string }[], ellipses?: { x: number, y: number, radiusX: number, radiusY: number, ownerIndex?: string }[], arcs?: { x: number, y: number, radius: number, radiusY?: number, ownerIndex?: string }[], pies?: { x: number, y: number, radius: number, radiusY?: number, ownerIndex?: string }[] }} bodyPrimitives
      * @returns {{ x: number, y: number, text: string, name?: string, ownerIndex?: string, recordType?: string, rotation?: number, anchor?: 'start' | 'middle' | 'end' }[]}
      */
     static anchorComponentTextsFromOwnerBounds(
@@ -144,17 +79,22 @@ export class SchematicTextPostProcessor {
         lines,
         pins,
         ports = [],
-        rectangles = []
+        bodyPrimitives = []
     ) {
+        const normalizedBodyPrimitives =
+            SchematicTextPostProcessor.#normalizeOwnerBodyPrimitives(
+                bodyPrimitives
+            )
         const ownerBounds = SchematicTextPostProcessor.#buildOwnerBounds(
             lines,
             pins
         )
-        const ownerBodyBounds = SchematicTextPostProcessor.#buildOwnerBounds(
-            lines,
-            pins,
-            rectangles
-        )
+        const ownerBodyBounds =
+            SchematicTextPostProcessor.#buildOwnerBodyBounds(
+                lines,
+                pins,
+                normalizedBodyPrimitives
+            )
         const ownerPinCounts =
             SchematicTextPostProcessor.#buildOwnerPinCounts(pins)
         const ownerPinOrientations =
@@ -236,6 +176,131 @@ export class SchematicTextPostProcessor {
         })
     }
 
+    /**
+     * Normalizes owner body primitive arguments while preserving the older
+     * rectangle-array call shape.
+     * @param {{ x: number, y: number, width: number, height: number, ownerIndex?: string }[] | { rectangles?: { x: number, y: number, width: number, height: number, ownerIndex?: string }[], roundedRectangles?: { x: number, y: number, width: number, height: number, ownerIndex?: string }[], ellipses?: { x: number, y: number, radiusX: number, radiusY: number, ownerIndex?: string }[], arcs?: { x: number, y: number, radius: number, radiusY?: number, ownerIndex?: string }[], pies?: { x: number, y: number, radius: number, radiusY?: number, ownerIndex?: string }[] }} bodyPrimitives
+     * @returns {{ rectangles: { x: number, y: number, width: number, height: number, ownerIndex?: string }[], roundedRectangles: { x: number, y: number, width: number, height: number, ownerIndex?: string }[], ellipses: { x: number, y: number, radiusX: number, radiusY: number, ownerIndex?: string }[], arcs: { x: number, y: number, radius: number, radiusY?: number, ownerIndex?: string }[], pies: { x: number, y: number, radius: number, radiusY?: number, ownerIndex?: string }[] }}
+     */
+    static #normalizeOwnerBodyPrimitives(bodyPrimitives) {
+        if (Array.isArray(bodyPrimitives)) {
+            return {
+                rectangles: bodyPrimitives,
+                roundedRectangles: [],
+                ellipses: [],
+                arcs: [],
+                pies: []
+            }
+        }
+
+        return {
+            rectangles: bodyPrimitives?.rectangles || [],
+            roundedRectangles: bodyPrimitives?.roundedRectangles || [],
+            ellipses: bodyPrimitives?.ellipses || [],
+            arcs: bodyPrimitives?.arcs || [],
+            pies: bodyPrimitives?.pies || []
+        }
+    }
+
+    /**
+     * Builds per-owner body bounds from straight and curved owner primitives.
+     * @param {{ x1: number, y1: number, x2: number, y2: number, ownerIndex?: string }[]} lines
+     * @param {{ x: number, y: number, ownerIndex: string }[]} pins
+     * @param {{ rectangles: { x: number, y: number, width: number, height: number, ownerIndex?: string }[], roundedRectangles: { x: number, y: number, width: number, height: number, ownerIndex?: string }[], ellipses: { x: number, y: number, radiusX: number, radiusY: number, ownerIndex?: string }[], arcs: { x: number, y: number, radius: number, radiusY?: number, ownerIndex?: string }[], pies: { x: number, y: number, radius: number, radiusY?: number, ownerIndex?: string }[] }} bodyPrimitives
+     * @returns {Map<string, { minX: number, minY: number, maxX: number, maxY: number }>}
+     */
+    static #buildOwnerBodyBounds(lines, pins, bodyPrimitives) {
+        const ownerBounds = SchematicTextPostProcessor.#buildOwnerBounds(
+            lines,
+            pins,
+            [...bodyPrimitives.rectangles, ...bodyPrimitives.roundedRectangles]
+        )
+
+        SchematicTextPostProcessor.#extendCenteredOwnerBounds(
+            ownerBounds,
+            bodyPrimitives.ellipses
+        )
+        SchematicTextPostProcessor.#extendCenteredOwnerBounds(
+            ownerBounds,
+            bodyPrimitives.arcs
+        )
+        SchematicTextPostProcessor.#extendCenteredOwnerBounds(
+            ownerBounds,
+            bodyPrimitives.pies
+        )
+
+        return ownerBounds
+    }
+
+    /**
+     * Extends owner bounds by primitives expressed as a center and radii.
+     * @param {Map<string, { minX: number, minY: number, maxX: number, maxY: number }>} ownerBounds
+     * @param {{ x: number, y: number, radius?: number, radiusX?: number, radiusY?: number, ownerIndex?: string }[]} primitives
+     * @returns {void}
+     */
+    static #extendCenteredOwnerBounds(ownerBounds, primitives) {
+        for (const primitive of primitives) {
+            if (!primitive.ownerIndex) {
+                continue
+            }
+
+            const radiusX =
+                SchematicTextPostProcessor.#resolveHorizontalRadius(primitive)
+            const radiusY =
+                SchematicTextPostProcessor.#resolveVerticalRadius(primitive)
+
+            if (radiusX <= 0 || radiusY <= 0) {
+                continue
+            }
+
+            SchematicTextPostProcessor.#extendBounds(
+                ownerBounds,
+                primitive.ownerIndex,
+                [
+                    { x: primitive.x - radiusX, y: primitive.y - radiusY },
+                    { x: primitive.x + radiusX, y: primitive.y + radiusY }
+                ]
+            )
+        }
+    }
+
+    /**
+     * Resolves the horizontal radius of a center-defined primitive.
+     * @param {{ radius?: number, radiusX?: number }} primitive
+     * @returns {number}
+     */
+    static #resolveHorizontalRadius(primitive) {
+        return SchematicTextPostProcessor.#coercePositiveNumber(
+            primitive.radiusX ?? primitive.radius
+        )
+    }
+
+    /**
+     * Resolves the vertical radius of a center-defined primitive.
+     * @param {{ radius?: number, radiusY?: number }} primitive
+     * @returns {number}
+     */
+    static #resolveVerticalRadius(primitive) {
+        return SchematicTextPostProcessor.#coercePositiveNumber(
+            primitive.radiusY ?? primitive.radius
+        )
+    }
+
+    /**
+     * Converts finite positive numeric values, preserving zero for invalids.
+     * @param {number | string | undefined | null} value
+     * @returns {number}
+     */
+    static #coercePositiveNumber(value) {
+        const numericValue = Number(value)
+
+        if (!Number.isFinite(numericValue) || numericValue <= 0) {
+            return 0
+        }
+
+        return numericValue
+    }
+
     /**
      * Right-aligns wire labels that precede a same-row component designator so
      * they stay clear of the symbol body.
@@ -401,6 +466,8 @@ export class SchematicTextPostProcessor {
             case 2:
             case 33:
                 return 8
+            case 6:
+                return 12
             default:
                 return 2
         }
@@ -744,29 +811,6 @@ export class SchematicTextPostProcessor {
         )
     }
 
-    /**
-     * Converts one numeric multipart section id into an alphabetic suffix.
-     * @param {string | undefined} partId
-     * @returns {string}
-     */
-    static #formatMultipartPartSuffix(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
-    }
-
     /**
      * Returns true when the horizontal wire segment under the label starts at a
      * pin endpoint, which means the label should continue reading rightward.