Add 3D layout support and improve dataset ingestion

Author: mnm-matin

.gitignore

@@ -77,7 +77,9 @@ AGENTS.md
 .specstory/
 
 # Deployment repo (managed as a separate nested git repository)
-deploy/
+hyper-models/
+hyperview-spaces/
+eval/
 
 # Generated version file (hatch-vcs)
 src/hyperview/_version.py

docs/datasets.md

@@ -31,6 +31,28 @@ dataset.add_from_huggingface(
 )
 ```
 
+To target a named Hugging Face subset/configuration, pass `config="default"`
+or another config name alongside `split=`.
+
+To avoid materializing the full split before sampling, use `streaming=True`.
+This keeps ingestion on Hugging Face's iterable dataset path and stops after the
+requested rows:
+
+```python
+dataset.add_from_huggingface(
+    "uoft-cs/cifar100",
+    split="train",
+    image_key="img",
+    label_key="fine_label",
+    max_samples=500,
+    streaming=True,
+)
+```
+
+When `streaming=True` and `shuffle=True`, sampling becomes approximate and
+buffer-based. Tune `shuffle_buffer_size=` if you need more mixing and can afford
+additional read-ahead.
+
 ### From Directory
 ```python
 dataset.add_images_dir("/path/to/images", label_from_folder=True)
@@ -66,8 +88,8 @@ Samples are **never implicitly deleted**. Use `hv.Dataset.delete("name")` for ex
 # High-dimensional embeddings (CLIP)
 dataset.compute_embeddings(model="openai/clip-vit-base-patch32", show_progress=True)
 
-# 2D projections for visualization
-dataset.compute_visualization()  # UMAP to Euclidean + Hyperbolic
+# 2D projection for visualization
+dataset.compute_visualization()  # Defaults to euclidean:2d
 ```
 
 Embeddings are stored per-sample. If a sample already has embeddings, it's skipped.

frontend/package-lock.json

@@ -25,7 +25,7 @@
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
     "dockview": "^4.13.1",
-    "hyper-scatter": "^0.1.0",
+    "hyper-scatter": "file:../hyper-scatter",
     "justified-layout": "^4.1.0",
     "lucide-react": "^0.562.0",
     "next": "^16.1.6",

frontend/package.json

@@ -6,6 +6,7 @@ import { DockviewWorkspace, DockviewProvider } from "@/components/DockviewWorksp
 import { useStore } from "@/store/useStore";
 import type { Sample } from "@/types";
 import {
+  ApiError,
   fetchDataset,
   fetchSamples,
   fetchSamplesBatch,
@@ -35,12 +36,22 @@ export default function Home() {
     lassoTotal,
     lassoIsLoading,
     setLassoResults,
+    clearLassoSelection,
     labelFilter,
   } = useStore();
 
   const [loadingMore, setLoadingMore] = useState(false);
   const labelFilterRef = useRef<string | null>(labelFilter ?? null);
 
+  const refreshDatasetMetadata = useCallback(async () => {
+    try {
+      const dataset = await fetchDataset();
+      setDatasetInfo(dataset);
+    } catch (refreshErr) {
+      console.error("Failed to refresh dataset metadata:", refreshErr);
+    }
+  }, [setDatasetInfo]);
+
   // Initial data load - runs once on mount
   // Store setters are stable and don't need to be in deps
   useEffect(() => {
@@ -74,7 +85,6 @@ export default function Home() {
     const fetchSelectedSamples = async () => {
       if (isLassoSelection) return;
       if (selectedIds.size === 0) return;
-      if (selectionSource === "label") return;
 
       // Find IDs that are selected but not in our samples array
       const loadedIds = new Set(samples.map((s) => s.id));
@@ -131,6 +141,10 @@ export default function Home() {
         const res = await fetchLassoSelection({
           layoutKey: lassoQuery.layoutKey,
           polygon: lassoQuery.polygon,
+          labelFilter: lassoQuery.labelFilter ?? undefined,
+          view3d: lassoQuery.view3d,
+          viewportWidth: lassoQuery.viewportWidth,
+          viewportHeight: lassoQuery.viewportHeight,
           offset: 0,
           limit: SAMPLES_PER_PAGE,
           signal: abort.signal,
@@ -139,6 +153,18 @@ export default function Home() {
         setLassoResults(res.samples, res.total, false);
       } catch (err) {
         if (err instanceof DOMException && err.name === "AbortError") return;
+
+        if (
+          err instanceof ApiError &&
+          err.status === 404 &&
+          typeof err.detail === "string" &&
+          err.detail.includes("Layout not found")
+        ) {
+          clearLassoSelection();
+          void refreshDatasetMetadata();
+          return;
+        }
+
         console.error("Failed to fetch lasso selection:", err);
         setLassoResults([], 0, false);
       }
@@ -147,7 +173,14 @@ export default function Home() {
     run();
 
     return () => abort.abort();
-  }, [isLassoSelection, lassoIsLoading, lassoQuery, setLassoResults]);
+  }, [
+    clearLassoSelection,
+    isLassoSelection,
+    lassoIsLoading,
+    lassoQuery,
+    refreshDatasetMetadata,
+    setLassoResults,
+  ]);
 
   // Load more samples
   const loadMore = useCallback(async () => {
@@ -163,11 +196,26 @@ export default function Home() {
         const res = await fetchLassoSelection({
           layoutKey: lassoQuery.layoutKey,
           polygon: lassoQuery.polygon,
+          labelFilter: lassoQuery.labelFilter ?? undefined,
+          view3d: lassoQuery.view3d,
+          viewportWidth: lassoQuery.viewportWidth,
+          viewportHeight: lassoQuery.viewportHeight,
           offset: lassoSamples.length,
           limit: SAMPLES_PER_PAGE,
         });
         setLassoResults(res.samples, res.total, true);
       } catch (err) {
+        if (
+          err instanceof ApiError &&
+          err.status === 404 &&
+          typeof err.detail === "string" &&
+          err.detail.includes("Layout not found")
+        ) {
+          clearLassoSelection();
+          void refreshDatasetMetadata();
+          return;
+        }
+
         console.error("Failed to load more lasso samples:", err);
       } finally {
         setLoadingMore(false);
@@ -194,8 +242,10 @@ export default function Home() {
     lassoQuery,
     lassoSamples.length,
     lassoTotal,
+    clearLassoSelection,
     samplesLoaded,
     totalSamples,
+    refreshDatasetMetadata,
     setLassoResults,
     labelFilter,
   ]);