altium-toolkit 0.1.1 → 0.1.16

package/src/core/altium/PcbComponentAnnotationNormalizer.mjs

@@ -0,0 +1,290 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Applies component annotations recovered from PCB sidecar streams.
+ */
+export class PcbComponentAnnotationNormalizer {
+    /**
+     * Enriches component records with Texts6 designators and parameters.
+     * @param {{ componentIndex: number, designator: string, uniqueId?: string, description?: string, parameters?: Record<string, string> }[]} components
+     * @param {{ text?: string, ownerIndex?: number | null, componentIndex?: number | null, role?: string, isDesignator?: boolean }[]} texts
+     * @param {{ byPrimitiveId?: Record<string, Record<string, string>>, groups?: { primitiveId: string, parameters: Record<string, string> }[] } | undefined} primitiveParameters
+     * @returns {object[]}
+     */
+    static enrichComponents(components, texts, primitiveParameters) {
+        return PcbComponentAnnotationNormalizer.#applyPrimitiveParameters(
+            PcbComponentAnnotationNormalizer.#applyTextDesignators(
+                components,
+                texts
+            ),
+            PcbComponentAnnotationNormalizer.#primitiveParameterLookup(
+                primitiveParameters
+            )
+        )
+    }
+
+    /**
+     * Marks decoded PCB text primitives as visible or hidden based on linked
+     * component display flags.
+     * @param {{ text: string, ownerIndex?: number | null, componentIndex?: number | null, kind?: number, visibilityFlags?: number, role?: string, isDesignator?: boolean }[]} texts
+     * @param {{ componentIndex: number, designator: string, nameOn: boolean, commentOn: boolean }[]} components
+     * @returns {object[]}
+     */
+    static normalizeTexts(texts, components) {
+        return (texts || []).map((text) => ({
+            ...text,
+            visible: PcbComponentAnnotationNormalizer.#isVisibleText(
+                text,
+                components
+            )
+        }))
+    }
+
+    /**
+     * Applies Texts6-owned designator strings to their native component.
+     * @param {{ componentIndex: number, designator: string }[]} components
+     * @param {{ text?: string, ownerIndex?: number | null, componentIndex?: number | null, role?: string, isDesignator?: boolean }[]} texts
+     * @returns {object[]}
+     */
+    static #applyTextDesignators(components, texts) {
+        const designatorsByComponentIndex =
+            PcbComponentAnnotationNormalizer.#textDesignatorLookup(texts)
+
+        return (components || []).map((component) => {
+            const displayDesignator = designatorsByComponentIndex.get(
+                Number(component.componentIndex)
+            )
+
+            if (
+                !displayDesignator ||
+                PcbComponentAnnotationNormalizer.#normalizeText(
+                    displayDesignator
+                ) ===
+                    PcbComponentAnnotationNormalizer.#normalizeText(
+                        component.designator
+                    )
+            ) {
+                return component
+            }
+
+            return {
+                ...component,
+                baseDesignator: component.designator,
+                designator: displayDesignator,
+                displayDesignator,
+                designatorSource: 'Texts6/Data'
+            }
+        })
+    }
+
+    /**
+     * Builds a component-indexed lookup from explicit Texts6 designators.
+     * @param {{ text?: string, ownerIndex?: number | null, componentIndex?: number | null, role?: string, isDesignator?: boolean }[]} texts
+     * @returns {Map<number, string>}
+     */
+    static #textDesignatorLookup(texts) {
+        const designatorsByComponentIndex = new Map()
+
+        for (const text of texts || []) {
+            const componentIndex =
+                PcbComponentAnnotationNormalizer.#textComponentIndex(text)
+            if (
+                !Number.isInteger(componentIndex) ||
+                !PcbComponentAnnotationNormalizer.#isDesignatorTextPrimitive(
+                    text
+                ) ||
+                !text.text
+            ) {
+                continue
+            }
+
+            designatorsByComponentIndex.set(componentIndex, String(text.text))
+        }
+
+        return designatorsByComponentIndex
+    }
+
+    /**
+     * Resolves the native component index from a decoded text primitive.
+     * @param {{ ownerIndex?: number | null, componentIndex?: number | null }} text
+     * @returns {number | null}
+     */
+    static #textComponentIndex(text) {
+        const componentIndex = Number(text?.componentIndex)
+        if (Number.isInteger(componentIndex)) {
+            return componentIndex
+        }
+
+        const ownerIndex = Number(text?.ownerIndex)
+        return Number.isInteger(ownerIndex) ? ownerIndex : null
+    }
+
+    /**
+     * Returns true when one text primitive explicitly represents a designator.
+     * @param {{ role?: string, isDesignator?: boolean }} text
+     * @returns {boolean}
+     */
+    static #isDesignatorTextPrimitive(text) {
+        return text?.isDesignator === true || text?.role === 'designator'
+    }
+
+    /**
+     * Applies PrimitiveParameters/Data values to components by unique ID.
+     * @param {{ uniqueId?: string, description?: string, parameters?: Record<string, string> }[]} components
+     * @param {Map<string, Record<string, string>>} parametersByPrimitiveId
+     * @returns {object[]}
+     */
+    static #applyPrimitiveParameters(components, parametersByPrimitiveId) {
+        return (components || []).map((component) => {
+            const primitiveId = String(component.uniqueId || '')
+            const parameters = primitiveId
+                ? parametersByPrimitiveId.get(primitiveId)
+                : null
+
+            if (!parameters) {
+                return component
+            }
+
+            const mergedParameters = {
+                ...(component.parameters || {}),
+                ...parameters
+            }
+
+            return {
+                ...component,
+                description:
+                    component.description ||
+                    PcbComponentAnnotationNormalizer.#firstParameterValue(
+                        mergedParameters,
+                        ['Description', 'Comment', 'Value']
+                    ),
+                parameters: mergedParameters,
+                parameterSource: 'PrimitiveParameters/Data'
+            }
+        })
+    }
+
+    /**
+     * Builds a primitive-parameter lookup from supported extraction shapes.
+     * @param {{ byPrimitiveId?: Record<string, Record<string, string>>, groups?: { primitiveId: string, parameters: Record<string, string> }[] } | undefined} primitiveParameters
+     * @returns {Map<string, Record<string, string>>}
+     */
+    static #primitiveParameterLookup(primitiveParameters) {
+        const lookup = new Map()
+
+        for (const [primitiveId, parameters] of Object.entries(
+            primitiveParameters?.byPrimitiveId || {}
+        )) {
+            lookup.set(String(primitiveId), { ...(parameters || {}) })
+        }
+
+        for (const group of primitiveParameters?.groups || []) {
+            if (group?.primitiveId && !lookup.has(String(group.primitiveId))) {
+                lookup.set(String(group.primitiveId), {
+                    ...(group.parameters || {})
+                })
+            }
+        }
+
+        return lookup
+    }
+
+    /**
+     * Returns the first non-empty parameter value using case-insensitive names.
+     * @param {Record<string, string>} parameters
+     * @param {string[]} names
+     * @returns {string}
+     */
+    static #firstParameterValue(parameters, names) {
+        const normalizedParameters = new Map(
+            Object.entries(parameters || {}).map(([name, value]) => [
+                name.toLowerCase(),
+                String(value || '')
+            ])
+        )
+
+        for (const name of names) {
+            const value = normalizedParameters.get(name.toLowerCase())
+            if (value) {
+                return value
+            }
+        }
+
+        return ''
+    }
+
+    /**
+     * Returns true when one PCB text primitive should render in board view.
+     * @param {{ text: string, ownerIndex?: number | null, componentIndex?: number | null, kind?: number, visibilityFlags?: number, role?: string, isDesignator?: boolean }} text
+     * @param {{ componentIndex: number, designator: string, nameOn: boolean, commentOn: boolean }[]} components
+     * @returns {boolean}
+     */
+    static #isVisibleText(text, components) {
+        const componentIndex =
+            PcbComponentAnnotationNormalizer.#textComponentIndex(text)
+
+        if (!Number.isInteger(componentIndex)) {
+            return true
+        }
+
+        const component =
+            PcbComponentAnnotationNormalizer.#componentByNativeIndex(
+                components,
+                componentIndex
+            )
+        if (!component) {
+            return (Number(text?.visibilityFlags || 0) & 1) === 0
+        }
+
+        if (PcbComponentAnnotationNormalizer.#isDesignatorTextPrimitive(text)) {
+            return component.nameOn
+        }
+
+        if (
+            PcbComponentAnnotationNormalizer.#normalizeText(text.text) ===
+            PcbComponentAnnotationNormalizer.#normalizeText(
+                component.designator
+            )
+        ) {
+            return component.nameOn
+        }
+
+        if (Number(text?.kind) === 1) {
+            return component.commentOn
+        }
+
+        if ((Number(text?.visibilityFlags || 0) & 1) !== 0) {
+            return component.nameOn
+        }
+
+        return true
+    }
+
+    /**
+     * Finds one normalized component by native component table index.
+     * @param {{ componentIndex: number }[]} components
+     * @param {number} componentIndex
+     * @returns {object | null}
+     */
+    static #componentByNativeIndex(components, componentIndex) {
+        return (
+            (components || []).find(
+                (component) =>
+                    Number(component?.componentIndex) === componentIndex
+            ) || null
+        )
+    }
+
+    /**
+     * Normalizes text for display-flag comparisons.
+     * @param {unknown} text
+     * @returns {string}
+     */
+    static #normalizeText(text) {
+        return String(text || '')
+            .trim()
+            .toUpperCase()
+    }
+}

