altium-toolkit 0.1.21 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "altium-toolkit",
-    "version": "0.1.21",
+    "version": "0.1.22",
     "description": "Altium document parsing and non-interactive rendering utilities",
     "keywords": [
         "altium",

package/src/scene3d.mjs

@@ -7,3 +7,4 @@ export { PcbScene3dModelRegistry } from './ui/PcbScene3dModelRegistry.mjs'
 export { PcbScene3dPackages } from './ui/PcbScene3dPackages.mjs'
 export { PcbScene3dScenePreparator } from './ui/PcbScene3dScenePreparator.mjs'
 export { PcbScene3dSummaryRenderer } from './ui/PcbScene3dSummaryRenderer.mjs'
+export { PcbScene3dTextBoxLayoutResolver } from './ui/PcbScene3dTextBoxLayoutResolver.mjs'

package/src/ui/PcbScene3dBuilder.mjs

@@ -6,6 +6,8 @@ import { PcbEdgeFacingGlyphNormalizer } from './PcbEdgeFacingGlyphNormalizer.mjs
 import { PcbScene3dDrillCutoutBuilder } from './PcbScene3dDrillCutoutBuilder.mjs'
 import { PcbFootprintPrimitiveSelector } from './PcbFootprintPrimitiveSelector.mjs'
 import { PcbScene3dPackages } from './PcbScene3dPackages.mjs'
+import { PcbScene3dPlacementSideResolver } from './PcbScene3dPlacementSideResolver.mjs'
+import { PcbScene3dTextBoxLayoutResolver } from './PcbScene3dTextBoxLayoutResolver.mjs'
 
 /**
  * Builds deterministic 3D scene data from the normalized PCB model.
@@ -114,6 +116,7 @@ export class PcbScene3dBuilder {
                     PcbScene3dBuilder.#buildExternalPlacement(
                         componentBody,
                         bodyMatches[index],
+                        components,
                         board,
                         thicknessMil,
                         modelRegistry
@@ -195,6 +198,7 @@ export class PcbScene3dBuilder {
      * body metadata.
      * @param {{ modelId?: string, checksum?: number | null, embedded?: boolean, name?: string, identifier?: string, layer?: string, positionMil?: { x?: number, y?: number }, rotationDeg?: number, modelRotationDeg?: { x?: number, y?: number, z?: number }, dzMil?: number }} componentBody
      * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, rotation?: number, height?: number | null } | null} matchedComponent
+     * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, source?: string, modelPath?: string }[]} components
      * @param {{ centerX: number, centerY: number }} board
      * @param {number} thicknessMil
      * @param {{ resolveComponentBodyModel?: (componentBody: any) => { origin: string, name: string, format: string, payloadText?: string, sourceStream?: string, relativePath?: string } | null } | null} modelRegistry
@@ -203,6 +207,7 @@ export class PcbScene3dBuilder {
     static #buildExternalPlacement(
         componentBody,
         matchedComponent,
+        components,
         board,
         thicknessMil,
         modelRegistry
@@ -220,9 +225,10 @@ export class PcbScene3dBuilder {
             return null
         }
 
-        const mountSide = PcbScene3dBuilder.#resolveExternalPlacementMountSide(
+        const mountSide = PcbScene3dPlacementSideResolver.resolvePlacementSide(
             componentBody,
-            matchedComponent
+            matchedComponent,
+            components
         )
         const halfBoardThickness = thicknessMil / 2
         const sourcePosition =
@@ -327,7 +333,9 @@ export class PcbScene3dBuilder {
         const groupedBodyIndexes = new Map()
         componentBodies.forEach((componentBody, bodyIndex) => {
             const groupKey =
-                PcbScene3dBuilder.#resolveBodyGroupKey(componentBody)
+                PcbScene3dPlacementSideResolver.resolveBodyGroupKey(
+                    componentBody
+                )
             if (!groupedBodyIndexes.has(groupKey)) {
                 groupedBodyIndexes.set(groupKey, [])
             }
@@ -355,7 +363,7 @@ export class PcbScene3dBuilder {
                             bodyIndexes.includes(
                                 matches.indexOf(components[componentIndex])
                             )) &&
-                        PcbScene3dBuilder.#scoreBodyComponentAffinity(
+                        PcbScene3dPlacementSideResolver.scoreBodyComponentAffinity(
                             referenceBody,
                             component
                         ) > 0
@@ -401,7 +409,9 @@ export class PcbScene3dBuilder {
 
         for (const componentBody of componentBodies) {
             const groupKey =
-                PcbScene3dBuilder.#resolveBodyGroupKey(componentBody)
+                PcbScene3dPlacementSideResolver.resolveBodyGroupKey(
+                    componentBody
+                )
             bodyGroupCounts.set(
                 groupKey,
                 (bodyGroupCounts.get(groupKey) || 0) + 1
@@ -416,7 +426,7 @@ export class PcbScene3dBuilder {
                 groupKey,
                 components.filter(
                     (component) =>
-                        PcbScene3dBuilder.#scoreBodyComponentAffinity(
+                        PcbScene3dPlacementSideResolver.scoreBodyComponentAffinity(
                             componentBody,
                             component
                         ) > 0
@@ -450,7 +460,7 @@ export class PcbScene3dBuilder {
         }
 
         if (
-            PcbScene3dBuilder.#scoreBodyComponentAffinity(
+            PcbScene3dPlacementSideResolver.scoreBodyComponentAffinity(
                 componentBody,
                 component
             ) <= 0
@@ -458,7 +468,8 @@ export class PcbScene3dBuilder {
             return false
         }
 
-        const groupKey = PcbScene3dBuilder.#resolveBodyGroupKey(componentBody)
+        const groupKey =
+            PcbScene3dPlacementSideResolver.resolveBodyGroupKey(componentBody)
         const bodyCount = matchContext.bodyGroupCounts.get(groupKey) || 0
         const candidateCount =
             matchContext.candidateComponentCounts.get(groupKey) || 0
@@ -635,40 +646,6 @@ export class PcbScene3dBuilder {
         }
     }
 
-    /**
-     * Resolves which board side one explicit model should mount on.
-     * @param {{ layer?: string }} componentBody
-     * @param {{ layer?: string } | null} matchedComponent
-     * @returns {'top' | 'bottom'}
-     */
-    static #resolveExternalPlacementMountSide(componentBody, matchedComponent) {
-        const bodySide = PcbScene3dBuilder.#resolveMechanicalLayerSide(
-            componentBody?.layer
-        )
-        if (bodySide) {
-            return bodySide
-        }
-
-        return String(matchedComponent?.layer || 'TOP').toUpperCase() ===
-            'BOTTOM'
-            ? 'bottom'
-            : 'top'
-    }
-
-    /**
-     * Resolves a common Altium top/bottom mechanical layer pair.
-     * @param {string | undefined} layer
-     * @returns {'top' | 'bottom' | null}
-     */
-    static #resolveMechanicalLayerSide(layer) {
-        const match = String(layer || '').match(/^MECHANICAL\s*(\d+)$/i)
-        if (!match) {
-            return null
-        }
-
-        return Number(match[1]) % 2 === 0 ? 'bottom' : 'top'
-    }
-
     /**
      * Resolves the authored placement rotation for one explicit external model.
      * Altium stores the 3D model's board-facing yaw in MODEL.3D.ROTZ.
@@ -879,9 +856,11 @@ export class PcbScene3dBuilder {
      */
     static #normalizeSilkscreenText(text, side) {
         const height = Math.max(Number(text?.height || 0), 1)
