altium-toolkit 1.1.36 → 1.1.38

package/AGENTS.md

@@ -40,6 +40,21 @@
 - Keep parser and renderer fixes universal. Never special-case a specific file
   name, project identifier, fixture helper, or source-derived phrase.
 
+## Fix Quality Rules
+
+- Fixes must always address the general behavior, not a specific example,
+  fixture, file, project, or test case.
+- Do not implement workarounds, cheats, allowlists, hard-coded example handling,
+  or special-case logic to make one sample pass.
+- When you encounter existing workaround code, cheating behavior, or
+  example-specific handling, rewrite it into general-purpose behavior
+  immediately when it is in scope for the change.
+- Keep fixes universal and structural: derive behavior from the underlying data
+  model, format, protocol, or UI contract instead of matching known sample text,
+  filenames, labels, or project identifiers.
+- After fixing code, run the appropriate repo-owned tests and do not modify tests
+  just to make a workaround pass.
+
 ## Testing Guidelines
 
 - Use repo scripts only: `npm test`.

package/package.json

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

package/src/ui/AltiumScene3dAuthoredBodyAnchorAdapter.mjs

@@ -35,6 +35,13 @@ export class AltiumScene3dAuthoredBodyAnchorAdapter {
             return sceneDescription
         }
 
+        const repeatedPlacementKeys =
+            AltiumScene3dAuthoredBodyAnchorAdapter.#repeatedPlacementKeys(
+                sceneDescription.externalPlacements
+            )
+        const pads = Array.isArray(sceneDescription?.detail?.pads)
+            ? sceneDescription.detail.pads
+            : []
         let changed = false
         const externalPlacements = sceneDescription.externalPlacements.map(
             (placement) => {
@@ -52,10 +59,18 @@ export class AltiumScene3dAuthoredBodyAnchorAdapter {
                 }
 
                 changed = true
+                const preservesSourceOriginRepair =
+                    AltiumScene3dAuthoredBodyAnchorAdapter.#isRepeatedOwnedDrilledPadAnchor(
+                        placement,
+                        component,
+                        pads,
+                        repeatedPlacementKeys
+                    )
                 return AltiumScene3dAuthoredBodyAnchorAdapter.#markPlacement(
                     placement,
                     component,
-                    sceneDescription?.board
+                    sceneDescription?.board,
+                    { preservesSourceOriginRepair }
                 )
             }
         )
@@ -84,6 +99,55 @@ export class AltiumScene3dAuthoredBodyAnchorAdapter {
         )
     }
 
