altium-toolkit 1.1.36 → 1.1.37

package/src/ui/PcbScene3dModelRegistry.mjs

@@ -2,6 +2,10 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+const MILS_PER_METER = 39370.07874015748
+const MILS_PER_MILLIMETER = 1000 / 25.4
+const MILS_PER_INCH = 1000
+
 /**
  * Indexes session companion assets for 3D model lookup.
  */
@@ -9,12 +13,12 @@ export class PcbScene3dModelRegistry {
     /** @type {{ file?: File | Blob | null, name: string, relativePath: string, format: string, source: string, normalizedPath: string, normalizedBaseName: string }[]} */
     #modelFiles
 
-    /** @type {{ id: string, checksum: number | null, name: string, format: string, payloadText: string, sourceStream: string, normalizedId: string, normalizedBaseName: string }[]} */
+    /** @type {{ id: string, checksum: number | null, name: string, format: string, payloadText: string, sourceStream: string, normalizedId: string, normalizedBaseName: string, boundsMil?: { width: number, depth: number, height: number }, transform?: { rotationDeg?: { x?: number, y?: number, z?: number }, dzMil?: number } }[]} */
     #embeddedModels
 
     /**
      * @param {{ file?: File | Blob | null, name: string, relativePath: string, format: string, source: string, normalizedPath: string, normalizedBaseName: string }[]} modelFiles
-     * @param {{ id: string, checksum: number | null, name: string, format: string, payloadText: string, sourceStream: string, normalizedId: string, normalizedBaseName: string }[]} embeddedModels
+     * @param {{ id: string, checksum: number | null, name: string, format: string, payloadText: string, sourceStream: string, normalizedId: string, normalizedBaseName: string, boundsMil?: { width: number, depth: number, height: number }, transform?: { rotationDeg?: { x?: number, y?: number, z?: number }, dzMil?: number } }[]} embeddedModels
      */
     constructor(modelFiles, embeddedModels) {
         this.#modelFiles = modelFiles
@@ -24,7 +28,7 @@ export class PcbScene3dModelRegistry {
     /**
      * Creates one model registry from session files.
      * @param {{ name?: string, relativePath?: string, source?: string }[]} sessionFiles
-     * @param {{ id?: string, checksum?: number | null, name?: string, format?: string, payloadText?: string, sourceStream?: string }[]} [embeddedModels]
+     * @param {{ id?: string, checksum?: number | null, name?: string, format?: string, payloadText?: string, sourceStream?: string, transform?: object }[]} [embeddedModels]
      * @returns {PcbScene3dModelRegistry}
      */
     static create(sessionFiles, embeddedModels = []) {
@@ -223,11 +227,16 @@ export class PcbScene3dModelRegistry {
      * Resolves the best available model for one normalized component-body
      * placement.
      * @param {{ modelId?: string, checksum?: number | null, name?: string }} componentBody
-     * @returns {{ origin: 'embedded' | 'session', file?: File | Blob | null, name: string, relativePath?: string, format: string, payloadText?: string, sourceStream?: string } | null}
+     * @returns {{ origin: 'embedded' | 'session', file?: File | Blob | null, name: string, relativePath?: string, format: string, payloadText?: string, sourceStream?: string, boundsMil?: { width: number, depth: number, height: number }, transform?: { rotationDeg?: { x?: number, y?: number, z?: number }, dzMil?: number } } | null}
      */
     resolveComponentBodyModel(componentBody) {
         const embeddedMatch = this.#resolveEmbeddedMatch(componentBody)
-        if (embeddedMatch) {
+        if (
+            embeddedMatch &&
+            PcbScene3dModelRegistry.#isRenderableEmbeddedFormat(
+                embeddedMatch.format
+            )
+        ) {
             return embeddedMatch
         }
 
@@ -279,8 +288,8 @@ export class PcbScene3dModelRegistry {
 
     /**
      * Normalizes one embedded payload for registry lookup.
-     * @param {{ id?: string, checksum?: number | null, name?: string, format?: string, payloadText?: string, sourceStream?: string }} model
-     * @returns {{ id: string, checksum: number | null, name: string, format: string, payloadText: string, sourceStream: string, normalizedId: string, normalizedBaseName: string } | null}
+     * @param {{ id?: string, checksum?: number | null, name?: string, format?: string, payloadText?: string, sourceStream?: string, transform?: object }} model
+     * @returns {{ id: string, checksum: number | null, name: string, format: string, payloadText: string, sourceStream: string, normalizedId: string, normalizedBaseName: string, boundsMil?: { width: number, depth: number, height: number }, transform?: { rotationDeg?: { x?: number, y?: number, z?: number }, dzMil?: number } } | null}
      */
     static #normalizeEmbeddedModel(model) {
         const id = String(model?.id || '').trim()
@@ -293,6 +302,14 @@ export class PcbScene3dModelRegistry {
             return null
         }
 
+        const boundsMil = PcbScene3dModelRegistry.#resolveEmbeddedBoundsMil(
+            format,
+            payloadText
+        )
+        const transform = PcbScene3dModelRegistry.#normalizeModelTransform(
+            model?.transform
+        )
+
         return {
             id,
             checksum: Number.isFinite(Number(model?.checksum))
@@ -305,14 +322,16 @@ export class PcbScene3dModelRegistry {
             normalizedId: PcbScene3dModelRegistry.#normalizeToken(id),
             normalizedBaseName: PcbScene3dModelRegistry.#normalizeToken(
                 name.replace(/\.[^.]+$/, '')
-            )
+            ),
+            ...(boundsMil ? { boundsMil } : {}),
+            ...(transform ? { transform } : {})
         }
     }
 
     /**
      * Resolves one embedded model match from authored model metadata.
      * @param {{ modelId?: string, checksum?: number | null, name?: string }} componentBody
-     * @returns {{ origin: 'embedded', name: string, format: string, payloadText: string, sourceStream: string } | null}
+     * @returns {{ origin: 'embedded', name: string, format: string, payloadText: string, sourceStream: string, boundsMil?: { width: number, depth: number, height: number }, transform?: { rotationDeg?: { x?: number, y?: number, z?: number }, dzMil?: number } } | null}
      */
     #resolveEmbeddedMatch(componentBody) {
         const normalizedId = PcbScene3dModelRegistry.#normalizeToken(
@@ -351,7 +370,189 @@ export class PcbScene3dModelRegistry {
             name: embeddedMatch.name,
             format: embeddedMatch.format,
             payloadText: embeddedMatch.payloadText,
-            sourceStream: embeddedMatch.sourceStream
+            sourceStream: embeddedMatch.sourceStream,
+            ...(embeddedMatch.boundsMil
+                ? { boundsMil: embeddedMatch.boundsMil }
+                : {}),
+            ...(embeddedMatch.transform
+                ? { transform: embeddedMatch.transform }
+                : {})
+        }
+    }
+
+    /**
+     * Normalizes optional embedded model transform metadata.
+     * @param {object | null | undefined} transform Source transform metadata.
+     * @returns {{ rotationDeg?: { x?: number, y?: number, z?: number }, dzMil?: number } | null}
+     */
+    static #normalizeModelTransform(transform) {
+        if (!transform || typeof transform !== 'object') {
+            return null
+        }
+
+        const normalized = {}
+        const sourceRotation = transform.rotationDeg || {}
+        const rotationDeg = {}
+        for (const axis of ['x', 'y', 'z']) {
+            const value = Number(sourceRotation?.[axis])
+            if (Number.isFinite(value)) {
+                rotationDeg[axis] = value
+            }
+        }
+        if (Object.keys(rotationDeg).length) {
+            normalized.rotationDeg = rotationDeg
+        }
+
+        const dzMil = Number(transform.dzMil)
+        if (Number.isFinite(dzMil)) {
+            normalized.dzMil = dzMil
+        }
+
+        return Object.keys(normalized).length ? normalized : null
+    }
+
+    /**
+     * Resolves an embedded model envelope in mils when the payload format is
+     * inspectable without a geometry engine.
+     * @param {string} format Embedded model format.
+     * @param {string} payloadText Embedded model text payload.
+     * @returns {{ width: number, depth: number, height: number } | null}
+     */
+    static #resolveEmbeddedBoundsMil(format, payloadText) {
+        const normalizedFormat = String(format || '').toLowerCase()
+        if (normalizedFormat !== 'step' && normalizedFormat !== 'stp') {
+            return null
+        }
+
+        return PcbScene3dModelRegistry.#resolveStepBoundsMil(payloadText)
+    }
+
+    /**
+     * Resolves a STEP payload envelope from authored Cartesian points.
+     * @param {string} payloadText STEP text payload.
+     * @returns {{ width: number, depth: number, height: number } | null}
+     */
+    static #resolveStepBoundsMil(payloadText) {
+        const text = String(payloadText || '')
+        const points = []
+        const pointPattern =
+            /CARTESIAN_POINT\s*\(\s*(?:'[^']*'|[^,]*),\s*\(([^)]*)\)\s*\)/giu
+        let match = pointPattern.exec(text)
+
+        while (match) {
+            const coordinates = String(match[1] || '')
+                .split(',')
+                .slice(0, 3)
+                .map((value) => Number(value.trim()))
+            if (
+                coordinates.length === 3 &&
+                coordinates.every((value) => Number.isFinite(value))
+            ) {
+                points.push(coordinates)
+            }
+
+            match = pointPattern.exec(text)
+        }
+
+        if (points.length < 2) {
+            return null
+        }
+
+        const scale = PcbScene3dModelRegistry.#resolveStepMilScale(text)
+        const [firstPoint] = points
+        const bounds = {
+            minX: firstPoint[0],
+            maxX: firstPoint[0],
+            minY: firstPoint[1],
+            maxY: firstPoint[1],
+            minZ: firstPoint[2],
+            maxZ: firstPoint[2]
+        }
+
+        points.slice(1).forEach(([x, y, z]) => {
+            bounds.minX = Math.min(bounds.minX, x)
+            bounds.maxX = Math.max(bounds.maxX, x)
+            bounds.minY = Math.min(bounds.minY, y)
+            bounds.maxY = Math.max(bounds.maxY, y)
+            bounds.minZ = Math.min(bounds.minZ, z)
+            bounds.maxZ = Math.max(bounds.maxZ, z)
+        })
+
+        return {
+            width: (bounds.maxX - bounds.minX) * scale,
+            depth: (bounds.maxY - bounds.minY) * scale,
+            height: (bounds.maxZ - bounds.minZ) * scale
+        }
+    }
+
+    /**
+     * Resolves the STEP length-unit scale to mils.
+     * @param {string} payloadText STEP text payload.
+     * @returns {number}
+     */
+    static #resolveStepMilScale(payloadText) {
+        const text = String(payloadText || '').toUpperCase()
+        if (/\bINCH\b|\.INCH\./u.test(text)) {
+            return MILS_PER_INCH
+        }
+
+        const siUnitMatch = text.match(
+            /SI_UNIT\s*\(\s*(\.[A-Z]+\.|\$)\s*,\s*\.METRE\.\s*\)/u
+        )
+        if (siUnitMatch) {
+            return (
+                PcbScene3dModelRegistry.#metricPrefixMeterScale(
+                    siUnitMatch[1]
+                ) * MILS_PER_METER
+            )
+        }
+
+        return MILS_PER_MILLIMETER
+    }
+
+    /**
+     * Resolves one SI metric prefix into metres per STEP coordinate unit.
+     * @param {string} prefix STEP SI prefix token.
+     * @returns {number}
+     */
+    static #metricPrefixMeterScale(prefix) {
+        switch (String(prefix || '').toUpperCase()) {
+            case '.EXA.':
+                return 1e18
+            case '.PETA.':
+                return 1e15
+            case '.TERA.':
+                return 1e12
+            case '.GIGA.':
+                return 1e9
+            case '.MEGA.':
+                return 1e6
+            case '.KILO.':
+                return 1e3
+            case '.HECTO.':
+                return 1e2
+            case '.DECA.':
+                return 1e1
+            case '$':
+                return 1
+            case '.DECI.':
+                return 1e-1
+            case '.CENTI.':
+                return 1e-2
+            case '.MILLI.':
+                return 1e-3
+            case '.MICRO.':
+                return 1e-6
+            case '.NANO.':
+                return 1e-9
+            case '.PICO.':
+                return 1e-12
+            case '.FEMTO.':
+                return 1e-15
+            case '.ATTO.':
+                return 1e-18
+            default:
+                return 1e-3
         }
     }
 
