@ifc-lite/viewer 1.22.0 → 1.22.1

package/src/lib/geo/geo-scale.ts

@@ -33,10 +33,38 @@ export function getEffectiveHorizontalScale(
   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;
+  const specEffective = ((ifcMapConversionScale ?? 1.0) * mus) / lus;
+
+  // Heuristic for files that don't follow the IFC schema's unit-bridging rule.
+  //
+  // Spec: IfcMapConversion.Scale converts LOCAL ENGINEERING coords (in the
+  // project length unit) to MAP coords (in MapUnit). So a file with mm
+  // project units + m map units MUST set Scale=0.001 to bridge the gap, and
+  // (Scale * mapUnitScale) / lengthUnitScale evaluates to 1 — geometry passes
+  // through unchanged.
+  //
+  // Reality: Bonsai/IfcOpenShell, Revit's IFC exporter, and many CAD tools
+  // either leave Scale unset (default 1.0) or hard-code Scale=1 regardless of
+  // unit pairing. The author's intent in those cases is "geometry and offsets
+  // share the same metric unit", but the spec-strict formula then multiplies
+  // viewer-space metres by 1/lengthUnitScale (e.g. 1000x for mm projects),
+  // inflating the model so far that proj4 extrapolates to the projection's
+  // antipode (Hans's `IXAS_KW 018_georeffed.ifc`: 126500/480000 RD offsets +
+  // mm units + Scale unset → South Pacific instead of the Netherlands).
+  //
+  // When the file's Scale is unset or exactly 1 AND the units don't match,
+  // honour the practical intent: behave as if Scale had been set per spec
+  // (effectiveScale = 1) so the metre-converted geometry passes through.
+  // Files that genuinely use Scale ≠ 1 (e.g. units bridging a foot/metre
+  // gap with Scale=0.3048) are left alone — they followed the spec.
+  const rawScaleProvided = ifcMapConversionScale != null
+    && Math.abs(ifcMapConversionScale - 1) > 1e-9;
+  if (!rawScaleProvided && Math.abs(mus - lus) > 1e-9) {
+    return 1;
+  }
+  return specEffective;
 }
 
 export interface ScaleUnitMismatch {
@@ -102,3 +130,31 @@ export function inferMapUnitScale(
   if (normalized.includes('METRE') || normalized.includes('METER')) return 1;
   return fallback;
 }
+
+/**
+ * Resolve the scale factor converting `IfcMapConversion.eastings/northings/
+ * orthogonalHeight` into metres (the unit proj4 expects).
+ *
+ * IFC4 spec: those offsets are in `IfcProjectedCRS.MapUnit`, falling back to
+ * the project's `IfcUnitAssignment` LengthUnit when MapUnit is absent.
+ *
+ * Real-world practice diverges: Bonsai, IfcOpenShell, and most surveying
+ * pipelines emit metre values regardless of the project's length unit because
+ * survey CRS offsets come in metres. When MapUnit is absent AND the project
+ * unit isn't metres, applying the spec interpretation pushes coords miles
+ * outside the CRS's valid range, and projections like RD New / OSGB / Lambert
+ * extrapolate to the projection's antipode (e.g. an RD easting of `126500`
+ * read as mm = `126.5 m` → South Pacific instead of the Netherlands).
+ *
+ * Heuristic: when no explicit MapUnit is set, treat the offsets as metres.
+ * Files that genuinely use non-metre offsets can set MapUnit explicitly
+ * (e.g. `IfcProjectedCRS.MapUnit = MILLIMETRE`) to opt out.
+ */
+export function resolveMapUnitToMetreScale(
+  mapUnitScaleFromCrs: number | undefined,
+  lengthUnitScale: number,
+): number {
+  if (mapUnitScaleFromCrs && mapUnitScaleFromCrs > 0) return mapUnitScaleFromCrs;
+  void lengthUnitScale; // parameter kept for future spec-strict override
+  return 1;
+}

package/src/lib/geo/ifc-origin.test.ts

@@ -0,0 +1,176 @@
+/* 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 { computeIfcOriginViewerPosition, type ModelGeorefInput } from './ifc-origin.js';
+import type { MapConversion, ProjectedCRS } from '@ifc-lite/parser';
+import type { CoordinateInfo } from '@ifc-lite/geometry';
+
+function rdCrs(): ProjectedCRS {
+  return { id: 1, name: 'EPSG:28992', mapUnit: 'METRE', mapUnitScale: 1 };
+}
+
+function utm31Crs(): ProjectedCRS {
+  return { id: 2, name: 'EPSG:25831', mapUnit: 'METRE', mapUnitScale: 1 };
+}
+
+function makeConversion(eastings: number, northings: number, height = 0): MapConversion {
+  return {
+    id: 100,
+    sourceCRS: 10,
+    targetCRS: 1,
+    eastings,
+    northings,
+    orthogonalHeight: height,
+    xAxisAbscissa: 1,
+    xAxisOrdinate: 0,
+    scale: 1,
+  };
+}
+
+function emptyCoordinateInfo(): CoordinateInfo {
+  return {
+    originShift: { x: 0, y: 0, z: 0 },
+    originalBounds: { min: { x: 0, y: 0, z: 0 }, max: { x: 0, y: 0, z: 0 } },
+    shiftedBounds: { min: { x: 0, y: 0, z: 0 }, max: { x: 0, y: 0, z: 0 } },
+    hasLargeCoordinates: false,
+  };
+}
+
+describe('computeIfcOriginViewerPosition', () => {
+  it('returns -shift - rtcYup for a standalone model (no anchor)', async () => {
+    const model: ModelGeorefInput = {
+      coordinateInfo: {
+        ...emptyCoordinateInfo(),
+        originShift: { x: 50, y: 3, z: -20 },
+        wasmRtcOffset: { x: 10, y: 7, z: -4 },
+      },
+    };
+    const out = await computeIfcOriginViewerPosition(model, null);
+    assert.ok(out);
+    assert.strictEqual(out!.source, 'self');
+    // rtcYup = (10, -4, -7); total offset (60, -1, -27); negated = (-60, 1, 27)
+    assert.strictEqual(out!.viewer.x, -60);
+    assert.strictEqual(out!.viewer.y, 1);
+    assert.strictEqual(out!.viewer.z, 27);
+  });
+
+  it('treats the anchor model as its own frame even with georef present', async () => {
+    const conversion = makeConversion(155000, 463000);
+    const model: ModelGeorefInput = {
+      coordinateInfo: { ...emptyCoordinateInfo(), originShift: { x: 1, y: 2, z: 3 } },
+      mapConversion: conversion,
+      projectedCRS: rdCrs(),
+      lengthUnitScale: 1,
+    };
+    const out = await computeIfcOriginViewerPosition(model, model);
+    assert.ok(out);
+    assert.strictEqual(out!.source, 'self');
+    assert.strictEqual(out!.viewer.x, -1);
+    assert.strictEqual(out!.viewer.y, -2);
+    assert.strictEqual(out!.viewer.z, -3);
+  });
+
+  it('places a same-CRS non-anchor model relative to the anchor by easting/northing diff', async () => {
+    // Anchor IFC origin sits at (eastings=124000, northings=477000, h=0) in RD.
+    // A second model with eastings=124100, northings=477050 should land in
+    // the anchor's viewer-Y-up space at (Δeasting, Δheight, -Δnorthing) =
+    // (100, 0, -50) after accounting for the IFC Z-up → viewer Y-up swap,
+    // minus the anchor's shift.
+    const anchorConv = makeConversion(124000, 477000);
+    const anchor: ModelGeorefInput = {
+      coordinateInfo: emptyCoordinateInfo(),
+      mapConversion: anchorConv,
+      projectedCRS: rdCrs(),
+      lengthUnitScale: 1,
+    };
+    const otherConv = makeConversion(124100, 477050);
+    const other: ModelGeorefInput = {
+      coordinateInfo: emptyCoordinateInfo(),
+      mapConversion: otherConv,
+      projectedCRS: rdCrs(),
+      lengthUnitScale: 1,
+    };
+    const out = await computeIfcOriginViewerPosition(other, anchor);
+    assert.ok(out);
+    assert.strictEqual(out!.source, 'anchor');
+    // ifcX = +100, ifcY = +50 (Δnorthing positive); viewer Z = -ifcY = -50
+    assert.ok(Math.abs(out!.viewer.x - 100) < 1e-9, `viewer.x = ${out!.viewer.x}`);
+    assert.ok(Math.abs(out!.viewer.y - 0) < 1e-9, `viewer.y = ${out!.viewer.y}`);
+    assert.ok(Math.abs(out!.viewer.z - -50) < 1e-9, `viewer.z = ${out!.viewer.z}`);
+  });
+
+  it('accounts for orthogonalHeight differences (vertical offset)', async () => {
+    const anchor: ModelGeorefInput = {
+      coordinateInfo: emptyCoordinateInfo(),
+      mapConversion: makeConversion(0, 0, 100),
+      projectedCRS: rdCrs(),
+      lengthUnitScale: 1,
+    };
+    const other: ModelGeorefInput = {
+      coordinateInfo: emptyCoordinateInfo(),
+      mapConversion: makeConversion(0, 0, 150),
+      projectedCRS: rdCrs(),
+      lengthUnitScale: 1,
+    };
+    const out = await computeIfcOriginViewerPosition(other, anchor);
+    assert.ok(out);
+    // Δheight = +50, viewer Y is vertical → y = 50.
+    assert.ok(Math.abs(out!.viewer.y - 50) < 1e-9, `viewer.y = ${out!.viewer.y}`);
+    assert.ok(Math.abs(out!.viewer.x) < 1e-9);
+    assert.ok(Math.abs(out!.viewer.z) < 1e-9);
+  });
+
+  it('reprojects across CRSs (RD New ↔ UTM zone 31N) within a few metres', async () => {
+    // Anchor in RD at (155000, 463000) — Amersfoort tower origin.
+    // Same physical location, expressed in UTM 31N, is roughly (660000, 5780000).
+    // Use proj4 to get the exact expected UTM coords, then verify the function
+    // brings the second model's origin to the anchor's IFC (0,0,0) (i.e. viewer 0,0,0)
+    // within a small tolerance.
+    const proj4 = (await import('proj4')).default;
+    const rdDef = '+proj=sterea +lat_0=52.1561605555556 +lon_0=5.38763888888889 +k=0.9999079 +x_0=155000 +y_0=463000 +ellps=bessel +towgs84=565.4171,50.3319,465.5524,1.9342,-1.6677,9.1019,4.0725 +units=m +no_defs';
+    const utmDef = '+proj=utm +zone=31 +datum=WGS84 +units=m +no_defs';
+    const [utmE, utmN] = proj4(rdDef, utmDef, [155000, 463000]);
+
+    const anchor: ModelGeorefInput = {
+      coordinateInfo: emptyCoordinateInfo(),
+      mapConversion: makeConversion(155000, 463000),
+      projectedCRS: rdCrs(),
+      lengthUnitScale: 1,
+    };
+    const other: ModelGeorefInput = {
+      coordinateInfo: emptyCoordinateInfo(),
+      mapConversion: makeConversion(utmE, utmN),
+      projectedCRS: utm31Crs(),
+      lengthUnitScale: 1,
+    };
+    const out = await computeIfcOriginViewerPosition(other, anchor);
+    assert.ok(out);
+    assert.strictEqual(out!.source, 'anchor');
+    // Round-trip should land at the anchor origin within a small tolerance.
+    // Both directions go through +towgs84 approximations, so a few metres of
+    // residual is acceptable.
+    assert.ok(Math.abs(out!.viewer.x) < 5, `viewer.x residual = ${out!.viewer.x}`);
+    assert.ok(Math.abs(out!.viewer.z) < 5, `viewer.z residual = ${out!.viewer.z}`);
+  });
+
+  it('falls back to the model own frame when the anchor lacks georef', async () => {
+    const model: ModelGeorefInput = {
+      coordinateInfo: { ...emptyCoordinateInfo(), originShift: { x: 99, y: 1, z: 2 } },
+      mapConversion: makeConversion(1, 2),
+      projectedCRS: rdCrs(),
+      lengthUnitScale: 1,
+    };
+    const anchorWithoutGeoref: ModelGeorefInput = {
+      coordinateInfo: emptyCoordinateInfo(),
+      // No mapConversion / projectedCRS — represents a model loaded without georef.
+    };
+    const out = await computeIfcOriginViewerPosition(model, anchorWithoutGeoref);
+    assert.ok(out);
+    assert.strictEqual(out!.source, 'fallback');
+    assert.strictEqual(out!.viewer.x, -99);
+  });
+});

package/src/lib/geo/ifc-origin.ts

@@ -0,0 +1,144 @@
+/* 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/. */
+
+/**
+ * Compute the viewer-space position where a model's IFC (0,0,0) point
+ * currently sits — the "true" IFC origin, regardless of any federation
+ * alignment that re-baked the vertices.
+ *
+ * Standalone load or this model is the federation anchor:
+ *   viewer = -(originShift + wasmRtcOffset_Yup)
+ *
+ * Non-anchor federated model:
+ *   1. IFC (0,0,0)  → model projected coords (E_m, N_m, H_m)  [the pivot,
+ *      so MapConversion rotation/scale collapses to the offsets]
+ *   2. model projected → anchor projected via proj4 (identity if same CRS)
+ *   3. anchor projected → anchor IFC frame via inverse MapConversion
+ *   4. anchor IFC (Z-up) → world Y-up via axis swap
+ *   5. subtract anchor's shift + rtc to land in anchor viewer-local space
+ *
+ * This works for both same-CRS arithmetic alignment and cross-CRS proj4
+ * alignment without depending on stored alignment transforms or vertex
+ * snapshots — it derives everything from the MapConversion + ProjectedCRS
+ * the IFC file declares.
+ */
+
+import proj4 from 'proj4';
+import type { MapConversion, ProjectedCRS } from '@ifc-lite/parser';
+import type { CoordinateInfo } from '@ifc-lite/geometry';
+import { resolveProjection } from './reproject';
+import { getEffectiveHorizontalScale, resolveMapUnitToMetreScale } from './geo-scale';
+
+export interface IfcOriginPlacement {
+  /** Viewer-local position (Y-up) where this model's IFC (0,0,0) currently sits. */
+  viewer: { x: number; y: number; z: number };
+  /**
+   * How the position was computed:
+   *   - `'self'`      — model is its own frame (standalone or anchor)
+   *   - `'anchor'`    — projected from model georef → anchor georef
+   *   - `'fallback'`  — anchor has no usable georef; used model's own
+   *                     pre-alignment frame as a best-effort guess
+   */
+  source: 'self' | 'anchor' | 'fallback';
+}
+
+export interface ModelGeorefInput {
+  coordinateInfo?: CoordinateInfo;
+  mapConversion?: MapConversion;
+  projectedCRS?: ProjectedCRS;
+  lengthUnitScale?: number;
+  preAlignmentCoordinateInfo?: CoordinateInfo;
+}
+
+function totalYupOffset(info?: CoordinateInfo): { x: number; y: number; z: number } {
+  const shift = info?.originShift ?? { x: 0, y: 0, z: 0 };
+  const rtc = info?.wasmRtcOffset;
+  const rtcYup = rtc ? { x: rtc.x, y: rtc.z, z: -rtc.y } : { x: 0, y: 0, z: 0 };
+  return { x: shift.x + rtcYup.x, y: shift.y + rtcYup.y, z: shift.z + rtcYup.z };
+}
+
+export async function computeIfcOriginViewerPosition(
+  model: ModelGeorefInput,
+  anchor?: ModelGeorefInput | null,
+): Promise<IfcOriginPlacement | null> {
+  // Standalone load, or model has no georef → its own frame.
+  if (!anchor || !model.mapConversion || !model.projectedCRS) {
+    const off = totalYupOffset(model.coordinateInfo);
+    return { viewer: { x: -off.x, y: -off.y, z: -off.z }, source: 'self' };
+  }
+  if (model === anchor) {
+    const off = totalYupOffset(anchor.coordinateInfo);
+    return { viewer: { x: -off.x, y: -off.y, z: -off.z }, source: 'self' };
+  }
+  if (!anchor.mapConversion || !anchor.projectedCRS) {
+    // Anchor has no usable georef. The model's geometry was either left in
+    // its own frame or aligned via RTC-only — fall back to pre-alignment.
+    const off = totalYupOffset(model.preAlignmentCoordinateInfo ?? model.coordinateInfo);
+    return { viewer: { x: -off.x, y: -off.y, z: -off.z }, source: 'fallback' };
+  }
+
+  // Step 1: model IFC (0,0,0) → model projected. At the pivot, rotation+scale
+  // multiply zero — only the eastings/northings/orthogonalHeight remain.
+  const modelLengthScale = model.lengthUnitScale ?? 1;
+  const modelMapUnitScale = resolveMapUnitToMetreScale(model.projectedCRS.mapUnitScale, modelLengthScale);
+  const eM = model.mapConversion.eastings * modelMapUnitScale;
+  const nM = model.mapConversion.northings * modelMapUnitScale;
+  const hM = model.mapConversion.orthogonalHeight * modelMapUnitScale;
+
+  // Step 2: same CRS → identity; different CRS → proj4 hop.
+  let eA = eM;
+  let nA = nM;
+  const sameCrs = (model.projectedCRS.name ?? '').toUpperCase()
+    === (anchor.projectedCRS.name ?? '').toUpperCase();
+  if (!sameCrs) {
+    const srcDef = await resolveProjection(model.projectedCRS);
+    const refDef = await resolveProjection(anchor.projectedCRS);
+    if (!srcDef || !refDef) return null;
+    try {
+      const result = proj4(srcDef, refDef, [eM, nM]);
+      eA = result[0];
+      nA = result[1];
+    } catch (error) {
+      console.warn(
+        `[ifc-origin] proj4 reprojection failed (${model.projectedCRS.name} → ${anchor.projectedCRS.name}) for [${eM}, ${nM}]:`,
+        error,
+      );
+      return null;
+    }
+  }
+  const hA = hM; // No vertical datum transform in browser.
+
+  // Step 3: anchor projected → anchor IFC (invert anchor's MapConversion).
+  const anchorLengthScale = anchor.lengthUnitScale ?? 1;
+  const anchorMapUnitScale = resolveMapUnitToMetreScale(anchor.projectedCRS.mapUnitScale, anchorLengthScale);
+  const eAnchor = anchor.mapConversion.eastings * anchorMapUnitScale;
+  const nAnchor = anchor.mapConversion.northings * anchorMapUnitScale;
+  const hAnchor = anchor.mapConversion.orthogonalHeight * anchorMapUnitScale;
+  const anchorAbsc = anchor.mapConversion.xAxisAbscissa ?? 1;
+  const anchorOrd = anchor.mapConversion.xAxisOrdinate ?? 0;
+  const anchorScale = getEffectiveHorizontalScale(
+    anchor.mapConversion.scale,
+    anchorMapUnitScale,
+    anchorLengthScale,
+  );
+  const anchorDenom = anchorScale * Math.max(anchorAbsc * anchorAbsc + anchorOrd * anchorOrd, 1e-12);
+  if (Math.abs(anchorDenom) < 1e-12) return null;
+  const invDenom = 1 / anchorDenom;
+  const dE = eA - eAnchor;
+  const dN = nA - nAnchor;
+  const ifcX = invDenom * (anchorAbsc * dE + anchorOrd * dN);
+  const ifcY = invDenom * (-anchorOrd * dE + anchorAbsc * dN);
+  const ifcZ = hA - hAnchor;
+
+  // Step 4 + 5: IFC Z-up → world Y-up → anchor viewer-local
+  const anchorOff = totalYupOffset(anchor.coordinateInfo);
+  return {
+    viewer: {
+      x: ifcX - anchorOff.x,
+      y: ifcZ - anchorOff.y,
+      z: -ifcY - anchorOff.z,
+    },
+    source: 'anchor',
+  };
+}