+    /**
+     * Finds repeated external-model identities within one built scene.
+     * @param {object[]} placements Scene external placements.
+     * @returns {Set<string>}
+     */
+    static #repeatedPlacementKeys(placements) {
+        const counts = new Map()
+        const placementList = Array.isArray(placements) ? placements : []
+
+        placementList.forEach((placement) => {
+            const key =
+                AltiumScene3dAuthoredBodyAnchorAdapter.#placementIdentityKey(
+                    placement
+                )
+            if (!key) {
+                return
+            }
+
+            counts.set(key, Number(counts.get(key) || 0) + 1)
+        })
+
+        return new Set(
+            [...counts.entries()]
+                .filter(([, count]) => count > 1)
+                .map(([key]) => key)
+        )
+    }
+
+    /**
+     * Builds a stable model-placement identity for repeated body detection.
+     * @param {object} placement External placement.
+     * @returns {string}
+     */
+    static #placementIdentityKey(placement) {
+        const designator = String(placement?.designator || '').trim()
+        const model = placement?.externalModel || {}
+        const modelParts = [
+            model?.origin,
+            model?.sourceStream,
+            model?.relativePath,
+            model?.name,
+            model?.format
+        ].map((value) => String(value || '').trim())
+
+        return designator && modelParts.some(Boolean)
+            ? [designator, ...modelParts].join('::')
+            : ''
+    }
+
     /**
      * Checks whether one placement should bypass runtime pad-fallback
      * recentering.
@@ -97,6 +161,7 @@ export class AltiumScene3dAuthoredBodyAnchorAdapter {
             !component ||
             String(placement?.projection?.source || '').toLowerCase() !==
                 'pad-fallback' ||
+            placement?.projection?.preservePadFallbackCentering ||
             !placement?.positionMil ||
             !placement?.bodyPositionMil
         ) {
@@ -206,33 +271,189 @@ export class AltiumScene3dAuthoredBodyAnchorAdapter {
             .join(' ')
     }
 
+    /**
+     * Checks whether one placement is one member of a repeated drilled-pad
+     * body set whose source-origin repair must remain enabled.
+     * @param {object} placement External placement.
+     * @param {object | undefined} component Matched scene component.
+     * @param {object[]} pads Scene detail pads.
+     * @param {Set<string>} repeatedPlacementKeys Repeated placement keys.
+     * @returns {boolean}
+     */
+    static #isRepeatedOwnedDrilledPadAnchor(
+        placement,
+        component,
+        pads,
+        repeatedPlacementKeys
+    ) {
+        const key =
+            AltiumScene3dAuthoredBodyAnchorAdapter.#placementIdentityKey(
+                placement
+            )
+
+        return (
+            repeatedPlacementKeys.has(key) &&
+            AltiumScene3dAuthoredBodyAnchorAdapter.#isOwnedDrilledPadAnchor(
+                placement,
+                component,
+                pads
+            )
+        )
+    }
+
+    /**
+     * Checks whether the body anchor sits inside a drilled pad owned by the
+     * resolved component.
+     * @param {object} placement External placement.
+     * @param {object | undefined} component Matched scene component.
+     * @param {object[]} pads Scene detail pads.
+     * @returns {boolean}
+     */
+    static #isOwnedDrilledPadAnchor(placement, component, pads) {
+        const componentIndex = Number(component?.componentIndex)
+        if (!Number.isFinite(componentIndex)) {
+            return false
+        }
+
+        const bodyPosition = placement?.bodyPositionMil
+        if (
+            !AltiumScene3dAuthoredBodyAnchorAdapter.#hasFinitePoint(
+                bodyPosition
+            )
+        ) {
+            return false
+        }
+
+        return (Array.isArray(pads) ? pads : []).some(
+            (pad) =>
+                Number(pad?.componentIndex) === componentIndex &&
+                AltiumScene3dAuthoredBodyAnchorAdapter.#hasDrilledPadOpening(
+                    pad
+                ) &&
+                AltiumScene3dAuthoredBodyAnchorAdapter.#padContainsPoint(
+                    pad,
+                    bodyPosition
+                )
+        )
+    }
+
+    /**
+     * Checks whether a pad contains a drilled or slotted board opening.
+     * @param {object} pad Scene detail pad.
+     * @returns {boolean}
+     */
+    static #hasDrilledPadOpening(pad) {
+        const holeGeometry = pad?.holeGeometry || {}
+
+        return [
+            pad?.holeDiameter,
+            pad?.drillDiameter,
+            pad?.holeSize,
+            pad?.holeSlotLength,
+            pad?.slotLength,
+            holeGeometry?.diameter,
+            holeGeometry?.length,
+            holeGeometry?.slotLength
+        ].some((value) => Number(value || 0) > 0)
+    }
+
+    /**
+     * Checks whether one XY point falls inside the effective pad anchor span.
+     * @param {object} pad Scene detail pad.
+     * @param {{ x?: number, y?: number }} point Board-space point.
+     * @returns {boolean}
+     */
+    static #padContainsPoint(pad, point) {
+        if (!AltiumScene3dAuthoredBodyAnchorAdapter.#hasFinitePoint(pad)) {
+            return false
+        }
+
+        const radius =
+            AltiumScene3dAuthoredBodyAnchorAdapter.#padAnchorRadiusMil(pad)
+        return (
+            radius > 0 &&
+            AltiumScene3dAuthoredBodyAnchorAdapter.#distance(pad, point) <=
+                radius +
+                    AltiumScene3dAuthoredBodyAnchorAdapter
+                        .#BODY_ANCHOR_TOLERANCE_MIL
+        )
+    }
+
+    /**
+     * Resolves the effective XY radius around a drilled pad center.
+     * @param {object} pad Scene detail pad.
+     * @returns {number}
+     */
+    static #padAnchorRadiusMil(pad) {
+        const holeGeometry = pad?.holeGeometry || {}
+        const diameter = Math.max(
+            Number(pad?.sizeTopX || 0),
+            Number(pad?.sizeTopY || 0),
+            Number(pad?.sizeMidX || 0),
+            Number(pad?.sizeMidY || 0),
+            Number(pad?.sizeBottomX || 0),
+            Number(pad?.sizeBottomY || 0),
+            Number(pad?.holeDiameter || 0),
+            Number(pad?.drillDiameter || 0),
+            Number(pad?.holeSize || 0),
+            Number(pad?.holeSlotLength || 0),
+            Number(pad?.slotLength || 0),
+            Number(holeGeometry?.diameter || 0),
+            Number(holeGeometry?.length || 0),
+            Number(holeGeometry?.slotLength || 0)
+        )
+
+        return Number.isFinite(diameter) && diameter > 0 ? diameter / 2 : 0
+    }
+
     /**
      * Marks one placement as authored-anchor based.
      * @param {object} placement External placement.
      * @param {object} component Matched scene component.
      * @param {object | undefined} board Scene board.
+     * @param {{ preservesSourceOriginRepair?: boolean }} [options] Marking options.
      * @returns {object}
      */