+        const textBox = PcbScene3dTextBoxLayoutResolver.resolve(text)
 
         return {
             ...text,
+            ...(textBox ? { textBox } : {}),
             text: String(text?.text ?? text?.value ?? ''),
             value: String(text?.text ?? text?.value ?? ''),
             sizeX: height,
@@ -1159,85 +1138,6 @@ export class PcbScene3dBuilder {
         )
     }
 
-    /**
-     * Resolves the grouping key for repeated component-body matching.
-     * @param {{ modelId?: string, name?: string, identifier?: string }} componentBody
-     * @returns {string}
-     */
-    static #resolveBodyGroupKey(componentBody) {
-        return PcbScene3dBuilder.#normalizeLookupToken(
-            componentBody?.modelId ||
-                componentBody?.name ||
-                componentBody?.identifier
-        )
-    }
-
-    /**
-     * Scores how strongly one component record appears to belong to one body
-     * record based on shared model/footprint tokens.
-     * @param {{ name?: string, identifier?: string }} componentBody
-     * @param {{ pattern?: string, source?: string, modelPath?: string }} component
-     * @returns {number}
-     */
-    static #scoreBodyComponentAffinity(componentBody, component) {
-        const bodyTokens = PcbScene3dBuilder.#collectMeaningfulTokens([
-            componentBody?.identifier,
-            String(componentBody?.name || '').replace(/\.[^.]+$/, '')
-        ])
-        const componentTokens = PcbScene3dBuilder.#collectMeaningfulTokens([
-            component?.pattern,
-            component?.source,
-            component?.modelPath
-        ])
-        let score = 0
-
-        bodyTokens.forEach((token) => {
-            if (componentTokens.has(token)) {
-                score += token.length
-            }
-        })
-
-        return score
-    }
-
-    /**
-     * Collects normalized model tokens from free-form strings.
-     * @param {(string | undefined)[]} values
-     * @returns {Set<string>}
-     */
-    static #collectMeaningfulTokens(values) {
-        const tokens = new Set()
-
-        ;(Array.isArray(values) ? values : []).forEach((value) => {
-            String(value || '')
-                .toLowerCase()
-                .split(/[^a-z0-9]+/g)
-                .forEach((fragment) => {
-                    ;(fragment.match(/[a-z]+|\d+/g) || []).forEach((token) => {
-                        if (PcbScene3dBuilder.#isMeaningfulToken(token)) {
-                            tokens.add(token)
-                        }
-                    })
-                })
-        })
-
-        return tokens
-    }
-
-    /**
-     * Returns true when one normalized token carries useful model identity.
-     * @param {string} token
-     * @returns {boolean}
-     */
-    static #isMeaningfulToken(token) {
-        return (
-            String(token || '').length >= 2 &&
-            !new Set(['con', 'step', 'stp', 'model', 'default', 'black']).has(
-                String(token || '')
-            )
-        )
-    }
-
     /**
      * Returns true when one unresolved body anchor still lies close enough to
      * the board envelope to be renderable without a component match.
@@ -1258,17 +1158,6 @@ export class PcbScene3dBuilder {
         return bodyX >= minX && bodyX <= maxX && bodyY >= minY && bodyY <= maxY
     }
 
-    /**
-     * Normalizes one lookup token for repeated-model grouping.
-     * @param {string | undefined} value
-     * @returns {string}
-     */
-    static #normalizeLookupToken(value) {
-        return String(value || '')
-            .toLowerCase()
-            .replace(/[^a-z0-9]+/g, '')
-    }
-
     /**
      * Normalizes one angle into the range [0, 360).
      * @param {number} angle

package/src/ui/PcbScene3dPlacementSideResolver.mjs

@@ -0,0 +1,272 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Resolves 3D component-body identity and mount-side hints.
+ */
+export class PcbScene3dPlacementSideResolver {
+    static #NEARBY_SIDE_HINT_MAX_DISTANCE_MIL = 600
+    static #NEGATIVE_STANDOFF_SIDE_RATIO = 0.3
+    static #MIN_NEGATIVE_STANDOFF_SIDE_MIL = 20
+
+    /**
+     * Resolves which board side one explicit model should mount on.
+     * @param {{ layer?: string, standoffHeightMil?: number | null, overallHeightMil?: number | null }} componentBody
+     * @param {{ layer?: string } | null} matchedComponent
+     * @param {{ layer?: string, pattern?: string, source?: string, modelPath?: string, x?: number, y?: number }[]} components
+     * @returns {'top' | 'bottom'}
+     */
+    static resolvePlacementSide(
+        componentBody,
+        matchedComponent,
+        components = []
+    ) {
+        const matchedSide =
+            PcbScene3dPlacementSideResolver.#resolveComponentLayerSide(
+                matchedComponent?.layer
+            )
+        if (matchedSide) {
+            return matchedSide
+        }
+
+        const standoffSide =
+            PcbScene3dPlacementSideResolver.#resolveStandoffSide(componentBody)
+        if (standoffSide) {
+            return standoffSide
+        }
+
+        const nearbySide =
+            PcbScene3dPlacementSideResolver.#resolveNearbyComponentSide(
+                componentBody,
+                components
+            )
+        if (nearbySide) {
+            return nearbySide
+        }
+
+        return (
+            PcbScene3dPlacementSideResolver.#resolveMechanicalLayerSide(
+                componentBody?.layer
+            ) || 'top'
+        )
+    }
+
+    /**
+     * Resolves the grouping key for repeated component-body matching.
+     * @param {{ modelId?: string, name?: string, identifier?: string }} componentBody
+     * @returns {string}
+     */
+    static resolveBodyGroupKey(componentBody) {
+        return PcbScene3dPlacementSideResolver.#normalizeLookupToken(
+            componentBody?.modelId ||
+                componentBody?.name ||
+                componentBody?.identifier
+        )
+    }
+
+    /**
+     * Scores how strongly one component record appears to belong to one body
+     * record based on shared model/footprint tokens.
+     * @param {{ name?: string, identifier?: string }} componentBody
+     * @param {{ pattern?: string, source?: string, modelPath?: string }} component
+     * @returns {number}
+     */
+    static scoreBodyComponentAffinity(componentBody, component) {
+        const bodyTokens =
+            PcbScene3dPlacementSideResolver.#collectMeaningfulTokens([
+                componentBody?.identifier,
+                String(componentBody?.name || '').replace(/\.[^.]+$/, '')
+            ])
+        const componentTokens =
+            PcbScene3dPlacementSideResolver.#collectMeaningfulTokens([
+                component?.pattern,
+                component?.source,
+                component?.modelPath
+            ])
+        let score = 0
+
+        bodyTokens.forEach((token) => {
+            if (componentTokens.has(token)) {
+                score += token.length
+            }
+        })
+
+        return score
+    }
+
+    /**
+     * Resolves side from the normalized component layer.
+     * @param {string | undefined} layer
+     * @returns {'top' | 'bottom' | null}
+     */
+    static #resolveComponentLayerSide(layer) {
+        const normalized = String(layer || '')
+            .trim()
+            .toUpperCase()
+
+        if (!normalized) {
+            return null
+        }
+
+        if (normalized.includes('BOTTOM') || normalized === 'BOT') {
+            return 'bottom'
+        }
+
+        if (normalized.includes('TOP')) {
+            return 'top'
+        }
+
+        return null
+    }
+
+    /**
+     * Resolves underside bodies from significant negative standoff metadata.
+     * @param {{ standoffHeightMil?: number | null, overallHeightMil?: number | null } | null} componentBody
+     * @returns {'bottom' | null}
+     */
+    static #resolveStandoffSide(componentBody) {
+        const standoff = Number(componentBody?.standoffHeightMil)
+        const overallHeight = Number(componentBody?.overallHeightMil)
+
+        if (!Number.isFinite(standoff) || standoff >= 0) {
+            return null
+        }
+
+        const threshold =
+            Number.isFinite(overallHeight) && overallHeight > 0
+                ? Math.max(
+                      overallHeight *
+                          PcbScene3dPlacementSideResolver
+                              .#NEGATIVE_STANDOFF_SIDE_RATIO,
+                      PcbScene3dPlacementSideResolver
+                          .#MIN_NEGATIVE_STANDOFF_SIDE_MIL
+                  )
+                : PcbScene3dPlacementSideResolver
+                      .#MIN_NEGATIVE_STANDOFF_SIDE_MIL
+
+        return Math.abs(standoff) >= threshold ? 'bottom' : null
+    }
+
+    /**
+     * Resolves side from the nearest footprint-compatible component.
+     * @param {{ positionMil?: { x?: number, y?: number } } & { name?: string, identifier?: string }} componentBody
+     * @param {{ layer?: string, pattern?: string, source?: string, modelPath?: string, x?: number, y?: number }[]} components
+     * @returns {'top' | 'bottom' | null}
+     */
+    static #resolveNearbyComponentSide(componentBody, components) {
+        const candidates = (Array.isArray(components) ? components : [])
+            .map((component) => ({
+                component,
+                side: PcbScene3dPlacementSideResolver.#resolveComponentLayerSide(
+                    component?.layer
+                ),
+                score: PcbScene3dPlacementSideResolver.scoreBodyComponentAffinity(
+                    componentBody,
+                    component
+                ),
+                distance:
+                    PcbScene3dPlacementSideResolver.#distanceBetweenBodyAndComponent(
+                        componentBody,
+                        component
+                    )
+            }))
+            .filter(
+                (candidate) =>
+                    candidate.side &&
+                    candidate.score > 0 &&
+                    candidate.distance <=
+                        PcbScene3dPlacementSideResolver
+                            .#NEARBY_SIDE_HINT_MAX_DISTANCE_MIL
+            )
+            .sort(
+                (left, right) =>
+                    right.score - left.score || left.distance - right.distance
+            )
+
+        return candidates[0]?.side || null
+    }
+
+    /**
+     * Resolves a common Altium top/bottom mechanical layer pair.
+     * @param {string | undefined} layer
+     * @returns {'top' | 'bottom' | null}
+     */
+    static #resolveMechanicalLayerSide(layer) {
+        const match = String(layer || '').match(/^MECHANICAL\s*(\d+)$/i)
+        if (!match) {
+            return null
+        }
+
+        return Number(match[1]) % 2 === 0 ? 'bottom' : 'top'
+    }
+
+    /**
+     * Returns the euclidean distance between one body anchor and one component
+     * anchor.
+     * @param {{ positionMil?: { x?: number, y?: number } }} componentBody
+     * @param {{ x?: number, y?: number }} component
+     * @returns {number}
+     */
+    static #distanceBetweenBodyAndComponent(componentBody, component) {
+        return Math.hypot(
+            Number(component?.x || 0) -
+                Number(componentBody?.positionMil?.x || 0),
+            Number(component?.y || 0) -
+                Number(componentBody?.positionMil?.y || 0)
+        )
+    }
+
+    /**
+     * Collects normalized model tokens from free-form strings.
+     * @param {(string | undefined)[]} values
+     * @returns {Set<string>}
+     */
+    static #collectMeaningfulTokens(values) {
+        const tokens = new Set()
+
+        ;(Array.isArray(values) ? values : []).forEach((value) => {
+            String(value || '')
+                .toLowerCase()
+                .split(/[^a-z0-9]+/g)
+                .forEach((fragment) => {
+                    ;(fragment.match(/[a-z]+|\d+/g) || []).forEach((token) => {
+                        if (
+                            PcbScene3dPlacementSideResolver.#isMeaningfulToken(
+                                token
+                            )
+                        ) {
+                            tokens.add(token)
+                        }
+                    })
+                })
+        })
+
+        return tokens
+    }
+
+    /**
+     * Returns true when one normalized token carries useful model identity.
+     * @param {string} token
+     * @returns {boolean}
+     */
+    static #isMeaningfulToken(token) {
+        return (
+            String(token || '').length >= 2 &&
+            !new Set(['con', 'step', 'stp', 'model', 'default', 'black']).has(
+                String(token || '')
+            )
+        )
+    }
+
+    /**
+     * Normalizes one lookup token for repeated-model grouping.
+     * @param {string | undefined} value
+     * @returns {string}
+     */
+    static #normalizeLookupToken(value) {
+        return String(value || '')
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '')
+    }
+}