@@ -364,6 +565,17 @@ export class PcbScene3dModelRegistry {
         return format === 'wrl' ? 0 : 1
     }
 
+    /**
+     * Checks whether one embedded payload format can be loaded inline.
+     * @param {string} format Embedded payload format.
+     * @returns {boolean}
+     */
+    static #isRenderableEmbeddedFormat(format) {
+        return ['step', 'stp', 'wrl'].includes(
+            String(format || '').toLowerCase()
+        )
+    }
+
     /**
      * Checks whether one model path is in a conventional board model folder.
      * @param {string | undefined} relativePath

package/src/ui/PcbScene3dPlacementSideResolver.mjs

@@ -9,10 +9,21 @@ 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
+    static #IGNORED_IDENTITY_TOKENS = new Set([
+        'con',
+        'step',
+        'stp',
+        'model',
+        'default',
+        'black'
+    ])
+    static #BODY_TOKEN_CACHE = new WeakMap()
+    static #COMPONENT_TOKEN_CACHE = new WeakMap()
+    static #AFFINITY_SCORE_CACHE = new WeakMap()
 
     /**
      * Resolves which board side one explicit model should mount on.
-     * @param {{ layer?: string, positionMil?: { x?: number, y?: number }, standoffHeightMil?: number | null, overallHeightMil?: number | null }} componentBody
+     * @param {{ layer?: string, positionMil?: { x?: number, y?: number }, dzMil?: number | null, 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
      * @param {{ minX?: number, minY?: number, widthMil?: number, heightMil?: number } | null} board
@@ -34,14 +45,21 @@ export class PcbScene3dPlacementSideResolver {
 
         const standoffSide =
             PcbScene3dPlacementSideResolver.#resolveStandoffSide(componentBody)
+        const trustedStandoffSide =
+            PcbScene3dPlacementSideResolver.#shouldTrustStandoffSide(
+                componentBody,
+                standoffSide
+            )
+                ? standoffSide
+                : null
         if (
-            standoffSide &&
+            trustedStandoffSide &&
             PcbScene3dPlacementSideResolver.#isBodyAnchorInsideBoard(
                 componentBody,
                 board
             )
         ) {
-            return standoffSide
+            return trustedStandoffSide
         }
 
         const nearbySide =
@@ -61,14 +79,14 @@ export class PcbScene3dPlacementSideResolver {
             return mechanicalSide
         }
 
-        return standoffSide || 'top'
+        return trustedStandoffSide || 'top'
     }
 
     /**
      * Resolves which board side one authored static shape body should mount on.
      * Shape bodies carry explicit mechanical-layer intent, so that side wins
      * over loose nearby-package identity unless the body was directly matched.
-     * @param {{ layer?: string, positionMil?: { x?: number, y?: number }, standoffHeightMil?: number | null, overallHeightMil?: number | null }} componentBody
+     * @param {{ layer?: string, positionMil?: { x?: number, y?: number }, dzMil?: number | null, 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
      * @param {{ minX?: number, minY?: number, widthMil?: number, heightMil?: number } | null} board
@@ -90,14 +108,21 @@ export class PcbScene3dPlacementSideResolver {
 
         const standoffSide =
             PcbScene3dPlacementSideResolver.#resolveStandoffSide(componentBody)
+        const trustedStandoffSide =
+            PcbScene3dPlacementSideResolver.#shouldTrustStandoffSide(
+                componentBody,
+                standoffSide
+            )
+                ? standoffSide
+                : null
         if (
-            standoffSide &&
+            trustedStandoffSide &&
             PcbScene3dPlacementSideResolver.#isBodyAnchorInsideBoard(
                 componentBody,
                 board
             )
         ) {
-            return standoffSide
+            return trustedStandoffSide
         }
 
         const mechanicalSide =
@@ -117,7 +142,7 @@ export class PcbScene3dPlacementSideResolver {
             return nearbySide
         }
 
-        return standoffSide || 'top'
+        return trustedStandoffSide || 'top'
     }
 
     /**
@@ -141,21 +166,39 @@ export class PcbScene3dPlacementSideResolver {
      * @returns {number}
      */
     static scoreBodyComponentAffinity(componentBody, component) {
+        const bodyValues =
+            PcbScene3dPlacementSideResolver.#bodyAffinityValues(componentBody)
+        const componentValues =
+            PcbScene3dPlacementSideResolver.#componentAffinityValues(component)
+        const bodyKey =
+            PcbScene3dPlacementSideResolver.#cacheIdentityKey(bodyValues)
+        const componentKey =
+            PcbScene3dPlacementSideResolver.#cacheIdentityKey(componentValues)
+        const cachedScore =
+            PcbScene3dPlacementSideResolver.#cachedAffinityScore(
+                componentBody,
+                component,
+                bodyKey,
+                componentKey
+            )
+        if (cachedScore !== null) {
+            return cachedScore
+        }
+
         const bodyTokens =
