feat(example): 3D visualization of the lifted dimension

Author: Neiko2002

examples/graph_2d/README.md

@@ -103,7 +103,7 @@ construction cost in milliseconds.
 The colour key under the plot is itself a control: clicking an entry withdraws that reference graph's colour
 and the edges it claimed fall through to the next graph holding them, which is how the nesting gets peeled
 apart one layer at a time. `DEG only` names the remainder and is deliberately not a switch — the
-`theory colours` checkbox owns that flag on its own.
+`edge colors` checkbox owns that flag on its own.
 
 | Action | Key |
 |---|---|
@@ -112,7 +112,7 @@ apart one layer at a time. `DEG only` names the remainder and is deliberately no
 | Release the selection or the start node | `Esc` |
 | Next graph | `v` |
 | New sample from the same distribution | `r` |
-| Overlays: coordinate cross, edges, vertex ids, theory colours, query markers | `g` / `e` / `i` / `c` / `q` |
+| Overlays: coordinate cross, edges, vertex ids, edge colors, query markers | `g` / `e` / `i` / `c` / `q` |
 | Zoom at the cursor / pan by dragging / restore the framing | scroll / drag / `0` |
 | Control sheet | `h` or `?` |
 

examples/graph_2d/conftest.py

@@ -0,0 +1,113 @@
+"""Shared fixtures and test helpers for the graph_2d test suite."""
+
+from __future__ import annotations
+
+import matplotlib
+
+matplotlib.use("Agg")
+
+from functools import partial
+
+import pytest
+from deg_graph import DEFAULT_K
+from deglib.distances import Metric
+from main import build_scene
+from matplotlib.backend_bases import KeyEvent
+from viewer import (
+    DEG_VIEW,
+    FLAG_START,
+    GraphViewer,
+)
+
+BUILD_START = ("blobs", 240, DEFAULT_K, 3, Metric.FP32_L2)
+
+
+@pytest.fixture(scope="module")
+def window():
+    instance = GraphViewer(partial(build_scene, threads=1), *BUILD_START)
+    instance._fig.canvas.draw_idle = lambda *_args, **_keywords: None
+    yield instance
+    instance.close()
+
+
+@pytest.fixture()
+def viewer(window: GraphViewer) -> GraphViewer:
+    stale = (window.preset, window.num_points, window.k, window.seed, window.metric) != BUILD_START
+    window.preset, window.num_points, window.k, window.seed, window.metric = BUILD_START
+    window.selected = window.entry = window.hovered = None
+    window.free_query = None
+    window.query = window.status = None
+    window._home = None
+    window._drag = None
+    window.view = DEG_VIEW
+    window.search_metric = BUILD_START[4]
+    window.top_k = 1
+    window.overlays = window._held_graphs()
+    window._held_seen = set(window.overlays)
+    window._knng_edges = None
+    for position, wanted in enumerate(FLAG_START):
+        checks = window._checks1 if position < 3 else window._checks2
+        local = position if position < 3 else position - 3
+        if checks.get_status()[local] != wanted:
+            window._toggle_flag(position)
+    if window.show_3d:
+        window.show_3d = False
+        window._set_3d_visible(False)
+    window._cube_3d.reset_limits()
+    if stale:
+        window._rebuild()
+    else:
+        window.entry = window.model.farthest_from_centroid()
+        window.redraw()
+    return window
+
+
+@pytest.fixture(scope="module")
+def mips_window():
+    instance = GraphViewer(partial(build_scene, threads=1), *BUILD_START, mips=True)
+    instance._fig.canvas.draw_idle = lambda *_args, **_keywords: None
+    yield instance
+    instance.close()
+
+
+@pytest.fixture()
+def mips_viewer(mips_window: GraphViewer) -> GraphViewer:
+    stale = (
+        mips_window.preset,
+        mips_window.num_points,
+        mips_window.k,
+        mips_window.seed,
+        mips_window.metric,
+        mips_window.mips,
+    ) != (*BUILD_START, True)
+    mips_window.preset, mips_window.num_points, mips_window.k, mips_window.seed, mips_window.metric = BUILD_START
+    mips_window.mips = True
+    mips_window.selected = mips_window.entry = mips_window.hovered = None
+    mips_window.free_query = None
+    mips_window.query = mips_window.status = None
+    mips_window._home = None
+    mips_window._drag = None
+    mips_window.view = DEG_VIEW
+    mips_window.search_metric = BUILD_START[4]
+    mips_window.top_k = 1
+    mips_window.overlays = mips_window._held_graphs()
+    mips_window._held_seen = set(mips_window.overlays)
+    mips_window._knng_edges = None
+    for position, wanted in enumerate(FLAG_START):
+        checks = mips_window._checks1 if position < 3 else mips_window._checks2
+        local = position if position < 3 else position - 3
+        if checks.get_status()[local] != wanted:
+            mips_window._toggle_flag(position)
+    if mips_window.show_3d:
+        mips_window.show_3d = False
+        mips_window._set_3d_visible(False)
+    mips_window._cube_3d.reset_limits()
+    if stale:
+        mips_window._rebuild()
+    else:
+        mips_window.redraw()
+    return mips_window
+
+
+def _key(viewer: GraphViewer, key: str) -> KeyEvent:
+    return KeyEvent("key_press_event", viewer._fig.canvas, key)

examples/graph_2d/deg_graph.py

@@ -11,7 +11,7 @@
 from deglib.distances import FloatSpace, Metric
 from deglib.optimization import mips_l2_transform_query
 from pysearch import epsilon_search
-from theory import TheoryReport, compare, dissimilarities, knng_edges, nsw_edges
+from theory import TheoryReport, compare, knng_edges, nsw_edges
 
 __all__ = [
     "DEFAULT_K",

examples/graph_2d/main.py

@@ -50,9 +50,7 @@ def build_scene(
     """
     points, groups = make_points(preset, num_points, seed)
     features = mips_l2_transform(points)[0] if mips else points
-    return build_model(
-        features, groups, k=k, seed=seed, threads=threads, metric=metric, plot_points=points, mips=mips
-    )
+    return build_model(features, groups, k=k, seed=seed, threads=threads, metric=metric, plot_points=points, mips=mips)
 
 
 def main() -> None:

examples/graph_2d/pyproject.toml

@@ -19,7 +19,7 @@ requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
-py-modules = ["main", "dataset", "deg_graph", "theory", "viewer"]
+py-modules = ["main", "dataset", "deg_graph", "theory", "viewer", "viewer_3d", "viewer_controls", "viewer_panel"]
 
 [tool.uv.sources]
 deglib = { path = "../../python", editable = true }