hyperview 0.4.2__tar.gz → 0.5.0__tar.gz

{hyperview-0.4.2 → hyperview-0.5.0}/.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.

{hyperview-0.4.2 → hyperview-0.5.0}/.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

{hyperview-0.4.2 → hyperview-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperview
-Version: 0.4.2
+Version: 0.5.0
 Summary: Open-source dataset curation with hyperbolic embeddings visualization
 Project-URL: Homepage, https://github.com/Hyper3Labs/HyperView
 Project-URL: Documentation, https://github.com/Hyper3Labs/HyperView#readme
@@ -206,7 +206,7 @@ Traditional Euclidean embeddings struggle with hierarchical data. In Euclidean s
 
 ## Community
 
-**Weekly Open Discussion** — Every Tuesday at 15:00 UTC on [Discord](https://discord.gg/Az7k4Ure?event=1469730571440885944)
+**Weekly Open Discussion** — Every Tuesday at 15:00 UTC on [Discord](https://discord.gg/Za3rBkTPSf)
 
 Join us to see the latest features demoed live, walk through new code, and get help with local setup. Whether you're a core maintainer or looking for your first contribution, everyone is welcome.
 

{hyperview-0.4.2 → hyperview-0.5.0}/README.md

@@ -155,7 +155,7 @@ Traditional Euclidean embeddings struggle with hierarchical data. In Euclidean s
 
 ## Community
 
-**Weekly Open Discussion** — Every Tuesday at 15:00 UTC on [Discord](https://discord.gg/Az7k4Ure?event=1469730571440885944)
+**Weekly Open Discussion** — Every Tuesday at 15:00 UTC on [Discord](https://discord.gg/Za3rBkTPSf)
 
 Join us to see the latest features demoed live, walk through new code, and get help with local setup. Whether you're a core maintainer or looking for your first contribution, everyone is welcome.
 

{hyperview-0.4.2 → hyperview-0.5.0}/src/hyperview/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.4.2'
-__version_tuple__ = version_tuple = (0, 4, 2)
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
 
 __commit_id__ = commit_id = None

{hyperview-0.4.2 → hyperview-0.5.0}/src/hyperview/cli.py

@@ -13,7 +13,10 @@ from urllib.request import Request, urlopen
 
 from hyperview import Dataset
 from hyperview.api import Session
+from hyperview.core.selection import OrbitViewState3D
+from hyperview.figures import FigureRenderOptions, render_layout_figure
 from hyperview.runtime import HyperViewRuntime, ProviderRegistry, WorkspaceRegistry
+from hyperview.storage.schema import parse_layout_dimension
 
 
 def _read_json_response(response: Any) -> Any:
@@ -270,6 +273,28 @@ def _build_control_parser() -> argparse.ArgumentParser:
     jobs_inspect.add_argument("job_id")
     _add_json_flag(jobs_inspect)
 
+    figure_parser = subparsers.add_parser("figure")
+    figure_subparsers = figure_parser.add_subparsers(dest="figure_command", required=True)
+    figure_export = figure_subparsers.add_parser("export")
+    figure_export.add_argument("output")
+    figure_export.add_argument("--workspace")
+    figure_export.add_argument("--dataset")
+    figure_export.add_argument("--layout")
+    figure_export.add_argument("--width", type=int, default=900)
+    figure_export.add_argument("--height", type=int, default=900)
+    figure_export.add_argument("--scale", type=int, default=2)
+    figure_export.add_argument("--theme", choices=["dark", "light"], default="light")
+    figure_export.add_argument("--background")
+    figure_export.add_argument("--point-radius", type=float, default=4.0)
+    figure_export.add_argument("--guide-style", choices=["paper", "rings", "outline", "none"], default="paper")
+    figure_export.add_argument("--guide-alpha", type=int)
+    figure_export.add_argument("--legend", choices=["auto", "on", "off", "direct"], default="auto")
+    figure_export.add_argument("--title")
+    figure_export.add_argument("--show-selection", action="store_true")
+    figure_export.add_argument("--no-guide", action="store_true")
+    figure_export.add_argument("--ignore-selection", action="store_true")
+    _add_json_flag(figure_export)
+
     ui_parser = subparsers.add_parser("ui")
     ui_subparsers = ui_parser.add_subparsers(dest="ui_command", required=True)
     ui_workspace = ui_subparsers.add_parser("workspace")
@@ -598,6 +623,87 @@ def _run_jobs_command(args: argparse.Namespace) -> None:
     raise RuntimeError(f"Unsupported jobs command: {args.jobs_command}")
 
 
+def _resolve_figure_layout_key(
+    dataset: Dataset,
+    active_layout_key: str | None,
+    requested_layout_key: str | None,
+) -> str:
+    layouts = dataset.list_layouts()
+
+    if requested_layout_key and requested_layout_key != "active":
+        return requested_layout_key
+
+    if requested_layout_key == "active":
+        if not active_layout_key:
+            raise RuntimeError("No active layout is set for this workspace")
+        return active_layout_key
+
+    if active_layout_key:
+        try:
+            if parse_layout_dimension(active_layout_key) == 3:
+                return active_layout_key
+        except ValueError:
+            pass
+
+    for layout in layouts:
+        try:
+            if parse_layout_dimension(layout.layout_key) == 3:
+                return layout.layout_key
+        except ValueError:
+            continue
+
+    raise RuntimeError("No 3D layout is available for figure export")
+
+
+def _run_figure_command(args: argparse.Namespace) -> None:
+    if args.figure_command != "export":
+        raise RuntimeError(f"Unsupported figure command: {args.figure_command}")
+
+    runtime = HyperViewRuntime()
+    workspace = runtime.get_workspace(args.workspace)
+    dataset = runtime.get_dataset(workspace.id, args.dataset)
+    layout_key = _resolve_figure_layout_key(
+        dataset,
+        workspace.ui.active_layout_key,
+        args.layout,
+    )
+
+    layout_view = workspace.ui.layout_views.get(layout_key)
+    camera = layout_view.camera_3d if layout_view is not None else None
+    view = OrbitViewState3D(**camera) if camera is not None else None
+
+    options = FigureRenderOptions(
+        width=args.width,
+        height=args.height,
+        scale=args.scale,
+        theme=args.theme,
+        background=args.background,
+        point_radius=args.point_radius,
+        show_guide=not args.no_guide,
+        guide_style=args.guide_style,
+        guide_alpha=args.guide_alpha,
+        legend=args.legend,
+        title=args.title,
+        selected_ids=set(workspace.ui.selected_ids) if args.show_selection and not args.ignore_selection else set(),
+    )
+    try:
+        result = render_layout_figure(
+            dataset=dataset,
+            layout_key=layout_key,
+            output_path=args.output,
+            view=view,
+            options=options,
+        )
+    except ValueError as exc:
+        raise SystemExit(str(exc)) from None
+
+    payload = {"figure": result.to_dict()}
+    if args.json:
+        _print_output(payload, as_json=True)
+        return
+    print(f"Wrote {result.output_path} ({result.width}x{result.height}, {result.num_points} points)")
+
+
 def _run_ui_command(args: argparse.Namespace) -> None:
     base_url = _server_base_url(args.host, args.port)
     if args.ui_command == "workspace" and args.ui_workspace_command == "set":
@@ -780,6 +886,9 @@ def main(argv: list[str] | None = None):
     if args.command == "jobs":
         _run_jobs_command(args)
         return
+    if args.command == "figure":
+        _run_figure_command(args)
+        return
     if args.command == "ui":
         _run_ui_command(args)
         return

{hyperview-0.4.2 → hyperview-0.5.0}/src/hyperview/core/selection.py

@@ -236,6 +236,26 @@ def _project_points_3d_to_screen(
     return screen_x, screen_y, depth, pixel_index
 
 
+def build_mvp_for_orbit(
+    view: OrbitViewState3D,
+    coords: np.ndarray,
+    viewport_width: int,
+    viewport_height: int,
+) -> np.ndarray:
+    """Build an orbit-camera MVP matrix matching the 3D scatter renderer."""
+    return _build_mvp_for_orbit(view, coords, viewport_width, viewport_height)
+
+
+def project_points_3d_to_screen(
+    mvp: np.ndarray,
+    coords: np.ndarray,
+    width: int,
+    height: int,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """Project 3D points to screen coordinates using scatter renderer math."""
+    return _project_points_3d_to_screen(mvp, coords, width, height)
+
+
 def select_ids_for_3d_lasso(
     *,
     ids: list[str],

hyperview-0.5.0/src/hyperview/figures/__init__.py

@@ -0,0 +1,13 @@
+"""Static figure export helpers for HyperView."""
+
+from hyperview.figures.render import (
+    FigureExportResult,
+    FigureRenderOptions,
+    render_layout_figure,
+)
+
+__all__ = [
+    "FigureExportResult",
+    "FigureRenderOptions",
+    "render_layout_figure",
+]

hyperview-0.5.0/src/hyperview/figures/colors.py

@@ -0,0 +1,102 @@
+"""Deterministic categorical colors shared by static figure export."""
+
+from __future__ import annotations
+
+import colorsys
+
+MISSING_LABEL_SENTINEL = "undefined"
+MISSING_LABEL_COLOR = "#39d3cc"
+FALLBACK_LABEL_COLOR = "#8b949e"
+
+TAB_20_LABEL_PALETTE = [
+    "#0072b2",
+    "#e69f00",
+    "#009e73",
+    "#d55e00",
+    "#cc79a7",
+    "#56b4e9",
+    "#000000",
+    "#7f7f7f",
+    "#332288",
+    "#88ccee",
+    "#44aa99",
+    "#117733",
+    "#999933",
+    "#ddcc77",
+    "#cc6677",
+    "#882255",
+    "#aa4499",
+    "#6699cc",
+    "#661100",
+    "#888888",
+]
+
+OVERFLOW_HUE_STEP_DEGREES = 137.508
+
+
+def normalize_label(label: str | None) -> str:
+    return label if label else MISSING_LABEL_SENTINEL
+
+
+def _stable_label_sort_key(label: str) -> tuple[int, str]:
+    return (1, label) if label == MISSING_LABEL_SENTINEL else (0, label)
+
+
+def _overflow_color(index: int) -> str:
+    hue = (43.0 + index * OVERFLOW_HUE_STEP_DEGREES) % 360.0
+    saturation = [0.72, 0.64, 0.78][index % 3]
+    lightness = [0.46, 0.54, 0.38, 0.62][(index // 3) % 4]
+    r, g, b = colorsys.hls_to_rgb(hue / 360.0, lightness, saturation)
+    return f"#{round(r * 255):02x}{round(g * 255):02x}{round(b * 255):02x}"
+
+
+def create_label_color_map(labels: list[str | None]) -> dict[str, str]:
+    unique = sorted({normalize_label(label) for label in labels}, key=_stable_label_sort_key)
+    colors: dict[str, str] = {}
+    used: set[str] = set()
+    non_missing_index = 0
+    overflow_index = 0
+
+    for label in unique:
+        if label == MISSING_LABEL_SENTINEL:
+            colors[label] = MISSING_LABEL_COLOR
+            used.add(MISSING_LABEL_COLOR.lower())
+            continue
+
+        if non_missing_index < len(TAB_20_LABEL_PALETTE):
+            candidate = TAB_20_LABEL_PALETTE[non_missing_index]
+        else:
+            candidate = _overflow_color(overflow_index)
+
+        safety = 0
+        while candidate.lower() in used and safety < 2048:
+            overflow_index += 1
+            candidate = _overflow_color(overflow_index)
+            safety += 1
+
+        if non_missing_index >= len(TAB_20_LABEL_PALETTE):
+            overflow_index += 1
+
+        if candidate.lower() in used:
+            candidate = FALLBACK_LABEL_COLOR
+
+        colors[label] = candidate
+        used.add(candidate.lower())
+        non_missing_index += 1
+
+    return colors
+
+
+def hex_to_rgba(color: str, alpha: int = 255) -> tuple[int, int, int, int]:
+    raw = color.strip()
+    if raw.startswith("#"):
+        raw = raw[1:]
+    if len(raw) == 3:
+        raw = "".join(ch * 2 for ch in raw)
+    if len(raw) not in {6, 8}:
+        return 255, 255, 255, alpha
+    r = int(raw[0:2], 16)
+    g = int(raw[2:4], 16)
+    b = int(raw[4:6], 16)
+    a = int(raw[6:8], 16) if len(raw) == 8 else alpha
+    return r, g, b, a