altium-toolkit 0.1.0

package/src/ui/PcbScene3dModelRegistry.mjs

@@ -0,0 +1,309 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Indexes session companion assets for 3D model lookup.
+ */
+export class PcbScene3dModelRegistry {
+    /** @type {{ file?: File | Blob | null, name: string, relativePath: string, format: string, normalizedPath: string, normalizedBaseName: string }[]} */
+    #modelFiles
+
+    /** @type {{ id: string, checksum: number | null, name: string, format: string, payloadText: string, sourceStream: string, normalizedId: string, normalizedBaseName: string }[]} */
+    #embeddedModels
+
+    /**
+     * @param {{ file?: File | Blob | null, name: string, relativePath: string, format: string, normalizedPath: string, normalizedBaseName: string }[]} modelFiles
+     * @param {{ id: string, checksum: number | null, name: string, format: string, payloadText: string, sourceStream: string, normalizedId: string, normalizedBaseName: string }[]} embeddedModels
+     */
+    constructor(modelFiles, embeddedModels) {
+        this.#modelFiles = modelFiles
+        this.#embeddedModels = embeddedModels
+    }
+
+    /**
+     * Creates one model registry from session files.
+     * @param {{ name?: string, relativePath?: string }[]} sessionFiles
+     * @param {{ id?: string, checksum?: number | null, name?: string, format?: string, payloadText?: string, sourceStream?: string }[]} [embeddedModels]
+     * @returns {PcbScene3dModelRegistry}
+     */
+    static create(sessionFiles, embeddedModels = []) {
+        const modelFiles = (Array.isArray(sessionFiles) ? sessionFiles : [])
+            .map((file) => PcbScene3dModelRegistry.#normalizeFile(file))
+            .filter(Boolean)
+        const normalizedEmbeddedModels = (
+            Array.isArray(embeddedModels) ? embeddedModels : []
+        )
+            .map((model) =>
+                PcbScene3dModelRegistry.#normalizeEmbeddedModel(model)
+            )
+            .filter(Boolean)
+
+        return new PcbScene3dModelRegistry(modelFiles, normalizedEmbeddedModels)
+    }
+
+    /**
+     * Resolves the best available external model for one component.
+     * @param {{ pattern?: string, source?: string, modelPath?: string }} component
+     * @returns {{ file?: File | Blob | null, name: string, relativePath: string, format: string } | null}
+     */
+    resolveComponentModel(component) {
+        const explicitMatch = this.#resolveExplicitMatch(component.modelPath)
+        if (explicitMatch) {
+            return explicitMatch
+        }
+
+        const heuristicMatch = this.#resolveHeuristicMatch(component)
+        if (heuristicMatch) {
+            return heuristicMatch
+        }
+
+        return null
+    }
+
+    /**
+     * Normalizes one session file into registry metadata.
+     * @param {{ name?: string, relativePath?: string }} file
+     * @returns {{ file?: File | Blob | null, name: string, relativePath: string, format: string, normalizedPath: string, normalizedBaseName: string } | null}
+     */
+    static #normalizeFile(file) {
+        const relativePath = String(file?.relativePath || file?.name || '')
+        const name = String(file?.name || relativePath.split('/').pop() || '')
+        const format = PcbScene3dModelRegistry.#resolveFormat(relativePath)
+
+        if (!name || !format) {
+            return null
+        }
+
+        return {
+            file: file?.file || file?.blob || null,
+            name,
+            relativePath,
+            format,
+            normalizedPath:
+                PcbScene3dModelRegistry.#normalizeToken(relativePath),
+            normalizedBaseName: PcbScene3dModelRegistry.#normalizeToken(
+                name.replace(/\.[^.]+$/, '')
+            )
+        }
+    }
+
+    /**
+     * Resolves the supported model format from one file path.
+     * @param {string} filePath
+     * @returns {string}
+     */
+    static #resolveFormat(filePath) {
+        const lowerCasePath = String(filePath || '').toLowerCase()
+        if (lowerCasePath.endsWith('.wrl') || lowerCasePath.endsWith('.vrml')) {
+            return 'wrl'
+        }
+
+        if (lowerCasePath.endsWith('.step') || lowerCasePath.endsWith('.stp')) {
+            return 'step'
+        }
+
+        return ''
+    }
+
+    /**
+     * Resolves one explicit model-path match.
+     * @param {string | undefined} modelPath
+     * @returns {{ file?: File | Blob | null, name: string, relativePath: string, format: string } | null}
+     */
+    #resolveExplicitMatch(modelPath) {
+        const normalizedPath =
+            PcbScene3dModelRegistry.#normalizeToken(modelPath)
+        if (!normalizedPath) {
+            return null
+        }
+
+        const byPath = this.#modelFiles.find(
+            (file) => file.normalizedPath === normalizedPath
+        )
+        if (byPath) {
+            return {
+                origin: 'session',
+                file: byPath.file,
+                name: byPath.name,
+                relativePath: byPath.relativePath,
+                format: byPath.format
+            }
+        }
+
+        const fileName =
+            String(modelPath || '')
+                .split('/')
+                .pop() || ''
+        const normalizedBaseName = PcbScene3dModelRegistry.#normalizeToken(
+            fileName.replace(/\.[^.]+$/, '')
+        )
+        return this.#resolveByBaseName(normalizedBaseName)
+    }
+
+    /**
+     * Resolves a heuristic model match from component naming fields.
+     * @param {{ pattern?: string, source?: string }} component
+     * @returns {{ file?: File | Blob | null, name: string, relativePath: string, format: string } | null}
+     */
+    #resolveHeuristicMatch(component) {
+        const candidates = [component?.pattern, component?.source]
+
+        for (const candidate of candidates) {
+            const normalized = PcbScene3dModelRegistry.#normalizeToken(
+                String(candidate || '')
+            )
+            const match = this.#resolveByBaseName(normalized)
+            if (match) {
+                return match
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Resolves one indexed file by normalized basename and format priority.
+     * @param {string} normalizedBaseName
+     * @returns {{ file?: File | Blob | null, name: string, relativePath: string, format: string } | null}
+     */
+    #resolveByBaseName(normalizedBaseName) {
+        if (!normalizedBaseName) {
+            return null
+        }
+
+        const rankedMatches = this.#modelFiles
+            .filter((file) => file.normalizedBaseName === normalizedBaseName)
+            .sort(
+                (left, right) =>
+                    PcbScene3dModelRegistry.#formatRank(left.format) -
+                    PcbScene3dModelRegistry.#formatRank(right.format)
+            )
+
+        if (!rankedMatches.length) {
+            return null
+        }
+
+        return {
+            origin: 'session',
+            file: rankedMatches[0].file,
+            name: rankedMatches[0].name,
+            relativePath: rankedMatches[0].relativePath,
+            format: rankedMatches[0].format
+        }
+    }
+
+    /**
+     * Resolves the best available model for one normalized component-body
+     * placement.
+     * @param {{ modelId?: string, checksum?: number | null, name?: string }} componentBody
+     * @returns {{ origin: 'embedded' | 'session', file?: File | Blob | null, name: string, relativePath?: string, format: string, payloadText?: string, sourceStream?: string } | null}
+     */
+    resolveComponentBodyModel(componentBody) {
+        const embeddedMatch = this.#resolveEmbeddedMatch(componentBody)
+        if (embeddedMatch) {
+            return embeddedMatch
+        }
+
+        return this.#resolveExplicitMatch(componentBody?.name)
+    }
+
+    /**
+     * Normalizes one embedded payload for registry lookup.
+     * @param {{ id?: string, checksum?: number | null, name?: string, format?: string, payloadText?: string, sourceStream?: string }} model
+     * @returns {{ id: string, checksum: number | null, name: string, format: string, payloadText: string, sourceStream: string, normalizedId: string, normalizedBaseName: string } | null}
+     */
+    static #normalizeEmbeddedModel(model) {
+        const id = String(model?.id || '').trim()
+        const name = String(model?.name || '').trim()
+        const format = String(model?.format || '').trim()
+        const payloadText = String(model?.payloadText || '')
+        const sourceStream = String(model?.sourceStream || '').trim()
+
+        if (!id || !name || !format || !payloadText || !sourceStream) {
+            return null
+        }
+
+        return {
+            id,
+            checksum: Number.isFinite(Number(model?.checksum))
+                ? Number(model?.checksum)
+                : null,
+            name,
+            format,
+            payloadText,
+            sourceStream,
+            normalizedId: PcbScene3dModelRegistry.#normalizeToken(id),
+            normalizedBaseName: PcbScene3dModelRegistry.#normalizeToken(
+                name.replace(/\.[^.]+$/, '')
+            )
+        }
+    }
+
+    /**
+     * Resolves one embedded model match from authored model metadata.
+     * @param {{ modelId?: string, checksum?: number | null, name?: string }} componentBody
+     * @returns {{ origin: 'embedded', name: string, format: string, payloadText: string, sourceStream: string } | null}
+     */
+    #resolveEmbeddedMatch(componentBody) {
+        const normalizedId = PcbScene3dModelRegistry.#normalizeToken(
+            componentBody?.modelId
+        )
+        const checksum = Number.isFinite(Number(componentBody?.checksum))
+            ? Number(componentBody?.checksum)
+            : null
+        const normalizedBaseName = PcbScene3dModelRegistry.#normalizeToken(
+            String(componentBody?.name || '').replace(/\.[^.]+$/, '')
+        )
+
+        const embeddedMatch =
+            this.#embeddedModels.find(
+                (model) => normalizedId && model.normalizedId === normalizedId
+            ) ||
+            this.#embeddedModels.find(
+                (model) =>
+                    checksum !== null &&
+                    model.checksum === checksum &&
+                    normalizedBaseName &&
+                    model.normalizedBaseName === normalizedBaseName
+            ) ||
+            this.#embeddedModels.find(
+                (model) =>
+                    normalizedBaseName &&
+                    model.normalizedBaseName === normalizedBaseName
+            )
+
+        if (!embeddedMatch) {
+            return null
+        }
+
+        return {
+            origin: 'embedded',
+            name: embeddedMatch.name,
+            format: embeddedMatch.format,
+            payloadText: embeddedMatch.payloadText,
+            sourceStream: embeddedMatch.sourceStream
+        }
+    }
+
+    /**
+     * Resolves the format priority for ties.
+     * @param {string} format
+     * @returns {number}
+     */
+    static #formatRank(format) {
+        return format === 'wrl' ? 0 : 1
+    }
+
+    /**
+     * Normalizes one lookup token.
+     * @param {string | undefined} value
+     * @returns {string}
+     */
+    static #normalizeToken(value) {
+        return String(value || '')
+            .toLowerCase()
+            .replaceAll('\\', '/')
+            .replace(/[^a-z0-9/]+/g, '')
+    }
+}

