altium-toolkit 1.1.3 → 1.1.23

package/src/core/altium/AltiumPcbLibExporter.mjs

@@ -0,0 +1,101 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { OleCompoundDocumentWriter } from '../ole/OleCompoundDocumentWriter.mjs'
+import { AltiumLibraryRecordBuilder } from './AltiumLibraryRecordBuilder.mjs'
+import { SourceComponentBundleNormalizer } from './SourceComponentBundleNormalizer.mjs'
+
+/**
+ * Exports normalized bundles into a compact OLE-backed footprint library.
+ */
+export class AltiumPcbLibExporter {
+    /**
+     * Exports one or more component bundles as `.PcbLib` bytes.
+     * @param {object[] | object} bundles Component bundles.
+     * @returns {Uint8Array}
+     */
+    static export(bundles) {
+        const normalizedBundles =
+            AltiumPcbLibExporter.#normalizeBundles(bundles)
+        const streams = new Map()
+        const modelRows = AltiumPcbLibExporter.#collectModels(normalizedBundles)
+
+        streams.set(
+            'Library/Data',
+            AltiumLibraryRecordBuilder.buildPcbLibraryData(normalizedBundles)
+        )
+        streams.set(
+            'Library/ComponentParamsTOC/Data',
+            AltiumLibraryRecordBuilder.buildComponentParamsToc(
+                normalizedBundles
+            )
+        )
+        streams.set(
+            'SectionKeys',
+            AltiumLibraryRecordBuilder.buildSectionKeys(normalizedBundles)
+        )
+
+        for (const bundle of normalizedBundles) {
+            const storageName = AltiumLibraryRecordBuilder.sanitizeStorageName(
+                bundle.footprint.name
+            )
+            streams.set(
+                storageName + '/Header',
+                AltiumLibraryRecordBuilder.createCountHeader(0)
+            )
+            streams.set(
+                storageName + '/Parameters',
+                AltiumLibraryRecordBuilder.buildFootprintParameters(bundle)
+            )
+            streams.set(
+                storageName + '/Data',
+                AltiumLibraryRecordBuilder.buildFootprintData(bundle)
+            )
+            streams.set(
+                storageName + '/SourceRecord',
+                new TextEncoder().encode(
+                    AltiumLibraryRecordBuilder.buildPcbFootprintRecord(bundle)
+                )
+            )
+        }
+
+        if (modelRows.length) {
+            streams.set(
+                'Models/Data',
+                AltiumLibraryRecordBuilder.buildModelsData(modelRows)
+            )
+            modelRows.forEach((row, index) => {
+                streams.set('Models/' + index, row.model.bytes)
+            })
+        }
+
+        return OleCompoundDocumentWriter.write({ streams })
+    }
+
+    /**
+     * Collects model rows with deterministic generated ids.
+     * @param {object[]} bundles Normalized bundles.
+     * @returns {{ model: object, id: string, checksum: number }[]}
+     */
+    static #collectModels(bundles) {
+        return bundles.flatMap((bundle, bundleIndex) =>
+            bundle.models.map((model, modelIndex) => ({
+                model,
+                id: 'model-' + bundleIndex + '-' + modelIndex,
+                checksum: AltiumLibraryRecordBuilder.checksumBytes(model.bytes)
+            }))
+        )
+    }
+
+    /**
+     * Normalizes one or more bundles.
+     * @param {object[] | object} bundles Bundle input.
+     * @returns {object[]}
+     */
+    static #normalizeBundles(bundles) {
+        return (Array.isArray(bundles) ? bundles : [bundles]).map((bundle) =>
+            SourceComponentBundleNormalizer.normalize(bundle)
+        )
+    }
+}

package/src/core/altium/AltiumSchLibExporter.mjs