package/src/ui/PcbScene3dTextBoxLayoutResolver.mjs

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Resolves Altium TrueType text-box metadata for 3D scene consumers.
+ */
+export class PcbScene3dTextBoxLayoutResolver {
+    static #COMPACT_IMPLICIT_WIDTH_RATIO = 2.25
+
+    /**
+     * Resolves one Altium inverted text box into renderable dimensions.
+     * @param {{ isInverted?: boolean, useInvertedRectangle?: boolean, textboxRectWidth?: number, textboxRectHeight?: number, textboxRectJustification?: number, marginBorderWidth?: number, height?: number }} text
+     * @returns {{ source: string, mode: 'explicit' | 'implicit', compact: boolean, widthMil: number, heightMil: number, marginMil: number, renderWidthMil: number, renderHeightMil: number, justification: { column: number, row: number } | null } | null}
+     */
+    static resolve(text) {
+        const width = Number(text?.textboxRectWidth)
+        const height = Number(text?.textboxRectHeight)
+
+        if (
+            !Boolean(text?.isInverted) ||
+            !Number.isFinite(width) ||
+            !Number.isFinite(height) ||
+            width <= 0 ||
+            height <= 0
+        ) {
+            return null
+        }
+
+        const mode = Boolean(text?.useInvertedRectangle)
+            ? 'explicit'
+            : 'implicit'
+        const margin = PcbScene3dTextBoxLayoutResolver.#margin(text)
+        const compact =
+            mode === 'implicit' &&
+            width <=
+                PcbScene3dTextBoxLayoutResolver.#height(text) *
+                    PcbScene3dTextBoxLayoutResolver
+                        .#COMPACT_IMPLICIT_WIDTH_RATIO
+        const border = compact ? margin * 2 : 0
+
+        return {
+            source: 'altium-textbox',
+            mode,
+            compact,
+            widthMil: width,
+            heightMil: height,
+            marginMil: margin,
+            renderWidthMil: width + border,
+            renderHeightMil: height + border,
+            justification: PcbScene3dTextBoxLayoutResolver.#justification(text)
+        }
+    }
+
+    /**
+     * Resolves one non-negative margin value.
+     * @param {{ marginBorderWidth?: number }} text
+     * @returns {number}
+     */
+    static #margin(text) {
+        const margin = Number(text?.marginBorderWidth)
+
+        return Number.isFinite(margin) && margin >= 0 ? margin : 0
+    }
+
+    /**
+     * Resolves the authored text height used for compact box detection.
+     * @param {{ height?: number }} text
+     * @returns {number}
+     */
+    static #height(text) {
+        return Math.max(Number(text?.height || 0), 1)
+    }
+
+    /**
+     * Decodes Altium's three-by-three text-box justification code.
+     * @param {{ textboxRectJustification?: number }} text
+     * @returns {{ column: number, row: number } | null}
+     */
+    static #justification(text) {
+        const justification = Number(text?.textboxRectJustification)
+
+        if (!Number.isInteger(justification) || justification <= 0) {
+            return null
+        }
+
+        return {
+            column: Math.max(
+                0,
+                Math.min(2, Math.floor((justification - 1) / 3))
+            ),
+            row: (justification - 1) % 3
+        }
+    }
+}