package/src/ui/PcbScene3dPackages.mjs

@@ -0,0 +1,137 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Resolves procedural PCB package families and dimensions.
+ */
+export class PcbScene3dPackages {
+    /**
+     * Resolves one procedural package description for a component.
+     * @param {{ pattern?: string, height?: number | null }} component
+     * @param {{ width: number, depth: number }} [padSpan]
+     * @returns {{ family: string, sizeMil: { width: number, depth: number, height: number } }}
+     */
+    static resolve(component, padSpan = { width: 0, depth: 0 }) {
+        const family = PcbScene3dPackages.#resolveFamily(component.pattern)
+        const defaults = PcbScene3dPackages.#resolveDefaultSize(
+            family,
+            component.pattern
+        )
+        const explicitHeight = Number(component.height)
+        const height =
+            Number.isFinite(explicitHeight) && explicitHeight > 0
+                ? explicitHeight
+                : defaults.height
+
+        return {
+            family,
+            sizeMil: {
+                width: Math.max(defaults.width, Number(padSpan.width) || 0),
+                depth: Math.max(defaults.depth, Number(padSpan.depth) || 0),
+                height
+            }
+        }
+    }
+
+    /**
+     * Resolves a generic package family from one footprint pattern.
+     * @param {string | undefined} pattern
+     * @returns {string}
+     */
+    static #resolveFamily(pattern) {
+        const normalized = String(pattern || '').toUpperCase()
+
+        if (/(0402|0603|0805|1206|C0805|C0603)/.test(normalized)) {
+            return 'chip'
+        }
+
+        if (normalized.includes('SOT')) {
+            return 'sot'
+        }
+
+        if (
+            normalized.includes('QFN') ||
+            normalized.includes('QFP') ||
+            normalized.includes('DFN') ||
+            normalized.includes('SOIC') ||
+            normalized.includes('SO16') ||
+            normalized.includes('TSSOP') ||
+            normalized.includes('SSOP')
+        ) {
+            return 'ic'
+        }
+
+        if (/C\d+(?:\.\d+)?A/.test(normalized)) {
+            return 'radial-capacitor'
+        }
+
+        if (normalized.includes('TP')) {
+            return 'test-point'
+        }
+
+        if (
+            normalized.includes('CON/') ||
+            normalized.includes('PH') ||
+            normalized.includes('CK-')
+        ) {
+            return 'connector-block'
+        }
+
+        if (normalized.includes('SMA') || normalized.includes('SMB')) {
+            return 'diode'
+        }
+
+        return 'generic'
+    }
+
+    /**
+     * Resolves one default body size for the chosen family.
+     * @param {string} family
+     * @param {string | undefined} pattern
+     * @returns {{ width: number, depth: number, height: number }}
+     */
+    static #resolveDefaultSize(family, pattern) {
+        const normalized = String(pattern || '').toUpperCase()
+
+        if (family === 'chip') {
+            if (normalized.includes('0402')) {
+                return { width: 24, depth: 12, height: 14 }
+            }
+            if (normalized.includes('0805')) {
+                return { width: 80, depth: 50, height: 24 }
+            }
+            if (normalized.includes('1206')) {
+                return { width: 126, depth: 63, height: 28 }
+            }
+
+            return { width: 60, depth: 30, height: 20 }
+        }
+
+        if (family === 'sot') {
+            return { width: 110, depth: 90, height: 45 }
+        }
+
+        if (family === 'ic') {
+            return { width: 180, depth: 180, height: 55 }
+        }
+
+        if (family === 'radial-capacitor') {
+            return { width: 120, depth: 120, height: 180 }
+        }
+
+        if (family === 'test-point') {
+            return { width: 36, depth: 36, height: 60 }
+        }
+
+        if (family === 'connector-block') {
+            return { width: 320, depth: 120, height: 150 }
+        }
+
+        if (family === 'diode') {
+            return { width: 95, depth: 60, height: 34 }
+        }
+
+        return { width: 96, depth: 72, height: 48 }
+    }
+}

