altium-toolkit 1.1.1 → 1.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "altium-toolkit",
-    "version": "1.1.1",
+    "version": "1.1.3",
     "description": "Altium document parsing and non-interactive rendering utilities",
     "keywords": [
         "altium",

package/src/core/altium/AltiumLayoutParser.mjs

@@ -267,7 +267,7 @@ export class AltiumLayoutParser {
      * @param {{ width: number, height: number, marginWidth: number, paperSize?: string }} sheet
      * @param {{ fields: Record<string, string | string[]> }[]} textRecords
      * @param {{ x1: number, y1: number, x2: number, y2: number }[]} lines
-     * @param {{ x: number, y: number }[]} texts
+     * @param {{ x: number, y: number, cornerX?: number, cornerY?: number }[]} texts
      * @param {{ x: number, y: number }[]} components
      * @param {{ x: number, y: number }[]} pins
      * @param {{ x: number, y: number, width: number, height: number }[]} rectangles
@@ -303,12 +303,47 @@ export class AltiumLayoutParser {
         }
 
         const margin = Math.max(Number(sheet?.marginWidth || 20), 20)
+        const nativeTemplateSheet =
+            AltiumLayoutParser.#resolveNativeStandardTemplateSheetSize(
+                sheet,
+                bounds,
+                margin
+            )
+        if (nativeTemplateSheet) {
+            return {
+                ...sheet,
+                ...nativeTemplateSheet
+            }
+        }
+
+        if (
+            AltiumLayoutParser.#shouldPreserveNativeStandardTemplateSize(
+                sheet,
+                bounds,
+                margin
+            )
+        ) {
+            return sheet
+        }
+
         const footerBounds = AltiumLayoutParser.#collectSchematicFooterBounds(
             textRecords,
             Number(sheet?.width || 0)
         )
-        const requiredWidth =
-            Math.max(bounds.maxX, footerBounds?.maxX || 0) + margin * 2
+        const footerLineBounds =
+            AltiumLayoutParser.#collectSchematicFooterLineBounds(
+                lines,
+                sheet,
+                margin
+            )
+        const requiredWidthResult =
+            AltiumLayoutParser.#resolveSchematicRequiredWidth(
+                sheet,
+                Math.max(bounds.maxX, footerBounds?.maxX || 0),
+                footerLineBounds?.maxX || 0,
+                margin
+            )
+        const requiredWidth = requiredWidthResult.width
         const requiredHeight =
             Math.max(bounds.maxY, footerBounds?.maxY || 0) + margin * 2
 
@@ -322,10 +357,12 @@ export class AltiumLayoutParser {
             return sheet
         }
 