package/src/core/altium/PcbComponentBodyPlacementNormalizer.mjs

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Normalizes embedded component-body placements into viewer coordinates.
+ */
+export class PcbComponentBodyPlacementNormalizer {
+    /**
+     * Flips embedded component-body placements into the viewer coordinate
+     * system.
+     * @param {{ sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null }[]} componentBodies
+     * @param {{ minY: number, heightMil: number }} boardOutline
+     * @returns {{ sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null }[]}
+     */
+    static normalizeComponentBodies(componentBodies, boardOutline) {
+        const maxY =
+            Number(boardOutline?.minY || 0) +
+            Number(boardOutline?.heightMil || 0)
+        const mirrorY = (value) =>
+            Number(boardOutline?.minY || 0) + maxY - Number(value || 0)
+
+        return componentBodies.map((componentBody) => ({
+            ...componentBody,
+            positionMil: {
+                x: Number(componentBody.positionMil?.x || 0),
+                y: mirrorY(componentBody.positionMil?.y || 0)
+            },
+            rotationDeg: PcbComponentBodyPlacementNormalizer.#normalizeAngle(
+                360 - Number(componentBody.rotationDeg || 0)
+            ),
+            modelRotationDeg: {
+                x: Number(componentBody.modelRotationDeg?.x || 0),
+                y: Number(componentBody.modelRotationDeg?.y || 0),
+                z: PcbComponentBodyPlacementNormalizer.#normalizeAngle(
+                    360 - Number(componentBody.modelRotationDeg?.z || 0)
+                )
+            }
+        }))
+    }
+
+    /**
+     * Normalizes one angle into the range [0, 360).
+     * @param {number} angle
+     * @returns {number}
+     */
+    static #normalizeAngle(angle) {
+        const normalized = Number(angle || 0) % 360
+
+        return normalized < 0 ? normalized + 360 : normalized
+    }
+}

