altium-toolkit 1.1.32 → 1.1.35

package/src/ui/PcbScene3dCopperRegionDetailBuilder.mjs

@@ -0,0 +1,280 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Converts parsed PCB region primitives into 3D copper fill detail.
+ */
+export class PcbScene3dCopperRegionDetailBuilder {
+    /**
+     * Builds fill-compatible region primitives for 3D copper rendering.
+     * @param {{ regions?: object[], shapeBasedRegions?: object[] } | null} pcb Parsed PCB model.
+     * @returns {object[]}
+     */
+    static build(pcb) {
+        return PcbScene3dCopperRegionDetailBuilder.#sourceRegions(pcb)
+            .filter((region) =>
+                PcbScene3dCopperRegionDetailBuilder.#isCopperFillRegion(region)
+            )
+            .map((region) =>
+                PcbScene3dCopperRegionDetailBuilder.#withSegmentContours(region)
+            )
+    }
+
+    /**
+     * Resolves the region family used by the 2D PCB renderer.
+     * @param {{ regions?: object[], shapeBasedRegions?: object[] } | null} pcb Parsed PCB model.
+     * @returns {object[]}
+     */
+    static #sourceRegions(pcb) {
+        const shapeBasedRegions = Array.isArray(pcb?.shapeBasedRegions)
+            ? pcb.shapeBasedRegions
+            : []
+        if (shapeBasedRegions.length) {
+            return shapeBasedRegions
+        }
+
+        return Array.isArray(pcb?.regions) ? pcb.regions : []
+    }
+
+    /**
+     * Checks whether one region should become rendered copper.
+     * @param {object | null} region Parsed region primitive.
+     * @returns {boolean}
+     */
+    static #isCopperFillRegion(region) {
+        return (
+            PcbScene3dCopperRegionDetailBuilder.#isCopperLayerId(
+                region?.layerId
+            ) &&
+            !PcbScene3dCopperRegionDetailBuilder.#isCutoutOrKeepout(region) &&
+            PcbScene3dCopperRegionDetailBuilder.#pointLoop(region?.points)
+                .length >= 3
+        )
+    }
+
+    /**
+     * Checks whether one layer id belongs to Altium copper.
+     * @param {unknown} layerId Source layer id.
+     * @returns {boolean}
+     */
+    static #isCopperLayerId(layerId) {
+        const normalized = Number(layerId)
+        return (
+            Number.isInteger(normalized) && normalized >= 1 && normalized <= 32
+        )
+    }
+
+    /**
+     * Checks whether one region describes clearance instead of copper.
+     * @param {object | null} region Parsed region primitive.
+     * @returns {boolean}
+     */
+    static #isCutoutOrKeepout(region) {
+        return (
+            region?.isKeepout === true ||
+            region?.isBoardCutout === true ||
+            region?.isPolygonPourCutout === true ||
+            region?.isCutout === true ||
+            Boolean(region?.cutoutClassification) ||
+            PcbScene3dCopperRegionDetailBuilder.#looksLikeCutout(
+                region?.classification
+            ) ||
+            PcbScene3dCopperRegionDetailBuilder.#looksLikeCutout(
+                region?.rawKind
+            ) ||
+            PcbScene3dCopperRegionDetailBuilder.#looksLikeCutout(
+                region?.properties?.KIND
+            )
+        )
+    }
+
+    /**
+     * Checks a native classification token for cutout semantics.
+     * @param {unknown} value Classification token.
+     * @returns {boolean}
+     */
+    static #looksLikeCutout(value) {
+        return String(value || '')
+            .replace(/[^a-z0-9]/giu, '')
+            .toLowerCase()
+            .includes('cutout')
+    }
+
+    /**
+     * Adds segment contours when a region includes arc vertices.
+     * @param {object} region Parsed region primitive.
+     * @returns {object}
+     */
+    static #withSegmentContours(region) {
+        const loops = [
+            region?.points,
+            ...(Array.isArray(region?.holes) ? region.holes : [])
+        ]
+
+        if (
+            !loops.some((loop) =>
+                PcbScene3dCopperRegionDetailBuilder.#hasArcSegment(loop)
+            )
+        ) {
+            return { ...region }
+        }
+
+        const contours = loops
+            .map((loop) =>
+                PcbScene3dCopperRegionDetailBuilder.#segmentContour(loop)
+            )
+            .filter((contour) => contour.length >= 3)
+
+        return contours.length ? { ...region, contours } : { ...region }
+    }
+
+    /**
+     * Checks whether a loop carries arc metadata.
+     * @param {unknown[]} points Candidate loop points.
+     * @returns {boolean}
+     */
+    static #hasArcSegment(points) {
+        return PcbScene3dCopperRegionDetailBuilder.#pointLoop(points).some(
+            (point) => PcbScene3dCopperRegionDetailBuilder.#isArcPoint(point)
+        )
+    }
+
+    /**
+     * Converts one point loop into line and arc segments.
+     * @param {unknown[]} points Candidate loop points.
+     * @returns {object[]}
+     */
+    static #segmentContour(points) {
+        const loop = PcbScene3dCopperRegionDetailBuilder.#pointLoop(points)
+        if (loop.length < 3) {
+            return []
+        }
+
+        const segments = []
+        for (let index = 0; index < loop.length; index += 1) {
+            const current = loop[index]
+            const next = loop[(index + 1) % loop.length]
+            const segment =
+                PcbScene3dCopperRegionDetailBuilder.#arcSegment(
+                    current,
+                    next
+                ) ||
+                PcbScene3dCopperRegionDetailBuilder.#lineSegment(current, next)
+            segments.push(segment)
+        }
+
+        return segments
+    }
+
+    /**
+     * Builds a straight segment between two region vertices.
+     * @param {{ x: number, y: number }} current Start vertex.
+     * @param {{ x: number, y: number }} next End vertex.
+     * @returns {object}
+     */
+    static #lineSegment(current, next) {
+        return {
+            type: 'line',
+            x1: Number(current.x),
+            y1: Number(current.y),
+            x2: Number(next.x),
+            y2: Number(next.y)
+        }
+    }
+
+    /**
+     * Builds an arc segment when the start vertex carries arc metadata.
+     * @param {{ x: number, y: number }} current Start vertex.
+     * @param {{ x: number, y: number }} next End vertex.
+     * @returns {object | null}
+     */
+    static #arcSegment(current, next) {
+        if (!PcbScene3dCopperRegionDetailBuilder.#isArcPoint(current)) {
+            return null
+        }
+
+        const center = PcbScene3dCopperRegionDetailBuilder.#arcCenter(current)
+        const radius = Number(current.radius)
+        if (
+            !center ||
+            !Number.isFinite(radius) ||
+            radius <= 0 ||
+            !Number.isFinite(Number(current.startAngle)) ||
+            !Number.isFinite(Number(current.endAngle))
+        ) {
+            return null
+        }
+
+        return {
+            type: 'arc',
+            x1: Number(current.x),
+            y1: Number(current.y),
+            x2: Number(next.x),
+            y2: Number(next.y),
+            x: center.x,
+            y: center.y,
+            radius,
+            startAngle: Number(current.startAngle),
+            endAngle: Number(current.endAngle)
+        }
+    }
+
+    /**
+     * Resolves one arc center from known region vertex fields.
+     * @param {object} point Region vertex.
+     * @returns {{ x: number, y: number } | null}
+     */
+    static #arcCenter(point) {
+        const x = Number(point?.centerX ?? point?.cx ?? point?.center?.x)
+        const y = Number(point?.centerY ?? point?.cy ?? point?.center?.y)
+        return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : null
+    }
+
+    /**
+     * Checks whether a point starts an arc segment.
+     * @param {object | null} point Region vertex.
+     * @returns {boolean}
+     */
+    static #isArcPoint(point) {
+        return point?.isArc === true && Number(point?.radius) > 0
+    }
+
+    /**
+     * Builds a finite point loop and removes a duplicate closing vertex.
+     * @param {unknown[] | undefined} points Candidate loop points.
+     * @returns {object[]}
+     */
+    static #pointLoop(points) {
+        const loop = (Array.isArray(points) ? points : []).filter((point) =>
+            PcbScene3dCopperRegionDetailBuilder.#isFinitePoint(point)
+        )
+
+        if (loop.length < 2) {
+            return loop
+        }
+
+        const first = loop[0]
+        const last = loop[loop.length - 1]
+        if (
+            Math.abs(Number(first.x) - Number(last.x)) < 1e-6 &&
+            Math.abs(Number(first.y) - Number(last.y)) < 1e-6
+        ) {
+            return loop.slice(0, -1)
+        }
+
+        return loop
+    }
+
+    /**
+     * Checks whether one object carries finite point coordinates.
+     * @param {unknown} point Candidate point.
+     * @returns {boolean}
+     */
+    static #isFinitePoint(point) {
+        return (
+            Number.isFinite(Number(point?.x)) &&
+            Number.isFinite(Number(point?.y))
+        )
+    }
+}