-            PcbScene3dPlacementSideResolver.#collectMeaningfulTokens([
-                componentBody?.identifier,
-                String(componentBody?.name || '').replace(/\.[^.]+$/, '')
-            ])
+            PcbScene3dPlacementSideResolver.#cachedMeaningfulTokens(
+                PcbScene3dPlacementSideResolver.#BODY_TOKEN_CACHE,
+                componentBody,
+                bodyKey,
+                bodyValues
+            )
         const componentTokens =
-            PcbScene3dPlacementSideResolver.#collectMeaningfulTokens([
-                component?.pattern,
-                component?.source,
-                component?.modelPath,
-                component?.description,
-                ...PcbScene3dPlacementSideResolver.#componentPackageMetadata(
-                    component
-                )
-            ])
+            PcbScene3dPlacementSideResolver.#cachedMeaningfulTokens(
+                PcbScene3dPlacementSideResolver.#COMPONENT_TOKEN_CACHE,
+                component,
+                componentKey,
+                componentValues
+            )
         let score = 0
 
         bodyTokens.forEach((token) => {
@@ -164,9 +207,166 @@ export class PcbScene3dPlacementSideResolver {
             }
         })
 
+        PcbScene3dPlacementSideResolver.#cacheAffinityScore(
+            componentBody,
+            component,
+            bodyKey,
+            componentKey,
+            score
+        )
+
         return score
     }
 
