altium-toolkit 1.0.7 → 1.0.9

package/src/core/altium/PcbCustomPadShapeParser.mjs

@@ -0,0 +1,244 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbSidecarRecordParser } from './PcbSidecarRecordParser.mjs'
+
+/**
+ * Decodes custom pad shape sidecars and links pads to authored geometry.
+ */
+export class PcbCustomPadShapeParser {
+    static #SOURCE_STREAM = 'CustomShapes/Data'
+
+    /**
+     * Parses custom pad shape sidecar records.
+     * @param {Uint8Array | ArrayBuffer | undefined} dataBytes
+     * @param {string} [sourceStream]
+     * @returns {{ entries: object[], byPrimitiveIndex: Record<string, object[]> }}
+     */
+    static parse(
+        dataBytes,
+        sourceStream = PcbCustomPadShapeParser.#SOURCE_STREAM
+    ) {
+        const entries = PcbSidecarRecordParser.parseLengthPrefixedRecords(
+            dataBytes,
+            sourceStream
+        )
+            .map((record) => PcbCustomPadShapeParser.#normalizeRecord(record))
+            .filter(Boolean)
+        const byPrimitiveIndex = {}
+
+        for (const entry of entries) {
+            const key = String(entry.primitiveIndex)
+            byPrimitiveIndex[key] = byPrimitiveIndex[key] || []
+            byPrimitiveIndex[key].push(entry)
+        }
+
+        return {
+            entries,
+            byPrimitiveIndex
+        }
+    }
+
+    /**
+     * Links custom shape entries to pad records in place.
+     * @param {object[]} pads
+     * @param {{ byPrimitiveIndex?: Record<string, object[]> }} customShapes
+     * @param {{ regions?: object[], shapeBasedRegions?: object[], arcs?: object[], tracks?: object[], fills?: object[] }} geometry
+     */
+    static attachToPads(pads, customShapes, geometry = {}) {
+        if (!Array.isArray(pads) || !customShapes?.byPrimitiveIndex) {
+            return
+        }
+
+        for (let index = 0; index < pads.length; index += 1) {
+            const entries = customShapes.byPrimitiveIndex[String(index)] || []
+            if (!entries.length) {
+                continue
+            }
+
+            pads[index].customShape =
+                PcbCustomPadShapeParser.#buildPadCustomShape(
+                    index,
+                    entries,
+                    geometry
+                )
+        }
+    }
+
+    /**
+     * Normalizes one custom-shape sidecar record.
+     * @param {{ fields: Record<string, string>, sourceStream: string }} record
+     * @returns {object | null}
+     */
+    static #normalizeRecord(record) {
+        const primitiveIndex = PcbSidecarRecordParser.parseInteger(
+            PcbSidecarRecordParser.firstField(record.fields, [
+                'PRIMITIVEINDEX',
+                'PADINDEX',
+                'ANCHORINDEX'
+            ])
+        )
+
+        if (primitiveIndex === null) {
+            return null
+        }
+
+        return {
+            primitiveIndex,
+            layer: PcbSidecarRecordParser.firstField(record.fields, ['LAYER']),
+            layerId: PcbSidecarRecordParser.parseInteger(
+                PcbSidecarRecordParser.firstField(record.fields, [
+                    'LAYERID',
+                    'LAYERINDEX'
+                ])
+            ),
+            pasteMask: PcbSidecarRecordParser.parseBoolean(
+                PcbSidecarRecordParser.firstField(record.fields, [
+                    'PASTEMASK',
+                    'HASPASTEMASK'
+                ])
+            ),
+            solderMask: PcbSidecarRecordParser.parseBoolean(
+                PcbSidecarRecordParser.firstField(record.fields, [
+                    'SOLDERMASK',
+                    'HASSOLDERMASK'
+                ])
+            ),
+            regionIndexes: PcbCustomPadShapeParser.#parseIndexList(
+                record.fields,
+                ['REGIONINDEX', 'REGIONINDEXES']
+            ),
+            shapeRegionIndexes: PcbCustomPadShapeParser.#parseIndexList(
+                record.fields,
+                ['SHAPEREGIONINDEX', 'SHAPEREGIONINDEXES']
+            ),
+            arcIndexes: PcbCustomPadShapeParser.#parseIndexList(record.fields, [
+                'ARCINDEX',
+                'ARCINDEXES'
+            ]),
+            trackIndexes: PcbCustomPadShapeParser.#parseIndexList(
+                record.fields,
+                ['TRACKINDEX', 'TRACKINDEXES']
+            ),
+            fillIndexes: PcbCustomPadShapeParser.#parseIndexList(
+                record.fields,
+                ['FILLINDEX', 'FILLINDEXES']
+            ),
+            sourceStream: record.sourceStream,
+            fields: record.fields
+        }
+    }
+
+    /**
+     * Builds the custom-shape object attached to a pad.
+     * @param {number} primitiveIndex
+     * @param {object[]} entries
+     * @param {object} geometry
+     * @returns {object}
+     */
+    static #buildPadCustomShape(primitiveIndex, entries, geometry) {
+        return {
+            primitiveIndex,
+            sourceStream: entries[0]?.sourceStream || '',
+            layers: entries.map((entry) =>
+                PcbCustomPadShapeParser.#buildLayerShape(entry, geometry)
+            )
+        }
+    }
+
+    /**
+     * Resolves one layer-specific shape entry.
+     * @param {object} entry
+     * @param {object} geometry
+     * @returns {object}
+     */
+    static #buildLayerShape(entry, geometry) {
+        return {
+            layer: entry.layer,
+            layerId: entry.layerId,
+            pasteMask: entry.pasteMask,
+            solderMask: entry.solderMask,
+            regions: PcbCustomPadShapeParser.#lookupMany(
+                geometry.regions || [],
+                entry.regionIndexes
+            ),
+            arcs: PcbCustomPadShapeParser.#lookupMany(
+                geometry.arcs || [],
+                entry.arcIndexes
+            ),
+            tracks: PcbCustomPadShapeParser.#lookupMany(
+                geometry.tracks || [],
+                entry.trackIndexes
+            ),
+            fills: PcbCustomPadShapeParser.#lookupMany(
+                geometry.fills || [],
+                entry.fillIndexes
+            ),
+            ...(entry.shapeRegionIndexes.length
+                ? {
+                      shapeRegions: PcbCustomPadShapeParser.#lookupMany(
+                          geometry.shapeBasedRegions || [],
+                          entry.shapeRegionIndexes
+                      )
+                  }
+                : {})
+        }
+    }
+
+    /**
+     * Resolves several primitive indexes into object references.
+     * @param {object[]} collection
+     * @param {number[]} indexes
+     * @returns {object[]}
+     */
+    static #lookupMany(collection, indexes) {
+        return indexes
+            .map((index) => collection[index])
+            .filter((value) => value && typeof value === 'object')
+    }
+
+    /**
+     * Parses one or more integer indexes from scalar or numbered fields.
+     * @param {Record<string, string>} fields
+     * @param {string[]} baseKeys
+     * @returns {number[]}
+     */
+    static #parseIndexList(fields, baseKeys) {
+        const indexes = []
+
+        for (const baseKey of baseKeys) {
+            const directValue = fields[baseKey]
+            if (directValue) {
+                indexes.push(
+                    ...PcbCustomPadShapeParser.#splitIndexes(directValue)
+                )
+            }
+
+            for (const [key, value] of Object.entries(fields)) {
+                if (!key.startsWith(baseKey)) {
+                    continue
+                }
+                if (key === baseKey) {
+                    continue
+                }
+
+                indexes.push(...PcbCustomPadShapeParser.#splitIndexes(value))
+            }
+        }
+
+        return [...new Set(indexes)]
+    }
+
+    /**
+     * Parses a comma/semicolon-delimited index field.
+     * @param {string} value
+     * @returns {number[]}
+     */
+    static #splitIndexes(value) {
+        return String(value || '')
+            .split(/[;,\s]+/u)
+            .map((part) => PcbSidecarRecordParser.parseInteger(part))
+            .filter(Number.isInteger)
+    }
+}