package/src/ui/PcbScene3dModelRegistry.mjs

@@ -104,6 +104,22 @@ export class PcbScene3dModelRegistry {
             return 'step'
         }
 
+        if (lowerCasePath.endsWith('.glb')) {
+            return 'glb'
+        }
+
+        if (lowerCasePath.endsWith('.gltf')) {
+            return 'gltf'
+        }
+
+        if (lowerCasePath.endsWith('.stl')) {
+            return 'stl'
+        }
+
+        if (lowerCasePath.endsWith('.obj')) {
+            return 'obj'
+        }
+
         return ''
     }
 

package/src/ui/PcbScene3dPackageDimensionResolver.mjs

@@ -0,0 +1,107 @@
+/**
+ * Resolves package dimensions from structured component metadata.
+ */
+export class PcbScene3dPackageDimensionResolver {
+    static #MIL_PER_MM = 39.3700787402
+
+    /**
+     * Resolves explicit planar package dimensions in mils.
+     * @param {{ parameters?: Record<string, unknown> } | null | undefined} component Source component.
+     * @returns {{ width: number, depth: number } | null}
+     */
+    static resolvePlanarSize(component) {
+        const parameters = component?.parameters
+        if (
+            !parameters ||
+            typeof parameters !== 'object' ||
+            Array.isArray(parameters)
+        ) {
+            return null
+        }
+
+        const length = PcbScene3dPackageDimensionResolver.#dimensionByKeys(
+            parameters,
+            ['length', 'package length', 'body length']
+        )
+        const width = PcbScene3dPackageDimensionResolver.#dimensionByKeys(
+            parameters,
+            ['width', 'package width', 'body width']
+        )
+        if (!length || !width) {
+            return null
+        }
+
+        return { width: length, depth: width }
+    }
+
+    /**
+     * Finds a dimension parameter by normalized key.
+     * @param {Record<string, unknown>} parameters Component parameters.
+     * @param {string[]} keys Accepted keys.
+     * @returns {number | null}
+     */
+    static #dimensionByKeys(parameters, keys) {
+        const acceptedKeys = new Set(
+            keys.map((key) =>
+                PcbScene3dPackageDimensionResolver.#normalizeKey(key)
+            )
+        )
+
+        for (const [key, value] of Object.entries(parameters)) {
+            if (
+                acceptedKeys.has(
+                    PcbScene3dPackageDimensionResolver.#normalizeKey(key)
+                )
+            ) {
+                const dimension =
+                    PcbScene3dPackageDimensionResolver.#parseDimensionMil(value)
+                if (dimension) {
+                    return dimension
+                }
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Parses one dimension string into mils.
+     * @param {unknown} value Source parameter value.
+     * @returns {number | null}
+     */
+    static #parseDimensionMil(value) {
+        const text = String(value || '').replace(/,/gu, '.')
+        const match = text.match(
+            /(-?\d+(?:\.\d+)?)\s*(mm|millimeters?|mils?|in(?:ch(?:es)?)?|")/iu
+        )
+        if (!match) {
+            return null
+        }
+
+        const amount = Number(match[1])
+        if (!Number.isFinite(amount) || amount <= 0) {
+            return null
+        }
+
+        const unit = String(match[2] || '').toLowerCase()
+        if (unit === 'mm' || unit.startsWith('millimeter')) {
+            return amount * PcbScene3dPackageDimensionResolver.#MIL_PER_MM
+        }
+        if (unit === 'mil' || unit === 'mils') {
+            return amount
+        }
+        return amount * 1000
+    }
+
+    /**
+     * Normalizes one parameter key.
+     * @param {unknown} key Source key.
+     * @returns {string}
+     */
+    static #normalizeKey(key) {
+        return String(key || '')
+            .trim()
+            .toLowerCase()
+            .replace(/\s+/gu, ' ')
+    }
+}