-        const standardSheet = AltiumLayoutParser.#resolveStandardSheetSize(
-            requiredWidth,
-            requiredHeight
-        )
+        const standardSheet = requiredWidthResult.usesNativeFrameEdge
+            ? null
+            : AltiumLayoutParser.#resolveStandardSheetSize(
+                  requiredWidth,
+                  requiredHeight
+              )
 
         if (standardSheet) {
             return {
@@ -344,11 +381,12 @@ export class AltiumLayoutParser {
             sheet.height,
             requiredHeight
         )
-        const resolvedStandardSheet =
-            AltiumLayoutParser.#resolveStandardSheetSize(
-                resolvedWidth,
-                resolvedHeight
-            )
+        const resolvedStandardSheet = requiredWidthResult.usesNativeFrameEdge
+            ? null
+            : AltiumLayoutParser.#resolveStandardSheetSize(
+                  resolvedWidth,
+                  resolvedHeight
+              )
 
         if (resolvedStandardSheet) {
             return {
@@ -367,6 +405,126 @@ export class AltiumLayoutParser {
         }
     }
 
+    /**
+     * Resolves the standard template page named by Altium standard sheet
+     * records, preserving landscape or portrait orientation from the stored
+     * custom dimensions.
+     * @param {Record<string, string | string[]> | undefined} fields Sheet fields.
+     * @param {number} fallbackWidth Stored custom width.
+     * @param {number} fallbackHeight Stored custom height.
+     * @returns {{ width: number, height: number, paperSize: string, sourceWidth?: number, sourceHeight?: number } | null}
+     */
+    static resolveSchematicTemplatePageSize(
+        fields,
+        fallbackWidth,
+        fallbackHeight
+    ) {
+        if (parseNumericField(fields, 'SheetStyle') !== 1) {
+            return null
+        }
+
+        const templateFileName = getField(fields, 'TemplateFileName')
+        const match = String(templateFileName || '').match(
+            /(?:^|[^a-z0-9])A([0-5])(?:[^a-z0-9]|$)/iu
+        )
+
+        if (!match) {
+            return null
+        }
+
+        const paperSize = 'A' + match[1]
+        const portraitSheet = ISO_A_PORTRAIT_SHEETS.find(
+            (sheet) => sheet.label === paperSize
+        )
+
+        if (!portraitSheet) {
+            return null
+        }
+
+        const normalizedFallbackWidth = Number(fallbackWidth || 0)
+        const normalizedFallbackHeight = Number(fallbackHeight || 0)
+        const portraitTemplate =
+            parseNumericField(fields, 'WorkspaceOrientation') === 1 ||
+            /portrait/iu.test(String(templateFileName || ''))
+
+        if (
+            portraitTemplate &&
+            normalizedFallbackWidth > normalizedFallbackHeight &&
+            normalizedFallbackHeight > 0
+        ) {
+            return {
+                width: normalizedFallbackHeight,
+                height: normalizedFallbackWidth,
+                sourceWidth: normalizedFallbackHeight,
+                sourceHeight: normalizedFallbackWidth,
+                paperSize
+            }
+        }
+
+        const landscape = normalizedFallbackWidth >= normalizedFallbackHeight
+
+        return {
+            width: landscape ? portraitSheet.height : portraitSheet.width,
+            height: landscape ? portraitSheet.width : portraitSheet.height,
+            paperSize
+        }
+    }
+
+    /**
+     * Resolves the page width required by recovered schematic geometry.
+     * Native template linework can use the declared custom width as the inner
+     * frame edge; adding both margins would create an artificial right gutter.
+     * @param {{ width?: number, borderOn?: boolean, titleBlockOn?: boolean, sheetStyle?: number }} sheet
+     * @param {number} maxX
+     * @param {number} footerLineMaxX
+     * @param {number} margin
+     * @returns {{ width: number, usesNativeFrameEdge: boolean }}
+     */
+    static #resolveSchematicRequiredWidth(sheet, maxX, footerLineMaxX, margin) {
+        const reachesNativeFrameEdge =
+            Number(sheet?.sheetStyle || 0) !== 1 &&
+            Boolean(sheet?.borderOn || sheet?.titleBlockOn) &&
+            footerLineMaxX > 0 &&
+            maxX <= footerLineMaxX + 0.01
+        const rightPadding = reachesNativeFrameEdge ? margin : margin * 2
+
+        return {
+            width: maxX + rightPadding,
+            usesNativeFrameEdge: reachesNativeFrameEdge
+        }
+    }
+
+    /**
+     * Collects owned lower-page linework that represents native title-block or
+     * footer chrome rather than schematic content.
+     * @param {{ x1: number, y1: number, x2: number, y2: number, ownerIndex?: string }[]} lines
+     * @param {{ width?: number }} sheet
+     * @param {number} margin
+     * @returns {{ maxX: number } | null}
+     */
+    static #collectSchematicFooterLineBounds(lines, sheet, margin) {
+        const footerLimit = Math.max(margin * 6, 120)
+        const sheetWidth = Math.max(Number(sheet?.width || 0), 0)
+        const footerStartX = sheetWidth > 0 ? sheetWidth * 0.5 : 0
+        const coordinates = []
+
+        for (const line of lines || []) {
+            if (!line?.ownerIndex) continue
+            if (Math.max(line.y1, line.y2) > footerLimit) continue
+            if (Math.max(line.x1, line.x2) < footerStartX) continue
+
+            coordinates.push(line.x1, line.x2)
+        }
+
+        if (!coordinates.length) {
+            return null
+        }
+
+        return {
+            maxX: Math.max(...coordinates)
+        }
+    }
+
     /**
      * Returns true when the parser should trust the authored custom sheet
      * dimensions instead of shrinking the page to visible content bounds.
@@ -403,11 +561,108 @@ export class AltiumLayoutParser {
         return false
     }
 
+    /**
+     * Returns true when a standard template has already resolved to its native
+     * template coordinate frame rather than a promoted ISO sheet envelope.
+     * @param {{ width?: number, height?: number, sourceWidth?: number, sourceHeight?: number, paperSize?: string, sheetStyle?: number }} sheet
+     * @param {{ maxX: number, maxY: number }} bounds
+     * @param {number} margin
+     * @returns {boolean}
+     */
+    static #shouldPreserveNativeStandardTemplateSize(sheet, bounds, margin) {
+        const width = Number(sheet?.width || 0)
+        const height = Number(sheet?.height || 0)
+        const sourceWidth = Number(sheet?.sourceWidth || 0)
+        const sourceHeight = Number(sheet?.sourceHeight || 0)
+
+        if (
+            Number(sheet?.sheetStyle || 0) !== 1 ||
+            !sheet?.paperSize ||
+            width <= 0 ||
+            height <= 0 ||
+            width !== sourceWidth ||
+            height !== sourceHeight
+        ) {
+            return false
+        }
+
+        return (
+            Number(bounds?.maxX || 0) <= width - margin + 0.01 &&
+            Number(bounds?.maxY || 0) <= height - margin + 0.01
+        )
+    }
+
+    /**
+     * Derives a native standard-template frame from embedded template graphics
+     * when those graphics overrun the stored custom dimensions but fit inside
+     * a smaller-than-ISO template envelope.
+     * @param {{ width?: number, height?: number, sourceWidth?: number, sourceHeight?: number, paperSize?: string, sheetStyle?: number }} sheet
+     * @param {{ maxX: number, maxY: number }} bounds
+     * @param {number} margin
+     * @returns {{ width: number, height: number, sourceWidth: number, sourceHeight: number } | null}
+     */
+    static #resolveNativeStandardTemplateSheetSize(sheet, bounds, margin) {
+        const width = Number(sheet?.width || 0)
+        const height = Number(sheet?.height || 0)
+        const sourceWidth = Number(sheet?.sourceWidth || 0)
+        const sourceHeight = Number(sheet?.sourceHeight || 0)
+
+        if (
+            Number(sheet?.sheetStyle || 0) !== 1 ||
+            !sheet?.paperSize ||
+            sourceWidth <= 0 ||
+            sourceHeight <= 0 ||
+            width <= sourceWidth ||
+            height <= sourceHeight
+        ) {
+            return null
+        }
+
+        const maxX = Number(bounds?.maxX || 0)
+        const maxY = Number(bounds?.maxY || 0)
+        if (maxX <= sourceWidth && maxY <= sourceHeight) {
+            return null
+        }
+
+        const nativeWidth = AltiumLayoutParser.#roundTemplateExtent(
+            maxX + margin
+        )
+        const nativeHeight = AltiumLayoutParser.#roundTemplateExtent(
+            maxY + margin
+        )
+
+        if (
+            nativeWidth <= sourceWidth ||
+            nativeHeight <= sourceHeight ||
+            nativeWidth >= width ||
+            nativeHeight >= height
+        ) {
+            return null
+        }
+
+        return {
+            width: nativeWidth,
+            height: nativeHeight,
+            sourceWidth: nativeWidth,
+            sourceHeight: nativeHeight
+        }
+    }
+
+    /**
+     * Rounds a recovered template frame edge to the next schematic grid
+     * interval.
+     * @param {number} value Raw extent.
+     * @returns {number}
+     */
+    static #roundTemplateExtent(value) {
+        return Math.ceil(Math.max(Number(value || 0), 0) / 10) * 10
+    }
+
     /**
      * Collects the visible coordinate envelope from recovered schematic
      * primitives.
      * @param {{ x1: number, y1: number, x2: number, y2: number }[]} lines
-     * @param {{ x: number, y: number }[]} texts
+     * @param {{ x: number, y: number, cornerX?: number, cornerY?: number }[]} texts
      * @param {{ x: number, y: number }[]} components
      * @param {{ x: number, y: number }[]} pins
      * @param {{ x: number, y: number, width: number, height: number }[]} rectangles
@@ -434,6 +689,13 @@ export class AltiumLayoutParser {
 
         for (const text of texts) {
             coordinates.push([text.x, text.y])
+
+            if (
+                Number.isFinite(Number(text.cornerX)) &&
+                Number.isFinite(Number(text.cornerY))
+            ) {
+                coordinates.push([Number(text.cornerX), Number(text.cornerY)])
+            }
         }
 
         for (const component of components) {

package/src/core/altium/AltiumParser.mjs

@@ -59,6 +59,7 @@ const {
     extractSchematicFonts,
     extractSchematicFontDiagnostics,
     extractSchematicMetadata,
+    extractSchematicOwnerMetadata,
     extractSchematicTitleBlock,
     normalizeSchematicTextRecord
 } = SchematicTextParser
@@ -186,7 +187,7 @@ export class AltiumParser {
             AltiumParser.#collectOwnersWithImplicitDisplayMode(records)
         const activeMultipartOwnerParts =
             SchematicMultipartOwnerMatcher.collectActiveMultipartOwnerParts(
-                records,
+                recordIndexAwareRecords,
                 componentRecords
             )
         const sheetRecord = records.find(
@@ -329,21 +330,30 @@ export class AltiumParser {
         }
 
         const metadataTexts = extractSchematicMetadata(textRecords)
+        const ownerMetadataTexts = extractSchematicOwnerMetadata(textRecords)
         const schematicFonts = extractSchematicFonts(sheetRecord?.fields)
         const schematicRenderDiagnostics = extractSchematicFontDiagnostics(
             sheetRecord?.fields
         )
-        const sheetWidth =
+        const storedSheetWidth =
             parseNumericField(sheetRecord?.fields, 'CustomX') || 1500
-        const sheetHeight =
+        const storedSheetHeight =
             parseNumericField(sheetRecord?.fields, 'CustomY') || 950
+        const templatePageSize =
+            AltiumLayoutParser.resolveSchematicTemplatePageSize(
+                sheetRecord?.fields,
+                storedSheetWidth,
+                storedSheetHeight
+            )
+        const sheetWidth = templatePageSize?.width || storedSheetWidth
+        const sheetHeight = templatePageSize?.height || storedSheetHeight
         const sheetMargin =
             parseNumericField(sheetRecord?.fields, 'CustomMarginWidth') || 20
         const sheet = {
             width: sheetWidth,
             height: sheetHeight,
-            sourceWidth: sheetWidth,
-            sourceHeight: sheetHeight,
+            sourceWidth: templatePageSize?.sourceWidth || storedSheetWidth,
+            sourceHeight: templatePageSize?.sourceHeight || storedSheetHeight,
             visibleGrid:
                 parseNumericField(sheetRecord?.fields, 'VisibleGridSize') || 10,
             snapGrid:
@@ -363,6 +373,9 @@ export class AltiumParser {
             fonts: schematicFonts,
             sheetStyle:
                 parseNumericField(sheetRecord?.fields, 'SheetStyle') || 0,
+            ...(templatePageSize?.paperSize
+                ? { paperSize: templatePageSize.paperSize }
+                : {}),
             titleBlock: extractSchematicTitleBlock(
                 textRecords,
                 metadataTexts,
@@ -415,7 +428,19 @@ export class AltiumParser {
                 )
             )
         ]
-        const pins = parseSchematicPins(pinRecords)
+        const ownerDrawnInternalPinOwners =
+            AltiumParser.#collectInaccessibleOwnerDrawnPrimitiveOwners(
+                drawableRecords
+            )
+        const numericEndpointLabelOwners =
+            AltiumParser.#collectNumericEndpointLabelOwners(
+                componentRecords,
+                recordIndexAwareRecords
+            )
+        const pins = parseSchematicPins(pinRecords, {
+            ownerDrawnInternalPinOwners,
+            numericEndpointLabelOwners
+        })
         const junctions = SchematicJunctionParser.parseSchematicJunctions(
             recordIndexAwareRecords
         )
@@ -489,7 +514,8 @@ export class AltiumParser {
                     record.fields,
                     metadataTexts,
                     sheet,
-                    schematicFonts
+                    schematicFonts,
+                    ownerMetadataTexts
                 )
             )
             .filter(Boolean)
@@ -524,7 +550,13 @@ export class AltiumParser {
                     normalizedLines,
                     pins,
                     ports,
-                    rectangles
+                    {
+                        rectangles,
+                        roundedRectangles,
+                        ellipses,
+                        arcs,
+                        pies
+                    }
                 ),
                 normalizedLines,
                 pins,
@@ -584,6 +616,8 @@ export class AltiumParser {
 
         resolvedSheet.xZones =
             SchematicSheetStyleResolver.resolveXZones(resolvedSheet)
+        resolvedSheet.yZones =
+            SchematicSheetStyleResolver.resolveYZones(resolvedSheet)
         delete resolvedSheet.sheetStyle
 
         const title =
@@ -649,6 +683,11 @@ export class AltiumParser {
                 busEntries,
                 sheetEntries
             })
+        AltiumParser.#suppressRedundantSinglePinPowerNetNames(
+            pins,
+            nets,
+            anchoredTexts
+        )
         diagnostics.push(...netDiagnostics)
         const qa = SchematicQaReportBuilder.build({
             records: recordIndexAwareRecords,
@@ -741,6 +780,142 @@ export class AltiumParser {
         })
     }
 
+    /**
+     * Hides one-pin owner pin names when a connected power port already labels
+     * the same net, preserving the numeric pin endpoint label.
+     * @param {{ ownerIndex?: string, name?: string, labelMode?: 'hidden' | 'number-only' | 'name-only' | 'name-and-number' }[]} pins
+     * @param {{ powerPorts?: { text?: string }[], pins?: { ownerIndex?: string, name?: string, labelMode?: 'hidden' | 'number-only' | 'name-only' | 'name-and-number' }[] }[]} nets
+     * @param {{ x: number, y: number, text?: string, recordType?: string }[]} texts
+     * @returns {void}
+     */
+    static #suppressRedundantSinglePinPowerNetNames(pins, nets, texts = []) {
+        const ownerPinCounts = new Map()
+
+        for (const pin of pins || []) {
+            const ownerIndex = String(pin.ownerIndex || '').trim()
+
+            if (!ownerIndex) continue
+
+            ownerPinCounts.set(
+                ownerIndex,
+                (ownerPinCounts.get(ownerIndex) || 0) + 1
+            )
+        }
+
+        for (const net of nets || []) {
+            const powerPortNames = new Set(
+                (net.powerPorts || [])
+                    .map((powerPort) =>
+                        AltiumParser.#normalizePowerNetLabel(powerPort.text)
+                    )
+                    .filter(Boolean)
+            )
+
+            if (!powerPortNames.size) continue
+
+            for (const pin of net.pins || []) {
+                if (
+                    AltiumParser.#canSuppressSinglePinName(
+                        pin,
+                        ownerPinCounts
+                    ) &&
+                    powerPortNames.has(
+                        AltiumParser.#normalizePowerNetLabel(pin.name)
+                    )
+                ) {
+                    pin.labelMode = 'number-only'
+                }
+            }
+        }
+
+        const powerPorts = (texts || []).filter(
+            (text) => text?.recordType === '17'
+        )
+
+        for (const pin of pins || []) {
+            if (!AltiumParser.#canSuppressSinglePinName(pin, ownerPinCounts)) {
+                continue
+            }
+
+            const pinName = AltiumParser.#normalizePowerNetLabel(pin.name)
+            const connectionPoint = AltiumParser.#resolvePinConnectionPoint(pin)
+            const matchesDirectPowerPort = powerPorts.some(
+                (powerPort) =>
+                    pinName ===
+                        AltiumParser.#normalizePowerNetLabel(powerPort.text) &&
+                    AltiumParser.#pointsAreNear(connectionPoint, powerPort, 2)
+            )
+
+            if (matchesDirectPowerPort) {
+                pin.labelMode = 'number-only'
+            }
+        }
+    }
+
+    /**
+     * Returns true when a pin is the only pin on its owner and currently shows
+     * a name label.
+     * @param {{ ownerIndex?: string, labelMode?: 'hidden' | 'number-only' | 'name-only' | 'name-and-number' }} pin
+     * @param {Map<string, number>} ownerPinCounts
+     * @returns {boolean}
+     */
+    static #canSuppressSinglePinName(pin, ownerPinCounts) {
+        const ownerIndex = String(pin?.ownerIndex || '').trim()
+        const labelMode = pin?.labelMode || 'name-and-number'
+
+        return (
+            ownerIndex &&
+            ownerPinCounts.get(ownerIndex) === 1 &&
+            labelMode !== 'hidden' &&
+            labelMode !== 'number-only'
+        )
+    }
+
+    /**
+     * Resolves the outer electrical endpoint for a normalized schematic pin.
+     * @param {{ x: number, y: number, length: number, orientation: 'left' | 'right' | 'top' | 'bottom' }} pin
+     * @returns {{ x: number, y: number }}
+     */
+    static #resolvePinConnectionPoint(pin) {
+        switch (pin.orientation) {
+            case 'right':
+                return { x: pin.x + pin.length, y: pin.y }
+            case 'top':
+                return { x: pin.x, y: pin.y + pin.length }
+            case 'bottom':
+                return { x: pin.x, y: pin.y - pin.length }
+            case 'left':
+            default:
+                return { x: pin.x - pin.length, y: pin.y }
+        }
+    }
+
+    /**
+     * Returns true when two schematic points are close enough to represent the
+     * same recovered connection endpoint.
+     * @param {{ x: number, y: number }} left
+     * @param {{ x: number, y: number }} right
+     * @param {number} tolerance
+     * @returns {boolean}
+     */
+    static #pointsAreNear(left, right, tolerance) {
+        return (
+            Math.abs(Number(left.x) - Number(right.x)) <= tolerance &&
+            Math.abs(Number(left.y) - Number(right.y)) <= tolerance
+        )
+    }
+
+    /**
+     * Normalizes a power-net label for structural comparisons.
+     * @param {string | undefined} label
+     * @returns {string}
+     */
+    static #normalizePowerNetLabel(label) {
+        return String(label || '')
+            .trim()
+            .toUpperCase()
+    }
+
     /**
      * Finds a visible text string with a given logical name.
      * @param {{ fields: Record<string, string | string[]> }[]} records
@@ -784,6 +959,63 @@ export class AltiumParser {
         return owners
     }
 
+    /**
+     * Collects symbol owners that draw an inaccessible body around compact
+     * internal pins.
+     * @param {{ fields: Record<string, string | string[]> }[]} records
+     * @returns {Set<string>}
+     */
+    static #collectInaccessibleOwnerDrawnPrimitiveOwners(records) {
+        const owners = new Set()
+
+        for (const record of records) {
+            const ownerIndex = getField(record.fields, 'OwnerIndex')
+            const ownerPartId = getField(record.fields, 'OwnerPartId')
+
+            if (
+                ownerIndex &&
+                ownerPartId &&
+                ownerPartId !== '-1' &&
+                parseBoolean(record.fields.IsNotAccesible) &&
+                SchematicComponentOwnerTextResolver.isDisplayModeSelectablePrimitive(
+                    record.fields
+                )
+            ) {
+                owners.add(ownerIndex)
+            }
+        }
+
+        return owners
+    }
+
+    /**
+     * Collects component owners whose passive two-pin numeric endpoints are
+     * intended to remain visible in the schematic body.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }[]} componentRecords Component records.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }[]} records Indexed schematic records.
+     * @returns {Set<string>}
+     */
+    static #collectNumericEndpointLabelOwners(componentRecords, records) {
+        const owners = new Set()
+
+        for (const componentRecord of componentRecords) {
+            if (
+                parseNumericField(componentRecord.fields, 'ComponentKind') !== 4
+            ) {
+                continue
+            }
+
+            for (const ownerIndex of SchematicComponentOwnerTextResolver.resolveOwnerIndexes(
+                componentRecord,
+                records
+            )) {
+                owners.add(ownerIndex)
+            }
+        }
+
+        return owners
+    }
+
     /**
      * Returns true when one schematic record belongs to the active symbol
      * display mode for its owner.