Add browserless figure export

Author: mnm-matin

.agents/skills/hyperview-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hyperview-cli
-description: Use HyperView's control-plane CLI for hyperview serve, dataset create, workspace create, embeddings compute, layouts compute, runtime jobs, ui layout set, ui selection set, ui panel add, extension add, tools run, native module panels, backend tools, and local HyperView plugin workflows.
+description: Use HyperView's control-plane CLI for hyperview serve, dataset create, workspace create, embeddings compute, layouts compute, browserless paper figure export, runtime jobs, ui layout set, ui selection set, ui panel add, extension add, tools run, native module panels, backend tools, and local HyperView plugin workflows.
 license: MIT
 compatibility: Requires Python 3.10-3.13 and the hyperview CLI (`uv tool install --python 3.12 hyperview`). Runtime-control commands require a running HyperView server.
 metadata:
@@ -29,6 +29,7 @@ HyperView currently supports Python 3.10 through 3.13; `--python 3.12` keeps the
 - Start or control a running HyperView runtime.
 - Register a custom embedding provider.
 - Compute embeddings or layouts without restarting the UI.
+- Export paper-ready static 3D embedding figures without a browser or Node runtime.
 - Switch the active workspace, layout, or selection in a running session.
 - Add or remove agent-authored native module panels from local files.
 - Create, install, reload, or test a local plugin/extension with Python backend tools and a frontend panel.
@@ -41,7 +42,8 @@ HyperView currently supports Python 3.10 through 3.13; `--python 3.12` keeps the
 4. Register a provider if needed.
 5. Submit embedding or layout jobs through the runtime.
 6. Use `hyperview ui ...` commands to switch what the live UI shows.
-7. For plugins, create an extension folder and install it into the running workspace.
+7. Export paper figures with `hyperview figure export` when the user needs screenshots or publication diagrams.
+8. For plugins, create an extension folder and install it into the running workspace.
 
 ## Current model
 
@@ -54,8 +56,10 @@ HyperView currently supports Python 3.10 through 3.13; `--python 3.12` keeps the
 - Plugins are repo-local extension folders with `extension.toml`, optional Python tools, and optional native panel modules.
 - Plugin panels call backend tools through `HyperViewPanelSDK.hooks.useTool()` or `hyperview tools run`.
 - In practice, create datasets and workspaces before starting the runtime for that workspace. The current runtime loads workspace registry state on startup.
+- `figure export` is browserless and supports 3D layouts only. It reuses the persisted 3D camera for the layout when available, otherwise it chooses a paper-oriented default view.
+- Paper figure defaults are square, white-background, opaque PNGs with a faint sphere guide and direct labels for small label sets.
 
-Read [references/commands.md](references/commands.md) for command recipes covering datasets, workspaces, providers, embeddings, layouts, runtime UI state, selections, and jobs.
+Read [references/commands.md](references/commands.md) for command recipes covering datasets, workspaces, providers, embeddings, layouts, paper figures, runtime UI state, selections, and jobs.
 Read [references/native-panels.md](references/native-panels.md) when the task involves authoring or registering a custom panel.
 Read [references/plugins.md](references/plugins.md) when the task involves backend-plus-frontend plugins/extensions.
 
@@ -75,6 +79,8 @@ Read [references/plugins.md](references/plugins.md) when the task involves backe
 - For provider args, use repeated `--provider-arg key=value` flags.
 - Treat the workspace as the durable unit. Changing datasets means setting a new workspace dataset, not switching among many datasets inside one workspace.
 - Prefer native module panels over raw HTML. The panel system no longer relies on iframes.
+- For paper diagrams, prefer `hyperview figure export` over browser screenshots unless the user explicitly needs exact UI chrome. It does not require Playwright, browser bundling, or Node at runtime.
+- For publication figures, keep the defaults first: `--theme light`, `--guide-style paper`, and `--legend auto`. Use `--show-selection` only when selected samples are meaningful and will be explained in the caption.
 - The first `uv run hyperview ...` invocation in a session can take 30+ seconds (torch/datasets imports). Allow generous timeouts and avoid sending SIGINT.
 
 ## Inspecting runtime state