package/src/ui/PcbScene3dScenePreparator.mjs

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbScene3dBuilder } from './PcbScene3dBuilder.mjs'
+import { PcbScene3dModelRegistry } from './PcbScene3dModelRegistry.mjs'
+
+/**
+ * Builds renderer-ready 3D scene descriptions for the initial viewport mount.
+ */
+export class PcbScene3dScenePreparator {
+    /**
+     * Builds one scene description for the initial runtime mount.
+     * @param {any} documentModel
+     * @param {{ sessionAssets?: any[], modelRegistry?: PcbScene3dModelRegistry | null, buildScene?: (documentModel: any, options: { modelRegistry: PcbScene3dModelRegistry }) => any }} [options]
+     * @returns {Promise<any>}
+     */
+    static async prepare(documentModel, options = {}) {
+        const modelRegistry =
+            options.modelRegistry ||
+            PcbScene3dModelRegistry.create(
+                options.sessionAssets || [],
+                Array.isArray(documentModel?.pcb?.embeddedModels)
+                    ? documentModel.pcb.embeddedModels
+                    : []
+            )
+        const buildScene =
+            options.buildScene ||
+            ((nextDocumentModel, buildOptions) =>
+                PcbScene3dBuilder.build(nextDocumentModel, buildOptions))
+
+        return buildScene(documentModel, {
+            modelRegistry
+        })
+    }
+}