@@ -0,0 +1,57 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { OleCompoundDocumentWriter } from '../ole/OleCompoundDocumentWriter.mjs'
+import { AltiumLibraryRecordBuilder } from './AltiumLibraryRecordBuilder.mjs'
+import { SourceComponentBundleNormalizer } from './SourceComponentBundleNormalizer.mjs'
+
+/**
+ * Exports normalized bundles into a compact OLE-backed schematic library.
+ */
+export class AltiumSchLibExporter {
+    /**
+     * Exports one or more component bundles as `.SchLib` bytes.
+     * @param {object[] | object} bundles Component bundles.
+     * @returns {Uint8Array}
+     */
+    static export(bundles) {
+        const normalizedBundles =
+            AltiumSchLibExporter.#normalizeBundles(bundles)
+        const streams = new Map()
+        const libraryRecord = normalizedBundles
+            .map((bundle) =>
+                AltiumLibraryRecordBuilder.buildSchematicComponentRecord(bundle)
+            )
+            .join('\n')
+
+        streams.set('Library/Data', new TextEncoder().encode(libraryRecord))
+        for (const bundle of normalizedBundles) {
+            streams.set(
+                'Components/' +
+                    AltiumLibraryRecordBuilder.sanitizeStorageName(
+                        bundle.symbol.name
+                    ) +
+                    '/Data',
+                new TextEncoder().encode(
+                    AltiumLibraryRecordBuilder.buildSchematicComponentRecord(
+                        bundle
+                    )
+                )
+            )
+        }
+
+        return OleCompoundDocumentWriter.write({ streams })
+    }
+
+    /**
+     * Normalizes one or more bundles.
+     * @param {object[] | object} bundles Bundle input.
+     * @returns {object[]}
+     */
+    static #normalizeBundles(bundles) {
+        return (Array.isArray(bundles) ? bundles : [bundles]).map((bundle) =>
+            SourceComponentBundleNormalizer.normalize(bundle)
+        )
+    }
+}

package/src/core/altium/AltiumUnits.mjs