package/src/core/altium/PcbDefaultsParser.mjs

@@ -0,0 +1,171 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+const { getField, parseNumericField, toColor } = ParserUtils
+
+/**
+ * Builds read-only PCB and footprint-library default metadata.
+ */
+export class PcbDefaultsParser {
+    static SCHEMA_ID = 'altium-toolkit.pcb.defaults.a1'
+
+    /**
+     * Parses a defaults read model from one field bag.
+     * @param {Record<string, string | string[]> | undefined} fields Source fields.
+     * @param {string} source Defaults source label.
+     * @returns {object | null}
+     */
+    static parse(fields, source) {
+        const board = PcbDefaultsParser.#stripEmpty({
+            defaultFontName: PcbDefaultsParser.#firstField(fields, [
+                'DEFAULTFONTNAME',
+                'FONTNAME',
+                'TEXTFONTNAME'
+            ]),
+            units: PcbDefaultsParser.#firstField(fields, [
+                'UNITS',
+                'BOARDUNITS',
+                'MEASUREMENTUNITS'
+            ])
+        })
+        const primitiveStyles = PcbDefaultsParser.#stripEmpty({
+            trackWidthMil: PcbDefaultsParser.#firstNumber(fields, [
+                'TRACKWIDTH',
+                'DEFAULTTRACKWIDTH',
+                'ROUTINGWIDTH'
+            ]),
+            viaHoleSizeMil: PcbDefaultsParser.#firstNumber(fields, [
+                'VIAHOLESIZE',
+                'VIAHOLE',
+                'DEFAULTVIAHOLESIZE'
+            ]),
+            viaDiameterMil: PcbDefaultsParser.#firstNumber(fields, [
+                'VIADIAMETER',
+                'VIASIZE',
+                'DEFAULTVIADIAMETER'
+            ])
+        })
+        const maskPaste = PcbDefaultsParser.#stripEmpty({
+            solder: PcbDefaultsParser.#stripEmpty({
+                expansionMil: PcbDefaultsParser.#firstNumber(fields, [
+                    'SOLDERMASKEXPANSION',
+                    'SOLDERMASKEXPANSION_DEFAULT',
+                    'MASKEXPANSION'
+                ])
+            }),
+            paste: PcbDefaultsParser.#stripEmpty({
+                expansionMil: PcbDefaultsParser.#firstNumber(fields, [
+                    'PASTEMASKEXPANSION',
+                    'PASTEMASKEXPANSION_DEFAULT',
+                    'PASTEEXPANSION'
+                ])
+            })
+        })
+        const clearances = PcbDefaultsParser.#stripEmpty({
+            defaultClearanceMil: PcbDefaultsParser.#firstNumber(fields, [
+                'CLEARANCE',
+                'DEFAULTCLEARANCE',
+                'MINCLEARANCE'
+            ])
+        })
+        const colors = PcbDefaultsParser.#stripEmpty({
+            defaultColor: PcbDefaultsParser.#firstColor(fields, [
+                'DEFAULTCOLOR',
+                'COLOR'
+            ]),
+            solderMaskTopColor: PcbDefaultsParser.#firstColor(fields, [
+                'SOLDERMASKTOPCOLOR',
+                'TOPSOLDERMASKCOLOR',
+                'CFG3D.TOPSOLDERMASKCOLOR'
+            ]),
+            solderMaskBottomColor: PcbDefaultsParser.#firstColor(fields, [
+                'SOLDERMASKBOTTOMCOLOR',
+                'BOTTOMSOLDERMASKCOLOR',
+                'CFG3D.BOTTOMSOLDERMASKCOLOR'
+            ])
+        })
+        const defaults = PcbDefaultsParser.#stripEmpty({
+            schema: PcbDefaultsParser.SCHEMA_ID,
+            source,
+            board,
+            primitiveStyles,
+            maskPaste,
+            clearances,
+            colors
+        })
+
+        return Object.keys(defaults).length > 2 ? defaults : null
+    }
+
+    /**
+     * Returns the first populated field value.
+     * @param {Record<string, string | string[]> | undefined} fields Source fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {string}
+     */
+    static #firstField(fields, keys) {
+        for (const key of keys) {
+            const value = getField(fields, key)
+            if (value) return value
+        }
+
+        return ''
+    }
+
+    /**
+     * Returns the first parsed numeric field.
+     * @param {Record<string, string | string[]> | undefined} fields Source fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {number | undefined}
+     */
+    static #firstNumber(fields, keys) {
+        for (const key of keys) {
+            const value = parseNumericField(fields, key)
+            if (value !== null) return value
+        }
+
+        return undefined
+    }
+
+    /**
+     * Returns the first parsed color field.
+     * @param {Record<string, string | string[]> | undefined} fields Source fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {string}
+     */
+    static #firstColor(fields, keys) {
+        for (const key of keys) {
+            if (getField(fields, key)) return toColor(fields[key], '')
+        }
+
+        return ''
+    }
+
+    /**
+     * Removes empty properties from one object.
+     * @param {Record<string, unknown>} object Source object.
+     * @returns {Record<string, unknown>}
+     */
+    static #stripEmpty(object) {
+        const result = {}
+
+        for (const [key, value] of Object.entries(object || {})) {
+            if (value === undefined || value === null || value === '') {
+                continue
+            }
+            if (
+                typeof value === 'object' &&
+                !Array.isArray(value) &&
+                Object.keys(value).length === 0
+            ) {
+                continue
+            }
+            result[key] = value
+        }
+
+        return result
+    }
+}