package/src/core/altium/PcbComponentPrimitiveIndexer.mjs

@@ -0,0 +1,109 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Groups PCB primitives by native Altium component ownership indexes.
+ */
+export class PcbComponentPrimitiveIndexer {
+    /**
+     * Groups normalized primitives by their native component index.
+     * @param {{ componentIndex: number, designator: string }[]} components
+     * @param {{ fills?: object[], tracks?: object[], arcs?: object[], vias?: object[], pads?: object[], regions?: object[], shapeBasedRegions?: object[], texts?: object[] }} pcb
+     * @param {{ componentIndex?: number | null }[]} componentBodies
+     * @returns {{ componentIndex: number, designator: string, pads: object[], tracks: object[], arcs: object[], fills: object[], vias: object[], regions: object[], shapeBasedRegions: object[], texts: object[], componentBodies: object[] }[]}
+     */
+    static buildGroups(components, pcb, componentBodies) {
+        return (components || []).map((component) => {
+            const componentIndex = Number(component.componentIndex)
+
+            return {
+                componentIndex,
+                designator: component.designator,
+                pads: PcbComponentPrimitiveIndexer.#primitivesForComponent(
+                    pcb.pads,
+                    componentIndex
+                ),
+                tracks: PcbComponentPrimitiveIndexer.#primitivesForComponent(
+                    pcb.tracks,
+                    componentIndex
+                ),
+                arcs: PcbComponentPrimitiveIndexer.#primitivesForComponent(
+                    pcb.arcs,
+                    componentIndex
+                ),
+                fills: PcbComponentPrimitiveIndexer.#primitivesForComponent(
+                    pcb.fills,
+                    componentIndex
+                ),
+                vias: PcbComponentPrimitiveIndexer.#primitivesForComponent(
+                    pcb.vias,
+                    componentIndex
+                ),
+                regions: PcbComponentPrimitiveIndexer.#primitivesForComponent(
+                    pcb.regions,
+                    componentIndex
+                ),
+                shapeBasedRegions:
+                    PcbComponentPrimitiveIndexer.#primitivesForComponent(
+                        pcb.shapeBasedRegions,
+                        componentIndex
+                    ),
+                texts: (pcb.texts || []).filter(
+                    (text) => Number(text?.ownerIndex) === componentIndex
+                ),
+                componentBodies:
+                    PcbComponentPrimitiveIndexer.#primitivesForComponent(
+                        componentBodies,
+                        componentIndex
+                    )
+            }
+        })
+    }
+
+    /**
+     * Indexes component primitive groups by their native component index.
+     * @param {{ componentIndex: number, designator: string, pads: object[], tracks: object[], arcs: object[], fills: object[], vias: object[], regions: object[], shapeBasedRegions: object[], texts: object[], componentBodies: object[] }[]} componentPrimitiveGroups
+     * @returns {({ componentIndex: number, designator: string, pads: object[], tracks: object[], arcs: object[], fills: object[], vias: object[], regions: object[], shapeBasedRegions: object[], texts: object[], componentBodies: object[] } | null)[]}
+     */
+    static indexGroups(componentPrimitiveGroups) {
+        const indexedGroups = []
+
+        for (const group of componentPrimitiveGroups || []) {
+            const componentIndex = Number(group.componentIndex)
+
+            if (!Number.isInteger(componentIndex) || componentIndex < 0) {
+                continue
+            }
+
+            while (indexedGroups.length <= componentIndex) {
+                indexedGroups.push(null)
+            }
+
+            indexedGroups[componentIndex] = group
+        }
+
+        return indexedGroups
+    }
+
+    /**
+     * Returns primitives linked to a component by native Altium index.
+     * @param {{ componentIndex?: number | null }[] | undefined} primitives
+     * @param {number} componentIndex
+     * @returns {object[]}
+     */
+    static #primitivesForComponent(primitives, componentIndex) {
+        return (primitives || []).filter((primitive) => {
+            const rawComponentIndex = primitive?.componentIndex
+            if (
+                rawComponentIndex === null ||
+                rawComponentIndex === undefined ||
+                rawComponentIndex === ''
+            ) {
+                return false
+            }
+
+            return Number(rawComponentIndex) === componentIndex
+        })
+    }
+}