package/src/ui/PcbScene3dSummaryRenderer.mjs

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Renders a non-interactive summary of recovered PCB 3D scene inputs.
+ */
+export class PcbScene3dSummaryRenderer {
+    /**
+     * Renders static 3D summary markup for a parsed PCB document.
+     * @param {{ pcb?: { boardOutline?: { widthMil?: number, heightMil?: number }, components?: any[] }, bom?: any[] }} documentModel
+     * @returns {string}
+     */
+    static render(documentModel) {
+        const pcb = documentModel?.pcb
+        if (!pcb) {
+            return '<section class="altium-3d-summary altium-3d-summary--empty">3D summary is available after parsing a PCB document.</section>'
+        }
+
+        const widthMil = PcbScene3dSummaryRenderer.#roundMil(
+            pcb.boardOutline?.widthMil
+        )
+        const heightMil = PcbScene3dSummaryRenderer.#roundMil(
+            pcb.boardOutline?.heightMil
+        )
+        const componentCount = Array.isArray(pcb.components)
+            ? pcb.components.length
+            : 0
+        const bomRows = Array.isArray(documentModel?.bom)
+            ? documentModel.bom.length
+            : 0
+
+        return (
+            '<section class="altium-3d-summary">' +
+            '<header class="altium-3d-summary__header"><h3>3D summary</h3><p>' +
+            widthMil +
+            ' x ' +
+            heightMil +
+            ' mil board envelope</p></header>' +
+            '<dl class="altium-3d-summary__stats"><div><dt>Footprint</dt><dd>' +
+            widthMil +
+            ' x ' +
+            heightMil +
+            ' mil</dd></div><div><dt>Placements</dt><dd>' +
+            componentCount +
+            ' components</dd></div><div><dt>BOM groups</dt><dd>' +
+            bomRows +
+            '</dd></div></dl></section>'
+        )
+    }
+
+    /**
+     * Rounds a recovered mil dimension for display.
+     * @param {unknown} value
+     * @returns {number}
+     */
+    static #roundMil(value) {
+        const numericValue = Number(value)
+        if (!Number.isFinite(numericValue)) {
+            return 0
+        }
+
+        return Math.round(numericValue)
+    }
+}