altium-toolkit 1.0.8 → 1.0.10

package/src/core/altium/PcbPickPlacePositionResolver.mjs

@@ -0,0 +1,224 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+const DEFAULT_POSITION_MODE = 'altium-pick-place'
+const COMPONENT_ORIGIN_MODE = 'component-origin'
+
+/**
+ * Resolves PCB pick-and-place coordinates from component origins and owned pad
+ * anchors.
+ */
+export class PcbPickPlacePositionResolver {
+    /**
+     * Builds the public PnP model with the default mode and alternatives.
+     * @param {{ componentIndex: number, designator: string, pattern: string, layer: string, rotation: number, x: number, y: number }[]} components
+     * @param {{ componentIndex: number, pads?: { x?: number, y?: number }[] }[]} componentPrimitiveGroups
+     * @param {{ sourceComponents?: { componentIndex: number, rotation?: number }[] }} [options] Resolver options.
+     * @returns {{ units: object, positionMode: string, entries: object[], modes: { componentOrigin: { units: object, positionMode: string, entries: object[] } } }}
+     */
+    static buildModel(components, componentPrimitiveGroups, options = {}) {
+        const units = {
+            coordinate: 'mil',
+            angle: 'deg'
+        }
+
+        return {
+            units,
+            positionMode: DEFAULT_POSITION_MODE,
+            entries: PcbPickPlacePositionResolver.buildEntries(
+                components,
+                componentPrimitiveGroups,
+                DEFAULT_POSITION_MODE,
+                options
+            ),
+            modes: {
+                componentOrigin: {
+                    units,
+                    positionMode: COMPONENT_ORIGIN_MODE,
+                    entries: PcbPickPlacePositionResolver.buildEntries(
+                        components,
+                        componentPrimitiveGroups,
+                        COMPONENT_ORIGIN_MODE,
+                        options
+                    )
+                }
+            }
+        }
+    }
+
+    /**
+     * Builds PnP entries for one coordinate mode.
+     * @param {{ componentIndex: number, designator: string, pattern: string, layer: string, rotation: number, x: number, y: number }[]} components
+     * @param {{ componentIndex: number, pads?: { x?: number, y?: number }[] }[]} componentPrimitiveGroups
+     * @param {'altium-pick-place' | 'component-origin' | string} mode
+     * @param {{ sourceComponents?: { componentIndex: number, rotation?: number }[] }} [options] Resolver options.
+     * @returns {{ designator: string, pattern: string, layer: string, rotation: number, x: number, y: number, componentOriginX: number, componentOriginY: number, padAnchorCount: number, positionSource: string }[]}
+     */
+    static buildEntries(
+        components,
+        componentPrimitiveGroups,
+        mode,
+        options = {}
+    ) {
+        const groupsByIndex = PcbPickPlacePositionResolver.#buildGroupLookup(
+            componentPrimitiveGroups
+        )
+        const sourceComponentsByIndex =
+            PcbPickPlacePositionResolver.#buildGroupLookup(
+                options.sourceComponents || []
+            )
+        const normalizedMode =
+            PcbPickPlacePositionResolver.normalizePositionMode(mode)
+
+        return (components || []).map((component) =>
+            PcbPickPlacePositionResolver.#buildEntry(
+                component,
+                groupsByIndex.get(Number(component.componentIndex)),
+                normalizedMode,
+                sourceComponentsByIndex.get(Number(component.componentIndex))
+            )
+        )
+    }
+
+    /**
+     * Normalizes one public PnP coordinate-mode token.
+     * @param {string | null | undefined} mode
+     * @returns {'altium-pick-place' | 'component-origin'}
+     */
+    static normalizePositionMode(mode) {
+        const normalized = String(mode || DEFAULT_POSITION_MODE)
+            .trim()
+            .toLowerCase()
+            .replace(/_/gu, '-')
+
+        if (
+            normalized === '' ||
+            normalized === 'altium' ||
+            normalized === 'altium-pick-place' ||
+            normalized === 'pick-place'
+        ) {
+            return DEFAULT_POSITION_MODE
+        }
+
+        if (
+            normalized === 'component-origin' ||
+            normalized === 'origin' ||
+            normalized === 'part-origin' ||
+            normalized === 'footprint-origin'
+        ) {
+            return COMPONENT_ORIGIN_MODE
+        }
+
+        return DEFAULT_POSITION_MODE
+    }
+
+    /**
+     * Builds one PnP entry.
+     * @param {{ designator: string, pattern: string, layer: string, rotation: number, x: number, y: number }} component
+     * @param {{ pads?: { x?: number, y?: number }[] } | undefined} group
+     * @param {'altium-pick-place' | 'component-origin'} mode
+     * @param {{ rotation?: number } | undefined} sourceComponent Source component row.
+     * @returns {{ designator: string, pattern: string, layer: string, rotation: number, x: number, y: number, componentOriginX: number, componentOriginY: number, padAnchorCount: number, positionSource: string }}
+     */
+    static #buildEntry(component, group, mode, sourceComponent) {
+        const componentOriginX = Number(component.x || 0)
+        const componentOriginY = Number(component.y || 0)
+        const rotation = Number.isFinite(Number(sourceComponent?.rotation))
+            ? Number(sourceComponent.rotation)
+            : Number(component.rotation || 0)
+        const padAnchors = PcbPickPlacePositionResolver.#padAnchors(group?.pads)
+        const padCenter =
+            mode === DEFAULT_POSITION_MODE
+                ? PcbPickPlacePositionResolver.#padAnchorBoundsCenter(
+                      padAnchors
+                  )
+                : null
+        const position = padCenter || {
+            x: componentOriginX,
+            y: componentOriginY,
+            source: 'component-origin'
+        }
+
+        return {
+            designator: component.designator || '',
+            pattern: component.pattern || '',
+            layer: component.layer || '',
+            rotation: PcbPickPlacePositionResolver.#roundCoordinate(rotation),
+            x: PcbPickPlacePositionResolver.#roundCoordinate(position.x),
+            y: PcbPickPlacePositionResolver.#roundCoordinate(position.y),
+            componentOriginX:
+                PcbPickPlacePositionResolver.#roundCoordinate(componentOriginX),
+            componentOriginY:
+                PcbPickPlacePositionResolver.#roundCoordinate(componentOriginY),
+            padAnchorCount: padAnchors.length,
+            positionSource:
+                mode === COMPONENT_ORIGIN_MODE
+                    ? 'component-origin'
+                    : position.source
+        }
+    }
+
+    /**
+     * Builds a lookup of component primitive groups by native component index.
+     * @param {{ componentIndex: number }[]} componentPrimitiveGroups
+     * @returns {Map<number, object>}
+     */
+    static #buildGroupLookup(componentPrimitiveGroups) {
+        const groupsByIndex = new Map()
+
+        for (const group of componentPrimitiveGroups || []) {
+            const componentIndex = Number(group?.componentIndex)
+            if (Number.isInteger(componentIndex)) {
+                groupsByIndex.set(componentIndex, group)
+            }
+        }
+
+        return groupsByIndex
+    }
+
+    /**
+     * Returns pad anchor points with finite coordinates.
+     * @param {{ x?: number, y?: number }[] | undefined} pads
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #padAnchors(pads) {
+        return (pads || [])
+            .map((pad) => ({
+                x: Number(pad?.x),
+                y: Number(pad?.y)
+            }))
+            .filter(
+                (point) => Number.isFinite(point.x) && Number.isFinite(point.y)
+            )
+    }
+
+    /**
+     * Resolves the center of the owned pad-anchor bounds.
+     * @param {{ x: number, y: number }[]} padAnchors
+     * @returns {{ x: number, y: number, source: string } | null}
+     */
+    static #padAnchorBoundsCenter(padAnchors) {
+        if (!padAnchors.length) {
+            return null
+        }
+
+        const xs = padAnchors.map((point) => point.x)
+        const ys = padAnchors.map((point) => point.y)
+
+        return {
+            x: (Math.min(...xs) + Math.max(...xs)) / 2,
+            y: (Math.min(...ys) + Math.max(...ys)) / 2,
+            source: 'pad-anchor-bounds'
+        }
+    }
+
+    /**
+     * Rounds one PnP coordinate for deterministic JSON output.
+     * @param {number} value
+     * @returns {number}
+     */
+    static #roundCoordinate(value) {
+        return Number(Number(value || 0).toFixed(6))
+    }
+}

