altium-toolkit 1.1.26 → 1.1.30

package/package.json

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

package/src/ui/AltiumScene3dBottomPadRotationAdapter.mjs

@@ -0,0 +1,127 @@
+const BOTTOM_LAYER_ID = 32
+
+/**
+ * Pre-compensates Altium bottom-side pad rotations for shared 3D mirroring.
+ */
+export class AltiumScene3dBottomPadRotationAdapter {
+    /**
+     * Returns a scene with bottom-side pad rotations mirrored for rendering.
+     * @param {object} sceneDescription Scene description.
+     * @returns {object}
+     */
+    static apply(sceneDescription) {
+        const detail = sceneDescription?.detail || {}
+        const detailPads = Array.isArray(detail.pads)
+            ? AltiumScene3dBottomPadRotationAdapter.#mapPads(detail.pads)
+            : detail.pads
+        const scenePads = Array.isArray(sceneDescription?.pads)
+            ? sceneDescription.pads === detail.pads
+                ? detailPads
+                : AltiumScene3dBottomPadRotationAdapter.#mapPads(
+                      sceneDescription.pads
+                  )
+            : sceneDescription?.pads
+
+        if (
+            detailPads === detail.pads &&
+            scenePads === sceneDescription?.pads
+        ) {
+            return sceneDescription
+        }
+
+        return {
+            ...sceneDescription,
+            pads: scenePads,
+            detail: {
+                ...detail,
+                pads: detailPads
+            }
+        }
+    }
+
+    /**
+     * Maps bottom-side pad rotations in one pad list.
+     * @param {object[]} pads Scene pad list.
+     * @returns {object[]}
+     */
+    static #mapPads(pads) {
+        let changed = false
+        const mappedPads = pads.map((pad) => {
+            if (!AltiumScene3dBottomPadRotationAdapter.#isBottomPad(pad)) {
+                return pad
+            }
+
+            const rotation =
+                AltiumScene3dBottomPadRotationAdapter.#normalizeAngle(
+                    -Number(pad?.rotation || 0)
+                )
+            if (
+                AltiumScene3dBottomPadRotationAdapter.#anglesEqual(
+                    rotation,
+                    pad?.rotation
+                )
+            ) {
+                return pad
+            }
+
+            changed = true
+            return {
+                ...pad,
+                rotation
+            }
+        })
+
+        return changed ? mappedPads : pads
+    }
+
+    /**
+     * Returns true when one pad belongs to bottom copper.
+     * @param {object} pad Scene pad.
+     * @returns {boolean}
+     */
+    static #isBottomPad(pad) {
+        const layerId = Number(
+            pad?.layerId ?? pad?.layerCode ?? pad?.sourceLayerId
+        )
+        if (Number.isFinite(layerId) && layerId === BOTTOM_LAYER_ID) {
+            return true
+        }
+
+        const layerName = String(pad?.layer || pad?.layerName || '')
+            .trim()
+            .toUpperCase()
+        if (layerName === 'B.CU' || layerName.includes('BOTTOM')) {
+            return true
+        }
+
+        const sideName = String(pad?.side || pad?.mountSide || '')
+            .trim()
+            .toLowerCase()
+        return sideName === 'bottom' || sideName === 'back'
+    }
+
+    /**
+     * Returns true when two rotations are equal after normalization.
+     * @param {unknown} left First angle.
+     * @param {unknown} right Second angle.
+     * @returns {boolean}
+     */
+    static #anglesEqual(left, right) {
+        return (
+            Math.abs(
+                AltiumScene3dBottomPadRotationAdapter.#normalizeAngle(left) -
+                    AltiumScene3dBottomPadRotationAdapter.#normalizeAngle(right)
+            ) < 0.001
+        )
+    }
+
+    /**
+     * Normalizes an angle into [0, 360).
+     * @param {unknown} angle Angle in degrees.
+     * @returns {number}
+     */
+    static #normalizeAngle(angle) {
+        const value = Number(angle) || 0
+        return ((value % 360) + 360) % 360
+    }
+}

package/src/ui/AltiumScene3dComponentBodyAdapter.mjs