-    static #markPlacement(placement, component, board) {
+    static #markPlacement(placement, component, board, options = {}) {
+        const reason = options.preservesSourceOriginRepair
+            ? 'Altium repeated component body is anchored in an owned drilled pad, so the runtime preserves the body anchor while allowing embedded source-origin repair.'
+            : 'Altium component body uses an authored model-origin anchor offset from the owner footprint.'
+
         return {
             ...placement,
             projection: {
                 ...(placement.projection || {}),
                 source: AltiumScene3dAuthoredBodyAnchorAdapter.#AUTHORED_SOURCE,
-                reason: 'Altium component body uses an authored model-origin anchor offset from the owner footprint.'
+                reason
             },
-            modelTransform: {
-                ...(placement.modelTransform || {}),
-                ownerAnchorOffsetMil:
-                    AltiumScene3dAuthoredBodyAnchorAdapter.#ownerAnchorOffset(
-                        placement,
-                        component,
-                        board
-                    )
-            }
+            modelTransform: options.preservesSourceOriginRepair
+                ? AltiumScene3dAuthoredBodyAnchorAdapter.#withoutOwnerAnchorOffset(
+                      placement.modelTransform
+                  )
+                : {
+                      ...(placement.modelTransform || {}),
+                      ownerAnchorOffsetMil:
+                          AltiumScene3dAuthoredBodyAnchorAdapter.#ownerAnchorOffset(
+                              placement,
+                              component,
+                              board
+                          )
+                  }
         }
     }
 