package/src/core/altium/PcbPrimitiveParameterParser.mjs

@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+import { PrintableTextDecoder } from './PrintableTextDecoder.mjs'
+
 /**
  * Decodes Altium PrimitiveParameters/Data sidecar records.
  */
@@ -153,8 +155,7 @@ export class PcbPrimitiveParameterParser {
      * @returns {Record<string, string>}
      */
     static #parseRecordFields(bytes) {
-        const text = new TextDecoder()
-            .decode(bytes)
+        const text = PrintableTextDecoder.decodeBytes(bytes)
             .replace(/\u0000/gu, '')
             .replace(/\r\n?/gu, '\n')
             .trim()

package/src/core/altium/PcbRawRecordRegistry.mjs

@@ -365,82 +365,149 @@ export class PcbRawRecordRegistry {
     static #sliceSubrecordListRecords(descriptor, headerBytes, dataBytes) {
         const count = PcbRawRecordRegistry.#readRecordCount(headerBytes)
         const bytes = PcbRawRecordRegistry.#toUint8Array(dataBytes)
-        const records = []
-        let offset = 0
+        const boundaries = PcbRawRecordRegistry.#findSubrecordListBoundaries(
+            bytes,
+            0,
+            descriptor,
+            count
+        )
 
-        for (let index = 0; index < count; index += 1) {
-            const remainingCount = count - index - 1
-            const record = PcbRawRecordRegistry.#readSubrecordListRecordAt(
+        if (!boundaries) {
+            return []
+        }
+
+        return boundaries.map((boundary, index) => {
+            const endOffset = boundaries[index + 1]?.offset ?? bytes.byteLength
+
+            return {
+                recordBytes: bytes.slice(boundary.offset, endOffset),
+                offset: boundary.offset,
+                byteLength: endOffset - boundary.offset,
+                payloadByteLength: null,
+                encoding: 'subrecord-list',
+                objectId: descriptor.typeId,
+                recordIndex: index
+            }
+        })
+    }
+
+    /**
+     * Finds all subrecord-list record boundaries without recursive validation.
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @param {object} descriptor
+     * @param {number} count
+     * @returns {{ offset: number, minimumEnd: number }[] | null}
+     */
+    static #findSubrecordListBoundaries(bytes, offset, descriptor, count) {
+        if (!count) {
+            return []
+        }
+
+        const firstMinimumEnd =
+            PcbRawRecordRegistry.#readMinimumSubrecordListEnd(
                 bytes,
                 offset,
-                descriptor,
-                remainingCount
+                descriptor
             )
 
