altium-toolkit 0.1.20 → 0.1.22

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
+        }
+    }
+}

package/src/ui/SchematicImageRenderer.mjs

@@ -6,6 +6,7 @@ import { SchematicSvgUtils } from './SchematicSvgUtils.mjs'
 import { SchematicColorResolver } from './SchematicColorResolver.mjs'
 
 const { escapeHtml, formatNumber, projectSchematicY } = SchematicSvgUtils
+const MISSING_IMAGE_WRAP_SAFETY_FACTOR = 0.96
 
 /**
  * Renders normalized schematic image placements.
@@ -13,7 +14,7 @@ const { escapeHtml, formatNumber, projectSchematicY } = SchematicSvgUtils
 export class SchematicImageRenderer {
     /**
      * Builds markup for embedded schematic images and unresolved placeholders.
-     * @param {{ x: number, y: number, cornerX: number, cornerY: number, mimeType?: string, dataBase64?: string, diagnosticState?: string, keepAspect?: boolean }[]} images
+     * @param {{ x: number, y: number, cornerX: number, cornerY: number, fileName?: string, mimeType?: string, dataBase64?: string, diagnosticState?: string, keepAspect?: boolean }[]} images
      * @param {number} sheetHeight
      * @returns {string}
      */
@@ -63,20 +64,16 @@ export class SchematicImageRenderer {
 
     /**
      * Builds one placeholder frame when an image payload is unavailable.
-     * @param {{ x: number, y: number, cornerX: number, cornerY: number }} image
+     * @param {{ x: number, y: number, cornerX: number, cornerY: number, fileName?: string }} image
      * @param {number} sheetHeight
      * @returns {string}
      */
     static #buildPlaceholderMarkup(image, sheetHeight) {
         const bounds = SchematicImageRenderer.#resolveBounds(image, sheetHeight)
-        const stroke = SchematicColorResolver.resolveColor(
-            '#c0c0c0',
-            '--schematic-note-border-color'
-        )
 
         return (
             '<g class="schematic-image-placeholder">' +
-            '<rect x="' +
+            '<svg x="' +
             formatNumber(bounds.x) +
             '" y="' +
             formatNumber(bounds.y) +
@@ -84,35 +81,140 @@ export class SchematicImageRenderer {
             formatNumber(bounds.width) +
             '" height="' +
             formatNumber(bounds.height) +
-            '" fill="none" stroke="' +
-            escapeHtml(stroke) +
-            '" stroke-width="1" />' +
-            '<line x1="' +
-            formatNumber(bounds.x) +
-            '" y1="' +
-            formatNumber(bounds.y) +
-            '" x2="' +
-            formatNumber(bounds.x + bounds.width) +
-            '" y2="' +
-            formatNumber(bounds.y + bounds.height) +
-            '" stroke="' +
-            escapeHtml(stroke) +
-            '" stroke-width="1" />' +
-            '<line x1="' +
-            formatNumber(bounds.x) +
-            '" y1="' +
-            formatNumber(bounds.y + bounds.height) +
-            '" x2="' +
-            formatNumber(bounds.x + bounds.width) +
-            '" y2="' +
-            formatNumber(bounds.y) +
-            '" stroke="' +
-            escapeHtml(stroke) +
-            '" stroke-width="1" />' +
+            '" overflow="hidden">' +
+            SchematicImageRenderer.#buildMissingImageMessageMarkup(
+                image,
+                bounds
+            ) +
+            '</svg>' +
             '</g>'
         )
     }
 