+    /**
+     * Removes owner-anchor metadata while preserving renderable transforms.
+     * @param {object | null | undefined} modelTransform Placement transform.
+     * @returns {object}
+     */
+    static #withoutOwnerAnchorOffset(modelTransform) {
+        const { ownerAnchorOffsetMil, ...renderTransform } =
+            modelTransform || {}
+
+        return renderTransform
+    }
+
     /**
      * Resolves the source body offset from its owner footprint anchor.
      * @param {object} placement External placement.
@@ -313,6 +534,18 @@ export class AltiumScene3dAuthoredBodyAnchorAdapter {
         }
     }
 
+    /**
+     * Checks whether a value has finite XY coordinates.
+     * @param {object | undefined} point Source point.
+     * @returns {boolean}
+     */
+    static #hasFinitePoint(point) {
+        return (
+            Number.isFinite(Number(point?.x)) &&
+            Number.isFinite(Number(point?.y))
+        )
+    }
+
     /**
      * Measures XY distance between two points.
      * @param {{ x: number, y: number }} first First point.

package/src/ui/AltiumScene3dAuthoredConnectorYawPolicy.mjs

@@ -0,0 +1,176 @@
+/**
+ * Decides when explicit Altium connector-body yaw should win over footprint
+ * rotation for off-anchor 3D bodies.
+ */
+export class AltiumScene3dAuthoredConnectorYawPolicy {
+    static #CONNECTOR_OWNER_PATTERN =
+        /(?:pin\s*header|pinheader|header|connector|socket|fpc|flex|jtag)/i
+
+    /**
+     * Checks whether an offset connector body should keep Altium's authored
+     * body yaw instead of adopting the footprint yaw.
+     * @param {{ placement?: object, component?: object | null, pads?: object[], ownerOffsetToleranceMil?: number }} context Placement context.
+     * @returns {boolean}
+     */
+    static shouldPreserve(context) {
+        const placement = context?.placement
+        const component = context?.component
+        const ownerOffsetToleranceMil = Number(
+            context?.ownerOffsetToleranceMil || 0
+        )
+
+        if (
+            !component ||
+            !AltiumScene3dAuthoredConnectorYawPolicy.#supportsProjection(
+                placement
+            ) ||
+            AltiumScene3dAuthoredConnectorYawPolicy.#distanceToBody(
+                placement,
+                component
+            ) <= ownerOffsetToleranceMil ||
+            !AltiumScene3dAuthoredConnectorYawPolicy.#hasConnectorOwnerIdentity(
+                component
+            )
+        ) {
+            return false
+        }
+
+        return AltiumScene3dAuthoredConnectorYawPolicy.#hasSingleRowPadGeometry(
+            component,
+            context?.pads
+        )
+    }
+
+    /**
+     * Checks whether one projection can carry an authored off-center connector
+     * source yaw.
+     * @param {object | null | undefined} placement External placement.
+     * @returns {boolean}
+     */
+    static #supportsProjection(placement) {
+        const source = String(placement?.projection?.source || '').toLowerCase()
+
+        return source === 'pad-fallback' || source === 'model-bounds'
+    }
+
+    /**
+     * Checks whether component metadata describes connector/header hardware.
+     * @param {object} component PCB component.
+     * @returns {boolean}
+     */
+    static #hasConnectorOwnerIdentity(component) {
+        return AltiumScene3dAuthoredConnectorYawPolicy.#CONNECTOR_OWNER_PATTERN.test(
+            [
+                component?.designator,
+                component?.pattern,
+                component?.source,
+                component?.description,
+                ...Object.values(component?.parameters || {})
+            ]
+                .map((value) => String(value || ''))
+                .join(' ')
+        )
+    }
+
+    /**
+     * Checks whether owned pads form one long connector row.
+     * @param {object} component PCB component.
+     * @param {object[] | undefined} pads Source PCB pads.
+     * @returns {boolean}
+     */
+    static #hasSingleRowPadGeometry(component, pads) {
+        const measurablePads =
+            AltiumScene3dAuthoredConnectorYawPolicy.#componentPads(
+                component,
+                pads
+            ).filter((pad) =>
+                AltiumScene3dAuthoredConnectorYawPolicy.#isMeasurablePad(pad)
+            )
+        if (measurablePads.length < 3) {
+            return false
+        }
+
+        const xs = measurablePads.map((pad) => Number(pad?.x || 0))
+        const ys = measurablePads.map((pad) => Number(pad?.y || 0))
+        const spreadX = Math.max(...xs) - Math.min(...xs)
+        const spreadY = Math.max(...ys) - Math.min(...ys)
+        const majorSpread = Math.max(spreadX, spreadY)
+        const minorSpread = Math.min(spreadX, spreadY)
+        const maxPadSpan = Math.max(
+            ...measurablePads.map((pad) =>
+                Math.max(
+                    Number(pad?.sizeTopX || 0),
+                    Number(pad?.sizeTopY || 0),
+                    Number(pad?.sizeMidX || 0),
+                    Number(pad?.sizeMidY || 0),
+                    Number(pad?.sizeBottomX || 0),
+                    Number(pad?.sizeBottomY || 0)
+                )
+            )
+        )
+
+        return (
+            majorSpread >= Math.max(100, maxPadSpan * 3) &&
+            minorSpread <= Math.max(10, maxPadSpan * 1.25)
+        )
+    }
+
+    /**
+     * Returns pads owned by one component index.
+     * @param {object} component Owning component.
+     * @param {object[] | undefined} pads Source PCB pads.
+     * @returns {object[]}
+     */
+    static #componentPads(component, pads) {
+        const componentIndex = Number(component?.componentIndex)
+        if (!Number.isFinite(componentIndex)) {
+            return []
+        }
+
+        return (Array.isArray(pads) ? pads : []).filter(
+            (pad) => Number(pad?.componentIndex) === componentIndex
+        )
+    }
+
+    /**
+     * Checks whether one pad has finite coordinates and non-zero dimensions.
+     * @param {object} pad Source PCB pad.
+     * @returns {boolean}
+     */
+    static #isMeasurablePad(pad) {
+        const width = Math.max(
+            Number(pad?.sizeTopX || 0),
+            Number(pad?.sizeMidX || 0),
+            Number(pad?.sizeBottomX || 0)
+        )
+        const depth = Math.max(
+            Number(pad?.sizeTopY || 0),
+            Number(pad?.sizeMidY || 0),
+            Number(pad?.sizeBottomY || 0)
+        )
+
+        return (
+            Number.isFinite(Number(pad?.x)) &&
+            Number.isFinite(Number(pad?.y)) &&
+            width > 0 &&
+            depth > 0
+        )
+    }
+
+    /**
+     * Measures planar distance from placement body anchor to component origin.
+     * @param {object} placement External model placement.
+     * @param {object} component PCB component.
+     * @returns {number}
+     */
+    static #distanceToBody(placement, component) {
+        const dx =
+            Number(placement?.bodyPositionMil?.x || 0) -
+            Number(component?.x || 0)
+        const dy =
+            Number(placement?.bodyPositionMil?.y || 0) -
+            Number(component?.y || 0)
+
+        return Math.hypot(dx, dy)
+    }
+}