-            if (!record) {
-                return []
+        if (!firstMinimumEnd) {
+            return null
+        }
+
+        const boundaries = [{ offset, minimumEnd: firstMinimumEnd }]
+        const alternativeScanOffsets = [null]
+        let depth = 1
+        let scanOffset = firstMinimumEnd
+
+        while (depth < count) {
+            const candidate =
+                PcbRawRecordRegistry.#findNextSubrecordListCandidate(
+                    bytes,
+                    scanOffset,
+                    descriptor
+                )
+
+            if (!candidate) {
+                let foundAlternative = false
+
+                while (depth > 1 && !foundAlternative) {
+                    depth -= 1
+                    boundaries.length = depth
+
+                    const alternativeOffset = alternativeScanOffsets[depth]
+                    alternativeScanOffsets.length = depth
+
+                    if (alternativeOffset !== null) {
+                        scanOffset = alternativeOffset
+                        foundAlternative = true
+                    }
+                }
+
+                if (!foundAlternative) {
+                    return null
+                }
+
+                continue
             }
 
-            records.push({ ...record, recordIndex: index })
-            offset += record.byteLength
+            boundaries[depth] = {
+                offset: candidate.offset,
+                minimumEnd: candidate.minimumEnd
+            }
+            alternativeScanOffsets[depth] = candidate.alternativeOffset
+            depth += 1
+            scanOffset = candidate.minimumEnd
         }
 