@@ -0,0 +1,205 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Provides deterministic conversions for common Altium length units.
+ */
+export class AltiumUnits {
+    static RAW_UNITS_PER_MIL = 10000
+
+    static MM_PER_MIL = 0.0254
+
+    static MIL_PER_INCH = 1000
+
+    /**
+     * Converts millimeters to mils.
+     * @param {number} value Length in millimeters.
+     * @returns {number}
+     */
+    static mmToMil(value) {
+        return AltiumUnits.#round(Number(value) / AltiumUnits.MM_PER_MIL)
+    }
+
+    /**
+     * Converts mils to millimeters.
+     * @param {number} value Length in mils.
+     * @returns {number}
+     */
+    static milToMm(value) {
+        return AltiumUnits.#round(Number(value) * AltiumUnits.MM_PER_MIL)
+    }
+
+    /**
+     * Converts inches to mils.
+     * @param {number} value Length in inches.
+     * @returns {number}
+     */
+    static inchToMil(value) {
+        return AltiumUnits.#round(Number(value) * AltiumUnits.MIL_PER_INCH)
+    }
+
+    /**
+     * Converts mils to inches.
+     * @param {number} value Length in mils.
+     * @returns {number}
+     */
+    static milToInch(value) {
+        return AltiumUnits.#round(Number(value) / AltiumUnits.MIL_PER_INCH)
+    }
+
+    /**
+     * Converts raw Altium coordinate units to mils.
+     * @param {number} value Raw coordinate units.
+     * @returns {number}
+     */
+    static rawToMil(value) {
+        return AltiumUnits.#round(Number(value) / AltiumUnits.RAW_UNITS_PER_MIL)
+    }
+
+    /**
+     * Converts mils to raw Altium coordinate units.
+     * @param {number} value Length in mils.
+     * @returns {number}
+     */
+    static milToRaw(value) {
+        return AltiumUnits.#round(Number(value) * AltiumUnits.RAW_UNITS_PER_MIL)
+    }
+
+    /**
+     * Parses one numeric or textual length into a deterministic unit bundle.
+     * @param {unknown} value Length value.
+     * @param {{ defaultUnit?: 'mil' | 'mm' | 'in' | 'raw' }} [options]
+     * @returns {{ value: number, unit: string, mil: number, mm: number, inch: number, raw: number } | null}
+     */
+    static parseLength(value, options = {}) {
+        const parsed = AltiumUnits.#parseNumericAndUnit(value, options)
+        if (!parsed) return null
+
+        const mil = AltiumUnits.#toMil(parsed.value, parsed.unit)
+        if (!Number.isFinite(mil)) return null
+
+        return {
+            value: AltiumUnits.#round(parsed.value),
+            unit: parsed.unit,
+            mil: AltiumUnits.#round(mil),
+            mm: AltiumUnits.milToMm(mil),
+            inch: AltiumUnits.milToInch(mil),
+            raw: AltiumUnits.milToRaw(mil)
+        }
+    }
+
+    /**
+     * Formats a mil value in the requested target unit.
+     * @param {number} value Length in mils.
+     * @param {'mil' | 'mm' | 'in' | 'raw'} [unit]
+     * @returns {string}
+     */
+    static formatMil(value, unit = 'mil') {
+        const mil = Number(value)
+        if (!Number.isFinite(mil)) return ''
+
+        const normalizedUnit = AltiumUnits.#normalizeUnit(unit)
+        if (normalizedUnit === 'mm') {
+            return AltiumUnits.#formatNumber(AltiumUnits.milToMm(mil)) + 'mm'
+        }
+        if (normalizedUnit === 'in') {
+            return AltiumUnits.#formatNumber(AltiumUnits.milToInch(mil)) + 'in'
+        }
+        if (normalizedUnit === 'raw') {
+            return AltiumUnits.#formatNumber(AltiumUnits.milToRaw(mil)) + 'raw'
+        }
+        return AltiumUnits.#formatNumber(mil) + 'mil'
+    }
+
+    /**
+     * Parses an input value into a number and normalized unit token.
+     * @param {unknown} value Length input.
+     * @param {{ defaultUnit?: string }} options Parse options.
+     * @returns {{ value: number, unit: 'mil' | 'mm' | 'in' | 'raw' } | null}
+     */
+    static #parseNumericAndUnit(value, options) {
+        const defaultUnit = AltiumUnits.#normalizeUnit(
+            options?.defaultUnit || 'mil'
+        )
+
+        if (typeof value === 'number') {
+            return Number.isFinite(value) ? { value, unit: defaultUnit } : null
+        }
+
+        const text = String(value ?? '').trim()
+        const match = text.match(
+            /^([-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[-+]?\d+)?)\s*([A-Za-z]*)$/u
+        )
+        if (!match) return null
+
+        const numericValue = Number(match[1])
+        if (!Number.isFinite(numericValue)) return null
+
+        return {
+            value: numericValue,
+            unit: AltiumUnits.#normalizeUnit(match[2] || defaultUnit)
+        }
+    }
+
+    /**
+     * Converts one normalized length value to mils.
+     * @param {number} value Numeric length.
+     * @param {'mil' | 'mm' | 'in' | 'raw'} unit Length unit.
+     * @returns {number}
+     */
+    static #toMil(value, unit) {
+        if (unit === 'mm') return AltiumUnits.mmToMil(value)
+        if (unit === 'in') return AltiumUnits.inchToMil(value)
+        if (unit === 'raw') return AltiumUnits.rawToMil(value)
+        return Number(value)
+    }
+
+    /**
+     * Normalizes one unit label.
+     * @param {unknown} unit Unit label.
+     * @returns {'mil' | 'mm' | 'in' | 'raw'}
+     */
+    static #normalizeUnit(unit) {
+        const normalized = String(unit || '')
+            .trim()
+            .toLowerCase()
+        if (
+            normalized === 'mm' ||
+            normalized === 'millimeter' ||
+            normalized === 'millimeters'
+        ) {
+            return 'mm'
+        }
+        if (
+            normalized === 'in' ||
+            normalized === 'inch' ||
+            normalized === 'inches'
+        ) {
+            return 'in'
+        }
+        if (normalized === 'raw') {
+            return 'raw'
+        }
+        return 'mil'
+    }
+
+    /**
+     * Formats a number without unstable floating-point tails.
+     * @param {number} value Numeric value.
+     * @returns {string}
+     */
+    static #formatNumber(value) {
+        return String(AltiumUnits.#round(value))
+    }
+
+    /**
+     * Rounds a numeric value to stable JSON/report precision.
+     * @param {number} value Numeric value.
+     * @returns {number}
+     */
+    static #round(value) {
+        const numeric = Number(value)
+        return Number.isFinite(numeric) ? Number(numeric.toFixed(9)) : numeric
+    }
+}