package/src/ui/PcbScene3dPackages.mjs

@@ -2,13 +2,15 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+import { PcbScene3dPackageDimensionResolver } from './PcbScene3dPackageDimensionResolver.mjs'
+
 /**
  * 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 {{ pattern?: string, height?: number | null, parameters?: Record<string, unknown> }} component
      * @param {{ width: number, depth: number }} [padSpan]
      * @returns {{ family: string, sizeMil: { width: number, depth: number, height: number } }}
      */
@@ -23,12 +25,22 @@ export class PcbScene3dPackages {
             Number.isFinite(explicitHeight) && explicitHeight > 0
                 ? explicitHeight
                 : defaults.height
+        const explicitSize =
+            PcbScene3dPackageDimensionResolver.resolvePlanarSize(component)
 
         return {
             family,
             sizeMil: {
-                width: Math.max(defaults.width, Number(padSpan.width) || 0),
-                depth: Math.max(defaults.depth, Number(padSpan.depth) || 0),
+                width: Math.max(
+                    defaults.width,
+                    Number(padSpan.width) || 0,
+                    Number(explicitSize?.width) || 0
+                ),
+                depth: Math.max(
+                    defaults.depth,
+                    Number(padSpan.depth) || 0,
+                    Number(explicitSize?.depth) || 0
+                ),
                 height
             }
         }

package/src/ui/PcbScene3dPadYawResolver.mjs

@@ -0,0 +1,200 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Resolves procedural body yaw from owned PCB pad geometry.
+ */
+export class PcbScene3dPadYawResolver {
+    static #DOMINANT_AXIS_RATIO = 1.25
+    static #EPSILON = 1e-9
+
+    /**
+     * Resolves a component yaw from its owned pad-center distribution.
+     * @param {{ componentIndex?: number, rotation?: number }} component Source component.
+     * @param {object[]} pads Source PCB pads.
+     * @param {'top' | 'bottom' | string} [mountSide] Component mount side.
+     * @returns {number | null}
+     */
+    static resolve(component, pads, mountSide = 'top') {
+        const points = PcbScene3dPadYawResolver.#ownedPadCenters(
+            component,
+            pads,
+            mountSide
+        )
+        if (points.length < 2) {
+            return null
+        }
+
+        const axis = PcbScene3dPadYawResolver.#dominantAxis(points)
+        if (axis === null) {
+            return null
+        }
+
+        return PcbScene3dPadYawResolver.#closestHalfTurnEquivalent(
+            axis,
+            Number(component?.rotation || 0)
+        )
+    }
+
+    /**
+     * Resolves finite owned pad centers, preferring mounted-surface pads.
+     * @param {{ componentIndex?: number }} component Source component.
+     * @param {object[]} pads Source PCB pads.
+     * @param {'top' | 'bottom' | string} mountSide Component mount side.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #ownedPadCenters(component, pads, mountSide) {
+        const componentIndex = Number(component?.componentIndex)
+        if (!Number.isFinite(componentIndex) || !Array.isArray(pads)) {
+            return []
+        }
+
+        const ownedPads = pads.filter(
+            (pad) => Number(pad?.componentIndex) === componentIndex
+        )
+        const surfacePads = ownedPads.filter((pad) =>
+            PcbScene3dPadYawResolver.#isSurfacePad(pad, mountSide)
+        )
+        const yawPads = surfacePads.length ? surfacePads : ownedPads
+
+        return yawPads
+            .map((pad) => PcbScene3dPadYawResolver.#padCenter(pad))
+            .filter(Boolean)
+    }
+
+    /**
+     * Checks whether one pad belongs to the mounted paste-mask side.
+     * @param {object} pad Source pad.
+     * @param {'top' | 'bottom' | string} mountSide Component mount side.
+     * @returns {boolean}
+     */
+    static #isSurfacePad(pad, mountSide) {
+        return String(mountSide || '').toLowerCase() === 'bottom'
+            ? Boolean(pad?.hasBottomPasteMaskOpening)
+            : Boolean(pad?.hasTopPasteMaskOpening)
+    }
+
+    /**
+     * Resolves one finite pad center.
+     * @param {{ x?: number, y?: number }} pad Source pad.
+     * @returns {{ x: number, y: number } | null}
+     */
+    static #padCenter(pad) {
+        const x = Number(pad?.x)
+        const y = Number(pad?.y)
+
+        return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : null
+    }
+
+    /**
+     * Resolves a dominant pad-center axis, modulo 180 degrees.
+     * @param {{ x: number, y: number }[]} points Pad centers.
+     * @returns {number | null}
+     */
+    static #dominantAxis(points) {
+        const mean = PcbScene3dPadYawResolver.#meanPoint(points)
+        let xx = 0
+        let xy = 0
+        let yy = 0
+
+        for (const point of points) {
+            const dx = point.x - mean.x
+            const dy = point.y - mean.y
+            xx += dx * dx
+            xy += dx * dy
+            yy += dy * dy
+        }
+
+        xx /= points.length
+        xy /= points.length
+        yy /= points.length
+
+        const trace = xx + yy
+        const discriminant = Math.sqrt((xx - yy) ** 2 + 4 * xy * xy)
+        const primary = (trace + discriminant) / 2
+        const secondary = (trace - discriminant) / 2
+
+        if (
+            primary <= PcbScene3dPadYawResolver.#EPSILON ||
+            (secondary > PcbScene3dPadYawResolver.#EPSILON &&
+                primary / secondary <
+                    PcbScene3dPadYawResolver.#DOMINANT_AXIS_RATIO)
+        ) {
+            return null
+        }
+
+        return PcbScene3dPadYawResolver.#normalizeHalfTurn(
+            (Math.atan2(2 * xy, xx - yy) * 90) / Math.PI
+        )
+    }
+
+    /**
+     * Resolves the mean point for a non-empty point set.
+     * @param {{ x: number, y: number }[]} points Pad centers.
+     * @returns {{ x: number, y: number }}
+     */
+    static #meanPoint(points) {
+        const sum = points.reduce(
+            (accumulator, point) => ({
+                x: accumulator.x + point.x,
+                y: accumulator.y + point.y
+            }),
+            { x: 0, y: 0 }
+        )
+
+        return {
+            x: sum.x / points.length,
+            y: sum.y / points.length
+        }
+    }
+
+    /**
+     * Selects the 180-degree equivalent closest to the source rotation.
+     * @param {number} axis Dominant axis in degrees.
+     * @param {number} sourceRotation Source component rotation.
+     * @returns {number}
+     */
+    static #closestHalfTurnEquivalent(axis, sourceRotation) {
+        const first = PcbScene3dPadYawResolver.#normalizeAngle(axis)
+        const second = PcbScene3dPadYawResolver.#normalizeAngle(axis + 180)
+        const source = PcbScene3dPadYawResolver.#normalizeAngle(sourceRotation)
+
+        return PcbScene3dPadYawResolver.#angularDistance(first, source) <=
+            PcbScene3dPadYawResolver.#angularDistance(second, source)
+            ? first
+            : second
+    }
+
+    /**
+     * Resolves the smallest angular distance between two directions.
+     * @param {number} left First angle.
+     * @param {number} right Second angle.
+     * @returns {number}
+     */
+    static #angularDistance(left, right) {
+        const distance = Math.abs(
+            PcbScene3dPadYawResolver.#normalizeAngle(left - right)
+        )
+
+        return distance > 180 ? 360 - distance : distance
+    }
+
+    /**
+     * Normalizes an angle to 0 inclusive through 180 exclusive.
+     * @param {number} angle Angle in degrees.
+     * @returns {number}
+     */
+    static #normalizeHalfTurn(angle) {
+        return ((Number(angle || 0) % 180) + 180) % 180
+    }
+
+    /**
+     * Normalizes an angle to 0 inclusive through 360 exclusive.
+     * @param {number} angle Angle in degrees.
+     * @returns {number}
+     */
+    static #normalizeAngle(angle) {
+        return ((Number(angle || 0) % 360) + 360) % 360
+    }
+}