@ifc-lite/viewer 1.17.3 → 1.17.6

package/src/components/viewer/ViewportContainer.tsx

@@ -2,20 +2,27 @@
  * 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 { useMemo, useRef, useState, useCallback } from 'react';
+import { useMemo, useRef, useState, useCallback, useEffect, useSyncExternalStore } from 'react';
 import { Viewport } from './Viewport';
 import { ViewportOverlays } from './ViewportOverlays';
 import { ToolOverlays } from './ToolOverlays';
 import { Section2DPanel } from './Section2DPanel';
 import { BasketPresentationDock } from './BasketPresentationDock';
 import { BCFOverlay } from './bcf/BCFOverlay';
-import { useViewerStore } from '@/store';
+import { CesiumOverlay } from './CesiumOverlay';
+import { getViewerStoreApi, useViewerStore } from '@/store';
 import { toGlobalIdFromModels } from '@/store/globalId';
 import { collectIfcBuildingStoreyElementsWithIfcSpace } from '@/store/basketVisibleSet';
 import { useIfc } from '@/hooks/useIfc';
 import { useWebGPU } from '@/hooks/useWebGPU';
-import { Upload, MousePointer, Layers, Info, Command, AlertTriangle, ChevronDown, ExternalLink, Plus } from 'lucide-react';
+import { openIfcFileDialog } from '@/services/file-dialog';
+import { logToDesktopTerminal } from '@/services/desktop-logger';
+import { cacheFileBlobs, formatFileSize, getCachedFile, getRecentFiles, recordRecentFiles, type RecentFileEntry } from '@/lib/recent-files';
+import { isTauri } from '@/lib/platform';
+import { Upload, MousePointer, Layers, Info, Command, AlertTriangle, ChevronDown, ExternalLink, Plus, Clock3 } from 'lucide-react';
 import type { MeshData, CoordinateInfo, GeometryResult } from '@ifc-lite/geometry';