@@ -0,0 +1,153 @@
+import { PcbScene3dPadLocalSpanResolver } from './PcbScene3dPadLocalSpanResolver.mjs'
+
+const REFINABLE_FAMILIES = new Set(['chip', 'diode', 'generic', 'ic', 'sot'])
+
+/**
+ * Refines Altium procedural fallback body sizes from component-owned pads.
+ */
+export class AltiumScene3dComponentBodyAdapter {
+    static #OVERSIZE_RATIO = 1.75
+
+    /**
+     * Applies owned-pad body refinement to an Altium scene description.
+     * @param {object} sceneDescription Scene description.
+     * @param {object} documentModel Source document model.
+     * @returns {object}
+     */
+    static apply(sceneDescription, documentModel) {
+        if (
+            String(sceneDescription?.sourceFormat || '').toLowerCase() !==
+                'altium' ||
+            !Array.isArray(sceneDescription?.components)
+        ) {
+            return sceneDescription
+        }
+
+        const sourceComponents = Array.isArray(documentModel?.pcb?.components)
+            ? documentModel.pcb.components
+            : []
+        const pads = Array.isArray(documentModel?.pcb?.pads)
+            ? documentModel.pcb.pads
+            : []
+        if (!sourceComponents.length || !pads.length) {
+            return sceneDescription
+        }
+
+        const sourceByDesignator = new Map(
+            sourceComponents.map((component) => [
+                String(component?.designator || ''),
+                component
+            ])
+        )
+
+        return {
+            ...sceneDescription,
+            components: sceneDescription.components.map((component) =>
+                AltiumScene3dComponentBodyAdapter.#refineComponent(
+                    component,
+                    sourceByDesignator.get(String(component?.designator || '')),
+                    pads
+                )
+            )
+        }
+    }
+
+    /**
+     * Refines one procedural component body when nearby pads overinflated it.
+     * @param {object} component Scene component.
+     * @param {object | undefined} sourceComponent Source PCB component.
+     * @param {object[]} pads Source PCB pads.
+     * @returns {object}
+     */
+    static #refineComponent(component, sourceComponent, pads) {
+        const family = String(component?.body?.family || '')
+        if (
+            component?.externalModel ||
+            !sourceComponent ||
+            !REFINABLE_FAMILIES.has(family)
+        ) {
+            return component
+        }
+
+        const span = AltiumScene3dComponentBodyAdapter.#ownedPadSpan(
+            sourceComponent,
+            component.mountSide,
+            pads
+        )
+        const size = component?.body?.sizeMil || {}
+        if (
+            !span ||
+            !AltiumScene3dComponentBodyAdapter.#isOversized(size, span)
+        ) {
+            return component
+        }
+
+        return {
+            ...component,
+            body: {
+                ...component.body,
+                sizeMil: {
+                    ...size,
+                    width: span.width,
+                    depth: span.depth
+                }
+            }
+        }
+    }
+
+    /**
+     * Resolves the owned surface-pad span for one source component.
+     * @param {object} component Source component.
+     * @param {string} mountSide Component mount side.
+     * @param {object[]} pads Source PCB pads.
+     * @returns {{ width: number, depth: number } | null}
+     */
+    static #ownedPadSpan(component, mountSide, pads) {
+        const componentIndex = Number(component?.componentIndex)
+        if (!Number.isFinite(componentIndex)) {
+            return null
+        }
+
+        const ownedPads = pads.filter(
+            (pad) => Number(pad?.componentIndex) === componentIndex
+        )
+        const surfacePads = ownedPads.filter((pad) =>
+            AltiumScene3dComponentBodyAdapter.#isSurfacePad(pad, mountSide)
+        )
+        const spanPads = surfacePads.length ? surfacePads : ownedPads
+
+        return PcbScene3dPadLocalSpanResolver.resolve(
+            component,
+            spanPads,
+            mountSide
+        )
+    }
+
+    /**
+     * Checks whether one pad belongs to the component's mounted surface.
+     * @param {object} pad Source pad.
+     * @param {string} mountSide Component mount side.
+     * @returns {boolean}
+     */
+    static #isSurfacePad(pad, mountSide) {
+        return String(mountSide || '').toLowerCase() === 'bottom'
+            ? Boolean(pad?.hasBottomPasteMaskOpening)
+            : Boolean(pad?.hasTopPasteMaskOpening)
+    }
+
+    /**
+     * Checks whether the current body is clearly larger than owned pads.
+     * @param {object} size Current body size.
+     * @param {{ width: number, depth: number }} span Owned pad span.
+     * @returns {boolean}
+     */
+    static #isOversized(size, span) {
+        return (
+            Number(size?.width || 0) >
+                span.width *
+                    AltiumScene3dComponentBodyAdapter.#OVERSIZE_RATIO ||
+            Number(size?.depth || 0) >
+                span.depth * AltiumScene3dComponentBodyAdapter.#OVERSIZE_RATIO
+        )
+    }
+}