@@ -85,4 +91,4 @@ The runtime exposes JSON discovery endpoints alongside the CLI. Use them to obta
 - `GET /api/embeddings?workspace_id=<ws>` &mdash; the active or default layout, including `layout_key`, `geometry`, and sample `ids`. Use the returned `layout_key` for `hyperview ui layout set --layout-key ...` and pick from `ids` for `hyperview ui selection set --ids ...`.
 - `GET /api/tools` &mdash; registered tool URIs (also returned by `hyperview tools list --json`).
 
-Layout keys encode geometry and dimension as a substring (e.g. `..._euclidean_umap__2d_...`, `..._hyperbolic_umap__3d_...`). Match on those substrings when filtering by geometry/dimension.
+Layout keys encode geometry and dimension as a substring (e.g. `..._euclidean_umap__2d_...`, `..._hyperbolic_umap__3d_...`). Match on those substrings when filtering by geometry/dimension.

.agents/skills/hyperview-cli/references/commands.md

@@ -131,6 +131,63 @@ hyperview jobs list --json
 hyperview jobs inspect <job-id> --json
 ```
 
+## Paper Figures
+
+Export a browserless, paper-ready PNG from the active 3D layout:
+
+```bash
+hyperview figure export figures/embedding-sphere.png \
+  --workspace research \
+  --layout active \
+  --json
+```
+
+If `--layout` is omitted, HyperView uses the active 3D layout when one is set, otherwise the first available 3D layout. Use `--layout active` when you specifically want the live UI's active layout and want the command to fail if none is active.
+
+The export path is pure Python and does not require Playwright, browser bundling, Node, or a running frontend. It supports 3D layouts only; 2D layouts are rejected with a validation message.
+
+Paper defaults are tuned for academic figures:
+
+- `--width 900 --height 900 --scale 2`
+- `--theme light`
+- `--guide-style paper`
+- `--legend auto` (direct labels for small label sets)
+- opaque PNG output
+- selection rings hidden unless explicitly requested
+
+Use the 3D view selected in the UI by rotating the scatter panel first. HyperView persists the layout camera and `figure export` reuses it for that layout.
+
+Common variants:
+
+```bash
+# Cleanest sphere context: silhouette only.
+hyperview figure export figures/embedding-outline.png \
+  --workspace research \
+  --layout active \
+  --guide-style outline
+
+# No sphere guide, useful when the embedding separation is the whole message.
+hyperview figure export figures/embedding-clean.png \
+  --workspace research \
+  --layout active \
+  --guide-style none \
+  --legend direct
+
+# Browser-like guide rings and current selection markers.
+hyperview figure export figures/embedding-ui-like.png \
+  --workspace research \
+  --layout active \
+  --guide-style rings \
+  --legend on \
+  --show-selection
+
+# Add a short panel title when the figure will stand alone.
+hyperview figure export figures/embedding-panel-a.png \
+  --workspace research \
+  --layout active \
+  --title "ArcFace spherical embeddings"
+```
+
 ## Runtime UI
 
 Discover an existing layout key and sample IDs before mutating runtime state:
@@ -220,4 +277,4 @@ hyperview tools run selection_profile.summarize \
 - `--param 'top_k=5'` for numbers
 - `--param 'enabled=true'` for booleans
 - `--param 'name=foo'` for short strings (raw fallback) or `--param 'name="foo bar"'` for explicit JSON strings
-- `--param 'ids=["a","b"]'` or `--param 'opts={"k":1}'` for arrays/objects
+- `--param 'ids=["a","b"]'` or `--param 'opts={"k":1}'` for arrays/objects

frontend/src/app/useHomeData.ts

@@ -306,6 +306,7 @@ function useNeighborsDataFlow(args: {
   } = args;
 
   const neighborsResults = useStore((state) => state.neighborsResults);
+  const neighborsMetric = useStore((state) => state.neighborsMetric);
   const neighborsLoading = useStore((state) => state.neighborsLoading);
   const neighborsError = useStore((state) => state.neighborsError);
   const beginNeighborsQuery = useStore((state) => state.beginNeighborsQuery);
@@ -359,7 +360,7 @@ function useNeighborsDataFlow(args: {
 
         if (abort.signal.aborted) return;
 
-        setNeighborsResults(response.results);
+        setNeighborsResults(response.results, response.metric);
       } catch (err) {
         if (isAbortError(err)) return;
         console.error("Failed to fetch neighbors:", err);
@@ -402,6 +403,7 @@ function useNeighborsDataFlow(args: {
   return {
     neighborsError,
     neighborsLoading,
+    neighborsMetric,
     neighborsResults,
     hasMoreNeighbors,
     loadMoreNeighbors,
@@ -513,6 +515,8 @@ export function useHomeData(): {
         selectionSamples: selectedSamples,
         neighborSamples:
           samplesFlow.selectedIdsList.length === 1 ? derivedNeighborSamples : [],
+        neighborsMetric:
+          samplesFlow.selectedIdsList.length === 1 ? neighborsFlow.neighborsMetric : null,
         neighborsLoading:
           samplesFlow.selectedIdsList.length === 1 ? neighborsFlow.neighborsLoading : false,
         hasMoreNeighbors:
@@ -532,6 +536,7 @@ export function useHomeData(): {
       neighborsFlow.loadMoreNeighbors,
       neighborsFlow.neighborsError,
       neighborsFlow.neighborsLoading,
+      neighborsFlow.neighborsMetric,
       samplesCollection,
       samplesFlow.isLassoSelection,
       samplesFlow.selectedAnchorId,
@@ -545,4 +550,4 @@ export function useHomeData(): {
     error: samplesFlow.error,
     isLoading: samplesFlow.isLoading,
   };
-}
+}

frontend/src/components/SampleDerivedSpace.tsx

@@ -2,6 +2,7 @@
 
 import { AlertCircle, Loader2 } from "lucide-react";
 
+import { getDistanceMetricLabel } from "@/lib/similarity";
 import { cn } from "@/lib/utils";
 import { useStore } from "@/store/useStore";
 import type { Sample } from "@/types";
@@ -12,6 +13,7 @@ import { SampleTile } from "./SampleTile";
 interface SampleDerivedSpaceProps {
   selectionSamples: Sample[];
   neighborSamples: Sample[];
+  neighborsMetric: string | null;
   neighborsLoading: boolean;
   hasMoreNeighbors: boolean;
   loadMoreNeighbors?: () => void;
@@ -35,6 +37,7 @@ function getAnchorTileWidth(sample: Sample): number {
 export function SampleDerivedSpace({
   selectionSamples,
   neighborSamples,
+  neighborsMetric,
   neighborsLoading,
   hasMoreNeighbors,
   loadMoreNeighbors,
@@ -45,6 +48,7 @@ export function SampleDerivedSpace({
 
   const showNeighbors =
     neighborSamples.length > 0 || neighborsLoading || neighborsError !== null;
+  const distanceMetricLabel = getDistanceMetricLabel(neighborsMetric);
 
   return (
     <div className="flex flex-1 min-h-0 flex-col">
@@ -75,7 +79,7 @@ export function SampleDerivedSpace({
         <div className="flex min-h-0 flex-1 flex-col">
           <div className="h-6 min-h-[24px] border-y border-border bg-secondary/20 px-2 flex items-center">
             <span className="text-[11px] leading-4 text-muted-foreground">
-              Nearest neighbors
+              Nearest neighbors{distanceMetricLabel ? ` · ${distanceMetricLabel}` : ""}
             </span>
           </div>
           <div className="flex min-h-0 flex-1 w-full overflow-hidden">
@@ -87,6 +91,7 @@ export function SampleDerivedSpace({
                 scrollResetKey={neighborsScrollResetKey}
                 className="w-full"
                 showRankSimilarityBadge
+                distanceMetric={neighborsMetric}
               />
             ) : neighborsLoading ? (
               <div className="flex flex-1 items-center justify-center text-muted-foreground">
@@ -103,4 +108,4 @@ export function SampleDerivedSpace({
       )}
     </div>
   );
-}
+}

frontend/src/components/SampleGridView.tsx

@@ -4,6 +4,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useVirtualizer } from "@tanstack/react-virtual";
 import justifiedLayout from "justified-layout";
 
+import { formatDistanceValue, getDistanceMetricLabel } from "@/lib/similarity";
 import { cn } from "@/lib/utils";
 import { useStore } from "@/store/useStore";
 import type { Sample } from "@/types";
@@ -17,6 +18,7 @@ interface SampleGridViewProps {
   scrollResetKey?: string;
   className?: string;
   showRankSimilarityBadge?: boolean;
+  distanceMetric?: string | null;
 }
 
 const BOX_SPACING = 2;
@@ -112,6 +114,7 @@ export function SampleGridView({
   scrollResetKey,
   className,
   showRankSimilarityBadge = false,
+  distanceMetric = null,
 }: SampleGridViewProps) {
   const containerRef = useRef<HTMLDivElement>(null);
   const [containerWidth, setContainerWidth] = useState(0);
@@ -266,19 +269,18 @@ export function SampleGridView({
                   const isHovered = hoveredId === sample.id;
                   const sampleIndex = row.startIndex + index;
                   const distance = (sample as { distance?: number }).distance;
-                  const similarity =
-                    typeof distance === "number"
-                      ? Math.max(0, Math.min(1, 1 - distance))
-                      : null;
-                  const similarityPercent =
-                    similarity !== null ? Math.round(similarity * 100) : null;
+                  const distanceLabel =
+                    typeof distance === "number" ? formatDistanceValue(distance) : null;
+                  const preciseDistanceLabel =
+                    typeof distance === "number" ? formatDistanceValue(distance, 6) : null;
+                  const distanceMetricLabel = getDistanceMetricLabel(distanceMetric) ?? "distance";
                   const metricBadge =
-                    showRankSimilarityBadge && similarityPercent !== null
-                      ? `#${sampleIndex + 1} · ${similarityPercent}%`
+                    showRankSimilarityBadge && distanceLabel !== null
+                      ? `#${sampleIndex + 1} · d ${distanceLabel}`
                       : null;
                   const metricBadgeTitle =