+    /**
+     * Builds the visible message shown by Altium for unavailable image files.
+     * @param {{ fileName?: string }} image
+     * @param {{ x: number, y: number, width: number, height: number }} bounds
+     * @returns {string}
+     */
+    static #buildMissingImageMessageMarkup(image, bounds) {
+        const padding = Math.min(6, Math.max(bounds.width * 0.08, 2))
+        const fontSize = Math.min(8, Math.max(bounds.height / 18, 5))
+        const lineHeight = fontSize * 1.18
+        const usableWidth = Math.max(bounds.width - padding * 2, 1)
+        const lines = SchematicImageRenderer.#buildMissingImageMessageLines(
+            image.fileName,
+            usableWidth * MISSING_IMAGE_WRAP_SAFETY_FACTOR,
+            fontSize
+        )
+        const textColor = SchematicColorResolver.resolveColor(
+            '#2c3134',
+            '--schematic-text-color'
+        )
+        const startX = padding
+        const startY = padding + fontSize
+
+        return (
+            '<text class="schematic-image-placeholder-message" x="' +
+            formatNumber(startX) +
+            '" y="' +
+            formatNumber(startY) +
+            '" fill="' +
+            escapeHtml(textColor) +
+            '" font-family="Times New Roman" font-size="' +
+            formatNumber(fontSize) +
+            '">' +
+            lines
+                .map(
+                    (line, index) =>
+                        '<tspan x="' +
+                        formatNumber(startX) +
+                        '" dy="' +
+                        formatNumber(index === 0 ? 0 : lineHeight) +
+                        '">' +
+                        escapeHtml(line) +
+                        '</tspan>'
+                )
+                .join('') +
+            '</text>'
+        )
+    }
+
+    /**
+     * Wraps one missing-image message to the image placeholder width.
+     * @param {string | undefined} fileName
+     * @param {number} width
+     * @param {number} fontSize
+     * @returns {string[]}
+     */
+    static #buildMissingImageMessageLines(fileName, width, fontSize) {
+        return [
+            'Cannot open file',
+            ...SchematicImageRenderer.#wrapMissingImageFileName(
+                fileName || 'image file',
+                width,
+                fontSize
+            ),
+            '. File does not exist.'
+        ]
+    }
+
+    /**
+     * Wraps file names using conservative estimated rendered glyph widths.
+     * @param {string} fileName
+     * @param {number} width
+     * @param {number} fontSize
+     * @returns {string[]}
+     */
+    static #wrapMissingImageFileName(fileName, width, fontSize) {
+        const maxWidth = Math.max(Number(width || 0), 1)
+        const value = String(fileName || '').trim()
+        const lines = []
+        let line = ''
+        let lineWidth = 0
+
+        for (const character of value) {
+            const characterWidth =
+                SchematicImageRenderer.#estimateMissingImageCharacterWidth(
+                    character,
+                    fontSize
+                )
+
+            if (line && lineWidth + characterWidth > maxWidth) {
+                lines.push(line)
+                line = character
+                lineWidth = characterWidth
+                continue
+            }
+
+            line += character
+            lineWidth += characterWidth
+        }
+
+        if (line) {
+            lines.push(line)
+        }
+
+        return lines.length ? lines : ['image file']
+    }
+
+    /**
+     * Estimates one placeholder glyph width for Times-like schematic text.
+     * @param {string} character
+     * @param {number} fontSize
+     * @returns {number}
+     */
+    static #estimateMissingImageCharacterWidth(character, fontSize) {
+        if (/[^\x00-\x7F]/u.test(character)) return fontSize
+        if (/[A-Z]/.test(character)) return fontSize * 0.62
+        if (/[a-z]/.test(character)) return fontSize * 0.45
+        if (/[0-9]/.test(character)) return fontSize * 0.5
+        if (/[\\/]/.test(character)) return fontSize * 0.32
+        if (/[.:\-_]/.test(character)) return fontSize * 0.28
+
+        return fontSize * 0.35
+    }
+
     /**
      * Resolves one image placement into SVG-space bounds.
      * @param {{ x: number, y: number, cornerX: number, cornerY: number }} image

package/src/ui/SchematicJunctionRenderer.mjs

@@ -13,7 +13,7 @@ const { escapeHtml, formatNumber, projectSchematicY } = SchematicSvgUtils
 export class SchematicJunctionRenderer {
     /**
      * Builds junction-dot markup from connected wire linework.
-     * @param {{ x1: number, y1: number, x2: number, y2: number, color: string, ownerIndex?: string, isBus?: boolean }[]} lines
+     * @param {{ x1: number, y1: number, x2: number, y2: number, color: string, ownerIndex?: string, isBus?: boolean, recordType?: string }[]} lines
      * @param {{ x: number, y: number }[]} crosses
      * @param {{ x: number, y: number, width: number, direction?: 'left' | 'right' | 'up' | 'down' }[]} [ports]
      * @param {{ x: number, y: number, style?: number, powerPortDirection?: 'up' | 'down' | 'left' | 'right' }[]} [powerPorts]
@@ -53,15 +53,15 @@ export class SchematicJunctionRenderer {
 
     /**
      * Resolves all wire-junction points that should display a connection dot.
-     * @param {{ x1: number, y1: number, x2: number, y2: number, color: string, ownerIndex?: string, isBus?: boolean }[]} lines
+     * @param {{ x1: number, y1: number, x2: number, y2: number, color: string, ownerIndex?: string, isBus?: boolean, recordType?: string }[]} lines
      * @param {{ x: number, y: number }[]} crosses
      * @param {{ x: number, y: number, width: number, direction?: 'left' | 'right' | 'up' | 'down' }[]} ports
      * @param {{ x: number, y: number, style?: number, powerPortDirection?: 'up' | 'down' | 'left' | 'right' }[]} powerPorts
      * @returns {{ x: number, y: number, color: string }[]}
      */
     static #resolveJunctions(lines, crosses, ports, powerPorts) {
-        const wireLines = lines.filter(
-            (line) => !line.ownerIndex && line.isBus !== true
+        const wireLines = lines.filter((line) =>
+            SchematicJunctionRenderer.#isElectricalWireLine(line)
         )
         const verticalPorts = ports.filter((port) =>
             SchematicJunctionRenderer.#isVerticalPort(port)
@@ -370,6 +370,24 @@ export class SchematicJunctionRenderer {
         )
     }
 
+    /**
+     * Returns true when one line can participate in synthetic electrical
+     * junction dots.
+     * @param {{ ownerIndex?: string, isBus?: boolean, recordType?: string }} line
+     * @returns {boolean}
+     */
+    static #isElectricalWireLine(line) {
+        if (line?.ownerIndex || line?.isBus === true) {
+            return false
+        }
+
+        if (!Object.prototype.hasOwnProperty.call(line || {}, 'recordType')) {
+            return true
+        }
+
+        return !['6', '7', '26'].includes(String(line.recordType || ''))
+    }
+
     /**
      * Builds a stable map key for one point.
      * @param {{ x: number, y: number }} point