package/src/ui/AltiumScene3dBottomSourceHalfTurnPolicy.mjs

@@ -0,0 +1,93 @@
+const BOTTOM_SOURCE_HALF_TURN_PACKAGE_PATTERN =
+    /(?:^|[^a-z0-9])(?:[a-z0-9]*qfn[a-z0-9]*|[a-z0-9]*dfn[a-z0-9]*)(?:$|[^a-z0-9])/i
+
+/**
+ * Resolves whether a bottom-side source-model half-turn is part of the
+ * package's contact-side frame and must survive mount-side normalization.
+ */
+export class AltiumScene3dBottomSourceHalfTurnPolicy {
+    /**
+     * Checks whether a bottom-side model X half-turn should be preserved.
+     * @param {{ component?: object | null, componentBody?: object | null, placement?: object | null, modelTransform?: object | null }} context Placement context.
+     * @returns {boolean}
+     */
+    static shouldPreserve(context = {}) {
+        if (
+            !AltiumScene3dBottomSourceHalfTurnPolicy.#hasSourceHalfTurn(context)
+        ) {
+            return false
+        }
+
+        return BOTTOM_SOURCE_HALF_TURN_PACKAGE_PATTERN.test(
+            AltiumScene3dBottomSourceHalfTurnPolicy.#packageIdentityText(
+                context
+            )
+        )
+    }
+
+    /**
+     * Checks whether source data carries an X-axis half-turn.
+     * @param {{ componentBody?: object | null, modelTransform?: object | null }} context Placement context.
+     * @returns {boolean}
+     */
+    static #hasSourceHalfTurn(context) {
+        const sourceRotation = context?.componentBody?.modelRotationDeg
+        const renderRotation = context?.modelTransform?.rotationDeg
+        const sourceX =
+            sourceRotation?.x !== undefined
+                ? sourceRotation.x
+                : renderRotation?.x
+
+        return (
+            AltiumScene3dBottomSourceHalfTurnPolicy.#normalizeAngle(sourceX) ===
+            180
+        )
+    }
+
+    /**
+     * Builds identity text from the component, source body, and placement.
+     * @param {{ component?: object | null, componentBody?: object | null, placement?: object | null }} context Placement context.
+     * @returns {string}
+     */
+    static #packageIdentityText(context) {
+        const component = context?.component || {}
+        const componentBody = context?.componentBody || {}
+        const placement = context?.placement || {}
+
+        return [
+            component?.pattern,
+            component?.source,
+            component?.description,
+            ...AltiumScene3dBottomSourceHalfTurnPolicy.#recordValues(
+                component?.parameters
+            ),
+            componentBody?.identifier,
+            componentBody?.modelId,
+            componentBody?.name,
+            placement?.externalModel?.name
+        ]
+            .map((value) => String(value || ''))
+            .join(' ')
+    }
+
+    /**
+     * Resolves stringable values from one optional metadata record.
+     * @param {Record<string, unknown> | null | undefined} record Source record.
+     * @returns {unknown[]}
+     */
+    static #recordValues(record) {
+        return record && typeof record === 'object' ? Object.values(record) : []
+    }
+
+    /**
+     * Normalizes one angle into the positive 0-359 degree range.
+     * @param {unknown} angle Source angle.
+     * @returns {number}
+     */
+    static #normalizeAngle(angle) {
+        const numericAngle = Number(angle || 0)
+        const normalized = numericAngle % 360
+
+        return normalized < 0 ? normalized + 360 : normalized
+    }
+}