-        return records
+        return boundaries
     }
 
     /**
-     * Reads one subrecord-list primitive record at an offset.
+     * Finds the next plausible subrecord-list record boundary.
      * @param {Uint8Array} bytes
      * @param {number} offset
      * @param {object} descriptor
-     * @param {number} remainingCount
-     * @returns {object | null}
+     * @returns {{ offset: number, minimumEnd: number, alternativeOffset: number | null } | null}
      */
-    static #readSubrecordListRecordAt(
-        bytes,
-        offset,
-        descriptor,
-        remainingCount
-    ) {
-        if (
-            offset + 1 > bytes.byteLength ||
-            bytes[offset] !== descriptor.typeId
-        ) {
-            return null
-        }
+    static #findNextSubrecordListCandidate(bytes, offset, descriptor) {
+        let cursor = offset
 
-        const minimumEnd = PcbRawRecordRegistry.#readMinimumSubrecordListEnd(
-            bytes,
-            offset,
-            descriptor
-        )
+        while (cursor < bytes.byteLength) {
+            const minimumEnd =
+                PcbRawRecordRegistry.#readMinimumSubrecordListEnd(
+                    bytes,
+                    cursor,
+                    descriptor
+                )
+            const unknownSubrecord = PcbRawRecordRegistry.#readSubrecordAt(
+                bytes,
+                cursor
+            )
 
-        if (!minimumEnd) {
-            return null
-        }
+            if (minimumEnd) {
+                const alternativeOffset =
+                    unknownSubrecord?.nextOffset ?? cursor + 1
+
+                return {
+                    offset: cursor,
+                    minimumEnd,
+                    alternativeOffset:
+                        alternativeOffset < bytes.byteLength
+                            ? alternativeOffset
+                            : null
+                }
+            }
 
-        const endOffset = remainingCount
-            ? PcbRawRecordRegistry.#findNextSubrecordListRecordOffset(
-                  bytes,
-                  minimumEnd,
-                  descriptor,
-                  remainingCount
-              )
-            : bytes.byteLength
+            if (!unknownSubrecord) {
+                cursor += 1
+                continue
+            }
 
-        if (!endOffset) {
-            return null
+            cursor = unknownSubrecord.nextOffset
         }
 
