@ifc-lite/viewer 1.21.0 → 1.22.1

package/src/lib/geo/terrain-elevation.ts

@@ -13,13 +13,34 @@
 
 import { queryTerrainElevation } from './reproject';
 
+export type TerrainElevationSource =
+  | 'globe.getHeight'
+  | 'scene.sampleHeight'
+  | 'scene.sampleHeightMostDetailed'
+  | 'open-meteo';
+
+export type TerrainHeightReference = 'ellipsoidal' | 'visual-surface' | 'orthometric';
+
+export interface TerrainElevationSample {
+  height: number;
+  source: TerrainElevationSource;
+  reference: TerrainHeightReference;
+  cacheNamespace: string;
+  fromCache: boolean;
+}
+
+export interface ResolveTerrainElevationOptions {
+  cacheNamespace?: string;
+  preferOrthometric?: boolean;
+}
+
 // Module-level cache so bridge rebuilds (georef edits, clamp toggles)
 // re-use values within the session instead of re-hitting the network.
-const terrainElevationCache = new Map<string, number>();
+const terrainElevationCache = new Map<string, TerrainElevationSample>();
 
-function terrainCacheKey(lat: number, lon: number): string {
+function terrainCacheKey(lat: number, lon: number, cacheNamespace: string): string {
   // 5 decimal places ≈ 1.1m precision — plenty for site-level elevation.
-  return `${lat.toFixed(5)},${lon.toFixed(5)}`;
+  return `${cacheNamespace}:${lat.toFixed(5)},${lon.toFixed(5)}`;
 }
 
 // Earth's plausible terrestrial elevation range. Mariana Trench ≈ −11 km
@@ -45,122 +66,210 @@ export function clearTerrainElevationCache(): void {
  *
  * Order:
  *   1. Cache (instant — re-bridge after georef edit).
- *   2. globe.getHeight (sync, terrain provider — exact-zero treated as
- *      "no data" since the default ellipsoid provider returns 0 for every
- *      lat/lon).
- *   3. scene.sampleHeight (sync, queries 3D Tiles + terrain — only works
+ *   2. scene.sampleHeight (sync, queries 3D Tiles + terrain — only works
  *      if tiles for the location are already rendered).
- *   4. scene.sampleHeightMostDetailed with a bounded timeout — forces tile
+ *   3. scene.sampleHeightMostDetailed with a bounded timeout — forces tile
  *      load and returns the height of the actually-rendered surface (what
  *      the user SEES in Google Photorealistic 3D Tiles). Tried before
  *      Open-Meteo because the visible-tile elevation is what models need
  *      to sit on; Open-Meteo's DEM ignores buildings/road surfaces.
+ *   4. globe.getHeight (terrain provider fallback — exact-zero treated as
+ *      "no data" since the default ellipsoid provider returns 0 for every
+ *      lat/lon).
  *   5. Open-Meteo elevation API — bare-earth fallback when tiles can't be
  *      sampled (offline, no 3D tileset, timeout, etc.).
  */
 const SAMPLE_DETAILED_TIMEOUT_MS = 3500;
 
-export async function resolveTerrainElevation(
+function getTerrainSourceReference(source: TerrainElevationSource): TerrainHeightReference {
+  switch (source) {
+    case 'globe.getHeight':
+      return 'ellipsoidal';
+    case 'scene.sampleHeight':
+    case 'scene.sampleHeightMostDetailed':
+      return 'visual-surface';
+    case 'open-meteo':
+      return 'orthometric';
+  }
+}
+
+function acceptTerrainElevation(
+  cacheKey: string,
+  height: number,
+  source: TerrainElevationSource,
+  cacheNamespace: string,
+  ms?: number,
+): TerrainElevationSample {
+  const sample: TerrainElevationSample = {
+    height,
+    source,
+    reference: getTerrainSourceReference(source),
+    cacheNamespace,
+    fromCache: false,
+  };
+  terrainElevationCache.set(cacheKey, sample);
+  const timing = ms !== undefined ? ` (${ms.toFixed(0)}ms)` : '';
+  console.debug(
+    `[TerrainElevation] via ${source}: ${height.toFixed(2)}m`
+    + ` (${sample.reference}) at ${cacheKey}${timing}`,
+  );
+  return sample;
+}
+
+function getTerrainSourceCandidates(
+  preferOrthometric: boolean,
+): Array<{
+  source: TerrainElevationSource;
+  resolve: (
+    Cesium: typeof import('cesium'),
+    viewer: InstanceType<typeof import('cesium').Viewer>,
+    position: InstanceType<typeof import('cesium').Cartographic>,
+    lat: number,
+    lon: number,
+  ) => Promise<{ height: number | undefined | null; elapsedMs?: number; skipped?: boolean }>;
+}> {
+  const candidates = [
+    {
+      source: 'scene.sampleHeight' as const,
+      resolve: async (
+        _Cesium: typeof import('cesium'),
+        viewer: InstanceType<typeof import('cesium').Viewer>,
+        position: InstanceType<typeof import('cesium').Cartographic>,
+      ) => {
+        if (!viewer.scene.sampleHeightSupported) return { height: null, skipped: true };
+        return { height: viewer.scene.sampleHeight(position) };
+      },
+    },
+    {
+      source: 'scene.sampleHeightMostDetailed' as const,
+      resolve: async (
+        _Cesium: typeof import('cesium'),
+        viewer: InstanceType<typeof import('cesium').Viewer>,
+        position: InstanceType<typeof import('cesium').Cartographic>,
+      ) => {
+        if (!viewer.scene.sampleHeightSupported) return { height: null, skipped: true };
+
+        let timeoutId: ReturnType<typeof setTimeout> | undefined;
+        try {
+          const t0 = performance.now();
+          const detailed = viewer.scene.sampleHeightMostDetailed([position]);
+          const timeout = new Promise<null>((resolve) => {
+            timeoutId = setTimeout(() => resolve(null), SAMPLE_DETAILED_TIMEOUT_MS);
+          });
+          const winner = await Promise.race([detailed, timeout]);
+          const elapsedMs = performance.now() - t0;
+          if (winner === null) {
+            console.debug(
+              `[TerrainElevation] sampleHeightMostDetailed timed out after ${elapsedMs.toFixed(0)}ms`,
+            );
+            return { height: null, elapsedMs, skipped: true };
+          }
+
+          const r0 = winner[0] as { height?: number } | undefined;
+          return { height: r0?.height, elapsedMs };
+        } finally {
+          if (timeoutId !== undefined) clearTimeout(timeoutId);
+        }
+      },
+    },
+    {
+      source: 'globe.getHeight' as const,
+      resolve: async (
+        _Cesium: typeof import('cesium'),
+        viewer: InstanceType<typeof import('cesium').Viewer>,
+        position: InstanceType<typeof import('cesium').Cartographic>,
+      ) => {
+        const h = viewer.scene.globe.getHeight(position);
+        if (h !== undefined && Math.abs(h) <= 1e-3) {
+          return { height: null, skipped: true };
+        }
+        return { height: h };
+      },
+    },
+    {
+      source: 'open-meteo' as const,
+      resolve: async (
+        _Cesium: typeof import('cesium'),
+        _viewer: InstanceType<typeof import('cesium').Viewer>,
+        _position: InstanceType<typeof import('cesium').Cartographic>,
+        lat: number,
+        lon: number,
+      ) => {
+        const t0 = performance.now();
+        const elev = await queryTerrainElevation({ lat, lon });
+        return { height: elev, elapsedMs: performance.now() - t0 };
+      },
+    },
+  ];
+
+  if (!preferOrthometric) return candidates;
+  return [
+    candidates[3],
+    candidates[2],
+    candidates[0],
+    candidates[1],
+  ];
+}
+
+export async function resolveTerrainElevationDetailed(
   Cesium: typeof import('cesium'),
   viewer: InstanceType<typeof import('cesium').Viewer>,
   lat: number,
   lon: number,
-): Promise<number | null> {
-  const cacheKey = terrainCacheKey(lat, lon);
+  options: ResolveTerrainElevationOptions = {},
+): Promise<TerrainElevationSample | null> {
+  const cacheNamespace = options.cacheNamespace ?? 'default';
+  const preferOrthometric = options.preferOrthometric ?? false;
+  const cacheKey = terrainCacheKey(lat, lon, cacheNamespace);
   const cached = terrainElevationCache.get(cacheKey);
   if (cached !== undefined) {
-    console.debug(`[TerrainElevation] cached at ${cacheKey}: ${cached.toFixed(2)}m`);
-    return cached;
+    console.debug(
+      `[TerrainElevation] cached at ${cacheKey}: ${cached.height.toFixed(2)}m`
+      + ` via ${cached.source} (${cached.reference})`,
+    );
+    return { ...cached, fromCache: true };
   }
 
   const position = Cesium.Cartographic.fromDegrees(lon, lat);
-  const accept = (h: number, source: string, ms?: number): number => {
-    terrainElevationCache.set(cacheKey, h);
-    const t = ms !== undefined ? ` (${ms.toFixed(0)}ms)` : '';
-    console.debug(`[TerrainElevation] via ${source}: ${h.toFixed(2)}m at ${cacheKey}${t}`);
-    return h;
-  };
   const skip = (h: unknown, source: string) => {
     console.debug(`[TerrainElevation] ${source} returned implausible value ${h}; skipping`);
   };
 
-  // 1. Sync globe.getHeight. The default ellipsoid provider returns 0 for
-  //    every lat/lon, so when no real terrain provider is wired we'd lock
-  //    in 0 and never reach the network fallbacks. Treat exact-zero from
-  //    this source specifically as "no data" — Open-Meteo can still return
-  //    a true 0 elsewhere in the chain for legitimate sea-level sites.
-  try {
-    const h = viewer.scene.globe.getHeight(position);
-    if (h !== undefined && isPlausibleElevation(h) && Math.abs(h) > 1e-3) {
-      return accept(h, 'globe.getHeight');
-    }
-    if (h !== undefined && !isPlausibleElevation(h)) skip(h, 'globe.getHeight');
-  } catch (err) {
-    console.warn('[TerrainElevation] globe.getHeight threw:', err);
-  }
-
-  // 2. Sync scene.sampleHeight — works with 3D Tiles when tiles for this
-  //    location are already rendered.
-  if (viewer.scene.sampleHeightSupported) {
+  for (const candidate of getTerrainSourceCandidates(preferOrthometric)) {
     try {
-      const h = viewer.scene.sampleHeight(position);
-      if (h !== undefined && isPlausibleElevation(h)) {
-        return accept(h, 'scene.sampleHeight');
+      const { height, elapsedMs, skipped } = await candidate.resolve(
+        Cesium, viewer, position, lat, lon,
+      );
+      if (height !== undefined && height !== null && isPlausibleElevation(height)) {
+        return acceptTerrainElevation(
+          cacheKey,
+          height,
+          candidate.source,
+          cacheNamespace,
+          elapsedMs,
+        );
       }
-      if (h !== undefined) skip(h, 'scene.sampleHeight');
-    } catch (err) {
-      console.warn('[TerrainElevation] scene.sampleHeight threw:', err);
-    }
-  }
-
-  // 3. Force-load the 3D-Tile tile at this location and sample the
-  //    rendered surface. This is what Google Photorealistic 3D Tiles
-  //    show on screen, so the model lands on the SAME surface the user
-  //    sees — no "below the visible ground" mismatch with Open-Meteo's
-  //    DEM. Bounded by a timeout so a slow tile fetch doesn't keep the
-  //    bridge waiting forever; Open-Meteo runs after as a backstop.
-  if (viewer.scene.sampleHeightSupported) {
-    let timeoutId: ReturnType<typeof setTimeout> | undefined;
-    try {
-      const t0 = performance.now();
-      const detailed = viewer.scene.sampleHeightMostDetailed([position]);
-      const timeout = new Promise<null>((resolve) => {
-        timeoutId = setTimeout(() => resolve(null), SAMPLE_DETAILED_TIMEOUT_MS);
-      });
-      const winner = await Promise.race([detailed, timeout]);
-      const ms = performance.now() - t0;
-      if (winner !== null) {
-        const r0 = winner[0] as { height?: number } | undefined;
-        if (r0?.height !== undefined && isPlausibleElevation(r0.height)) {
-          return accept(r0.height, 'scene.sampleHeightMostDetailed', ms);
-        }
-        if (r0?.height !== undefined) skip(r0.height, 'scene.sampleHeightMostDetailed');
-      } else {
-        console.debug(`[TerrainElevation] sampleHeightMostDetailed timed out after ${ms.toFixed(0)}ms`);
+      if (height !== undefined && height !== null) {
+        skip(height, candidate.source);
+      } else if (!skipped) {
+        console.debug(`[TerrainElevation] ${candidate.source} returned no value`);
       }
     } catch (err) {
-      console.warn('[TerrainElevation] sampleHeightMostDetailed threw:', err);
-    } finally {
-      // Cancel the timeout if the detailed sample resolved first, so the
-      // timer doesn't dangle and resolve to null after we've moved on.
-      if (timeoutId !== undefined) clearTimeout(timeoutId);
+      console.warn(`[TerrainElevation] ${candidate.source} threw:`, err);
     }
   }
 
-  // 4. Open-Meteo bare-earth elevation. Used as a network fallback when
-  //    the visible-tile sample didn't resolve in time.
-  try {
-    const t0 = performance.now();
-    const elev = await queryTerrainElevation({ lat, lon });
-    const ms = performance.now() - t0;
-    if (elev !== null && isPlausibleElevation(elev)) {
-      return accept(elev, 'Open-Meteo', ms);
-    }
-    if (elev !== null) skip(elev, 'Open-Meteo');
-  } catch (err) {
-    console.warn('[TerrainElevation] Open-Meteo threw:', err);
-  }
-
   console.warn(`[TerrainElevation] no source returned a plausible value at ${cacheKey}`);
   return null;
 }
+
+export async function resolveTerrainElevation(
+  Cesium: typeof import('cesium'),
+  viewer: InstanceType<typeof import('cesium').Viewer>,
+  lat: number,
+  lon: number,
+  options: ResolveTerrainElevationOptions = {},
+): Promise<number | null> {
+  const result = await resolveTerrainElevationDetailed(Cesium, viewer, lat, lon, options);
+  return result?.height ?? null;
+}

package/src/lib/lens/adapter.ts

@@ -14,6 +14,8 @@ import type { LensDataProvider, PropertySetInfo, ClassificationInfo } from '@ifc
 import type { IfcDataStore } from '@ifc-lite/parser';
 import {
   extractEntityAttributesOnDemand,
+  extractPropertiesOnDemand,
+  extractTypePropertiesOnDemand,
   extractQuantitiesOnDemand,
   extractClassificationsOnDemand,
   extractMaterialsOnDemand,
@@ -105,17 +107,61 @@ export function createLensDataProvider(
     ): unknown {
       const resolved = resolveGlobalId(globalId, entries);
       if (!resolved) return undefined;
-      return resolved.entry.ifcDataStore.properties?.getPropertyValue?.(
-        resolved.expressId,
-        propertySetName,
-        propertyName,
-      );
+      const store = resolved.entry.ifcDataStore;
+      const id = resolved.expressId;
+
+      // On-demand extraction path: pre-built table is empty for client-parsed
+      // stores, so iterate the same psets we expose via getPropertySets.
+      if (store.onDemandPropertyMap && store.source?.length > 0) {
+        const instancePsets = extractPropertiesOnDemand(store, id);
+        for (const pset of instancePsets) {
+          if (pset.name !== propertySetName) continue;
+          for (const prop of pset.properties) {
+            if (prop.name === propertyName) return prop.value;
+          }
+        }
+        // Fall through to type-inherited psets (Pset_*Common is typically
+        // attached to IfcSpaceType / IfcWallType, not the instance).
+        const typeProps = extractTypePropertiesOnDemand(store, id);
+        if (typeProps) {
+          for (const pset of typeProps.properties) {
+            if (pset.name !== propertySetName) continue;
+            for (const prop of pset.properties) {
+              if (prop.name === propertyName) return prop.value;
+            }
+          }
+        }
+        return undefined;
+      }
+
+      return store.properties?.getPropertyValue?.(id, propertySetName, propertyName);
     },
 
     getPropertySets(globalId: number): PropertySetInfo[] {
       const resolved = resolveGlobalId(globalId, entries);
       if (!resolved) return [];
-      const psets = resolved.entry.ifcDataStore.properties?.getForEntity?.(resolved.expressId);
+      const store = resolved.entry.ifcDataStore;
+      const id = resolved.expressId;
+
+      // Properties are extracted lazily — the pre-built table is empty unless
+      // server-parsed. Mirror the quantity path and use the on-demand extractor,
+      // which itself falls back to the eager table when no on-demand map exists.
+      if (store.onDemandPropertyMap && store.source?.length > 0) {
+        const instancePsets = extractPropertiesOnDemand(store, id) as PropertySetInfo[];
+        // Merge type-inherited psets (Pset_*Common lives on the type entity
+        // for occurrences). Instance psets take precedence on name conflict.
+        const typeProps = extractTypePropertiesOnDemand(store, id);
+        if (!typeProps || typeProps.properties.length === 0) return instancePsets;
+
+        const seen = new Set(instancePsets.map((p) => p.name));
+        const merged = instancePsets.slice();
+        for (const pset of typeProps.properties) {
+          if (!seen.has(pset.name)) merged.push(pset as PropertySetInfo);
+        }
+        return merged;
+      }
+
+      const psets = store.properties?.getForEntity?.(id);
       if (!psets) return [];
       return psets as PropertySetInfo[];
     },

package/src/lib/level-offsets.test.ts

@@ -0,0 +1,153 @@
+/* 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 {
+  computeStoreyOffsets,
+  diffStoreyOffsets,
+  entitiesInStorey,
+  buildEntityTranslations,
+} from './level-offsets.js';
+
+/**
+ * Build a stub IfcDataStore with just the spatialHierarchy bits
+ * the offset helpers read. Other fields are typed as `unknown` so
+ * the cast doesn't pollute production code with test shims.
+ */
+function makeStore(
+  storeyElevations: Map<number, number>,
+  elementToStorey?: Map<number, number>,
+): Parameters<typeof computeStoreyOffsets>[0] {
+  return {
+    spatialHierarchy: {
+      storeyElevations,
+      elementToStorey: elementToStorey ?? new Map(),
+    },
+  } as unknown as Parameters<typeof computeStoreyOffsets>[0];
+}
+
+describe('level-offsets', () => {
+  describe('computeStoreyOffsets', () => {
+    it('returns empty for a missing data store', () => {
+      assert.strictEqual(computeStoreyOffsets(undefined, 4).size, 0);
+    });
+
+    it('returns empty when gap is zero', () => {
+      const store = makeStore(new Map([[1, 0], [2, 3]]));
+      assert.strictEqual(computeStoreyOffsets(store, 0).size, 0);
+    });
+
+    it('lifts higher storeys to index * gap', () => {
+      // Three storeys at elevations 0, 3, 6; with gap=5 they
+      // should land at 0, 5, 10 (offsets 0, +2, +4).
+      const store = makeStore(new Map([[10, 0], [20, 3], [30, 6]]));
+      const offsets = computeStoreyOffsets(store, 5);
+      assert.strictEqual(offsets.get(10), undefined); // zero — omitted
+      assert.strictEqual(offsets.get(20), 2);
+      assert.strictEqual(offsets.get(30), 4);
+    });
+
+    it('handles basement-style negative elevations', () => {
+      // Storeys at -3, 0, 3 with gap=4 → indices 0,1,2 → targets
+      // -3, 1, 5. Offsets 0, +1, +2.
+      const store = makeStore(new Map([[1, -3], [2, 0], [3, 3]]));
+      const offsets = computeStoreyOffsets(store, 4);
+      assert.strictEqual(offsets.get(1), undefined);
+      assert.strictEqual(offsets.get(2), 1);
+      assert.strictEqual(offsets.get(3), 2);
+    });
+
+    it('preserves elevation ordering with equal gaps', () => {
+      // Storeys with non-uniform original spacing should still
+      // become uniformly spaced under Exploded.
+      const store = makeStore(new Map([[1, 0], [2, 4], [3, 5], [4, 12]]));
+      const offsets = computeStoreyOffsets(store, 3);
+      // Targets: 0, 3, 6, 9. Deltas: 0, -1, +1, -3.
+      assert.strictEqual(offsets.get(1), undefined);
+      assert.strictEqual(offsets.get(2), -1);
+      assert.strictEqual(offsets.get(3), 1);
+      assert.strictEqual(offsets.get(4), -3);
+    });
+  });
+
+  describe('diffStoreyOffsets', () => {
+    it('returns the per-storey delta between target and previous', () => {
+      const target = new Map([[1, 2], [2, 5]]);
+      const previous = new Map([[1, 1], [2, 6]]);
+      const diff = diffStoreyOffsets(target, previous);
+      assert.strictEqual(diff.get(1), 1); // 2 - 1
+      assert.strictEqual(diff.get(2), -1); // 5 - 6
+    });
+
+    it('treats missing target as revert to zero', () => {
+      const target = new Map<number, number>();
+      const previous = new Map([[1, 3], [2, 4]]);
+      const diff = diffStoreyOffsets(target, previous);
+      assert.strictEqual(diff.get(1), -3);
+      assert.strictEqual(diff.get(2), -4);
+    });
+
+    it('treats new target with no previous as full lift', () => {
+      const target = new Map([[1, 5]]);
+      const previous = new Map<number, number>();
+      const diff = diffStoreyOffsets(target, previous);
+      assert.strictEqual(diff.get(1), 5);
+    });
+
+    it('omits zero-delta entries', () => {
+      const target = new Map([[1, 3]]);
+      const previous = new Map([[1, 3]]);
+      const diff = diffStoreyOffsets(target, previous);
+      assert.strictEqual(diff.size, 0);
+    });
+  });
+
+  describe('entitiesInStorey', () => {
+    it('returns globalIds of every entity in the storey', () => {
+      const store = makeStore(
+        new Map(),
+        new Map([
+          [100, 1],
+          [101, 1],
+          [200, 2],
+        ]),
+      );
+      const ids = entitiesInStorey(store, 1, (id) => id + 10000);
+      ids.sort();
+      assert.deepStrictEqual(ids, [10100, 10101]);
+    });
+
+    it('returns empty when the storey has no children', () => {
+      const store = makeStore(new Map(), new Map([[100, 2]]));
+      assert.deepStrictEqual(entitiesInStorey(store, 1, (id) => id), []);
+    });
+  });
+
+  describe('buildEntityTranslations', () => {
+    it('emits per-entity Y deltas for every entity in an offset-bearing storey', () => {
+      const store = makeStore(
+        new Map(),
+        new Map([
+          [100, 1], // storey 1, dy=2
+          [101, 1],
+          [200, 2], // storey 2, dy=5
+          [300, 3], // storey 3, no offset → skipped
+        ]),
+      );
+      const offsets = new Map([[1, 2], [2, 5]]);
+      const translations = buildEntityTranslations(store, offsets, (id) => id + 1000);
+      assert.deepStrictEqual(translations.get(1100), [0, 2, 0]);
+      assert.deepStrictEqual(translations.get(1101), [0, 2, 0]);
+      assert.deepStrictEqual(translations.get(1200), [0, 5, 0]);
+      assert.strictEqual(translations.get(1300), undefined);
+    });
+
+    it('omits zero offsets', () => {
+      const store = makeStore(new Map(), new Map([[100, 1]]));
+      const offsets = new Map([[1, 0]]);
+      assert.strictEqual(buildEntityTranslations(store, offsets, (id) => id).size, 0);
+    });
+  });
+});