@ifc-lite/viewer 1.19.0 → 1.21.0

package/src/components/viewer/CesiumOverlay.tsx

@@ -26,6 +26,8 @@ import type { MapConversion, ProjectedCRS } from '@ifc-lite/parser';
 import type { CoordinateInfo, GeometryResult } from '@ifc-lite/geometry';
 import { getGlobalRenderer } from '@/hooks/useBCF';
 import { createCesiumBridge, type CesiumBridge } from '@/lib/geo/cesium-bridge';
+import { findClampAnchorY } from '@/lib/geo/clamp-anchor';
+import { getEffectiveHorizontalScale } from '@/lib/geo/effective-georef';
 
 // Lazy-loaded Cesium module and CSS
 let cesiumPromise: Promise<typeof import('cesium')> | null = null;
@@ -167,11 +169,16 @@ function buildModelMatrix(
   Cesium: typeof import('cesium'),
   bridge: CesiumBridge,
   mapConversion: MapConversion | undefined,
+  projectedCRS: ProjectedCRS | undefined,
   coordinateInfo: CoordinateInfo | undefined,
-  clamp: boolean,
-  terrainH: number | null,
+  lengthUnitScale: number,
 ) {
-  const hScale = mapConversion?.scale ?? 1.0;
+  // GLB vertices are in viewer-space metres (geometry engine converts during
+  // extraction). IfcMapConversion.Scale is defined per IFC spec relative to
+  // the project length unit, so applying it raw to metre-converted geometry
+  // double-scales the model — see issue #595. Use the effective scale.
+  const mapUnitScale = projectedCRS?.mapUnitScale ?? lengthUnitScale;
+  const hScale = getEffectiveHorizontalScale(mapConversion?.scale, mapUnitScale, lengthUnitScale);
   const absc = mapConversion?.xAxisAbscissa ?? 1.0;
   const ordi = mapConversion?.xAxisOrdinate ?? 0.0;
   const bounds = coordinateInfo?.originalBounds;
@@ -180,15 +187,11 @@ function buildModelMatrix(
   const mvy = bounds ? (bounds.min.y + bounds.max.y) / 2 : 0;
   const mvz = bounds ? (bounds.min.z + bounds.max.z) / 2 : 0;
 
-  let placementHeight = bridge.modelOrigin.height;
-  if (clamp && terrainH !== null) {
-    const minY = bounds?.min.y ?? 0;
-    const bottomOffset = mvy - minY; // already in metres
-    placementHeight = terrainH + bottomOffset;
-  }
-
+  // bridge.modelOrigin.height is the placement altitude — Effect 2 already
+  // baked terrain clamping (when applicable) into it before constructing the
+  // bridge, so there's no per-frame clamp adjustment to make here.
   const origin = Cesium.Cartesian3.fromDegrees(
-    bridge.modelOrigin.longitude, bridge.modelOrigin.latitude, placementHeight,
+    bridge.modelOrigin.longitude, bridge.modelOrigin.latitude, bridge.modelOrigin.height,
   );
   const enuToEcef = Cesium.Transforms.eastNorthUpToFixedFrame(origin);
   // No lengthUnitScale here — viewer-space GLB vertices are already in metres.
@@ -212,6 +215,10 @@ export interface CesiumOverlayProps {
   geometryResult?: GeometryResult | null;
   /** IFC project length unit → metres (e.g. 0.001 for mm models). Default 1. */
   lengthUnitScale?: number;
+  /** IfcBuildingStorey elevations (express id → metres, viewer-Y aligned).
+   *  Used to clamp the model's ground-floor storey to terrain instead of
+   *  the lowest geometry vertex (which can be a basement or foundation). */
+  storeyElevations?: Map<number, number>;
 }
 
 export function CesiumOverlay({
@@ -220,6 +227,7 @@ export function CesiumOverlay({
   coordinateInfo,
   geometryResult,
   lengthUnitScale = 1,
+  storeyElevations,
 }: CesiumOverlayProps) {
   const containerRef = useRef<HTMLDivElement>(null);
   const viewerRef = useRef<InstanceType<typeof import('cesium').Viewer> | null>(null);
@@ -235,25 +243,23 @@ export function CesiumOverlay({
   const ionToken = useViewerStore((s) => s.cesiumIonToken);
   const terrainEnabled = useViewerStore((s) => s.cesiumTerrainEnabled);
   const terrainClamp = useViewerStore((s) => s.cesiumTerrainClamp);
-  const setCesiumTerrainClamp = useViewerStore((s) => s.setCesiumTerrainClamp);
   const terrainHeight = useViewerStore((s) => s.cesiumTerrainHeight);
   const setCesiumTerrainHeight = useViewerStore((s) => s.setCesiumTerrainHeight);
   const setCesiumTerrainClipY = useViewerStore((s) => s.setCesiumTerrainClipY);
   const setCesiumGlbLoaded = useViewerStore((s) => s.setCesiumGlbLoaded);
 
-  // Use refs so the camera sync loop always reads the latest values
-  const terrainClampRef = useRef(terrainClamp);
-  const terrainHeightRef = useRef(terrainHeight);
-  terrainClampRef.current = terrainClamp;
-  terrainHeightRef.current = terrainHeight;
-
-  // Track whether we've auto-clamped to terrain (only once, so user can still uncheck)
-  const autoClampedRef = useRef(false);
-
   // Track the Cesium model (IFC geometry loaded as glTF for correct world positioning)
   const cesiumModelRef = useRef<{ modelMatrix: any; destroy?: () => void } | null>(null);
   const glbCacheRef = useRef<{ meshCount: number; glb: Uint8Array } | null>(null);
 
+  // Last-known placement altitude (in metres) used to keep the user's WORLD
+  // camera position stable across bridge rebuilds. When the user toggles the
+  // clamp or edits OrthogonalHeight, the model placement changes and the
+  // entire viewer→ECEF frame translates with it; we offset the IFC viewer's
+  // camera Y by the inverse so the user perceives the model moving instead
+  // of the camera being dragged along.
+  const prevPlacementRef = useRef<number | null>(null);
+
   // ─── Effect 1: Create/destroy the Cesium viewer (heavy, rare) ───────────
   // Only depends on cesiumEnabled, ionToken, terrainEnabled, dataSource.
   // NOT on mapConversion/projectedCRS — those are handled by Effect 2.
@@ -296,10 +302,14 @@ export function CesiumOverlay({
 
         if (cancelled) { viewer.destroy(); return; }
 
-        // Disable Cesium's user input — the IFC viewer controls the camera.
-        // Keep collision detection off since we set the camera programmatically.
+        // Disable Cesium's user input — the IFC viewer drives the camera,
+        // and any input Cesium intercepts (even a stray wheel/touch event
+        // past pointer-events:none) interferes with our orbit/zoom and
+        // produces "stuck to terrain" symptoms. enableInputs is the
+        // master kill-switch; the per-mode flags below are belt-and-braces.
         const scene = viewer.scene;
         const sscc = scene.screenSpaceCameraController;
+        sscc.enableInputs = false;
         sscc.enableRotate = false;
         sscc.enableTranslate = false;
         sscc.enableZoom = false;
@@ -386,122 +396,150 @@ export function CesiumOverlay({
     };
   }, [cesiumEnabled, ionToken, terrainEnabled, dataSource]);
 
-  // ─── Effect 2: Rebuild coordinate bridge when georef changes (fast) ─────
-  // This is the live-edit handler. When the user changes EPSG, eastings,
-  // northings, rotation, etc., we rebuild the bridge and fly to the new spot.
+  // ─── Effect 2: Build the coordinate bridge with terrain-aware placement ─
+  // Precomputes the model placement (terrain-clamped if applicable) BEFORE
+  // building the bridge that the GLB and camera will share. This way the
+  // model loads into Cesium at its final altitude — no post-load shifting,
+  // no camera/model frame divergence, no compensation gymnastics.
+  //
+  // Sequence:
+  //   1. Build a tentative bridge to recover the model's WGS84 lat/lon.
+  //   2. Query terrain at that lat/lon (sync first, async with retry next).
+  //   3. Decide whether to clamp (user toggle OR model authored below terrain).
+  //   4. Rebuild the bridge with placementHeight baked into its enuToEcef
+  //      origin so model matrix and camera frame share a single altitude.
+  //   5. Push terrain-derived state (height, clip Y, clamp toggle) and
+  //      install the bridge.
   useEffect(() => {
     if (status !== 'ready' || !mapConversion || !projectedCRS) {
       bridgeRef.current = null;
+      prevPlacementRef.current = null;
       return;
     }
 
     let cancelled = false;
 
     (async () => {
-      const bridge = await createCesiumBridge(mapConversion, projectedCRS, coordinateInfo, lengthUnitScale);
-      if (cancelled) return;
+      const Cesium = cesiumModule;
+      const viewer = viewerRef.current;
+      if (!Cesium || !viewer) return;
 
-      if (!bridge) {
+      const tentative = await createCesiumBridge(
+        mapConversion, projectedCRS, coordinateInfo, lengthUnitScale,
+      );
+      if (cancelled) return;
+      if (!tentative) {
         bridgeRef.current = null;
         return;
       }
 
-      const prevBridge = bridgeRef.current;
-      bridgeRef.current = bridge;
-      autoClampedRef.current = false; // reset for new bridge
-      // Bump version so terrain query effect re-runs now that bridge is ready
-      setBridgeVersion((v) => v + 1);
-
-      // Fly to the new model location (smooth animation)
-      const viewer = viewerRef.current;
-      const Cesium = cesiumModule;
-      if (viewer && Cesium) {
-        const { modelOrigin } = bridge;
-
-        const isFirstPosition = !prevBridge;
-        const target = Cesium.Cartesian3.fromDegrees(
-          modelOrigin.longitude, modelOrigin.latitude, modelOrigin.height,
+      // Query terrain at the model's location. queryTerrainHeight tries
+      // Cesium's sync sources first (globe.getHeight, scene.sampleHeight),
+      // then Open-Meteo as a fast network fallback that works even with
+      // Google Photorealistic 3D Tiles (where there's no Cesium terrain
+      // provider for getHeight to read). Cached per-session.
+      const t0 = performance.now();
+      let terrainH: number | null = null;
+      try { terrainH = await tentative.queryTerrainHeight(Cesium, viewer); }
+      catch (err) { console.warn('[CesiumOverlay] terrain query failed:', err); }
+      if (cancelled) return;
+      const terrainMs = performance.now() - t0;
+
+      const bounds = coordinateInfo?.originalBounds;
+      const mvy = bounds ? (bounds.min.y + bounds.max.y) / 2 : 0;
+      const minY = bounds?.min.y ?? 0;
+      // Clamp anchor: viewer-Y of the storey nearest elevation 0 (typical
+      // ground floor), falling back to bounds.min.y. Without this, basements
+      // and foundations drag the model deep below terrain.
+      const clampAnchorY = findClampAnchorY(bounds, storeyElevations);
+      const anchorOffset = mvy - clampAnchorY;
+      const ifcOHeight = tentative.modelOrigin.height;
+      // Clamp is purely the user's choice. We do NOT auto-clamp on top of
+      // the user's setting — that would reactivate the toggle the moment
+      // the user disables it (since terrain is almost always above sea-level
+      // OrthogonalHeights, the auto condition would re-fire forever and the
+      // checkbox becomes un-uncheckable).
+      const placementHeight =
+        terrainClamp && terrainH !== null
+          ? terrainH + anchorOffset
+          : ifcOHeight;
+
+      console.debug(
+        `[CesiumOverlay] placement decision: terrain=${terrainH?.toFixed(2) ?? 'null'}m`
+        + ` ifcOHeight=${ifcOHeight.toFixed(2)}m anchorY=${clampAnchorY.toFixed(2)}m`
+        + ` (minY=${minY.toFixed(2)}m, ${storeyElevations?.size ?? 0} storeys)`
+        + ` clamp=${terrainClamp} placement=${placementHeight.toFixed(2)}m`
+        + ` (terrain query: ${terrainMs.toFixed(0)}ms)`
+      );
+
+      // Build the final bridge with the placement baked in (or reuse the
+      // tentative one when the placement matches its IFC-derived origin).
+      let bridge = tentative;
+      if (Math.abs(placementHeight - ifcOHeight) > 1e-6) {
+        const final = await createCesiumBridge(
+          mapConversion, projectedCRS, coordinateInfo, lengthUnitScale,
+          placementHeight,
         );
-
-        if (isFirstPosition) {
-          // First time: fly to the model location.
-          // On first load terrain tiles may not be ready, so globe.getHeight
-          // can return undefined. Use flyTo which handles terrain automatically,
-          // targeting a safe altitude above the model origin.
-          const safeHeight = Math.max(modelOrigin.height, 100);
-          viewer.camera.flyTo({
-            destination: Cesium.Cartesian3.fromDegrees(
-              modelOrigin.longitude, modelOrigin.latitude, safeHeight + 500,
-            ),
-            orientation: {
-              heading: 0,
-              pitch: Cesium.Math.toRadians(-45),
-              roll: 0,
-            },
-            duration: 0, // instant
-          });
-        } else if (prevBridge) {
-          // Georef edit: just re-render, the camera sync loop will pick
-          // up the new bridge on the next frame. No dramatic fly animation.
-          viewer.scene.requestRender();
+        if (cancelled) return;
+        if (!final) {
+          bridgeRef.current = null;
+          return;
         }
+        bridge = final;
       }
-    })();
-
-    return () => { cancelled = true; };
-  }, [status, mapConversion, projectedCRS, coordinateInfo, lengthUnitScale]);
-
-  // ─── Effect 2b: Query terrain height when bridge is ready ───────────────
-  // Also re-queries when terrainClamp is toggled on (in case first query failed)
-  useEffect(() => {
-    if (status !== 'ready') return;
-    const bridge = bridgeRef.current;
-    const viewer = viewerRef.current;
-    const Cesium = cesiumModule;
-    if (!bridge || !viewer || !Cesium) return;
 
-    let cancelled = false;
+      if (terrainH !== null) {
+        setCesiumTerrainHeight(terrainH);
+        // terrainClipY stays in viewer-space; it represents the world terrain
+        // altitude expressed in the bridge's frame so a clip plane at that Y
+        // matches the terrain surface. Use the clamp anchor (ground floor)
+        // rather than minY so the clip plane matches the user's ground level
+        // rather than the basement floor.
+        const terrainClipY = clampAnchorY + (terrainH - ifcOHeight);
+        setCesiumTerrainClipY(terrainClipY);
+      } else {
+        // Failed re-query (offline, API down) — clear stale store fields so
+        // the clip plane doesn't drift relative to the new bridge.
+        setCesiumTerrainHeight(null);
+        setCesiumTerrainClipY(null);
+      }
 
-    // Query immediately, then retry after a delay if terrain tiles weren't loaded yet
-    // Compute model center Y in viewer space for terrain clip offset
-    const bounds = coordinateInfo?.originalBounds;
-    const modelVY = bounds ? (bounds.min.y + bounds.max.y) / 2 : 0;
-    const modelMinY = bounds ? bounds.min.y : 0;
-
-    const doQuery = () => {
-      bridge.queryTerrainHeight(Cesium, viewer).then((h) => {
-        if (!cancelled && h !== null) {
-          setCesiumTerrainHeight(h);
-          // Compute terrain clip Y in viewer space (both h and modelOrigin.height are metres,
-          // bounds are also in metres since the geometry engine converts during extraction)
-          const terrainClipY = modelMinY + (h - bridge.modelOrigin.height);
-          setCesiumTerrainClipY(terrainClipY);
-
-          // Auto-enable terrain clamping if the model is significantly below terrain
-          // (only once — don't override if the user has manually toggled)
-          if (!autoClampedRef.current && h > bridge.modelOrigin.height + 5) {
-            autoClampedRef.current = true;
-            setCesiumTerrainClamp(true);
-            // Fly camera to the clamped position so the model is visible
-            viewer.camera.flyTo({
-              destination: Cesium.Cartesian3.fromDegrees(
-                bridge.modelOrigin.longitude, bridge.modelOrigin.latitude, h + 500,
-              ),
-              orientation: { heading: 0, pitch: Cesium.Math.toRadians(-45), roll: 0 },
-              duration: 0,
-            });
+      // World-camera stability: when this rebuild changes the placement
+      // altitude (clamp toggled, OrthogonalHeight edited), shift the IFC
+      // viewer-space camera Y by the inverse delta so the user's WORLD
+      // camera ECEF position stays put. Without this, the entire frame
+      // translates with the model and edits feel like the camera is
+      // moving instead of the model — exactly what the user reported.
+      const prevPlacement = prevPlacementRef.current;
+      prevPlacementRef.current = placementHeight;
+      if (prevPlacement !== null) {
+        const dh = placementHeight - prevPlacement;
+        // 5 cm threshold — rejects float jitter from cached terrain reads
+        // re-flowing through the same effect, while a real placement edit
+        // (clamp toggle, OrthogonalHeight change) is always far larger.
+        if (Math.abs(dh) > 0.05) {
+          const renderer = getGlobalRenderer();
+          if (renderer) {
+            const cam = renderer.getCamera();
+            const pos = cam.getPosition();
+            cam.setPosition(pos.x, pos.y - dh, pos.z);
+            console.debug(
+              `[CesiumOverlay] placement Δh=${dh.toFixed(2)}m → shifted IFC camera Y by ${(-dh).toFixed(2)}m to hold world camera`,
+            );
           }
         }
-      });
-    };
+      }
 
-    // First attempt
-    doQuery();
-    // Retry after 5s in case terrain tiles were still loading
-    const retryTimer = setTimeout(doQuery, 5000);
+      bridgeRef.current = bridge;
+      setBridgeVersion((v) => v + 1);
+    })();
 
-    return () => { cancelled = true; clearTimeout(retryTimer); };
-  }, [status, terrainEnabled, terrainClamp, bridgeVersion]);
+    return () => { cancelled = true; };
+    // terrainEnabled and ionToken intentionally omitted — Effect 1 already
+    // owns those (it destroys/recreates the viewer when they change), and
+    // listing them here would cause a redundant bridge rebuild while the
+    // viewer is being torn down.
+  }, [status, mapConversion, projectedCRS, coordinateInfo, lengthUnitScale, terrainClamp, storeyElevations]);
 
   // ─── Effect 2c: Load GLB into Cesium (only when geometry changes) ───────
   // This is the heavy operation — only re-runs when geometry actually changes.
@@ -545,7 +583,7 @@ export function CesiumOverlay({
         if (cancelled) return;
 
         // Build initial model matrix
-        const modelMatrix = buildModelMatrix(Cesium, bridge, mapConversion, coordinateInfo, terrainClampRef.current, terrainHeightRef.current);
+        const modelMatrix = buildModelMatrix(Cesium, bridge, mapConversion, projectedCRS, coordinateInfo, lengthUnitScale);
 
         const blob = new Blob([glbBytes as BlobPart], { type: 'model/gltf-binary' });
         const glbUrl = URL.createObjectURL(blob);
@@ -601,10 +639,15 @@ export function CesiumOverlay({
     const Cesium = cesiumModule;
     if (!model || !bridge || !viewer || !Cesium) return;
 
-    const newMatrix = buildModelMatrix(Cesium, bridge, mapConversion, coordinateInfo, terrainClamp, terrainHeight);
+    const newMatrix = buildModelMatrix(Cesium, bridge, mapConversion, projectedCRS, coordinateInfo, lengthUnitScale);
     model.modelMatrix = newMatrix;
     viewer.scene.requestRender();
-  }, [terrainClamp, terrainHeight, mapConversion, coordinateInfo, lengthUnitScale]);
+    // Depend on bridgeVersion so the matrix is rebuilt with the *new* bridge
+    // after async createCesiumBridge replaces it. Placement (terrain clamp)
+    // is now baked into bridge.modelOrigin.height by Effect 2, so terrain
+    // clamp/height changes drive a bridge rebuild instead of a per-frame
+    // matrix recomputation here.
+  }, [mapConversion, projectedCRS, coordinateInfo, lengthUnitScale, bridgeVersion]);
 
   // ─── Effect 3: Camera sync loop ─────────────────────────────────────────
   useEffect(() => {
@@ -632,7 +675,9 @@ export function CesiumOverlay({
       const camUp = camera.getUp();
       const fov = camera.getFOV();
 
-      // Sync Cesium camera (no terrain offset — model matrix handles clamping)
+      // bridge.modelOrigin.height already has the placement baked in (terrain
+      // clamp resolved at bridge creation by Effect 2), so the camera frame
+      // and the model matrix share the same enuToEcef origin altitude.
       bridge.syncCamera(Cesium, viewer, camPos, camTarget, camUp, fov);
 
       rafRef.current = requestAnimationFrame(syncCamera);

package/src/components/viewer/DeviationPanel.tsx

@@ -0,0 +1,172 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * BIM ↔ scan deviation heatmap controls.
+ *
+ * Renders a "Compute Deviation" button when the scene has at least
+ * one mesh and one point cloud. Once compute completes, exposes a
+ * range slider + diverging-ramp legend; the splat shader's
+ * deviation colour mode then visualises signed distance to the
+ * nearest mesh surface.
+ *
+ * Lives inside the `PointCloudPanel`; rendered conditionally on
+ * `pointCloudAssetCount > 0`.
+ */
+
+import { useCallback, useState } from 'react';
+import { useViewerStore } from '@/store';
+import { getGlobalRenderer } from '@/hooks/useBCF';
+import { cn } from '@/lib/utils';
+
+export interface DeviationPanelProps {
+  /** Total number of triangles currently in the scene — gates the
+   *  compute button on the existence of a BIM model. */
+  triangleCount: number;
+}
+
+export function DeviationPanel({ triangleCount }: DeviationPanelProps) {
+  const halfRange = useViewerStore((s) => s.pointCloudDeviationHalfRange);
+  const setHalfRange = useViewerStore((s) => s.setPointCloudDeviationHalfRange);
+  const computed = useViewerStore((s) => s.pointCloudDeviationComputed);
+  const setComputed = useViewerStore((s) => s.setPointCloudDeviationComputed);
+  const colorMode = useViewerStore((s) => s.pointCloudColorMode);
+  const setColorMode = useViewerStore((s) => s.setPointCloudColorMode);
+
+  const [running, setRunning] = useState(false);
+  const [stats, setStats] = useState<{
+    triangles: number;
+    points: number;
+    durationMs: number;
+  } | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleCompute = useCallback(async () => {
+    const renderer = getGlobalRenderer();
+    if (!renderer) {
+      setError('Renderer not initialised yet.');
+      return;
+    }
+    setError(null);
+    setRunning(true);
+    const t0 = performance.now();
+    try {
+      const result = await renderer.computeDeviations({ maxRange: 1.0 });
+      const dt = performance.now() - t0;
+      if (result.pointsProcessed === 0) {
+        setError('No points processed — load a point cloud first.');
+        setRunning(false);
+        return;
+      }
+      if (result.bvhTriangles === 0) {
+        setError('No mesh geometry in the scene — load an IFC first.');
+        setRunning(false);
+        return;
+      }
+      setStats({
+        triangles: result.bvhTriangles,
+        points: result.pointsProcessed,
+        durationMs: dt,
+      });
+      setComputed(true);
+      // Default-pick a sensible half-range from the BVH's bbox if the
+      // user hasn't touched the slider yet (initial 5 cm is fine for
+      // small models but useless for a city-block scan).
+      if (halfRange === 0.05 && result.suggestedHalfRange !== 0.05) {
+        setHalfRange(result.suggestedHalfRange);
+      }
+      // Auto-switch the colour mode to deviation so the user sees
+      // the result immediately.
+      setColorMode('deviation');
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setRunning(false);
+    }
+  }, [halfRange, setHalfRange, setColorMode, setComputed]);
+
+  // Hide the panel entirely when there's no BIM to compare against.
+  // Point-cloud-only sessions (just a LAS / IFCx scan) have nothing
+  // to deviate from so the button would always fail.
+  if (triangleCount === 0) return null;
+
+  return (
+    <div className="flex flex-col gap-1 mt-1 pt-1 border-t border-border/40">
+      <span className="text-[9px] uppercase text-muted-foreground tracking-wider">
+        Deviation (BIM ↔ scan)
+      </span>
+      <button
+        type="button"
+        onClick={handleCompute}
+        disabled={running}
+        className={cn(
+          'text-xs px-2 py-1 rounded transition-colors',
+          running
+            ? 'bg-muted text-muted-foreground'
+            : 'bg-teal-600 text-white hover:bg-teal-500 disabled:opacity-50',
+        )}
+        title={`Build BVH from ${triangleCount.toLocaleString()} triangles, then signed-distance every loaded point against the nearest surface`}
+      >
+        {running ? 'Computing…' : computed ? 'Recompute' : 'Compute deviation'}
+      </button>
+      {error && (
+        <span className="text-[10px] text-destructive">{error}</span>
+      )}
+      {stats && (
+        <div className="text-[10px] text-muted-foreground">
+          {stats.points.toLocaleString()} pts vs.{' '}
+          {stats.triangles.toLocaleString()} tris in{' '}
+          {Math.round(stats.durationMs)} ms
+        </div>
+      )}
+
+      {computed && (
+        <>
+          {/* Range slider: half-width in mm. Range from 1 mm to 1 m
+              (logarithmic feel via the millimetre conversion). */}
+          <label className="flex items-center gap-2 mt-1">
+            <span className="text-[10px] text-muted-foreground w-12 shrink-0">
+              ±{(halfRange * 1000).toFixed(halfRange < 0.01 ? 1 : 0)}mm
+            </span>
+            <input
+              type="range"
+              min={1}
+              max={1000}
+              step={1}
+              value={Math.round(halfRange * 1000)}
+              onChange={(e) => setHalfRange(Number(e.target.value) / 1000)}
+              className="flex-1 h-1 accent-teal-600 cursor-pointer"
+              title="Deviation half-range in millimetres — values past ±this map to the ramp endpoints"
+              aria-label="Deviation range half-width"
+            />
+          </label>
+
+          {/* Legend: blue → white → red gradient with labelled endpoints. */}
+          <div
+            className="h-2 rounded-sm border border-foreground/10 mt-0.5"
+            style={{
+              background: 'linear-gradient(to right, rgb(26,77,217), rgb(242,242,242), rgb(217,51,26))',
+            }}
+            aria-label="Deviation ramp from negative (blue) to positive (red)"
+          />
+          <div className="flex justify-between text-[9px] text-muted-foreground">
+            <span>−{(halfRange * 1000).toFixed(0)}mm (inside)</span>
+            <span>0</span>
+            <span>+{(halfRange * 1000).toFixed(0)}mm (outside)</span>
+          </div>
+
+          {colorMode !== 'deviation' && (
+            <button
+              type="button"
+              onClick={() => setColorMode('deviation')}
+              className="text-[10px] text-teal-600 hover:text-teal-500 underline text-left mt-0.5"
+            >
+              Switch colour mode to Deviation
+            </button>
+          )}
+        </>
+      )}
+    </div>
+  );
+}

package/src/components/viewer/HierarchyPanel.tsx

@@ -126,13 +126,39 @@ export function HierarchyPanel() {
     groupingMode,
     setGroupingMode,
     unifiedStoreys,
-    filteredNodes,
-    storeysNodes,
-    modelsNodes,
+    filteredNodes: rawFilteredNodes,
+    storeysNodes: rawStoreysNodes,
+    modelsNodes: rawModelsNodes,
     toggleExpand,
     getNodeElements,
   } = useHierarchyTree({ models, ifcDataStore, isMultiModel, geometryResult });
 
+  // Issue #540: when the user has the merge-layers load setting on,
+  // hide `IfcBuildingElementPart` rows from the tree — the Rust layer
+  // suppresses their meshes, so leaving the rows visible would lead
+  // to dead-clicks. Filter at the consumer (this panel) rather than
+  // in `spatialHierarchy.ts` per the agent coordination plan.
+  const mergeLayersHidesParts = useViewerStore((s) => s.mergeLayers);
+  const PART_TYPE_KEY = 'ifcbuildingelementpart';
+  const stripPartNodes = useCallback(
+    (nodes: TreeNode[]): TreeNode[] => {
+      if (!mergeLayersHidesParts) return nodes;
+      return nodes.filter((node) => {
+        // Only element rows carry an `ifcType` we can compare. Class
+        // grouping ("IfcBuildingElementPart (N)") and ifc-type nodes
+        // also expose an `ifcType`; we strip those too because they
+        // would expand to empty groups after merge.
+        const t = node.ifcType?.toLowerCase();
+        if (!t) return true;
+        return t !== PART_TYPE_KEY;
+      });
+    },
+    [mergeLayersHidesParts],
+  );
+  const filteredNodes = useMemo(() => stripPartNodes(rawFilteredNodes), [stripPartNodes, rawFilteredNodes]);
+  const storeysNodes = useMemo(() => stripPartNodes(rawStoreysNodes), [stripPartNodes, rawStoreysNodes]);
+  const modelsNodes = useMemo(() => stripPartNodes(rawModelsNodes), [stripPartNodes, rawModelsNodes]);
+
   // Refs for both scroll areas
   const storeysRef = useRef<HTMLDivElement>(null);
   const modelsRef = useRef<HTMLDivElement>(null);

package/src/components/viewer/HoverTooltip.tsx

@@ -77,6 +77,11 @@ export function HoverTooltip() {
       <div className="text-xs text-muted-foreground">
         #{hoverState.entityId}
       </div>
+      {hoverState.worldXYZ && (
+        <div className="text-[10px] font-mono text-muted-foreground/80 mt-0.5">
+          {hoverState.worldXYZ.x.toFixed(2)}, {hoverState.worldXYZ.y.toFixed(2)}, {hoverState.worldXYZ.z.toFixed(2)}
+        </div>
+      )}
     </div>
   );
 }