+    /**
+     * Resolves body identity fields used for affinity scoring.
+     * @param {{ name?: string, identifier?: string } | null | undefined} componentBody Component-body record.
+     * @returns {(string | undefined)[]}
+     */
+    static #bodyAffinityValues(componentBody) {
+        return [
+            componentBody?.identifier,
+            String(componentBody?.name || '').replace(/\.[^.]+$/, '')
+        ]
+    }
+
+    /**
+     * Resolves component identity fields used for affinity scoring.
+     * @param {{ pattern?: string, source?: string, modelPath?: string, description?: string, parameters?: object, provenance?: object } | null | undefined} component Component record.
+     * @returns {(string | undefined)[]}
+     */
+    static #componentAffinityValues(component) {
+        return [
+            component?.pattern,
+            component?.source,
+            component?.modelPath,
+            component?.description,
+            ...PcbScene3dPlacementSideResolver.#componentPackageMetadata(
+                component
+            )
+        ]
+    }
+
+    /**
+     * Resolves a deterministic key for identity fields.
+     * @param {unknown[]} values Identity field values.
+     * @returns {string}
+     */
+    static #cacheIdentityKey(values) {
+        return (Array.isArray(values) ? values : [])
+            .map((value) => String(value || ''))
+            .join('\u0000')
+    }
+
+    /**
+     * Returns a cached score when both input identity keys still match.
+     * @param {unknown} componentBody Component-body record.
+     * @param {unknown} component Component record.
+     * @param {string} bodyKey Current body identity key.
+     * @param {string} componentKey Current component identity key.
+     * @returns {number | null}
+     */
+    static #cachedAffinityScore(
+        componentBody,
+        component,
+        bodyKey,
+        componentKey
+    ) {
+        if (
+            !PcbScene3dPlacementSideResolver.#isObjectLike(componentBody) ||
+            !PcbScene3dPlacementSideResolver.#isObjectLike(component)
+        ) {
+            return null
+        }
+
+        const componentScores =
+            PcbScene3dPlacementSideResolver.#AFFINITY_SCORE_CACHE.get(
+                componentBody
+            )
+        const cachedScore = componentScores?.get(component)
+
+        return cachedScore?.bodyKey === bodyKey &&
+            cachedScore?.componentKey === componentKey
+            ? cachedScore.score
+            : null
+    }
+
+    /**
+     * Caches one body/component affinity score.
+     * @param {unknown} componentBody Component-body record.
+     * @param {unknown} component Component record.
+     * @param {string} bodyKey Current body identity key.
+     * @param {string} componentKey Current component identity key.
+     * @param {number} score Affinity score.
+     * @returns {void}
+     */
+    static #cacheAffinityScore(
+        componentBody,
+        component,
+        bodyKey,
+        componentKey,
+        score
+    ) {
+        if (
+            !PcbScene3dPlacementSideResolver.#isObjectLike(componentBody) ||
+            !PcbScene3dPlacementSideResolver.#isObjectLike(component)
+        ) {
+            return
+        }
+
+        let componentScores =
+            PcbScene3dPlacementSideResolver.#AFFINITY_SCORE_CACHE.get(
+                componentBody
+            )
+        if (!componentScores) {
+            componentScores = new WeakMap()
+            PcbScene3dPlacementSideResolver.#AFFINITY_SCORE_CACHE.set(
+                componentBody,
+                componentScores
+            )
+        }
+
+        componentScores.set(component, { bodyKey, componentKey, score })
+    }
+
+    /**
+     * Collects cached normalized identity tokens.
+     * @param {WeakMap<object, { key: string, tokens: Set<string> }>} cache Token cache.
+     * @param {unknown} owner Source object that owns the identity fields.
+     * @param {string} key Current identity key.
+     * @param {unknown[]} values Identity field values.
+     * @returns {Set<string>}
+     */
+    static #cachedMeaningfulTokens(cache, owner, key, values) {
+        if (!PcbScene3dPlacementSideResolver.#isObjectLike(owner)) {
+            return PcbScene3dPlacementSideResolver.#collectMeaningfulTokens(
+                values
+            )
+        }
+
+        const cached = cache.get(owner)
+        if (cached?.key === key) {
+            return cached.tokens
+        }
+
+        const tokens =
+            PcbScene3dPlacementSideResolver.#collectMeaningfulTokens(values)
+        cache.set(owner, { key, tokens })
+        return tokens
+    }
+
+    /**
+     * Returns true when a value can be used as a WeakMap key.
+     * @param {unknown} value Candidate value.
+     * @returns {boolean}
+     */
+    static #isObjectLike(value) {
+        return (
+            (typeof value === 'object' && value !== null) ||
+            typeof value === 'function'
+        )
+    }
+
     /**
      * Resolves package-related component metadata that can identify generic
      * embedded 3D bodies when pattern/source only name the electrical part.
@@ -248,6 +448,46 @@ export class PcbScene3dPlacementSideResolver {
         return Math.abs(standoff) >= threshold ? 'bottom' : null
     }
 
+    /**
+     * Checks whether negative standoff metadata is reliable enough to infer
+     * the board side before nearby package or mechanical-layer evidence.
+     * @param {{ dzMil?: number | null, standoffHeightMil?: number | null, overallHeightMil?: number | null } | null} componentBody Component body row.
+     * @param {'bottom' | null} standoffSide Side inferred from the standoff.
+     * @returns {boolean}
+     */
+    static #shouldTrustStandoffSide(componentBody, standoffSide) {
+        if (!standoffSide) {
+            return false
+        }
+
+        return !PcbScene3dPlacementSideResolver.#hasInEnvelopeDzAgainstOverlargeStandoff(
+            componentBody
+        )
+    }
+
+    /**
+     * Returns true for source-origin artifacts where Altium's standoff exceeds
+     * the model envelope but the authored dz offset is still physically valid.
+     * @param {{ dzMil?: number | null, standoffHeightMil?: number | null, overallHeightMil?: number | null } | null} componentBody Component body row.
+     * @returns {boolean}
+     */
+    static #hasInEnvelopeDzAgainstOverlargeStandoff(componentBody) {
+        const standoff = Number(componentBody?.standoffHeightMil)
+        const dz = Number(componentBody?.dzMil)
+        const overallHeight = Number(componentBody?.overallHeightMil)
+
+        return (
+            Number.isFinite(standoff) &&
+            standoff < 0 &&
+            Number.isFinite(dz) &&
+            dz < 0 &&
+            Number.isFinite(overallHeight) &&
+            overallHeight > 0 &&
+            Math.abs(standoff) > overallHeight &&
+            Math.abs(dz) < overallHeight
+        )
+    }
+
     /**
      * Returns true when one body anchor sits inside the normalized board bounds.
      * @param {{ positionMil?: { x?: number, y?: number } } | null} componentBody
@@ -383,7 +623,7 @@ export class PcbScene3dPlacementSideResolver {
     static #isMeaningfulToken(token) {
         return (
             String(token || '').length >= 2 &&
-            !new Set(['con', 'step', 'stp', 'model', 'default', 'black']).has(
+            !PcbScene3dPlacementSideResolver.#IGNORED_IDENTITY_TOKENS.has(
                 String(token || '')
             )
         )