altium-toolkit 1.1.2 → 1.1.22

package/src/core/altium/AltiumLibraryRecordBuilder.mjs

@@ -0,0 +1,293 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds deterministic textual and byte records for generated Altium libraries.
+ */
+export class AltiumLibraryRecordBuilder {
+    /**
+     * Builds a schematic component record.
+     * @param {object} bundle Normalized component bundle.
+     * @returns {string}
+     */
+    static buildSchematicComponentRecord(bundle) {
+        return AltiumLibraryRecordBuilder.#pipeRecord({
+            RECORD: 'Component',
+            Name: bundle.symbol.name,
+            SourceId: bundle.id,
+            DisplayName: bundle.name,
+            PinCount: String(bundle.symbol.pins.length),
+            PrimitiveCount: String(bundle.symbol.primitives.length)
+        })
+    }
+
+    /**
+     * Builds a PCB footprint record.
+     * @param {object} bundle Normalized component bundle.
+     * @returns {string}
+     */
+    static buildPcbFootprintRecord(bundle) {
+        return AltiumLibraryRecordBuilder.#pipeRecord({
+            RECORD: 'Footprint',
+            Name: bundle.footprint.name,
+            SourceId: bundle.id,
+            DisplayName: bundle.name,
+            PadCount: String(bundle.footprint.pads.length),
+            TrackCount: String(bundle.footprint.tracks.length),
+            ModelCount: String(bundle.models.length)
+        })
+    }
+
+    /**
+     * Builds a PcbLib Library/Data stream.
+     * @param {object[]} bundles Normalized component bundles.
+     * @returns {Uint8Array}
+     */
+    static buildPcbLibraryData(bundles) {
+        const countBytes = AltiumLibraryRecordBuilder.createCountHeader(
+            bundles.length
+        )
+
+        return AltiumLibraryRecordBuilder.concatBytes([
+            AltiumLibraryRecordBuilder.createProperties({
+                HEADER: 'PCB 6.0 Binary Library File',
+                WEIGHT: '0',
+                GENERATEDBY: 'ECAD Forge'
+            }),
+            countBytes,
+            ...bundles.map((bundle) =>
+                AltiumLibraryRecordBuilder.createStringBlock(
+                    bundle.footprint.name
+                )
+            )
+        ])
+    }
+
+    /**
+     * Builds a PcbLib component parameters table.
+     * @param {object[]} bundles Normalized component bundles.
+     * @returns {Uint8Array}
+     */
+    static buildComponentParamsToc(bundles) {
+        return AltiumLibraryRecordBuilder.concatBytes(
+            bundles.map((bundle) =>
+                AltiumLibraryRecordBuilder.createLengthPrefixedAscii(
+                    AltiumLibraryRecordBuilder.#pipeRecord({
+                        Name: bundle.footprint.name,
+                        'Pad Count': String(bundle.footprint.pads.length),
+                        Height: String(bundle.metadata.height || ''),
+                        Description: String(bundle.metadata.description || '')
+                    }) + '\r\n\u0000'
+                )
+            )
+        )
+    }
+
+    /**
+     * Builds a SectionKeys stream.
+     * @param {object[]} bundles Normalized component bundles.
+     * @returns {Uint8Array}
+     */
+    static buildSectionKeys(bundles) {
+        const entries = bundles.map((bundle) => ({
+            fullName: bundle.footprint.name,
+            storageName: AltiumLibraryRecordBuilder.sanitizeStorageName(
+                bundle.footprint.name
+            )
+        }))
+
+        return AltiumLibraryRecordBuilder.concatBytes([
+            AltiumLibraryRecordBuilder.createCountHeader(entries.length),
+            ...entries.flatMap((entry) => [
+                AltiumLibraryRecordBuilder.createStringBlock(entry.fullName),
+                AltiumLibraryRecordBuilder.createStringBlock(entry.storageName)
+            ])
+        ])
+    }
+
+    /**
+     * Builds a footprint Data stream.
+     * @param {object} bundle Normalized component bundle.
+     * @returns {Uint8Array}
+     */
+    static buildFootprintData(bundle) {
+        return AltiumLibraryRecordBuilder.concatBytes([
+            AltiumLibraryRecordBuilder.createStringBlock(bundle.footprint.name)
+        ])
+    }
+
+    /**
+     * Builds a footprint Parameters stream.
+     * @param {object} bundle Normalized component bundle.
+     * @returns {Uint8Array}
+     */
+    static buildFootprintParameters(bundle) {
+        return AltiumLibraryRecordBuilder.createProperties({
+            PATTERN: bundle.footprint.name,
+            DESCRIPTION: String(bundle.metadata.description || ''),
+            HEIGHT: String(bundle.metadata.height || ''),
+            ITEMGUID: AltiumLibraryRecordBuilder.#guidFromText(bundle.id)
+        })
+    }
+
+    /**
+     * Builds model metadata entries.
+     * @param {{ model: object, id: string, checksum: number }[]} models Model rows.
+     * @returns {Uint8Array}
+     */
+    static buildModelsData(models) {
+        return AltiumLibraryRecordBuilder.concatBytes(
+            models.map((row) =>
+                AltiumLibraryRecordBuilder.createLengthPrefixedAscii(
+                    AltiumLibraryRecordBuilder.#pipeRecord({
+                        ID: row.id,
+                        NAME: row.model.name,
+                        CHECKSUM: String(row.checksum),
+                        FORMAT: row.model.format
+                    }) + '\u0000'
+                )
+            )
+        )
+    }
+
+    /**
+     * Creates a little-endian count header.
+     * @param {number} count Count value.
+     * @returns {Uint8Array}
+     */
+    static createCountHeader(count) {
+        const bytes = new Uint8Array(4)
+        new DataView(bytes.buffer).setUint32(0, Number(count || 0), true)
+        return bytes
+    }
+
+    /**
+     * Creates a PcbLib property stream.
+     * @param {Record<string, string>} properties Properties.
+     * @returns {Uint8Array}
+     */
+    static createProperties(properties) {
+        return AltiumLibraryRecordBuilder.createLengthPrefixedAscii(
+            AltiumLibraryRecordBuilder.#pipeRecord(properties) + '\u0000'
+        )
+    }
+
+    /**
+     * Creates a Pascal-style string block.
+     * @param {string} text Text value.
+     * @returns {Uint8Array}
+     */
+    static createStringBlock(text) {
+        const encoded = new TextEncoder().encode(String(text || ''))
+        const bytes = new Uint8Array(4 + 1 + encoded.byteLength)
+        const view = new DataView(bytes.buffer)
+
+        view.setUint32(0, 1 + encoded.byteLength, true)
+        bytes[4] = encoded.byteLength
+        bytes.set(encoded, 5)
+
+        return bytes
+    }
+
+    /**
+     * Creates a length-prefixed ASCII/UTF-8 byte block.
+     * @param {string} text Text body.
+     * @returns {Uint8Array}
+     */
+    static createLengthPrefixedAscii(text) {
+        const encoded = new TextEncoder().encode(String(text || ''))
+        const bytes = new Uint8Array(4 + encoded.byteLength)
+
+        new DataView(bytes.buffer).setUint32(0, encoded.byteLength, true)
+        bytes.set(encoded, 4)
+
+        return bytes
+    }
+
+    /**
+     * Concatenates byte chunks.
+     * @param {Uint8Array[]} chunks Byte chunks.
+     * @returns {Uint8Array}
+     */
+    static concatBytes(chunks) {
+        const byteLength = chunks.reduce(
+            (sum, chunk) => sum + chunk.byteLength,
+            0
+        )
+        const bytes = new Uint8Array(byteLength)
+        let offset = 0
+
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset)
+            offset += chunk.byteLength
+        }
+
+        return bytes
+    }
+
+    /**
+     * Sanitizes one OLE storage name.
+     * @param {string} name Storage name.
+     * @returns {string}
+     */
+    static sanitizeStorageName(name) {
+        return String(name || 'Component')
+            .replace(/[\\/:\u0000-\u001f]/gu, '_')
+            .slice(0, 31)
+    }
+
+    /**
+     * Computes a simple deterministic checksum for generated model metadata.
+     * @param {Uint8Array} bytes Model bytes.
+     * @returns {number}
+     */
+    static checksumBytes(bytes) {
+        return [...bytes].reduce(
+            (checksum, value) => (checksum + value) >>> 0,
+            0
+        )
+    }
+
+    /**
+     * Builds one pipe-delimited record.
+     * @param {Record<string, string>} fields Record fields.
+     * @returns {string}
+     */
+    static #pipeRecord(fields) {
+        return (
+            '|' +
+            Object.entries(fields)
+                .filter(([, value]) => String(value ?? '') !== '')
+                .map(([key, value]) => key + '=' + String(value))
+                .join('|')
+        )
+    }
+
+    /**
+     * Builds a deterministic GUID-like id from text.
+     * @param {string} text Source text.
+     * @returns {string}
+     */
+    static #guidFromText(text) {
+        const hex = [...new TextEncoder().encode(String(text || ''))]
+            .map((value) => value.toString(16).padStart(2, '0'))
+            .join('')
+            .padEnd(32, '0')
+            .slice(0, 32)
+
+        return (
+            '{' +
+            hex.slice(0, 8) +
+            '-' +
+            hex.slice(8, 12) +
+            '-' +
+            hex.slice(12, 16) +
+            '-' +
+            hex.slice(16, 20) +
+            '-' +
+            hex.slice(20) +
+            '}'
+        )
+    }
+}

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(
@@ -237,8 +238,11 @@ export class AltiumParser {
         const rectangleRecords = drawableRecords.filter(
             (record) =>
                 SchematicPrimitiveParser.isRectangleRecord(record.fields) &&
-                AltiumParser.#hasCoordinatePair(record.fields, 'Location') &&
-                AltiumParser.#hasCoordinatePair(record.fields, 'Corner')
+                ((AltiumParser.#hasCoordinatePair(record.fields, 'Location') &&
+                    AltiumParser.#hasCoordinatePair(record.fields, 'Corner')) ||
+                    SchematicPrimitiveParser.isPointListedRectangleRecord(
+                        record.fields
+                    ))
         )
         const roundedRectangleRecords = drawableRecords.filter(
             (record) =>
@@ -329,21 +333,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 +376,9 @@ export class AltiumParser {
             fonts: schematicFonts,
             sheetStyle:
                 parseNumericField(sheetRecord?.fields, 'SheetStyle') || 0,
+            ...(templatePageSize?.paperSize
+                ? { paperSize: templatePageSize.paperSize }
+                : {}),
             titleBlock: extractSchematicTitleBlock(
                 textRecords,
                 metadataTexts,
@@ -415,7 +431,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 +517,8 @@ export class AltiumParser {
                     record.fields,
                     metadataTexts,
                     sheet,
-                    schematicFonts
+                    schematicFonts,
+                    ownerMetadataTexts
                 )
             )
             .filter(Boolean)
@@ -524,7 +553,13 @@ export class AltiumParser {
                     normalizedLines,
                     pins,
                     ports,
-                    rectangles
+                    {
+                        rectangles,
+                        roundedRectangles,
+                        ellipses,
+                        arcs,
+                        pies
+                    }
                 ),
                 normalizedLines,
                 pins,
@@ -584,6 +619,8 @@ export class AltiumParser {
 
         resolvedSheet.xZones =
             SchematicSheetStyleResolver.resolveXZones(resolvedSheet)
+        resolvedSheet.yZones =
+            SchematicSheetStyleResolver.resolveYZones(resolvedSheet)
         delete resolvedSheet.sheetStyle
 
         const title =
@@ -649,6 +686,11 @@ export class AltiumParser {
                 busEntries,
                 sheetEntries
             })
+        AltiumParser.#suppressRedundantSinglePinPowerNetNames(
+            pins,
+            nets,
+            anchoredTexts
+        )
         diagnostics.push(...netDiagnostics)
         const qa = SchematicQaReportBuilder.build({
             records: recordIndexAwareRecords,
@@ -741,6 +783,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 +962,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.