@ifc-lite/viewer 1.19.0 → 1.21.0

package/src/lib/geo/cesium-bridge.ts

@@ -29,6 +29,8 @@ import proj4 from 'proj4';
 import type { MapConversion, ProjectedCRS } from '@ifc-lite/parser';
 import type { CoordinateInfo } from '@ifc-lite/geometry';
 import { resolveProjection } from './reproject';
+import { resolveTerrainElevation } from './terrain-elevation';
+import { getEffectiveHorizontalScale } from './effective-georef';
 
 export interface GeodesicPosition {
   longitude: number;
@@ -64,18 +66,23 @@ export interface CesiumBridge {
   viewerToGeodetic(vx: number, vy: number, vz: number): GeodesicPosition | null;
 }
 
-const TERRAIN_QUERY_RETRY_DELAY_MS = 3000;
-
 export async function createCesiumBridge(
   mapConversion: MapConversion,
   projectedCRS: ProjectedCRS,
   coordinateInfo?: CoordinateInfo,
   lengthUnitScale = 1,
+  /**
+   * If provided, replaces the IFC-derived origin altitude (mapConversion's
+   * OrthogonalHeight + viewer-space Z) for the enuToEcef origin used by both
+   * the camera frame and the model matrix. Pass the terrain-clamped placement
+   * here to bake "model on terrain" into the bridge from creation, so the
+   * model never has to be moved after loading into Cesium.
+   */
+  placementHeightOverride?: number,
 ): Promise<CesiumBridge | null> {
   const projDef = await resolveProjection(projectedCRS);
   if (!projDef) return null;
 
-  const hScale = mapConversion.scale ?? 1.0;
   const absc = mapConversion.xAxisAbscissa ?? 1.0;
   const ordi = mapConversion.xAxisOrdinate ?? 0.0;
   const rotAngle = Math.atan2(ordi, absc);
@@ -103,9 +110,18 @@ export async function createCesiumBridge(
   // converts from the IFC file's native unit during extraction). MapConversion
   // values use the unit from IfcProjectedCRS.MapUnit; fall back to project unit.
   const mapScale = projectedCRS.mapUnitScale ?? lengthUnitScale;
+  // IfcMapConversion.Scale bridges project length unit → map unit (e.g. 0.001
+  // for mm→m). Geometry is already in metres, so the effective horizontal
+  // scale is (Scale * mapUnitScale) / lengthUnitScale — see issue #595.
+  const hScale = getEffectiveHorizontalScale(mapConversion.scale, mapScale, lengthUnitScale);
   const oEasting = mapConversion.eastings * mapScale + hScale * (absc * oIfcX - ordi * oIfcY);
   const oNorthing = mapConversion.northings * mapScale + hScale * (ordi * oIfcX + absc * oIfcY);
-  const oHeight = mapConversion.orthogonalHeight * mapScale + oIfcZ;
+  const ifcOHeight = mapConversion.orthogonalHeight * mapScale + oIfcZ;
+  // The actual altitude used for the enuToEcef origin. When the caller
+  // pre-computes a terrain-clamped placement, we honour it so the bridge,
+  // model matrix, and camera frame are all built around the SAME altitude
+  // from the start — no post-load shifting required.
+  const oHeight = placementHeightOverride ?? ifcOHeight;
 
   let originLon: number, originLat: number;
   try {
@@ -192,6 +208,21 @@ export async function createCesiumBridge(
     );
   }
 
+  /**
+   * Sync the Cesium camera from the IFC viewer's camera state.
+   *
+   * Best practice for an externally-driven camera: keep Cesium's screen-space
+   * controller fully disabled (Effect 1) and write camera state directly in
+   * ECEF coordinates. We previously called `lookAtTransform` so we could set
+   * position/direction/up in viewer-space, but that locks Cesium's reference
+   * frame and constrains certain operations (rotate, tilt, zoom) to the local
+   * frame — which manifested as "can't orbit upward, camera stuck to terrain"
+   * even though our overlay is supposed to be input-passive.
+   *
+   * Instead, transform the IFC camera's viewer-space pose to ECEF here and
+   * write it. Cesium handles RTC for primitives (Models, 3D Tilesets, terrain)
+   * internally so we don't need a local-frame trick for shader precision.
+   */
   function syncCamera(
     Cesium: typeof import('cesium'),
     viewer: InstanceType<typeof import('cesium').Viewer>,
@@ -205,48 +236,60 @@ export async function createCesiumBridge(
     ensureEcefCache(Cesium, clampUp);
     if (!viewerToEcefMatrix) return;
 
-    // Set the camera's reference frame to our viewer→ECEF transform.
-    // After this call, all camera properties (position, direction, up)
-    // are interpreted in IFC VIEWER coordinates, not ECEF.
-    viewer.camera.lookAtTransform(viewerToEcefMatrix);
-
-    // Now set camera in VIEWER coordinates — Cesium applies the transform
-    viewer.camera.position = new Cesium.Cartesian3(camPos.x, camPos.y, camPos.z);
-
-    const dirX = camTarget.x - camPos.x;
-    const dirY = camTarget.y - camPos.y;
-    const dirZ = camTarget.z - camPos.z;
-    const dirLen = Math.sqrt(dirX * dirX + dirY * dirY + dirZ * dirZ);
-    if (dirLen > 1e-8) {
-      viewer.camera.direction = new Cesium.Cartesian3(
-        dirX / dirLen, dirY / dirLen, dirZ / dirLen,
-      );
-    }
-
-    viewer.camera.up = new Cesium.Cartesian3(camUp.x, camUp.y, camUp.z);
+    // Make sure no prior lookAtTransform is still in effect — if the
+    // overlay was activated from a previous bridge that called it, the
+    // camera could still be locked to that frame.
+    viewer.camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
+
+    // Transform IFC viewer-space pose → ECEF.
+    // Position uses full matrix (rotation + translation).
+    const posECEF = Cesium.Matrix4.multiplyByPoint(
+      viewerToEcefMatrix,
+      new Cesium.Cartesian3(camPos.x, camPos.y, camPos.z),
+      new Cesium.Cartesian3(),
+    );
+    const targetECEF = Cesium.Matrix4.multiplyByPoint(
+      viewerToEcefMatrix,
+      new Cesium.Cartesian3(camTarget.x, camTarget.y, camTarget.z),
+      new Cesium.Cartesian3(),
+    );
 
-    // Recompute right = direction × up (maintain orthonormality)
-    const right = Cesium.Cartesian3.cross(
-      viewer.camera.direction, viewer.camera.up, new Cesium.Cartesian3(),
+    // Direction = (target − position) normalised, in ECEF.
+    const dirECEF = Cesium.Cartesian3.subtract(targetECEF, posECEF, new Cesium.Cartesian3());
+    const dirLen = Cesium.Cartesian3.magnitude(dirECEF);
+    if (dirLen < 1e-8) return; // degenerate: target ≡ position
+    Cesium.Cartesian3.normalize(dirECEF, dirECEF);
+
+    // Up: rotate the viewer-space up vector to ECEF (rotation only, no
+    // translation — multiplyByPointAsVector ignores the translation column).
+    const upECEF = Cesium.Matrix4.multiplyByPointAsVector(
+      viewerToEcefMatrix,
+      new Cesium.Cartesian3(camUp.x, camUp.y, camUp.z),
+      new Cesium.Cartesian3(),
     );
-    Cesium.Cartesian3.normalize(right, right);
-    viewer.camera.right = right;
-
-    // Sync FOV — CRITICAL for preventing model drift.
-    // IFC renderer uses `fov` as VERTICAL FOV always.
-    // Cesium's PerspectiveFrustum.fov is HORIZONTAL when aspect > 1 (landscape).
-    // If we set Cesium's fov = IFC's vertical fov, Cesium treats it as horizontal,
-    // producing a completely different projection — the model slides during orbit.
-    // Fix: convert vertical FOV → horizontal FOV.
+    Cesium.Cartesian3.normalize(upECEF, upECEF);
+
+    // Right = direction × up — recompute fresh each frame so the orthonormal
+    // basis stays clean. (The "drift" the previous implementation worried
+    // about only matters if we read Cesium's camera state back into our
+    // calculations; we always recompute from the IFC source of truth.)
+    const rightECEF = Cesium.Cartesian3.cross(dirECEF, upECEF, new Cesium.Cartesian3());
+    Cesium.Cartesian3.normalize(rightECEF, rightECEF);
+
+    viewer.camera.position = posECEF;
+    viewer.camera.direction = dirECEF;
+    viewer.camera.up = upECEF;
+    viewer.camera.right = rightECEF;
+
+    // Sync FOV — IFC renderer reports VERTICAL FOV; Cesium's
+    // PerspectiveFrustum.fov is HORIZONTAL when aspect > 1 (landscape).
+    // Convert vertical → horizontal so the projection matches.
     const frustum = viewer.camera.frustum;
     if (frustum instanceof Cesium.PerspectiveFrustum) {
       const aspect = frustum.aspectRatio || (viewer.canvas.width / viewer.canvas.height);
       if (aspect > 1) {
-        // Landscape: Cesium expects horizontal FOV
-        // horizontal_fov = 2 * atan(aspect * tan(vertical_fov / 2))
         frustum.fov = 2 * Math.atan(aspect * Math.tan(fov / 2));
       } else {
-        // Portrait: Cesium uses fov as vertical — pass through
         frustum.fov = fov;
       }
     }
@@ -254,38 +297,12 @@ export async function createCesiumBridge(
     viewer.scene.requestRender();
   }
 
-  async function queryTerrainHeight(
+  /** Resolve terrain elevation at the model origin via the shared pipeline. */
+  function queryTerrainHeight(
     Cesium: typeof import('cesium'),
     viewer: InstanceType<typeof import('cesium').Viewer>,
   ): Promise<number | null> {
-    const position = Cesium.Cartographic.fromDegrees(originLon, originLat);
-
-    try {
-      const globeHeight = viewer.scene.globe.getHeight(position);
-      if (globeHeight !== undefined && Number.isFinite(globeHeight)) {
-        return globeHeight;
-      }
-    } catch { /* not available yet */ }
-
-    try {
-      const terrainProvider = viewer.terrainProvider;
-      if (terrainProvider) {
-        const results = await Cesium.sampleTerrainMostDetailed(terrainProvider, [position]);
-        if (results && results.length > 0 && Number.isFinite(results[0].height)) {
-          return results[0].height;
-        }
-      }
-    } catch { /* terrain sampling failed */ }
-
-    await new Promise(r => setTimeout(r, TERRAIN_QUERY_RETRY_DELAY_MS));
-    try {
-      const globeHeight = viewer.scene.globe.getHeight(position);
-      if (globeHeight !== undefined && Number.isFinite(globeHeight)) {
-        return globeHeight;
-      }
-    } catch { /* still not available */ }
-
-    return null;
+    return resolveTerrainElevation(Cesium, viewer, originLat, originLon);
   }
 
   function viewerToGeodetic(vx: number, vy: number, vz: number): GeodesicPosition | null {

package/src/lib/geo/clamp-anchor.test.ts

@@ -0,0 +1,80 @@
+/* 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/. */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import { findClampAnchorY } from './clamp-anchor.js';
+
+describe('findClampAnchorY', () => {
+  const buildingBounds = { min: { y: -3.5 }, max: { y: 50 } }; // basement at -3.5m, top at 50m
+
+  it('falls back to bounds.min.y when no storeys are present', () => {
+    assert.strictEqual(findClampAnchorY(buildingBounds, undefined), -3.5);
+    assert.strictEqual(findClampAnchorY(buildingBounds, new Map()), -3.5);
+  });
+
+  it('falls back to bounds.min.y when bounds are missing', () => {
+    const storeys = new Map([[1, 0], [2, 3]]);
+    assert.strictEqual(findClampAnchorY(undefined, storeys), 0);
+  });
+
+  it('picks the storey closest to elevation 0 (ground floor)', () => {
+    const storeys = new Map([
+      [1, -3.0],   // basement
+      [2, 0.0],    // ground floor — closest to 0
+      [3, 3.5],    // 1st floor
+      [4, 7.0],    // 2nd floor
+    ]);
+    assert.strictEqual(findClampAnchorY(buildingBounds, storeys), 0.0);
+  });
+
+  it('handles a model authored with a non-zero ground (e.g. 0.15m above origin)', () => {
+    const storeys = new Map([
+      [1, -3.0],
+      [2, 0.15],   // ground floor — closest to 0
+      [3, 3.65],
+    ]);
+    assert.strictEqual(findClampAnchorY(buildingBounds, storeys), 0.15);
+  });
+
+  it('ignores storeys outside the model bounds (avoid stray site-only markers)', () => {
+    // A "Site" or "External" storey with elevation way outside the actual
+    // building extents shouldn't lift the clamp out into mid-air.
+    const storeys = new Map([
+      [1, -3.0],
+      [2, 200],    // out of bounds — site marker, must be skipped
+      [3, 5.0],
+    ]);
+    // Within bounds: -3.0 (|3|) and 5.0 (|5|). −3.0 is closer to 0.
+    assert.strictEqual(findClampAnchorY(buildingBounds, storeys), -3.0);
+  });
+
+  it('uses the lowest storey if all are below 0 (basement-level model)', () => {
+    const bounds = { min: { y: -10 }, max: { y: -1 } };
+    const storeys = new Map([[1, -8], [2, -3]]);
+    // -3 is closer to 0 than -8
+    assert.strictEqual(findClampAnchorY(bounds, storeys), -3);
+  });
+
+  it('handles negative-only storeys without crashing', () => {
+    const bounds = { min: { y: -100 }, max: { y: 0 } };
+    const storeys = new Map([[1, -50], [2, -20]]);
+    assert.strictEqual(findClampAnchorY(bounds, storeys), -20);
+  });
+
+  it('skips non-finite elevations defensively', () => {
+    const storeys = new Map([
+      [1, NaN],
+      [2, Infinity],
+      [3, 2.0],
+    ]);
+    assert.strictEqual(findClampAnchorY(buildingBounds, storeys), 2.0);
+  });
+
+  it('falls back to bounds.min.y when every storey is out of range', () => {
+    const storeys = new Map([[1, 1000], [2, -1000]]);
+    assert.strictEqual(findClampAnchorY(buildingBounds, storeys), -3.5);
+  });
+});

package/src/lib/geo/clamp-anchor.ts

@@ -0,0 +1,57 @@
+/* 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/. */
+
+/**
+ * Clamp anchor selection.
+ *
+ * "Auto-clamp to terrain" needs to decide WHICH viewer-Y of the model
+ * should be pinned to the terrain surface. The naïve choice — `bounds.min.y`
+ * — anchors the lowest geometry vertex (typically the bottom of the
+ * basement / foundation) to terrain, which buries the building's
+ * actual ground floor below the surface.
+ *
+ * Better: pick the IfcBuildingStorey whose elevation is closest to 0
+ * (the conventional "ground floor"). Fall back to `bounds.min.y` when
+ * no storeys are present or none lie within the model's vertical
+ * extent — that preserves the previous behaviour for non-architectural
+ * IFCs (structural-only models, civil works, point clouds, etc.).
+ */
+
+interface BoundsLike {
+  min: { y: number };
+  max: { y: number };
+}
+
+/**
+ * @param bounds            Model bounds in viewer-space (Y-up, metres).
+ * @param storeyElevations  IFC storey elevations (metres, viewer-Y aligned).
+ *                          The geometry pipeline already converts IFC Z-up
+ *                          values to viewer-Y, so values here can be
+ *                          compared against `bounds.min.y` / `max.y`.
+ *
+ * @returns viewer-Y altitude that should land at terrain when clamping.
+ */
+export function findClampAnchorY(
+  bounds: BoundsLike | undefined,
+  storeyElevations: Map<number, number> | undefined,
+): number {
+  const minY = bounds?.min.y ?? 0;
+  if (!storeyElevations || storeyElevations.size === 0) return minY;
+
+  const maxY = bounds?.max.y ?? minY;
+  const slack = 1; // metre — tolerate storey markers slightly outside the AABB
+  let bestElevation: number | null = null;
+  let bestDistanceFromZero = Infinity;
+  for (const elevation of storeyElevations.values()) {
+    if (!Number.isFinite(elevation)) continue;
+    if (elevation < minY - slack || elevation > maxY + slack) continue;
+    const distance = Math.abs(elevation);
+    if (distance < bestDistanceFromZero) {
+      bestDistanceFromZero = distance;
+      bestElevation = elevation;
+    }
+  }
+
+  return bestElevation ?? minY;
+}

package/src/lib/geo/effective-georef.test.ts

@@ -5,7 +5,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
 
-import { inferMapUnitScale, mergeMapConversion, mergeProjectedCRS } from './effective-georef.js';
+import { detectScaleUnitMismatch, getEffectiveHorizontalScale, inferMapUnitScale, mergeMapConversion, mergeProjectedCRS } from './effective-georef.js';
 import type { MapConversion, ProjectedCRS } from '@ifc-lite/parser';
 
 describe('effective georeferencing', () => {
@@ -70,4 +70,82 @@ describe('effective georeferencing', () => {
     assert.strictEqual(inferMapUnitScale('METRE'), 1);
     assert.strictEqual(inferMapUnitScale('MILLIMETRE'), 0.001);
   });
+
+  describe('getEffectiveHorizontalScale (issue #595)', () => {
+    it('returns 1 when project mm and map m, with Scale=0.001 (Bonsai-style)', () => {
+      // mm project (lengthUnitScale=0.001), m map (mapUnitScale=1), Scale=0.001
+      assert.strictEqual(getEffectiveHorizontalScale(0.001, 1, 0.001), 1);
+    });
+
+    it('returns 1 when project m and map m, with Scale=1', () => {
+      assert.strictEqual(getEffectiveHorizontalScale(1, 1, 1), 1);
+    });
+
+    it('returns 1 when project ft and map m, with Scale=0.3048', () => {
+      assert.strictEqual(getEffectiveHorizontalScale(0.3048, 1, 0.3048), 1);
+    });
+
+    it('returns 1 when project mm and map mm, with Scale=1 (consistent units)', () => {
+      assert.strictEqual(getEffectiveHorizontalScale(1, 0.001, 0.001), 1);
+    });
+
+    it('preserves a deliberate non-unit scaling (Scale=2 with metres throughout)', () => {
+      assert.strictEqual(getEffectiveHorizontalScale(2, 1, 1), 2);
+    });
+
+    it('defaults Scale to 1 when undefined', () => {
+      // Project mm, map m, Scale undefined (treated as 1):
+      //   effective = 1 * 1 / 0.001 = 1000 → model would appear 1000x too large.
+      // This matches the IFC spec; users who omit Scale in such files have an
+      // inconsistent file. Issue #595 reports that this happens to "work"
+      // because the workaround offsets a different bug — fixed here.
+      assert.strictEqual(getEffectiveHorizontalScale(undefined, 1, 0.001), 1000);
+    });
+
+    it('falls back to 1 for non-positive lengthUnitScale or mapUnitScale', () => {
+      assert.strictEqual(getEffectiveHorizontalScale(1, 0, 1), 1);
+      assert.strictEqual(getEffectiveHorizontalScale(1, 1, 0), 1);
+      assert.strictEqual(getEffectiveHorizontalScale(1, -1, 1), 1);
+    });
+  });
+
+  describe('detectScaleUnitMismatch', () => {
+    it('returns null for spec-compliant Scale (mm/m with Scale=0.001)', () => {
+      assert.strictEqual(detectScaleUnitMismatch(0.001, 1, 0.001), null);
+    });
+
+    it('returns null when project=map=metres and Scale=1', () => {
+      assert.strictEqual(detectScaleUnitMismatch(1, 1, 1), null);
+    });
+
+    it('returns null when project=map=metres and Scale is undefined', () => {
+      assert.strictEqual(detectScaleUnitMismatch(undefined, 1, 1), null);
+    });
+
+    it('flags the common Scale=1 + mm-project + m-map error', () => {
+      const m = detectScaleUnitMismatch(1, 1, 0.001);
+      assert.ok(m, 'expected a mismatch report');
+      assert.strictEqual(m!.rawScale, 1);
+      assert.strictEqual(m!.effectiveScale, 1000);
+      assert.strictEqual(m!.expectedScale, 0.001);
+    });
+
+    it('flags Scale omitted when units differ', () => {
+      const m = detectScaleUnitMismatch(undefined, 1, 0.001);
+      assert.ok(m);
+      assert.strictEqual(m!.effectiveScale, 1000);
+    });
+
+    it('tolerates tiny floating-point noise around 1.0', () => {
+      // Scale = 1.0 ± 0.4% should still be considered consistent.
+      assert.strictEqual(detectScaleUnitMismatch(1.004, 1, 1), null);
+      assert.strictEqual(detectScaleUnitMismatch(0.996, 1, 1), null);
+    });
+
+    it('flags a deliberate non-unit scaling (Scale=2 with metres)', () => {
+      const m = detectScaleUnitMismatch(2, 1, 1);
+      assert.ok(m);
+      assert.strictEqual(m!.effectiveScale, 2);
+    });
+  });
 });

package/src/lib/geo/effective-georef.ts

@@ -23,6 +23,89 @@ export interface EffectiveGeoreference extends GeoreferenceInfo {
   lengthUnitScale: number;
 }
 
+/**
+ * Compute the effective horizontal scale to apply to viewer-space coordinates
+ * (which are already in metres) when transforming through IfcMapConversion.
+ *
+ * Per the IFC schema, IfcMapConversion.Scale converts LOCAL ENGINEERING
+ * coordinates (in the project's length unit) to MAP coordinates (in the map
+ * CRS unit). For a typical file with mm project units and m map units, the
+ * Scale attribute is 0.001.
+ *
+ * The IFC formula is:
+ *   E_map_units = Eastings + (X_local * absc - Y_local * ordi) * Scale
+ *
+ * To produce metres for proj4, we multiply by mapUnitScale; and X_local can be
+ * recovered from the metre-converted geometry as X_metres / lengthUnitScale.
+ * Substituting:
+ *   E_metres = mapUnitScale * Eastings
+ *            + (mapUnitScale * Scale / lengthUnitScale)
+ *              * (X_metres * absc - Y_metres * ordi)
+ *
+ * So when geometry has already been converted to metres (as ifc-lite does),
+ * the effective horizontal scale is (Scale * mapUnitScale) / lengthUnitScale.
+ * For files where Scale is set per IFC spec to bridge the unit difference
+ * (Scale = lengthUnitScale / mapUnitScale), this evaluates to 1.0 and the
+ * geometry passes through unchanged. Applying the raw Scale would otherwise
+ * double-scale and shrink/expand the model — see issue #595.
+ */
+export function getEffectiveHorizontalScale(
+  ifcMapConversionScale: number | undefined,
+  mapUnitScale: number,
+  lengthUnitScale: number,
+): number {
+  const scale = ifcMapConversionScale ?? 1.0;
+  const lus = lengthUnitScale > 0 ? lengthUnitScale : 1;
+  const mus = mapUnitScale > 0 ? mapUnitScale : 1;
+  return (scale * mus) / lus;
+}
+
+export interface ScaleUnitMismatch {
+  /** Effective horizontal scale applied to viewer-space (metre) geometry. */
+  effectiveScale: number;
+  /** Raw IfcMapConversion.Scale (or 1 if absent). */
+  rawScale: number;
+  /** Map unit → metres factor (e.g. 1 for METRE, 0.001 for MILLIMETRE). */
+  mapUnitScale: number;
+  /** Project length unit → metres factor. */
+  lengthUnitScale: number;
+  /**
+   * Scale value the file would need for the IFC formula to map local→map
+   * coordinates without any extra scaling (i.e. lengthUnitScale / mapUnitScale).
+   */
+  expectedScale: number;
+}
+
+/**
+ * Detect when IfcMapConversion.Scale is inconsistent with the project and map
+ * units. Per the IFC schema, Scale × mapUnitScale should equal lengthUnitScale
+ * (i.e. effectiveScale = 1.0). A deviation usually means the authoring tool
+ * forgot to set Scale to bridge a unit difference (e.g. mm project + m map
+ * with Scale=1.0). Files like this render at the wrong size in any tool that
+ * follows the schema strictly — see issue #595.
+ *
+ * Returns null when the values are consistent (within 0.5% of 1.0); otherwise
+ * returns the diagnostic data so callers can surface a warning.
+ */
+export function detectScaleUnitMismatch(
+  ifcMapConversionScale: number | undefined,
+  mapUnitScale: number | undefined,
+  lengthUnitScale: number | undefined,
+): ScaleUnitMismatch | null {
+  const lus = lengthUnitScale && lengthUnitScale > 0 ? lengthUnitScale : 1;
+  const mus = mapUnitScale && mapUnitScale > 0 ? mapUnitScale : 1;
+  const rawScale = ifcMapConversionScale ?? 1.0;
+  const effectiveScale = (rawScale * mus) / lus;
+  if (Math.abs(effectiveScale - 1) <= 0.005) return null;
+  return {
+    effectiveScale,
+    rawScale,
+    mapUnitScale: mus,
+    lengthUnitScale: lus,
+    expectedScale: lus / mus,
+  };
+}
+
 export function inferMapUnitScale(mapUnit: string | undefined, fallback?: number): number | undefined {
   if (!mapUnit) return fallback;
   const normalized = mapUnit.toUpperCase();

package/src/lib/geo/reproject.ts

@@ -19,6 +19,7 @@ import proj4 from 'proj4';
 import type { MapConversion, ProjectedCRS } from '@ifc-lite/parser';
 import type { CoordinateInfo } from '@ifc-lite/geometry';
 import { lookupProj4 } from '@ifc-lite/data';
+import { getEffectiveHorizontalScale } from './effective-georef';
 
 export interface LatLon {
   lat: number;
@@ -230,20 +231,24 @@ export async function resolveProjection(crs: ProjectedCRS): Promise<string | nul
  */
 function computeProjectedCenter(
   conversion: MapConversion,
-  coordinateInfo?: CoordinateInfo,
-  lengthUnitScale = 1,
+  coordinateInfo: CoordinateInfo | undefined,
+  mapUnitScale: number,
+  lengthUnitScale: number,
 ): { easting: number; northing: number } {
   const { ifcX, ifcY } = computeLocalIfcCenter(coordinateInfo);
 
   // Geometry coordinates (ifcX, ifcY) are already in metres — the geometry engine
   // converts from the IFC file's native unit during extraction. Only MapConversion
   // values (eastings, northings) are in the file's native unit and need scaling.
-  const scale = conversion.scale ?? 1.0;
+  // IfcMapConversion.Scale converts project length unit → map unit (e.g. 0.001
+  // for mm→m); since geometry is already in metres, use the effective scale —
+  // see issue #595.
+  const scale = getEffectiveHorizontalScale(conversion.scale, mapUnitScale, lengthUnitScale);
   const abscissa = conversion.xAxisAbscissa ?? 1.0;
   const ordinate = conversion.xAxisOrdinate ?? 0.0;
 
-  const easting = conversion.eastings * lengthUnitScale + scale * (abscissa * ifcX - ordinate * ifcY);
-  const northing = conversion.northings * lengthUnitScale + scale * (ordinate * ifcX + abscissa * ifcY);
+  const easting = conversion.eastings * mapUnitScale + scale * (abscissa * ifcX - ordinate * ifcY);
+  const northing = conversion.northings * mapUnitScale + scale * (ordinate * ifcX + abscissa * ifcY);
 
   return { easting, northing };
 }
@@ -281,7 +286,7 @@ export async function reprojectToLatLon(
   // MapConversion values use the unit from IfcProjectedCRS.MapUnit. If MapUnit
   // is not specified, the IFC spec defaults to the project's length unit.
   const mapScale = crs.mapUnitScale ?? lengthUnitScale;
-  const { easting, northing } = computeProjectedCenter(conversion, coordinateInfo, mapScale);
+  const { easting, northing } = computeProjectedCenter(conversion, coordinateInfo, mapScale, lengthUnitScale);
 
   try {
     const [lon, lat] = proj4(projDef, 'WGS84', [easting, northing]);
@@ -349,11 +354,12 @@ export async function reprojectFromLatLon(
     const mapScale = crs.mapUnitScale ?? lengthUnitScale;
     const invScale = mapScale !== 0 ? 1 / mapScale : 1;
     const { ifcX, ifcY } = computeLocalIfcCenter(coordinateInfo);
-    const scale = conversion?.scale ?? 1.0;
+    // Effective horizontal scale for metre-converted geometry — see issue #595.
+    const scale = getEffectiveHorizontalScale(conversion?.scale, mapScale, lengthUnitScale);
     const abscissa = conversion?.xAxisAbscissa ?? 1.0;
     const ordinate = conversion?.xAxisOrdinate ?? 0.0;
 
-    // Result is in IFC native units (the reverse of: E_native * LUS + geom_offset = E_metres)
+    // Result is in IFC native units (the reverse of: E_native * mapScale + geom_offset = E_metres)
     const easting = (projE - scale * (abscissa * ifcX - ordinate * ifcY)) * invScale;
     const northing = (projN - scale * (ordinate * ifcX + abscissa * ifcY)) * invScale;
 
@@ -387,7 +393,9 @@ export async function computeFootprintGeoJSON(
     return null;
   }
 
-  const scale = conversion.scale ?? 1.0;
+  // Effective horizontal scale for metre-converted geometry — see issue #595.
+  const mapScale = crs.mapUnitScale ?? lengthUnitScale;
+  const scale = getEffectiveHorizontalScale(conversion.scale, mapScale, lengthUnitScale);
   const abscissa = conversion.xAxisAbscissa ?? 1.0;
   const ordinate = conversion.xAxisOrdinate ?? 0.0;
 
@@ -418,8 +426,8 @@ export async function computeFootprintGeoJSON(
     const ifcX = worldX;
     const ifcY = -worldZ;
 
-    // Geometry coords (ifcX/Y) are already in metres; only MapConversion needs scaling
-    const mapScale = crs.mapUnitScale ?? lengthUnitScale;
+    // Geometry coords (ifcX/Y) are already in metres; MapConversion values
+    // are converted to metres via mapScale.
     const easting = conversion.eastings * mapScale + scale * (abscissa * ifcX - ordinate * ifcY);
     const northing = conversion.northings * mapScale + scale * (ordinate * ifcX + abscissa * ifcY);
 
@@ -443,14 +451,19 @@ export async function computeFootprintGeoJSON(
  * Returns height in metres above sea level, or null on failure.
  */
 export async function queryTerrainElevation(latLon: LatLon): Promise<number | null> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 5000);
   try {
     const url = `https://api.open-meteo.com/v1/elevation?latitude=${latLon.lat}&longitude=${latLon.lon}`;
-    const resp = await fetch(url);
+    const resp = await fetch(url, { signal: controller.signal });
     if (!resp.ok) return null;
     const data = await resp.json();
     const elev = data?.elevation?.[0];
     return typeof elev === 'number' && Number.isFinite(elev) ? elev : null;
-  } catch {
+  } catch (err) {
+    console.warn(`[reproject] queryTerrainElevation failed for ${latLon.lat},${latLon.lon}:`, err);
     return null;
+  } finally {
+    clearTimeout(timeoutId);
   }
 }