-        return {
-            recordBytes: bytes.slice(offset, endOffset),
-            offset,
-            byteLength: endOffset - offset,
-            payloadByteLength: null,
-            encoding: 'subrecord-list',
-            objectId: descriptor.typeId,
-            recordIndex: 0
-        }
+        return null
     }
 
     /**
@@ -484,82 +551,6 @@ export class PcbRawRecordRegistry {
         return cursor
     }
 
-    /**
-     * Finds the next known subrecord-list primitive boundary.
-     * @param {Uint8Array} bytes
-     * @param {number} offset
-     * @param {object} descriptor
-     * @param {number} remainingCount
-     * @returns {number | null}
-     */
-    static #findNextSubrecordListRecordOffset(
-        bytes,
-        offset,
-        descriptor,
-        remainingCount
-    ) {
-        let cursor = offset
-
-        while (cursor < bytes.byteLength) {
-            if (
-                PcbRawRecordRegistry.#canReadSubrecordListSequence(
-                    bytes,
-                    cursor,
-                    descriptor,
-                    remainingCount
-                )
-            ) {
-                return cursor
-            }
-
-            const unknownSubrecord = PcbRawRecordRegistry.#readSubrecordAt(
-                bytes,
-                cursor
-            )
-            cursor = unknownSubrecord ? unknownSubrecord.nextOffset : cursor + 1
-        }
-
-        return null
-    }
-
-    /**
-     * Checks whether the remaining subrecord-list records are readable.
-     * @param {Uint8Array} bytes
-     * @param {number} offset
-     * @param {object} descriptor
-     * @param {number} remainingCount
-     * @returns {boolean}
-     */
-    static #canReadSubrecordListSequence(
-        bytes,
-        offset,
-        descriptor,
-        remainingCount
-    ) {
-        const minimumEnd = PcbRawRecordRegistry.#readMinimumSubrecordListEnd(
-            bytes,
-            offset,
-            descriptor
-        )
-
-        if (!minimumEnd) {
-            return false
-        }
-
-        if (remainingCount <= 1) {
-            return true
-        }
-
-        return (
-            PcbRawRecordRegistry.#findNextSubrecordListRecordOffset(
-                bytes,
-                minimumEnd,
-                descriptor,
-                remainingCount - 1
-            ) !== null
-        )
-    }
-
     /**
      * Slices PCB text records including their variable string tails.
      * @param {object} descriptor

package/src/core/altium/PcbRegionPrimitiveParser.mjs

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { PcbPrimitiveOwnershipIndexParser } from './PcbPrimitiveOwnershipIndexParser.mjs'
+import { PrintableTextDecoder } from './PrintableTextDecoder.mjs'
 
 /**
  * Decodes Altium PCB region primitive streams.
@@ -164,17 +165,26 @@ export class PcbRegionPrimitiveParser {
                 net: 3,
                 polygon: 5
             })
+        const kind = PcbRegionPrimitiveParser.#numericKind(properties.KIND)
+        const legacyCutout =
+            PcbRegionPrimitiveParser.#legacyCutoutClassification(
+                properties,
+                kind
+            )
 
         return {
             region: {
                 layerId,
                 layerCode: layerId,
                 ...ownershipIndexes,
-                kind: Number(properties.KIND || 0),
+                kind,
+                ...legacyCutout.fields,
                 isKeepout: flags2 === 2,
                 isBoardCutout:
+                    legacyCutout.isBoardCutout ||
                     String(properties.ISBOARDCUTOUT || '').toUpperCase() ===
-                    'TRUE',
+                        'TRUE',
+                ...legacyCutout.cutoutFlags,
                 isShapeBased:
                     shapeBased ||
                     String(properties.ISSHAPEBASED || '').toUpperCase() ===
@@ -187,6 +197,66 @@ export class PcbRegionPrimitiveParser {
         }
     }
 
+    /**
+     * Parses a region kind while avoiding NaN for legacy symbolic labels.
+     * @param {string | undefined} rawKind Raw KIND value.
+     * @returns {number | null}
+     */
+    static #numericKind(rawKind) {
+        if (rawKind === undefined || rawKind === null || rawKind === '') {
+            return 0
+        }
+
+        const kind = Number(rawKind)
+        return Number.isFinite(kind) ? kind : null
+    }
+
+    /**
+     * Builds cutout fields from legacy string KIND labels.
+     * @param {Record<string, string>} properties Native property map.
+     * @param {number | null} numericKind Parsed numeric kind.
+     * @returns {{ isBoardCutout: boolean, fields: object, cutoutFlags: object }}
+     */
+    static #legacyCutoutClassification(properties, numericKind) {
+        const rawKind = String(properties.KIND || '').trim()
+        if (numericKind !== null || !rawKind) {
+            return {
+                isBoardCutout: false,
+                fields: {},
+                cutoutFlags: {}
+            }
+        }
+
+        const normalized = rawKind.replace(/[^a-z0-9]/giu, '').toLowerCase()
+        const isBoardCutout = normalized === 'boardcutout'
+        const isPolygonPourCutout =
+            normalized === 'polygonpourcutout' ||
+            normalized === 'polygoncutout' ||
+            normalized === 'pourcutout'
+        const classification =
+            isBoardCutout || isPolygonPourCutout
+                ? {
+                      isBoardCutout,
+                      isPolygonPourCutout,
+                      source: 'legacy-kind',
+                      rawKind
+                  }
+                : null
+
+        return {
+            isBoardCutout,
+            fields: {
+                rawKind
+            },
+            cutoutFlags: classification
+                ? {
+                      isPolygonPourCutout,
+                      cutoutClassification: classification
+                  }
+                : {}
+        }
+    }
+
     /**
      * Reads one simple double-coordinate region vertex list.
      * @param {DataView} view
@@ -254,7 +324,10 @@ export class PcbRegionPrimitiveParser {
      * @returns {Record<string, string>}
      */
     static #parsePropertyBytes(bytes) {
-        const text = new TextDecoder().decode(bytes).replace(/\u0000+$/u, '')
+        const text = PrintableTextDecoder.decodeBytes(bytes).replace(
+            /\u0000+$/u,
+            ''
+        )
         const properties = {}
 
         for (const part of text.split('|')) {