package/src/core/altium/PcbDimensionParser.mjs

@@ -0,0 +1,229 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+const { getField, parseNumericField } = ParserUtils
+
+/**
+ * Normalizes read-only PCB dimension records.
+ */
+export class PcbDimensionParser {
+    /**
+     * Parses Dimensions6/Data records into public dimension objects.
+     * @param {{ fields: Record<string, string | string[]>, sourceStream?: string }[]} records
+     * @returns {object[]}
+     */
+    static parse(records) {
+        return (records || [])
+            .filter((record) => record.sourceStream === 'Dimensions6/Data')
+            .map((record, index) =>
+                PcbDimensionParser.#normalizeDimension(record.fields, index)
+            )
+            .filter(Boolean)
+    }
+
+    /**
+     * Normalizes one dimension record.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @param {number} index Source record index within the dimensions stream.
+     * @returns {object | null}
+     */
+    static #normalizeDimension(fields, index) {
+        const kindCode = PcbDimensionParser.#firstStringField(fields, [
+            'DIMENSIONTYPE',
+            'DIMENSIONKIND',
+            'KIND',
+            'TYPE'
+        ])
+        const references = PcbDimensionParser.#parseReferences(fields)
+        const textLocation = PcbDimensionParser.#parsePoint(fields, [
+            'TEXTLOCATION',
+            'TEXT',
+            'LOCATION'
+        ])
+
+        if (!kindCode && !references.length && !getField(fields, 'TEXT')) {
+            return null
+        }
+
+        return {
+            dimensionIndex: index,
+            kind: PcbDimensionParser.#normalizeKind(kindCode),
+            kindCode,
+            name: getField(fields, 'NAME'),
+            layer: getField(fields, 'LAYER'),
+            text: getField(fields, 'TEXT'),
+            prefix: getField(fields, 'PREFIX'),
+            suffix: PcbDimensionParser.#rawStringField(fields, 'SUFFIX'),
+            precision: PcbDimensionParser.#nullableNumber(
+                parseNumericField(fields, 'PRECISION')
+            ),
+            measuredValue: PcbDimensionParser.#nullableNumber(
+                PcbDimensionParser.#firstNumericField(fields, [
+                    'MEASUREDVALUE',
+                    'MEASURED',
+                    'VALUE'
+                ])
+            ),
+            angleValue: PcbDimensionParser.#nullableNumber(
+                PcbDimensionParser.#firstNumericField(fields, [
+                    'ANGLEVALUE',
+                    'ANGLE',
+                    'MEASUREDANGLE'
+                ])
+            ),
+            unit: PcbDimensionParser.#resolveUnit(fields),
+            references,
+            textLocation,
+            raw: { ...fields }
+        }
+    }
+
+    /**
+     * Parses reference points from indexed field names.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @returns {{ index: number, x: number, y: number }[]}
+     */
+    static #parseReferences(fields) {
+        const references = []
+
+        for (let index = 0; index < 16; index += 1) {
+            const point = PcbDimensionParser.#parsePoint(fields, [
+                'REFERENCE' + index,
+                'REF' + index,
+                'POINT' + index
+            ])
+            if (!point) {
+                continue
+            }
+            references.push({ index, ...point })
+        }
+
+        return references
+    }
+
+    /**
+     * Parses a point from common field prefixes.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @param {string[]} prefixes Candidate field prefixes.
+     * @returns {{ x: number, y: number } | null}
+     */
+    static #parsePoint(fields, prefixes) {
+        for (const prefix of prefixes) {
+            const x = PcbDimensionParser.#firstNumericField(fields, [
+                prefix + '_X',
+                prefix + '.X',
+                prefix + 'X'
+            ])
+            const y = PcbDimensionParser.#firstNumericField(fields, [
+                prefix + '_Y',
+                prefix + '.Y',
+                prefix + 'Y'
+            ])
+
+            if (x !== null && y !== null) {
+                return { x, y }
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Reads the first non-empty string field.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {string}
+     */
+    static #firstStringField(fields, keys) {
+        for (const key of keys) {
+            const value = getField(fields, key)
+            if (value) {
+                return value
+            }
+        }
+
+        return ''
+    }
+
+    /**
+     * Reads the first finite numeric field.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {number | null}
+     */
+    static #firstNumericField(fields, keys) {
+        for (const key of keys) {
+            const value = parseNumericField(fields, key)
+            if (value !== null) {
+                return value
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Normalizes a dimension kind code.
+     * @param {string} kindCode Raw dimension kind.
+     * @returns {string}
+     */
+    static #normalizeKind(kindCode) {
+        const normalized = String(kindCode || '').toLowerCase()
+        if (/ang/u.test(normalized)) return 'angular'
+        if (/radial|radius/u.test(normalized)) return 'radial'
+        if (/datum/u.test(normalized)) return 'datum'
+        if (/baseline/u.test(normalized)) return 'baseline'
+        if (/ordinate/u.test(normalized)) return 'ordinate'
+        return 'linear'
+    }
+
+    /**
+     * Returns a number when finite, otherwise null.
+     * @param {number | null} value Numeric candidate.
+     * @returns {number | null}
+     */
+    static #nullableNumber(value) {
+        return Number.isFinite(value) ? value : null
+    }
+
+    /**
+     * Resolves a display unit from explicit or value-bearing fields.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @returns {string}
+     */
+    static #resolveUnit(fields) {
+        const explicit = PcbDimensionParser.#firstStringField(fields, [
+            'UNIT',
+            'UNITS'
+        ])
+        if (explicit) {
+            return explicit
+        }
+
+        const suffix = getField(fields, 'SUFFIX').trim()
+        if (suffix) {
+            return suffix
+        }
+
+        const measured = getField(fields, 'MEASUREDVALUE')
+        const match = measured.match(/[a-zA-Z]+$/u)
+        return match ? match[0] : ''
+    }
+
+    /**
+     * Reads one field without trimming display-significant whitespace.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @param {string} key Field key.
+     * @returns {string}
+     */
+    static #rawStringField(fields, key) {
+        const value = fields?.[key]
+        if (Array.isArray(value)) {
+            return String(value.findLast((entry) => entry !== '') || '')
+        }
+        return String(value || '')
+    }
+}