+import { type IfcDataStore } from '@ifc-lite/parser';
+import { getEffectiveGeoreference } from '@/lib/geo/effective-georef';
 
 const ZERO_VEC3 = { x: 0, y: 0, z: 0 };
 const DEFAULT_COORDINATE_INFO: CoordinateInfo = {
@@ -26,20 +33,42 @@ const DEFAULT_COORDINATE_INFO: CoordinateInfo = {
 };
 
 export function ViewportContainer() {
-  const { geometryResult, ifcDataStore, loadFile, loading, models, clearAllModels, loadFilesSequentially } = useIfc();
+  const { loadFile, loading, clearAllModels, loadFilesSequentially } = useIfc();
+  const releaseGeometryMemory = useViewerStore((s) => s.releaseGeometryMemory);
   const selectedStoreys = useViewerStore((s) => s.selectedStoreys);
   const typeVisibility = useViewerStore((s) => s.typeVisibility);
   const isolatedEntities = useViewerStore((s) => s.isolatedEntities);
   const classFilter = useViewerStore((s) => s.classFilter);
-  // Multi-model support: get all loaded models from store (for merged geometry)
-  const storeModels = useViewerStore((s) => s.models);
   const resetViewerState = useViewerStore((s) => s.resetViewerState);
   const bcfOverlayVisible = useViewerStore((s) => s.bcfOverlayVisible);
+  const cesiumEnabled = useViewerStore((s) => s.cesiumEnabled);
+  const georefMutations = useViewerStore((s) => s.georefMutations);
+  const setCesiumSourceModelId = useViewerStore((s) => s.setCesiumSourceModelId);
+  const setCesiumAvailable = useViewerStore((s) => s.setCesiumAvailable);
+  // Subscribe to mutationVersion so Cesium reacts to georef edits
+  const mutationVersion = useViewerStore((s) => s.mutationVersion);
   const fileInputRef = useRef<HTMLInputElement>(null);
   const [isDragging, setIsDragging] = useState(false);
   const [showTroubleshooting, setShowTroubleshooting] = useState(false);
+  const [recentFiles, setRecentFiles] = useState<RecentFileEntry[]>([]);
   const webgpu = useWebGPU();
 
+  const viewerStoreApi = getViewerStoreApi();
+  const viewportStoreState = useSyncExternalStore(
+    viewerStoreApi.subscribe,
+    viewerStoreApi.getState,
+    viewerStoreApi.getState,
+  );
+
+  const {
+    geometryResult,
+    ifcDataStore,
+    models,
+    boundedGeometryMode,
+    geometryUpdateTick,
+  } = viewportStoreState;
+  const storeModels = models;
+
   // Check if we have models loaded (for determining add vs replace behavior)
   const hasModelsLoaded = models.size > 0 || (geometryResult?.meshes && geometryResult.meshes.length > 0);
 
@@ -53,39 +82,87 @@ export function ViewportContainer() {
     return map;
   }, [storeModels]);
 
+  const mergedCacheRef = useRef<MeshData[]>([]);
+  const mergedLengthsRef = useRef<Map<string, number>>(new Map());
+  const mergedVisibilityRef = useRef<Map<string, boolean>>(new Map());
+
   // Multi-model: merge geometries from all visible models
   const mergedGeometryResult = useMemo(() => {
-    // If we have federated models, merge their visible geometries
-    if (storeModels.size > 0) {
-      const allMeshes: MeshData[] = [];
+    if (storeModels.size === 1) {
+      const firstModel = storeModels.values().next().value;
+      if (!firstModel?.visible) {
+        return {
+          meshes: [],
+          totalVertices: 0,
+          totalTriangles: 0,
+          coordinateInfo: DEFAULT_COORDINATE_INFO,
+        } satisfies GeometryResult;
+      }
+      return firstModel.geometryResult ?? geometryResult;
+    }
+
+    if (storeModels.size > 1) {
       let totalVertices = 0;
       let totalTriangles = 0;
       let mergedCoordinateInfo: CoordinateInfo | undefined;
+      let shouldRebuild = false;
 
-      for (const [modelId, model] of storeModels) {
-        // Skip hidden models - this is how model visibility works
-        if (!model.visible) continue;
+      if (mergedLengthsRef.current.size !== storeModels.size) {
+        shouldRebuild = true;
+      }
 
+      for (const [modelId, model] of storeModels) {
         const modelGeometry = model.geometryResult;
-        const modelIndex = modelIdToIndex.get(modelId) ?? 0;
-        if (modelGeometry?.meshes) {
-          // Tag each mesh with its modelIndex for selection/highlighting
+        const meshCount = model.visible ? (modelGeometry?.meshes.length ?? 0) : 0;
+        totalVertices += model.visible ? (modelGeometry?.totalVertices ?? 0) : 0;
+        totalTriangles += model.visible ? (modelGeometry?.totalTriangles ?? 0) : 0;
+        if (!mergedCoordinateInfo && model.visible && modelGeometry?.coordinateInfo) {
+          mergedCoordinateInfo = modelGeometry.coordinateInfo;
+        }
+
+        if (
+          mergedVisibilityRef.current.get(modelId) !== model.visible ||
+          (mergedLengthsRef.current.get(modelId) ?? 0) > meshCount
+        ) {
+          shouldRebuild = true;
+        }
+      }
+
+      if (shouldRebuild) {
+        const rebuilt: MeshData[] = [];
+        mergedLengthsRef.current = new Map();
+        mergedVisibilityRef.current = new Map();
+        for (const [modelId, model] of storeModels) {
+          const modelGeometry = model.geometryResult;
+          mergedVisibilityRef.current.set(modelId, model.visible);
+          const modelIndex = modelIdToIndex.get(modelId) ?? 0;
+          if (!model.visible || !modelGeometry?.meshes) {
+            mergedLengthsRef.current.set(modelId, 0);
+            continue;
+          }
           for (const mesh of modelGeometry.meshes) {
-            allMeshes.push({ ...mesh, modelIndex });
+            rebuilt.push({ ...mesh, modelIndex });
           }
-          totalVertices += modelGeometry.totalVertices || 0;
-          totalTriangles += modelGeometry.totalTriangles || 0;
-
-          // Use first model's coordinate info as base (could be improved to compute union)
-          if (!mergedCoordinateInfo && modelGeometry.coordinateInfo) {
-            mergedCoordinateInfo = modelGeometry.coordinateInfo;
+          mergedLengthsRef.current.set(modelId, modelGeometry.meshes.length);
+        }
+        mergedCacheRef.current = rebuilt;
+      } else {
+        for (const [modelId, model] of storeModels) {
+          const modelGeometry = model.geometryResult;
+          const modelIndex = modelIdToIndex.get(modelId) ?? 0;
+          const previousLength = mergedLengthsRef.current.get(modelId) ?? 0;
+          const nextMeshes = model.visible ? (modelGeometry?.meshes ?? []) : [];
+          for (let i = previousLength; i < nextMeshes.length; i++) {
+            const mesh = nextMeshes[i];
+            mergedCacheRef.current.push({ ...mesh, modelIndex });
           }
+          mergedLengthsRef.current.set(modelId, nextMeshes.length);
+          mergedVisibilityRef.current.set(modelId, model.visible);
         }
       }
 
-      // Return merged result (may be empty if all models hidden)
       return {
-        meshes: allMeshes,
+        meshes: mergedCacheRef.current,
         totalVertices,
         totalTriangles,
         coordinateInfo: mergedCoordinateInfo ?? DEFAULT_COORDINATE_INFO,
@@ -96,6 +173,88 @@ export function ViewportContainer() {
     return geometryResult;
   }, [storeModels, geometryResult, modelIdToIndex]);
 
+  // Extract georeferencing info merged with any live mutations (for Cesium overlay).
+  // Reacts to: model load, Cesium toggle, and every georef field edit.
+  const georef = useMemo(() => {
+    if (!cesiumEnabled) return null;
+
+    // Check federated models first
+    for (const [modelId, model] of storeModels) {
+      const ds = model.ifcDataStore;
+      if (!ds) continue;
+      const effective = getEffectiveGeoreference(
+        ds as IfcDataStore,
+        model.geometryResult?.coordinateInfo,
+        georefMutations.get(modelId),
+      );
+      if (effective?.projectedCRS?.name && effective.mapConversion) {
+        return { ...effective, sourceModelId: modelId };
+      }
+    }
+
+    // Fallback to legacy single-model
+    if (ifcDataStore) {
+      const effective = getEffectiveGeoreference(
+        ifcDataStore as IfcDataStore,
+        mergedGeometryResult?.coordinateInfo,
+        georefMutations.get('__legacy__'),
+      );
+      if (effective?.projectedCRS?.name && effective.mapConversion) {
+        return { ...effective, sourceModelId: '__legacy__' };
+      }
+    }
+
+    return null;
+  }, [cesiumEnabled, storeModels, ifcDataStore, georefMutations, mutationVersion, mergedGeometryResult]);
+
+  // Determine whether Cesium button should be visible (model has georef or user added it via mutations).
+  // Runs independently of cesiumEnabled so the button appears/disappears reactively.
+  useEffect(() => {
+    function hasGeoref(): boolean {
+      // Check federated models
+      for (const [modelId, model] of storeModels) {
+        const ds = model.ifcDataStore;
+        if (!ds) continue;
+        const effective = getEffectiveGeoreference(
+          ds as IfcDataStore,
+          model.geometryResult?.coordinateInfo,
+          georefMutations.get(modelId),
+        );
+        if (effective?.projectedCRS?.name) return true;
+      }
+      // Fallback to legacy single-model
+      if (ifcDataStore) {
+        const effective = getEffectiveGeoreference(
+          ifcDataStore as IfcDataStore,
+          mergedGeometryResult?.coordinateInfo,
+          georefMutations.get('__legacy__'),
+        );
+        if (effective?.projectedCRS?.name) return true;
+      }
+      return false;
+    }
+    setCesiumAvailable(hasGeoref());
+  }, [storeModels, ifcDataStore, georefMutations, mutationVersion, setCesiumAvailable, mergedGeometryResult]);
+
+  // Sync the active Cesium source model ID so terrain actions are scoped correctly
+  useEffect(() => {
+    setCesiumSourceModelId(georef?.sourceModelId ?? null);
+  }, [georef?.sourceModelId, setCesiumSourceModelId]);
+
+  useEffect(() => {
+    // Recent files are a desktop-only feature — the web viewer should not
+    // show previously opened files in the landing page empty state.
+    if (!isTauri()) return;
+
+    const refreshRecentFiles = () => {
+      setRecentFiles(getRecentFiles().slice(0, 3));
+    };
+
+    refreshRecentFiles();
+    window.addEventListener('focus', refreshRecentFiles);
+    return () => window.removeEventListener('focus', refreshRecentFiles);
+  }, []);
+
   const handleDragOver = useCallback((e: React.DragEvent) => {
     e.preventDefault();
     e.stopPropagation();
@@ -128,6 +287,10 @@ export function ViewportContainer() {
 
     if (supportedFiles.length === 0) return;
 
+    recordRecentFiles(supportedFiles.map((file) => ({ name: file.name, size: file.size })));
+    void cacheFileBlobs(supportedFiles);
+    setRecentFiles(getRecentFiles().slice(0, 3));
+
     if (hasModelsLoaded) {
       // Models already loaded - add new files sequentially
       loadFilesSequentially(supportedFiles);
@@ -158,6 +321,10 @@ export function ViewportContainer() {
 
     if (supportedFiles.length === 0) return;
 
+    recordRecentFiles(supportedFiles.map((file) => ({ name: file.name, size: file.size })));
+    void cacheFileBlobs(supportedFiles);
+    setRecentFiles(getRecentFiles().slice(0, 3));
+
     if (supportedFiles.length === 1) {
       // Single file - use loadFile (simpler single-model path)
       loadFile(supportedFiles[0]);
@@ -184,6 +351,7 @@ export function ViewportContainer() {
   // A version counter triggers downstream re-renders via the Viewport prop.
   const filteredCacheRef = useRef<MeshData[]>([]);
   const filteredSourceLenRef = useRef(0);
+  const filteredSourceRef = useRef<MeshData[] | null>(null);
   const filteredTypeVisRef = useRef(typeVisibility);
   const filteredVersionRef = useRef(0);
 
@@ -191,6 +359,7 @@ export function ViewportContainer() {
     if (!mergedGeometryResult?.meshes) {
       filteredCacheRef.current = [];
       filteredSourceLenRef.current = 0;
+      filteredSourceRef.current = null;
       filteredVersionRef.current = 0;
       return null;
     }
@@ -204,9 +373,11 @@ export function ViewportContainer() {
       prevVis.spaces !== typeVisibility.spaces ||
       prevVis.openings !== typeVisibility.openings ||
       prevVis.site !== typeVisibility.site;
-    if (typeVisChanged || allMeshes.length < filteredSourceLenRef.current) {
+    const sourceChanged = filteredSourceRef.current !== allMeshes;
+    if (typeVisChanged || sourceChanged || allMeshes.length < filteredSourceLenRef.current) {
       cache.length = 0;
       filteredSourceLenRef.current = 0;
+      filteredSourceRef.current = allMeshes;
       filteredTypeVisRef.current = typeVisibility;
     }
 
@@ -238,7 +409,7 @@ export function ViewportContainer() {
 
     // Only bump version when cache content actually changed — avoids
     // unnecessary downstream re-renders when memo runs with same data.
-    if (cache.length !== prevCacheLen || typeVisChanged) {
+    if (cache.length !== prevCacheLen || typeVisChanged || sourceChanged) {
       filteredVersionRef.current++;
     }
 
@@ -531,7 +702,29 @@ export function ViewportContainer() {
 
             {/* Action */}
             <button
-              onClick={() => webgpu.supported && fileInputRef.current?.click()}
+              onClick={async () => {
+                if (!webgpu.supported) {
+                  return;
+                }
+
+                void logToDesktopTerminal('info', '[ViewportContainer] Empty-state open button clicked');
+                const file = await openIfcFileDialog();
+                if (file) {
+                  void logToDesktopTerminal('info', `[ViewportContainer] Native dialog selected ${file.path}`);
+                  recordRecentFiles([{
+                    name: file.name,
+                    size: file.size,
+                    path: file.path,
+                    modifiedMs: file.modifiedMs ?? null,
+                  }]);
+                  setRecentFiles(getRecentFiles().slice(0, 3));
+                  loadFile(file);
+                  return;
+                }
+
+                void logToDesktopTerminal('info', '[ViewportContainer] Falling back to browser file input');
+                fileInputRef.current?.click();
+              }}
               disabled={!webgpu.supported || webgpu.checking}
               className={`group w-full flex items-center justify-center gap-3 px-6 py-3 font-mono text-sm border transition-all ${
                 !webgpu.supported || webgpu.checking
@@ -546,6 +739,37 @@ export function ViewportContainer() {
             <p className="mt-3 text-xs font-mono text-zinc-400 dark:text-[#565f89]">
               {webgpu.supported ? 'or drag & drop anywhere' : 'file upload disabled'}
             </p>
+
+            {recentFiles.length > 0 && (
+              <div className="mt-6 w-full border-t border-zinc-200 dark:border-[#3b4261] pt-4">
+                <div className="mb-3 flex items-center gap-2 text-xs font-mono uppercase tracking-[0.2em] text-zinc-400 dark:text-[#565f89]">
+                  <Clock3 className="h-3.5 w-3.5" />
+                  <span>Recent Files</span>
+                </div>
+                <div className="flex flex-col gap-2">
+                  {recentFiles.map((file) => (
+                    <button
+                      key={`${file.name}-${file.timestamp}`}
+                      type="button"
+                      onClick={async () => {
+                        const cached = await getCachedFile(file);
+                        if (cached) {
+                          await loadFile(cached);
+                          return;
+                        }
+                        fileInputRef.current?.click();
+                      }}
+                      className="flex items-center justify-between gap-3 border border-zinc-200 bg-zinc-50 px-3 py-2 text-left transition-colors hover:border-primary hover:text-primary dark:border-[#3b4261] dark:bg-[#1f2335] dark:hover:border-primary"
+                    >
+                      <span className="min-w-0 truncate font-mono text-xs">{file.name}</span>
+                      <span className="shrink-0 font-mono text-[10px] uppercase tracking-wide text-zinc-400 dark:text-[#565f89]">
+                        {formatFileSize(file.size)}
+                      </span>
+                    </button>
+                  ))}
+                </div>
+              </div>
+            )}
           </div>
 
           {/* Feature Grid */}
@@ -607,18 +831,31 @@ export function ViewportContainer() {
         </div>
       )}
 
+      {/* Cesium 3D world context overlay — rendered behind the WebGPU canvas (web only) */}
+      {cesiumEnabled && georef && !isTauri() && (
+        <CesiumOverlay
+          mapConversion={georef.mapConversion}
+          projectedCRS={georef.projectedCRS}
+          coordinateInfo={georef.coordinateInfo}
+          geometryResult={mergedGeometryResult}
+          lengthUnitScale={georef.lengthUnitScale}
+        />
+      )}
       <Viewport
         geometry={filteredGeometry}
         geometryVersion={geometryVersion}
         coordinateInfo={mergedGeometryResult?.coordinateInfo}
         computedIsolatedIds={computedIsolatedIds}
         modelIdToIndex={modelIdToIndex}
+        cesiumActive={cesiumEnabled && georef !== null && !isTauri()}
+        releaseGeometryAfterStream={false}
+        onGeometryReleased={releaseGeometryMemory}
       />
       {bcfOverlayVisible && <BCFOverlay />}
       <ViewportOverlays />
       <ToolOverlays />
       <BasketPresentationDock />
-      <Section2DPanel 
+      <Section2DPanel
         mergedGeometry={mergedGeometryResult}
         computedIsolatedIds={computedIsolatedIds}
         modelIdToIndex={modelIdToIndex}

package/src/components/viewer/ViewportOverlays.tsx

@@ -8,13 +8,22 @@ import {
   ZoomIn,
   ZoomOut,
   Layers,
+  Globe2,
+  Mountain,
+  Building2,
+  Satellite,
+  X,
 } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
 import { useViewerStore } from '@/store';
+import type { CesiumDataSource } from '@/store/slices/cesiumSlice';
 import { goHomeFromStore } from '@/store/homeView';
 import { useIfc } from '@/hooks/useIfc';
 import { cn } from '@/lib/utils';
+import { isTauri } from '@/lib/platform';
+
+const isDesktop = isTauri();
 import { ViewCube, type ViewCubeRef } from './ViewCube';
 import { AxisHelper, type AxisHelperRef } from './AxisHelper';
 
@@ -28,6 +37,14 @@ export function ViewportOverlays({ hideViewCube = false }: { hideViewCube?: bool
   const setOnScaleChange = useViewerStore((s) => s.setOnScaleChange);
   const { ifcDataStore, geometryResult } = useIfc();
 
+  // Cesium state
+  const cesiumEnabled = useViewerStore((s) => s.cesiumEnabled);
+  const cesiumDataSource = useViewerStore((s) => s.cesiumDataSource);
+  const setCesiumDataSource = useViewerStore((s) => s.setCesiumDataSource);
+  const cesiumTerrainEnabled = useViewerStore((s) => s.cesiumTerrainEnabled);
+  const setCesiumTerrainEnabled = useViewerStore((s) => s.setCesiumTerrainEnabled);
+  const toggleCesium = useViewerStore((s) => s.toggleCesium);
+
   // Use refs for rotation to avoid re-renders - ViewCube updates itself directly
   const cameraRotationRef = useRef({ azimuth: 45, elevation: 25 });
   const viewCubeRef = useRef<ViewCubeRef | null>(null);
@@ -132,35 +149,45 @@ export function ViewportOverlays({ hideViewCube = false }: { hideViewCube?: bool
 
   return (
     <>
-      {/* Navigation Controls (bottom-right) */}
-      <div className="absolute bottom-4 right-4 flex flex-col gap-1 bg-background/80 backdrop-blur-sm rounded-lg border shadow-sm p-1">
-        <Tooltip>
-          <TooltipTrigger asChild>
-            <Button variant="ghost" size="icon-sm" onClick={handleHome}>
-              <Home className="h-4 w-4" />
-            </Button>
-          </TooltipTrigger>
-          <TooltipContent side="left">Home (H)</TooltipContent>
-        </Tooltip>
+      {/* Bottom-right: Cesium settings overlay OR Navigation controls (Cesium is web-only) */}
+      {cesiumEnabled && !isDesktop ? (
+        <CesiumSettingsOverlay
+          dataSource={cesiumDataSource}
+          onDataSourceChange={setCesiumDataSource}
+          terrainEnabled={cesiumTerrainEnabled}
+          onTerrainChange={setCesiumTerrainEnabled}
+          onClose={toggleCesium}
+        />
+      ) : (
+        <div className="absolute bottom-4 right-4 flex flex-col gap-1 bg-background/80 backdrop-blur-sm rounded-lg border shadow-sm p-1">
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button variant="ghost" size="icon-sm" onClick={handleHome}>
+                <Home className="h-4 w-4" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent side="left">Home (H)</TooltipContent>
+          </Tooltip>
 
-        <Tooltip>
-          <TooltipTrigger asChild>
-            <Button variant="ghost" size="icon-sm" onClick={handleZoomIn}>
-              <ZoomIn className="h-4 w-4" />
-            </Button>
-          </TooltipTrigger>
-          <TooltipContent side="left">Zoom In (+)</TooltipContent>
-        </Tooltip>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button variant="ghost" size="icon-sm" onClick={handleZoomIn}>
+                <ZoomIn className="h-4 w-4" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent side="left">Zoom In (+)</TooltipContent>
+          </Tooltip>
 
-        <Tooltip>
-          <TooltipTrigger asChild>
-            <Button variant="ghost" size="icon-sm" onClick={handleZoomOut}>
-              <ZoomOut className="h-4 w-4" />
-            </Button>
-          </TooltipTrigger>
-          <TooltipContent side="left">Zoom Out (-)</TooltipContent>
-        </Tooltip>
-      </div>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button variant="ghost" size="icon-sm" onClick={handleZoomOut}>
+                <ZoomOut className="h-4 w-4" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent side="left">Zoom Out (-)</TooltipContent>
+          </Tooltip>
+        </div>
+      )}
 
       {/* Context Info (bottom-center) - Storey names */}
       {storeyNames && storeyNames.length > 0 && (
@@ -209,3 +236,81 @@ export function ViewportOverlays({ hideViewCube = false }: { hideViewCube?: bool
     </>
   );
 }
+
+/* ------------------------------------------------------------------ */
+/*  Cesium Settings Overlay — replaces nav controls when Cesium is on  */
+/* ------------------------------------------------------------------ */
+
+const DATA_SOURCES: { value: CesiumDataSource; label: string; icon: typeof Globe2 }[] = [
+  { value: 'google-photorealistic', label: 'Google 3D', icon: Globe2 },
+  { value: 'osm-buildings', label: 'OSM', icon: Building2 },
+  { value: 'bing-aerial', label: 'Aerial', icon: Satellite },
+];
+
+function CesiumSettingsOverlay({
+  dataSource,
+  onDataSourceChange,
+  terrainEnabled,
+  onTerrainChange,
+  onClose,
+}: {
+  dataSource: CesiumDataSource;
+  onDataSourceChange: (ds: CesiumDataSource) => void;
+  terrainEnabled: boolean;
+  onTerrainChange: (enabled: boolean) => void;
+  onClose: () => void;
+}) {
+  return (
+    <div className="absolute bottom-4 right-4 z-10 pointer-events-auto bg-background/90 backdrop-blur-sm rounded-lg border shadow-lg p-2 flex flex-col gap-2 min-w-[160px]">
+      {/* Header */}
+      <div className="flex items-center justify-between gap-2">
+        <span className="text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+          3D World
+        </span>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button variant="ghost" size="icon-sm" className="h-5 w-5" onClick={onClose}>
+              <X className="h-3 w-3" />
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent side="left">Disable Cesium overlay</TooltipContent>
+        </Tooltip>
+      </div>
+
+      {/* Data Source Buttons */}
+      <div className="flex flex-col gap-0.5">
+        {DATA_SOURCES.map((ds) => {
+          const Icon = ds.icon;
+          const active = dataSource === ds.value;
+          return (
+            <button
+              key={ds.value}
+              onClick={() => onDataSourceChange(ds.value)}
+              className={cn(
+                'flex items-center gap-2 px-2 py-1.5 rounded text-xs transition-colors text-left',
+                active
+                  ? 'bg-teal-600 text-white'
+                  : 'hover:bg-muted text-foreground/80',
+              )}
+            >
+              <Icon className="h-3.5 w-3.5 shrink-0" />
+              {ds.label}
+            </button>
+          );
+        })}
+      </div>
+
+      {/* Terrain Toggle */}
+      <label className="flex items-center gap-2 px-2 py-1 cursor-pointer border-t border-border pt-2">
+        <Mountain className="h-3.5 w-3.5 text-muted-foreground shrink-0" />
+        <span className="text-xs text-foreground/80">Terrain</span>
+        <input
+          type="checkbox"
+          checked={terrainEnabled}
+          onChange={(e) => onTerrainChange(e.target.checked)}
+          className="ml-auto accent-teal-500"
+        />
+      </label>
+    </div>
+  );
+}

package/src/components/viewer/bcf/BCFTopicDetail.tsx

@@ -215,12 +215,12 @@ export function BCFTopicDetail({
                           <img
                             src={vp.snapshot}
                             alt="Viewpoint"
-                            className="w-full aspect-video object-cover cursor-pointer hover:opacity-90 transition-opacity"
+                            className="w-full max-h-48 object-contain bg-muted cursor-pointer hover:opacity-90 transition-opacity"
                             onClick={() => onActivateViewpoint(vp)}
                           />
                         ) : (
                           <div
-                            className="w-full aspect-video bg-muted flex items-center justify-center cursor-pointer hover:bg-muted/80 transition-colors"
+                            className="w-full aspect-video bg-muted flex items-center justify-center cursor-pointer hover:bg-muted/80 transition-colors min-h-[120px]"
                             onClick={() => onActivateViewpoint(vp)}
                           >
                             <Camera className="h-6 w-6 text-muted-foreground" />
@@ -294,7 +294,7 @@ export function BCFTopicDetail({
                         <img
                           src={associatedViewpoint.snapshot}
                           alt="Associated viewpoint"
-                          className="w-full h-16 object-cover"
+                          className="w-full max-h-24 object-contain bg-muted"
                         />
                       </div>
                     )}
@@ -327,7 +327,7 @@ export function BCFTopicDetail({
               <img
                 src={selectedViewpoint.snapshot}
                 alt="Selected viewpoint"
-                className="w-10 h-10 object-cover rounded"
+                className="w-12 h-10 object-contain rounded bg-muted"
               />
             )}
             <div className="flex-1 min-w-0">