-                    showRankSimilarityBadge && similarity !== null
-                      ? `Rank ${sampleIndex + 1}, cosine similarity ${(similarity * 100).toFixed(1)}%`
+                    showRankSimilarityBadge && preciseDistanceLabel !== null
+                      ? `Rank ${sampleIndex + 1}, ${distanceMetricLabel} ${preciseDistanceLabel}. Lower is closer.`
                       : undefined;
 
                   return (
@@ -313,4 +315,4 @@ export function SampleGridView({
       </div>
     </div>
   );
-}
+}

frontend/src/components/ScatterPanel.tsx

@@ -28,6 +28,7 @@ import {
   fetchDataset,
   fetchEmbeddings,
   isLayoutNotFoundError,
+  setLayoutView,
 } from "@/lib/api";
 
 interface ScatterPanelProps {
@@ -61,6 +62,9 @@ export function ScatterPanel({
     requestedLayoutKey,
     scatterLabelOverlayMode,
     setScatterLabelOverlayMode,
+    activeWorkspaceId,
+    layoutViews,
+    setLayoutViewCamera,
   } = useStore();
 
   const highlightedIds = useMemo(() => {
@@ -321,6 +325,24 @@ export function ScatterPanel({
   );
 
   const embeddings = resolvedLayoutKey ? embeddingsByLayoutKey[resolvedLayoutKey] ?? null : null;
+  const savedView3d = resolvedLayoutKey
+    ? (layoutViews[resolvedLayoutKey]?.camera_3d ?? null)
+    : null;
+
+  const handleView3DChange = useCallback(
+    (view: NonNullable<typeof savedView3d>) => {
+      if (!activeWorkspaceId || !resolvedLayoutKey) return;
+      setLayoutViewCamera(resolvedLayoutKey, view);
+      void setLayoutView({
+        workspaceId: activeWorkspaceId,
+        layoutKey: resolvedLayoutKey,
+        camera3d: view,
+      }).catch((err) => {
+        console.error("Failed to persist 3D scatter view:", err);
+      });
+    },
+    [activeWorkspaceId, resolvedLayoutKey, setLayoutViewCamera]
+  );
 
   useEffect(() => {
     if (!resolvedLayoutKey) return;
@@ -392,12 +414,14 @@ export function ScatterPanel({
     labelsInfo,
     labelFilter,
     semanticLabelDisplayMode: scatterLabelOverlayMode,
+    initialView3d: savedView3d,
     selectedIds,
     highlightedIds,
     hoveredId,
     setSelectedIds,
     beginLassoSelection,
     setHoveredId,
+    onView3DChange: handleView3DChange,
   });
 
   const focusLayout = useCallback(() => {