package/src/core/altium/AsciiRecordParser.mjs

@@ -63,6 +63,15 @@ export class AsciiRecordParser {
         return records
     }
 
+    /**
+     * Parses one pipe-delimited record string into a field object.
+     * @param {string} raw Raw record text.
+     * @returns {{ raw: string, fields: Record<string, string | string[]> }}
+     */
+    static parseRecord(raw) {
+        return AsciiRecordParser.#parseRecord(raw)
+    }
+
     /**
      * Returns true when a printable run looks like an Altium record block.
      * @param {string} candidate
@@ -146,17 +155,11 @@ export class AsciiRecordParser {
             const rawKey = AsciiRecordParser.#trimAscii(
                 segment.slice(0, separatorIndex)
             )
-            const value = PrintableTextDecoder.decodeBytes(
-                AsciiRecordParser.#binaryStringToBytes(
-                    AsciiRecordParser.#trimAscii(
-                        segment.slice(separatorIndex + 1)
-                    )
-                ),
-                {
-                    encoding: rawKey.startsWith('%UTF8%') ? 'utf-8' : undefined
-                }
-            )
             const isUtf8Field = rawKey.startsWith('%UTF8%')
+            const value = AsciiRecordParser.#decodeFieldValue(
+                AsciiRecordParser.#trimAscii(segment.slice(separatorIndex + 1)),
+                isUtf8Field ? 'utf-8' : ''
+            )
             const key = rawKey.replace(/^%UTF8%/, '')
             if (!key) continue
 
@@ -228,13 +231,51 @@ export class AsciiRecordParser {
         return normalizedKeyIndex
     }
 
+    /**
+     * Decodes one pipe-delimited field value from the byte-preserving run
+     * string. Plain ASCII is already decoded by construction and can avoid
+     * byte-array allocation plus TextDecoder fallback probing.
+     * @param {string} value Byte-preserving field value.
+     * @param {string} preferredEncoding Optional preferred decoder encoding.
+     * @returns {string}
+     */
+    static #decodeFieldValue(value, preferredEncoding) {
+        if (!AsciiRecordParser.#hasExtendedByte(value)) {
+            return value
+        }
+
+        return PrintableTextDecoder.decodeBytes(
+            AsciiRecordParser.#binaryStringToBytes(value),
+            { encoding: preferredEncoding || undefined }
+        )
+    }
+
     /**
      * Converts one binary string into bytes without altering byte values.
      * @param {string} value
      * @returns {Uint8Array}
      */
     static #binaryStringToBytes(value) {
-        return Uint8Array.from(value, (character) => character.charCodeAt(0))
+        const bytes = new Uint8Array(value.length)
+
+        for (let index = 0; index < value.length; index += 1) {
+            bytes[index] = value.charCodeAt(index) & 0xff
+        }
+
+        return bytes
+    }
+
+    /**
+     * Returns true when the byte-preserving string contains non-ASCII bytes.
+     * @param {string} value Field value.
+     * @returns {boolean}
+     */
+    static #hasExtendedByte(value) {
+        for (let index = 0; index < value.length; index += 1) {
+            if (value.charCodeAt(index) > 0x7f) return true
+        }
+
+        return false
     }
 
     /**