"""
GPU-accelerated 3D renderer with interactive controls — faithful port of
Android's My3DScatterRenderer.java + FlowFieldSystem.java + DashboardFragment.
WARNING — Import order matters on Windows:
Do NOT import this module before running pipeline.analyze() (which uses
ChromaDB). Loading OpenGL libraries (via vispy/PyOpenGL) before the
ChromaDB Rust backend can cause an access-violation segfault on Windows.
Use the lazy launch_renderer() wrapper in tracescope/__init__.py instead
of importing this module directly.
GPU rendering (vispy + OpenGL):
- Flow halo particles: circular discard, pow(1.6) alpha falloff, heat bloom
- Cluster points: vibrant boost (*1.3 + 0.1), centre-lit spherical gradient
- Turbo speed colormap: exact degree-5 polynomial coefficients
- 64,000 particles (40^3), auto-rotation 7.5 deg/s, dark background
Interactive controls (Qt panel):
- Flow / Ball / Auto-Rotate toggle checkboxes
- Show Points / Show Path toggles
- Bidirectional X/Y/Z probe sliders (track ball OR set position manually)
- Mark Point / Clear buttons with Catmull-Rom connecting spline
- Cluster legend with counts
- Info panel: axis %, cluster distances, nearest message texts
Keyboard shortcuts (when 3D canvas has focus):
Space drag probe by flow F flow particles B ball
M mark probe point E explain attractor / marked path
P points L path R reset camera Esc quit
+/- particle size
Requires: pip install vispy PyOpenGL PyQt5 (or PySide6)
"""
from __future__ import annotations
import threading
import warnings
import numpy as np
# Silence vispy's isosurface scalar overflow warnings (harmless — they fire
# during marching-cubes shift computation on narrow integer dtypes).
warnings.filterwarnings(
"ignore",
message="overflow encountered in scalar",
category=RuntimeWarning,
module=r"vispy\.geometry\.isosurface",
)
try:
from vispy import app, scene, gloo
from vispy.visuals import Visual
from vispy.scene.visuals import create_visual_node
from vispy.visuals.transforms import STTransform
except ImportError:
raise ImportError(
"vispy is required for the GPU renderer.\n"
"Install with: pip install vispy PyOpenGL PyQt5\n"
" (or replace PyQt5 with PySide6 / pyglet / glfw)"
)
def _ensure_viable_backend():
"""Try to use the best available vispy backend, falling back to software
rendering if GPU/OpenGL is not available. Called once before building the
canvas so that vispy is configured for the current environment.
"""
# If a backend is already set and working, leave it alone.
try:
current = app.use_app()
if current is not None:
return
except Exception:
pass
# Preferred order: PyQt5 (GPU), PySide6 (GPU), pyglet, osmesa (CPU-only)
for backend in ("pyqt5", "pyside6", "pyglet", "osmesa"):
try:
app.use_app(backend)
return
except Exception:
continue
# Last resort — let vispy pick whatever it can find
try:
app.use_app()
except Exception:
pass
# Qt imports — try PyQt5 first (most common), then PySide6
try:
from PyQt5 import QtWidgets, QtCore
except ImportError:
try:
from PySide6 import QtWidgets, QtCore
except ImportError:
QtWidgets = None # type: ignore[assignment]
from .flow_field import FlowFieldSystem
from .scatter3d import catmull_rom_spline
from .probe import probe_point, probe_with_explanation
# ═══════════════════════════════════════════════════════════════════
# GLSL shaders — exact port of Android My3DScatterRenderer.java
# ═══════════════════════════════════════════════════════════════════
FLOW_HALO_VERT = """
attribute vec3 a_position;
attribute vec4 a_color;
varying vec4 v_color;
uniform float u_base_size;
void main() {
vec4 clip = $transform(vec4(a_position, 1.0));
gl_Position = clip;
float size = u_base_size / max(0.001, clip.w);
gl_PointSize = clamp(size, 2.0, 64.0);
v_color = a_color;
}
"""
FLOW_HALO_FRAG = """
varying vec4 v_color;
void main() {
vec2 d = gl_PointCoord - vec2(0.5);
float r2 = dot(d, d);
if (r2 > 0.25) discard;
float alpha = pow(clamp((0.5 - sqrt(r2)) * 2.0, 0.0, 1.0), 1.6);
vec3 rgb = mix(v_color.rgb * 0.65, v_color.rgb, alpha);
gl_FragColor = vec4(rgb, alpha * v_color.a);
}
"""
CLUSTER_POINT_VERT = """
attribute vec3 a_position;
attribute vec4 a_color;
varying vec4 v_color;
uniform float u_point_size;
void main() {
vec4 clip = $transform(vec4(a_position, 1.0));
gl_Position = clip;
float dist = length(clip.xyz);
gl_PointSize = u_point_size + (1.0 / dist);
v_color = a_color;
}
"""
CLUSTER_POINT_FRAG = """
varying vec4 v_color;
void main() {
vec2 coord = gl_PointCoord - vec2(0.5);
float dist = length(coord);
if (dist > 0.5) discard;
float lightFactor = 0.8 + 0.2 * (1.0 - smoothstep(0.0, 0.5, dist));
vec3 vibrant = clamp(v_color.rgb * 1.3 + vec3(0.1), vec3(0.0), vec3(1.0));
gl_FragColor = vec4(vibrant * lightFactor, v_color.a);
}
"""
# ═══════════════════════════════════════════════════════════════════
# Color palettes (matching Android exactly)
# ═══════════════════════════════════════════════════════════════════
CLUSTER_COLORS_GL = np.array([
[1.0, 0.0, 0.0, 1.0], # red
[0.0, 1.0, 0.0, 1.0], # green
[0.0, 0.0, 1.0, 1.0], # blue
[1.0, 1.0, 0.0, 1.0], # yellow
[1.0, 0.0, 1.0, 1.0], # magenta
[0.0, 1.0, 1.0, 1.0], # cyan
[1.0, 0.5, 0.0, 1.0], # orange
[0.5, 0.0, 1.0, 1.0], # purple
[0.0, 0.5, 1.0, 1.0], # sky blue
[0.5, 1.0, 0.5, 1.0], # pastel green
], dtype=np.float32)
AXIS_COLORS = [
np.array([112, 73, 78, 255], dtype=np.float32) / 255,
np.array([73, 112, 78, 255], dtype=np.float32) / 255,
np.array([73, 78, 112, 255], dtype=np.float32) / 255,
]
# ═══════════════════════════════════════════════════════════════════
# Custom vispy Visuals (unchanged — exact Android shaders)
# ═══════════════════════════════════════════════════════════════════
class _FlowHaloVisual(Visual):
def __init__(self, base_size=40.0):
Visual.__init__(self, vcode=FLOW_HALO_VERT, fcode=FLOW_HALO_FRAG)
self._draw_mode = 'points'
self._n = 0
self.set_gl_state(depth_test=True, cull_face=False, blend=True,
blend_func=('src_alpha', 'one_minus_src_alpha'))
self.shared_program['u_base_size'] = float(base_size)
self.shared_program['a_position'] = gloo.VertexBuffer(np.zeros((1, 3), dtype=np.float32))
self.shared_program['a_color'] = gloo.VertexBuffer(np.zeros((1, 4), dtype=np.float32))
def set_data(self, positions, colors):
self._n = len(positions)
pos = positions if positions.flags['C_CONTIGUOUS'] and positions.dtype == np.float32 \
else np.ascontiguousarray(positions, dtype=np.float32)
col = colors if colors.flags['C_CONTIGUOUS'] and colors.dtype == np.float32 \
else np.ascontiguousarray(colors, dtype=np.float32)
self.shared_program['a_position'].set_data(pos)
self.shared_program['a_color'].set_data(col)
self.update()
def set_base_size(self, size):
self.shared_program['u_base_size'] = float(size)
self.update()
def _prepare_transforms(self, view):
view.view_program.vert['transform'] = view.transforms.get_transform()
def _prepare_draw(self, view):
if self._n < 1:
return False
gloo.set_state(depth_mask=False)
return True
def draw(self, *args, **kwargs):
super().draw(*args, **kwargs)
gloo.set_state(depth_mask=True)
class _ClusterPointVisual(Visual):
def __init__(self, point_size=9.0):
Visual.__init__(self, vcode=CLUSTER_POINT_VERT, fcode=CLUSTER_POINT_FRAG)
self._draw_mode = 'points'
self._n = 0
self.set_gl_state(depth_test=True, cull_face=False, blend=True,
blend_func=('src_alpha', 'one_minus_src_alpha'))
self.shared_program['u_point_size'] = float(point_size)
self.shared_program['a_position'] = gloo.VertexBuffer(np.zeros((1, 3), dtype=np.float32))
self.shared_program['a_color'] = gloo.VertexBuffer(np.zeros((1, 4), dtype=np.float32))
def set_data(self, positions, colors):
self._n = len(positions)
self.shared_program['a_position'].set_data(np.ascontiguousarray(positions, dtype=np.float32))
self.shared_program['a_color'].set_data(np.ascontiguousarray(colors, dtype=np.float32))
self.update()
def set_point_size(self, size):
self.shared_program['u_point_size'] = float(size)
self.update()
def _prepare_transforms(self, view):
view.view_program.vert['transform'] = view.transforms.get_transform()
def _prepare_draw(self, view):
return self._n > 0
FlowHalo = create_visual_node(_FlowHaloVisual)
ClusterPoint = create_visual_node(_ClusterPointVisual)
# ═══════════════════════════════════════════════════════════════════
# Qt dark theme
# ═══════════════════════════════════════════════════════════════════
def _build_dark_qss(scale: float = 1.0) -> str:
"""Build Qt stylesheet with font sizes scaled for window size."""
fs_12 = max(9, int(round(12 * scale)))
fs_11 = max(9, int(round(11 * scale)))
return f"""
QMainWindow, QWidget#central {{ background: #1E1E1E; }}
QGroupBox {{
background: #2A2A2A; border: 1px solid #3A3A3A; border-radius: 6px;
margin-top: 4px; padding: 24px 8px 8px 8px; font-size: {fs_12}px;
}}
QGroupBox::title {{
subcontrol-origin: padding;
subcontrol-position: top center;
padding: 4px 8px;
color: white; font-weight: bold;
}}
QCheckBox {{ color: #E0E0E0; spacing: 6px; font-size: {fs_12}px; }}
QCheckBox::indicator {{ width: 14px; height: 14px; }}
QLabel {{ color: #E0E0E0; font-size: {fs_12}px; }}
QSlider::groove:horizontal {{
height: 4px; background: #3A3A3A; border-radius: 2px;
}}
QSlider::handle:horizontal {{
width: 14px; height: 14px; margin: -5px 0;
background: #FF6B35; border-radius: 7px;
}}
QPushButton {{
background: #FF6B35; color: white; border: none;
border-radius: 4px; padding: 5px 14px; font-size: {fs_12}px;
}}
QPushButton:hover {{ background: #FF8555; }}
QPushButton#btn-secondary {{ background: #555; }}
QPushButton#btn-secondary:hover {{ background: #777; }}
QTextEdit {{
background: #1E1E1E; color: #E0E0E0; border: 1px solid #3A3A3A;
font-size: {fs_11}px; font-family: Consolas, monospace;
}}
QScrollArea {{ border: none; background: transparent; }}
QScrollBar:vertical {{
width: 4px; background: transparent; margin: 0; padding: 0;
}}
QScrollBar::handle:vertical {{
background: rgba(255, 255, 255, 30); border-radius: 2px; min-height: 20px;
}}
QScrollBar::add-line:vertical, QScrollBar::sub-line:vertical,
QScrollBar::add-page:vertical, QScrollBar::sub-page:vertical {{
background: transparent; height: 0px;
}}
"""
DARK_QSS = _build_dark_qss(1.0)
# ═══════════════════════════════════════════════════════════════════
# FlowRenderer — GPU rendering + interactive Qt controls
# ═══════════════════════════════════════════════════════════════════
class _SliderEventFilter(QtCore.QObject if QtWidgets is not None else object):
"""Detects mouse press/release on sliders to temporarily pause ball sync."""
def __init__(self, renderer):
if QtWidgets is not None:
super().__init__()
self._renderer = renderer
def eventFilter(self, obj, event):
if event.type() == QtCore.QEvent.MouseButtonPress:
self._renderer._manual_slider_override = True
elif event.type() == QtCore.QEvent.MouseButtonRelease:
self._renderer._manual_slider_override = False
return False
class FlowRenderer:
"""GPU-accelerated 3D flow renderer with interactive controls panel."""
AUTO_ROTATE_SPEED = 7.5
BALL_RADIUS = 0.07
BALL_COLOR = (1.0, 0.2, 0.2, 1.0)
TRAIL_COLOR = (1.0, 1.0, 0.0, 1.0)
PATH_COLOR = (1.0, 0.0, 0.0, 1.0)
PROBE_COLOR = np.array([[1.0, 1.0, 0.0, 1.0]], dtype=np.float32)
def __init__(self, result, particle_grid=40, base_size=28.0,
window_size=(1400, 800), title='TraceScope Flow Renderer',
explainer=None, dataset_name=None, initial_state=None):
self.result = result
self.base_size = base_size
self._title = title
self._explainer = explainer
self._dataset_name = dataset_name
self._initial_state = initial_state or {}
# ── State ─────────────────────────────────────
self._has_flow = result.velocity_grid is not None
self.flow_active = self._has_flow
self.show_points = False
self.show_path = False
self.ball_flowing = self._has_flow
self.auto_rotate = False
self._last_time = None
self._frame_count = 0
self._updating_sliders = False
self._manual_slider_override = False
self._control_points: list = []
self._particle_grid = particle_grid
self._spline_path = False # default: straight lines; True = Catmull-Rom splines
self._explain_pending = None # async explain result (set by bg thread, consumed by timer)
self._explain_pending_stage = None # intermediate progress text
self._debug_prompts = False # set True to print all LLM prompts to stdout
# Persistent explained paths & attractor explanations
self._saved_paths: list = [] # [{control_points, explanation}]
self._saved_path_visuals: list = [] # [{'markers': vis, 'line': vis}]
self._highlighted_path: int | None = None
self._saved_paths_visible = True
self._attractor_explanations: dict = {} # {idx: explanation_text}
# Cluster colors (positions scaled below)
n_cls = result.clusters.n_clusters
self._cluster_colors_arr = np.array([
CLUSTER_COLORS_GL[c % len(CLUSTER_COLORS_GL)][:3]
for c in range(n_cls)
], dtype=np.float32) # (K, 3)
# ── Bounds ────────────────────────────────────
pts = result.projected_3d
self._data_center = pts.mean(axis=0).astype(np.float32)
self._axis_min = (np.asarray(result.axis_min, dtype=np.float32)
if result.axis_min is not None
else pts.min(axis=0).astype(np.float32) - 0.1)
self._axis_max = (np.asarray(result.axis_max, dtype=np.float32)
if result.axis_max is not None
else pts.max(axis=0).astype(np.float32) + 0.1)
# ── Scene Normalization ─────────────────────────
# Apply a SCALE TRANSFORM to the scene so the data always appears
# at a standard extent (target span magnitude = 6.0). This way all
# visual sizes (particles, fonts, camera distance, speed) can be
# FIXED absolute values and look identical across datasets.
_raw_span = self._axis_max - self._axis_min
_raw_mag = float(np.linalg.norm(_raw_span))
_TARGET_SPAN_MAG = 6.0
self._scene_scale = _TARGET_SPAN_MAG / _raw_mag if _raw_mag > 0.01 else 1.0
print(f"[SCALE] raw_span_mag={_raw_mag:.2f}, scene_scale={self._scene_scale:.3f} "
f"(scene rescaled to standard size)")
# Cluster centroids (in original data space)
self._cluster_centroids = (
result.cluster_centroids_3d.astype(np.float32)
if result.cluster_centroids_3d is not None
else np.zeros((n_cls, 3), dtype=np.float32)
)
# Use fixed absolute visual params — same for every dataset
self.base_size = base_size # Fixed (default 32)
# ── Path sample points for flow blob (computed before flow init) ──
# Build per-path splines to avoid spurious cross-path connections.
# Always include the raw data points as blob seeds so every data
# point is guaranteed to be inside the blob.
self._path_sample_pts = None
if len(result.projected_3d) >= 2:
path_groups: dict[int | None, list[int]] = {}
for idx, entry in enumerate(result.session.entries):
pid = entry.path_id
path_groups.setdefault(pid, []).append(idx)
spline_parts = [result.projected_3d.copy()] # raw data points first
for pid, indices in path_groups.items():
if len(indices) < 2:
continue
path_pts = result.projected_3d[indices]
sps = max(2, 20 // max(1, len(path_groups) // 10))
spline_parts.append(catmull_rom_spline(path_pts, sps))
self._path_sample_pts = np.concatenate(spline_parts, axis=0).astype(np.float32)
# ── Flow system ──────────────────────────────
self.flow: FlowFieldSystem | None = None
if self._has_flow:
self.flow = FlowFieldSystem(
result.velocity_grid, self._axis_min, self._axis_max,
particle_grid=particle_grid,
path_points=self._path_sample_pts,
confidence_grid=getattr(result, 'confidence_grid', None),
)
# Fixed speed — scene is already normalized via transform
self.flow.speed_multiplier = 0.95
# Pre-allocate flow RGBA buffer for performance
if self.flow is not None:
self._flow_rgba = np.empty((self.flow.particle_count, 4), dtype=np.float32)
else:
self._flow_rgba = None
# ── Canvas + Scene ────────────────────────────
self.canvas = scene.SceneCanvas(
keys='interactive', bgcolor=(0.12, 0.12, 0.12, 1.0),
size=window_size, show=False, title=title,
vsync=False, # Windows DWM otherwise throttles paints on
# small/unfocused windows, making the animation look slow
# until the window is resized larger.
)
self.view = self.canvas.central_widget.add_view()
# Scaled center so camera sees the normalized scene
_scaled_center = tuple((self._data_center * self._scene_scale).tolist())
self.view.camera = scene.TurntableCamera(
fov=60, distance=9.0,
center=_scaled_center,
up='+y', azimuth=0, elevation=20,
)
# Render root: intermediate Node with a scale transform so all
# visuals render at a standard size regardless of raw data extent.
# All 3D visuals are parented to this node instead of view.scene.
self._render_root = scene.Node(parent=self.view.scene)
self._render_root.transform = STTransform(
scale=(self._scene_scale, self._scene_scale, self._scene_scale)
)
# ── Build 3D visuals ──────────────────────────
self._build_visuals()
# ── Build Qt window with controls ─────────────
self.window = None
if QtWidgets is not None:
self._build_qt_window(window_size)
# ── Keyboard (fallback when canvas has focus) ─
self.canvas.events.key_press.connect(self._on_key)
# ── Mouse double-click to select nearest data point ─
self.canvas.events.mouse_double_click.connect(self._on_double_click)
# ── Ctrl+drag gizmo for probe positioning ─
self.canvas.events.mouse_press.connect(self._on_click_track_press)
self.canvas.events.mouse_move.connect(self._on_click_track_move)
self.canvas.events.mouse_release.connect(self._on_click_track_release)
self.canvas.events.mouse_press.connect(self._on_gizmo_press)
self.canvas.events.mouse_release.connect(self._on_attractor_click)
self.canvas.events.mouse_move.connect(self._on_gizmo_move)
self.canvas.events.mouse_release.connect(self._on_gizmo_release)
self.canvas.events.key_press.connect(self._on_gizmo_key)
self.canvas.events.key_release.connect(self._on_gizmo_key_release)
# ── Timer ─────────────────────────────────────
self._timer = app.Timer(interval=1.0 / 60, connect=self._on_timer)
# Force Qt PreciseTimer so the callback rate isn't throttled when the
# window is small or unfocused (Windows DWM otherwise coalesces the
# default CoarseTimer with paint events, slowing the animation until
# the window is resized/maximized).
try:
self._timer._backend.setTimerType(QtCore.Qt.PreciseTimer)
except Exception:
pass
# ═══════════════════════════════════════════════════
# 3D Visual construction
# ═══════════════════════════════════════════════════
def _build_visuals(self):
# Cluster points
self.vis_clusters = ClusterPoint(point_size=7.0, parent=self._render_root)
self.vis_clusters.order = 0
self._setup_cluster_data()
self.vis_clusters.visible = self.show_points
# Flow halo particles
self.vis_flow = FlowHalo(base_size=self.base_size, parent=self._render_root)
self.vis_flow.order = 1
self.vis_flow.visible = self.flow_active
# Spline path — both Tube and Line visuals (toggle with Simple Lines)
spline_pts, spline_colors = self._compute_path()
self._spline_pts = spline_pts # store for blob computation
# Base alpha for path
self._path_base_alpha = 0.88
spline_colors[:, 3] = self._path_base_alpha
# Tube path (no directional lighting — flat vertex colors)
tube_points = 10
vertex_colors = np.repeat(spline_colors, tube_points, axis=0)
try:
self.vis_path_tube = scene.visuals.Tube(
points=spline_pts, radius=0.015,
tube_points=tube_points, shading=None,
vertex_colors=vertex_colors,
parent=self._render_root,
)
except Exception:
self.vis_path_tube = scene.visuals.Line(
pos=spline_pts, color=spline_colors, width=4,
parent=self._render_root, antialias=True,
)
self.vis_path_tube.order = 2
self.vis_path_tube.visible = self.show_path and self._spline_path
# Simple line path — straight lines between actual data points
straight_pts, straight_colors = self._compute_straight_path()
straight_colors[:, 3] = self._path_base_alpha
self.vis_path_line = scene.visuals.Line(
pos=straight_pts, color=straight_colors, width=3,
parent=self._render_root, antialias=True,
)
self.vis_path_line.order = 2
self.vis_path_line.visible = self.show_path and not self._spline_path
# Probe marker (yellow) — render on top of everything (incl. attractor mesh)
self.vis_probe = ClusterPoint(point_size=15.0, parent=self._render_root)
self.vis_probe.order = 10
self.vis_probe.set_gl_state(
depth_test=False, cull_face=False, blend=True,
blend_func=('src_alpha', 'one_minus_src_alpha'),
)
self.vis_probe.set_data(
self._data_center.reshape(1, 3),
self.PROBE_COLOR,
)
# ── Gizmo: 3 axis arrows for Ctrl+drag probe positioning ──
pts = self.result.projected_3d
self._gizmo_arrow_len = float(np.max(pts.max(0) - pts.min(0))) * 0.084
self._gizmo_colors = [
(1.0, 0.2, 0.2, 0.9), # X = red
(0.2, 1.0, 0.2, 0.9), # Y = green
(0.3, 0.5, 1.0, 0.9), # Z = blue
]
self._gizmo_axes = [
np.array([1, 0, 0], dtype=np.float32),
np.array([0, 1, 0], dtype=np.float32),
np.array([0, 0, 1], dtype=np.float32),
]
self._gizmo_lines = [] # shaft lines
self._gizmo_heads = [] # arrowhead lines
for i in range(3):
line = scene.visuals.Line(
pos=np.zeros((2, 3), dtype=np.float32),
color=self._gizmo_colors[i], width=3,
parent=self._render_root, antialias=True,
)
line.order = 10
line.set_gl_state(depth_test=False, blend=True,
blend_func=('src_alpha', 'one_minus_src_alpha'))
line.visible = False
self._gizmo_lines.append(line)
# Arrowhead (two short lines forming a V)
head = scene.visuals.Line(
pos=np.zeros((3, 3), dtype=np.float32),
color=self._gizmo_colors[i], width=3,
connect='segments',
parent=self._render_root, antialias=True,
)
head.order = 10
head.set_gl_state(depth_test=False, blend=True,
blend_func=('src_alpha', 'one_minus_src_alpha'))
head.visible = False
self._gizmo_heads.append(head)
# Gizmo drag state
self._gizmo_visible = False
self._gizmo_dragging = None # axis index (0/1/2) or None
self._gizmo_drag_start_pos = None
self._gizmo_drag_start_click = None
self._gizmo_drag_axis_screen_n = None
self._gizmo_drag_px_per_unit = 1.0
self._gizmo_persistent = False
# Plain-click tracking (for click-near-probe detection)
self._click_track_pos = None
self._click_track_moved = False
# Start stuck so the initial hint invites the user to interact with the probe.
# Flips to False once the ball has actually been moving for a while.
self._ball_is_stuck = True
self._ball_stuck_frames = 0
self._ball_motion_frames = 0
self._last_ball_pos = None
# Control-point markers (white) + connecting spline
self.vis_markers = ClusterPoint(point_size=10.0, parent=self._render_root)
self.vis_markers.order = 3
self.vis_markers.visible = False
self.vis_marked_path = scene.visuals.Line(
pos=np.zeros((2, 3), dtype=np.float32),
color=(1.0, 0.5, 0.2, 0.8), width=3,
parent=self._render_root, antialias=True,
)
self.vis_marked_path.order = 3
self.vis_marked_path.visible = False
# Attractor basin point clouds (like blob debug, but colored by score)
self._attractor_clouds = [] # list of ClusterPoint visuals
self._attractor_labels = [] # list of Text visuals
self._attractor_data = [] # cached attractor dicts
self._attractors_visible = False
self._highlighted_attractor = None # index into _attractor_data or None
self._attractor_highlight_border = None # ClusterPoint for selected border
# Ball sphere
self.vis_ball = scene.visuals.Sphere(
radius=self.BALL_RADIUS, cols=24, rows=24,
color=self.BALL_COLOR, parent=self._render_root, method='latitude',
)
self.vis_ball.order = 4
self.vis_ball.visible = False
# Ball trail
self.vis_trail = scene.visuals.Line(
pos=np.zeros((2, 3), dtype=np.float32),
color=self.TRAIL_COLOR, width=4,
parent=self._render_root, antialias=True,
)
self.vis_trail.order = 4
self.vis_trail.visible = False
# Debug: blob boundary visualization (toggle with D key)
# Shows a point cloud of the blob-occupied cells as semi-transparent markers
self._debug_blob = False
self.vis_blob_debug = ClusterPoint(point_size=4.0, parent=self._render_root)
self.vis_blob_debug.order = 6
self.vis_blob_debug.visible = False
if self.flow is not None:
blob_pts = self.flow.get_blob_surface_points()
if blob_pts is not None:
blob_colors = np.ones((len(blob_pts), 4), dtype=np.float32)
blob_colors[:, :3] = [0.2, 0.8, 0.4] # green
blob_colors[:, 3] = 0.15 # very transparent
self.vis_blob_debug.set_data(blob_pts, blob_colors)
# Axes + labels
self._setup_axes()
self._setup_axis_labels()
def _setup_cluster_data(self):
pts = np.ascontiguousarray(self.result.projected_3d, dtype=np.float32)
colors = np.zeros((len(pts), 4), dtype=np.float32)
for i, label in enumerate(self.result.clusters.labels):
colors[i] = CLUSTER_COLORS_GL[label % len(CLUSTER_COLORS_GL)]
self.vis_clusters.set_data(pts, colors)
def _compute_path(self):
"""Compute Catmull-Rom spline with per-vertex cluster-interpolated colors."""
pts = self.result.projected_3d
if len(pts) < 2:
return np.zeros((2, 3), dtype=np.float32), np.array([[1, 0, 0, 1]] * 2, dtype=np.float32)
spline = catmull_rom_spline(pts, 20).astype(np.float32)
# Assign cluster colors to each spline point by nearest data point
# For each data point, get its cluster color
data_colors = np.zeros((len(pts), 4), dtype=np.float32)
for i, label in enumerate(self.result.clusters.labels):
data_colors[i] = CLUSTER_COLORS_GL[label % len(CLUSTER_COLORS_GL)]
# For each spline point, find nearest data point (KDTree avoids O(S*N) memory)
from scipy.spatial import cKDTree
tree = cKDTree(pts)
_, nearest_idx = tree.query(spline, k=1)
spline_colors = data_colors[nearest_idx]
# Smooth colors with a simple moving average (window=5) for nice transitions
kernel = 5
if len(spline_colors) > kernel:
pad = kernel // 2
padded = np.pad(spline_colors, ((pad, pad), (0, 0)), mode='edge')
smoothed = np.zeros_like(spline_colors)
for j in range(len(spline_colors)):
smoothed[j] = padded[j:j + kernel].mean(axis=0)
smoothed[:, 3] = 1.0 # keep alpha = 1
spline_colors = smoothed
return spline, spline_colors
def _compute_straight_path(self):
"""Straight lines between actual data points with cluster colors."""
pts = self.result.projected_3d
if len(pts) < 2:
return np.zeros((2, 3), dtype=np.float32), np.array([[1, 0, 0, 1]] * 2, dtype=np.float32)
pts = pts.astype(np.float32)
colors = np.zeros((len(pts), 4), dtype=np.float32)
for i, label in enumerate(self.result.clusters.labels):
colors[i] = CLUSTER_COLORS_GL[label % len(CLUSTER_COLORS_GL)]
return pts, colors
def _setup_axes(self):
mn, mx = self._axis_min, self._axis_max
self.vis_axes = []
for i in range(3):
start, end = mn.copy(), mn.copy()
end[i] = mx[i]
line = scene.visuals.Line(
pos=np.array([start, end], dtype=np.float32),
color=AXIS_COLORS[i], width=3,
parent=self._render_root, antialias=True,
)
line.order = 5
self.vis_axes.append(line)
# ── Axis label config ────────────────────────────────
# Fixed absolute font sizes — scene is pre-normalized to standard extent.
AXIS_LABEL_SIZE = 26
ATTRACTOR_LABEL_SIZE = 15
def _setup_axis_labels(self):
mn, mx = self._axis_min, self._axis_max
labels = getattr(self.result.axis_info, 'labels', ['Axis 1', 'Axis 2', 'Axis 3'])
axis_names = ['X', 'Y', 'Z']
self.vis_labels = []
offset = (mx - mn) * 0.03
for i in range(3):
pos = mn.copy()
pos[i] = mx[i] + offset[i]
label_text = labels[i] if i < len(labels) else f'Axis {i+1}'
t = scene.visuals.Text(
text=f'{axis_names[i]}: {label_text}',
pos=pos.reshape(1, 3).astype(np.float32),
color=AXIS_COLORS[i][:3], font_size=self.AXIS_LABEL_SIZE,
parent=self._render_root, anchor_x='left',
)
t.order = 6
self.vis_labels.append(t)
# ═══════════════════════════════════════════════════
# Qt window + controls panel
# ═══════════════════════════════════════════════════
def _build_qt_window(self, window_size):
self.window = QtWidgets.QMainWindow()
self.window.setWindowTitle(self._title)
self.window.setStyleSheet(DARK_QSS)
central = QtWidgets.QWidget()
central.setObjectName('central')
layout = QtWidgets.QHBoxLayout(central)
layout.setContentsMargins(0, 0, 0, 0)
layout.setSpacing(0)
# Left: vispy 3D canvas
layout.addWidget(self.canvas.native, stretch=3)
# Right: controls panel
layout.addWidget(self._build_controls(), stretch=0)
self.window.setCentralWidget(central)
self.window.resize(window_size[0], window_size[1])
# ── Canvas overlays ───────────────────────────
self._build_canvas_overlays()
_BASE_PANEL_WIDTH = 290
def _build_controls(self):
scroll = QtWidgets.QScrollArea()
scroll.setWidgetResizable(True)
scroll.setFixedWidth(self._BASE_PANEL_WIDTH)
self._controls_scroll = scroll
widget = QtWidgets.QWidget()
vbox = QtWidgets.QVBoxLayout(widget)
vbox.setContentsMargins(10, 8, 14, 8)
vbox.setSpacing(6)
axis_labels = getattr(self.result.axis_info, 'labels', ['X', 'Y', 'Z'])
# ── 1. Flow Controls ─────────────────────────────
grp = QtWidgets.QGroupBox("Flow Controls")
gl = QtWidgets.QVBoxLayout()
self.chk_flow = QtWidgets.QCheckBox("Flow Animation")
self.chk_flow.setChecked(self.flow_active)
self.chk_flow.setEnabled(self._has_flow)
self.chk_flow.toggled.connect(self._qt_flow_toggle)
gl.addWidget(self.chk_flow)
self.chk_ball = QtWidgets.QCheckBox("Drag probe by the flow")
self.chk_ball.setChecked(self._has_flow)
self.chk_ball.setEnabled(self._has_flow)
self.chk_ball.toggled.connect(self._qt_ball_toggle)
gl.addWidget(self.chk_ball)
self._gizmo_hint = QtWidgets.QLabel("Hold Ctrl + drag gizmo arrows to move probe")
self._gizmo_hint.setStyleSheet("color: #88ccff; font-size: 11px; padding: 2px 0;")
self._gizmo_hint.setVisible(not self._has_flow) # show when ball flow is off
gl.addWidget(self._gizmo_hint)
grp.setLayout(gl)
vbox.addWidget(grp)
# ── 2. Display ───────────────────────────────────
grp = QtWidgets.QGroupBox("Display")
gl = QtWidgets.QVBoxLayout()
self.chk_points = QtWidgets.QCheckBox("Show Data Points")
self.chk_points.setChecked(False)
self.chk_points.toggled.connect(self._qt_points_toggle)
gl.addWidget(self.chk_points)
self.chk_path = QtWidgets.QCheckBox("Show Path")
self.chk_path.setChecked(False)
self.chk_path.toggled.connect(self._qt_path_toggle)
gl.addWidget(self.chk_path)
self.chk_spline_path = QtWidgets.QCheckBox("Spline Path")
self.chk_spline_path.setChecked(False)
self.chk_spline_path.toggled.connect(self._qt_spline_path)
gl.addWidget(self.chk_spline_path)
self.chk_info_overlay = QtWidgets.QCheckBox("Show Info Overlay")
self.chk_info_overlay.setChecked(True)
self.chk_info_overlay.toggled.connect(self._qt_info_overlay_toggle)
gl.addWidget(self.chk_info_overlay)
self.chk_attractors = QtWidgets.QCheckBox("Show Attractors")
self.chk_attractors.setChecked(False)
self.chk_attractors.toggled.connect(self._qt_attractors_toggle)
gl.addWidget(self.chk_attractors)
# Sensitivity slider (hidden until attractors are shown)
self._attractor_sensitivity = 0.7 # default
self._sensitivity_row = QtWidgets.QWidget()
sl_lay = QtWidgets.QHBoxLayout(self._sensitivity_row)
sl_lay.setContentsMargins(0, 0, 0, 0)
self._lbl_sensitivity = QtWidgets.QLabel("Sensitivity: 70.0%")
sl_lay.addWidget(self._lbl_sensitivity)
self._sl_sensitivity = QtWidgets.QSlider(QtCore.Qt.Horizontal)
self._sl_sensitivity.setRange(0, 1000) # 0.0–100.0% with 0.1 steps
self._sl_sensitivity.setValue(700)
self._sl_sensitivity.setTracking(True) # update label in real-time
self._sl_sensitivity.valueChanged.connect(self._qt_sensitivity_label_update)
self._sl_sensitivity.sliderReleased.connect(self._qt_sensitivity_released)
sl_lay.addWidget(self._sl_sensitivity)
self._sensitivity_row.setVisible(False)
gl.addWidget(self._sensitivity_row)
grp.setLayout(gl)
vbox.addWidget(grp)
# ── 3. Probe Sliders ─────────────────────────────
grp = QtWidgets.QGroupBox("Probe")
gl = QtWidgets.QVBoxLayout()
self._slider_labels = []
self._sliders = []
for i in range(3):
lbl = QtWidgets.QLabel(f"{axis_labels[i]}: 50%")
gl.addWidget(lbl)
self._slider_labels.append(lbl)
sl = QtWidgets.QSlider(QtCore.Qt.Horizontal)
sl.setRange(0, 1000)
sl.setValue(500)
sl.valueChanged.connect(lambda v, idx=i: self._qt_slider_changed(idx, v))
gl.addWidget(sl)
self._sliders.append(sl)
self._slider_filter = _SliderEventFilter(self)
for sl in self._sliders:
sl.installEventFilter(self._slider_filter)
btn_row = QtWidgets.QHBoxLayout()
btn_mark = QtWidgets.QPushButton("Mark Point")
btn_mark.clicked.connect(self._qt_mark)
btn_row.addWidget(btn_mark)
btn_clear = QtWidgets.QPushButton("Clear")
btn_clear.setObjectName('btn-secondary')
btn_clear.clicked.connect(self._qt_clear)
btn_row.addWidget(btn_clear)
gl.addLayout(btn_row)
btn_explain = QtWidgets.QPushButton("Explain")
btn_explain.clicked.connect(self._qt_explain)
gl.addWidget(btn_explain)
# Toggle saved paths visibility
self._btn_toggle_paths = QtWidgets.QPushButton("Hide Saved Paths")
self._btn_toggle_paths.setObjectName('btn-secondary')
self._btn_toggle_paths.clicked.connect(self._toggle_saved_paths_visibility)
self._btn_toggle_paths.setVisible(False)
gl.addWidget(self._btn_toggle_paths)
grp.setLayout(gl)
vbox.addWidget(grp)
# ── 4. Cluster Legend ─────────────────────────────
grp = QtWidgets.QGroupBox("Clusters")
gl = QtWidgets.QVBoxLayout()
for c in range(self.result.clusters.n_clusters):
col = CLUSTER_COLORS_GL[c % len(CLUSTER_COLORS_GL)]
hexc = '#%02x%02x%02x' % (int(col[0]*255), int(col[1]*255), int(col[2]*255))
name = (self.result.cluster_labels[c]
if c < len(self.result.cluster_labels) else f"Cluster {c}")
cnt = sum(1 for l in self.result.clusters.labels if l == c)
lbl = QtWidgets.QLabel(
f'● '
f'{name} ({cnt})')
lbl.setTextFormat(QtCore.Qt.RichText)
lbl.setWordWrap(True)
gl.addWidget(lbl)
grp.setLayout(gl)
vbox.addWidget(grp)
# ── 5. Flow Settings ────────────────────────────
grp = QtWidgets.QGroupBox("Flow Settings")
gl = QtWidgets.QVBoxLayout()
self._flow_opacity = 0.8
lbl_op = QtWidgets.QLabel("Opacity: 80%")
gl.addWidget(lbl_op)
sl_opacity = QtWidgets.QSlider(QtCore.Qt.Horizontal)
sl_opacity.setRange(0, 100)
sl_opacity.setValue(80)
sl_opacity.valueChanged.connect(lambda v, l=lbl_op: self._qt_flow_opacity(v, l))
gl.addWidget(sl_opacity)
self._lbl_speed = QtWidgets.QLabel("Speed: 0.95x")
gl.addWidget(self._lbl_speed)
self._sl_speed = QtWidgets.QSlider(QtCore.Qt.Horizontal)
self._sl_speed.setRange(10, 300)
self._sl_speed.setValue(95)
self._sl_speed.valueChanged.connect(lambda v, l=self._lbl_speed: self._qt_flow_speed(v, l))
gl.addWidget(self._sl_speed)
init_count = self._particle_grid ** 3
lbl_pc = QtWidgets.QLabel(f"Particles: {init_count:,} ({self._particle_grid}\u00b3)")
gl.addWidget(lbl_pc)
sl_particles = QtWidgets.QSlider(QtCore.Qt.Horizontal)
sl_particles.setRange(8, 50)
sl_particles.setValue(self._particle_grid)
sl_particles.valueChanged.connect(lambda v, l=lbl_pc: self._qt_particle_count(v, l))
gl.addWidget(sl_particles)
# Confidence opacity slider (MDN only)
has_conf = (self.flow is not None and self.flow._confidence_grid is not None)
self._confidence_strength = 0.0
lbl_conf = QtWidgets.QLabel("Confidence fade: OFF")
gl.addWidget(lbl_conf)
sl_conf = QtWidgets.QSlider(QtCore.Qt.Horizontal)
sl_conf.setRange(0, 100)
sl_conf.setValue(0)
sl_conf.setEnabled(has_conf)
sl_conf.valueChanged.connect(lambda v, l=lbl_conf: self._qt_confidence(v, l))
gl.addWidget(sl_conf)
if not has_conf:
lbl_conf.setText("Confidence fade: N/A (no density data)")
# Constrain to path toggle
self._chk_blob = QtWidgets.QCheckBox("Constrain to paths")
self._chk_blob.setChecked(True)
self._chk_blob.setEnabled(self.flow is not None)
self._chk_blob.toggled.connect(self._qt_blob_toggle)
gl.addWidget(self._chk_blob)
self._flow_color_mode = "speed"
self._chk_entropy = QtWidgets.QCheckBox("Entropy Colors")
self._chk_entropy.setChecked(False)
self._chk_entropy.toggled.connect(self._qt_entropy_colors)
gl.addWidget(self._chk_entropy)
self._chk_cluster_colors = QtWidgets.QCheckBox("Cluster Colors")
self._chk_cluster_colors.setChecked(False)
self._chk_cluster_colors.toggled.connect(self._qt_cluster_colors)
gl.addWidget(self._chk_cluster_colors)
# Score-based coloring (only shown when scores exist)
self._score_color_checkboxes = []
score_channels = self.result.score_channels
if score_channels:
for ch in score_channels:
chk = QtWidgets.QCheckBox(f"Score: {ch}")
chk.setChecked(False)
chk.toggled.connect(lambda checked, c=ch: self._qt_score_colors(c, checked))
gl.addWidget(chk)
self._score_color_checkboxes.append((ch, chk))
grp.setLayout(gl)
grp.setEnabled(self._has_flow)
vbox.addWidget(grp)
# Score-based point coloring (separate from flow)
if score_channels:
grp_score = QtWidgets.QGroupBox("Point Coloring")
gl_score = QtWidgets.QVBoxLayout()
self._point_color_mode = "cluster"
self._score_point_checkboxes = []
for ch in score_channels:
chk = QtWidgets.QCheckBox(f"Color points by: {ch}")
chk.setChecked(False)
chk.toggled.connect(lambda checked, c=ch: self._qt_score_point_coloring(c, checked))
gl_score.addWidget(chk)
self._score_point_checkboxes.append((ch, chk))
grp_score.setLayout(gl_score)
vbox.addWidget(grp_score)
# ── Explanation Panel (hidden until Explain is pressed) ──
self._explain_group = QtWidgets.QGroupBox("Explanation")
gl = QtWidgets.QVBoxLayout()
self._explain_text = QtWidgets.QTextEdit()
self._explain_text.setReadOnly(True)
self._explain_text.setMaximumHeight(300)
gl.addWidget(self._explain_text)
btn_close_explain = QtWidgets.QPushButton("Close")
btn_close_explain.setObjectName('btn-secondary')
btn_close_explain.clicked.connect(lambda: self._explain_group.setVisible(False))
gl.addWidget(btn_close_explain)
self._explain_group.setLayout(gl)
self._explain_group.setVisible(False)
vbox.addWidget(self._explain_group)
self.info_text = None
vbox.addStretch()
scroll.setWidget(widget)
# Prevent sidebar widgets from stealing keyboard focus (Space, Enter, etc.)
# so that all key presses go to the vispy canvas.
for child in scroll.findChildren(QtWidgets.QWidget):
child.setFocusPolicy(QtCore.Qt.NoFocus)
scroll.setFocusPolicy(QtCore.Qt.NoFocus)
return scroll
def _build_canvas_overlays(self):
"""Create transparent overlays on the 3D canvas for info + point details."""
canvas_widget = self.canvas.native
overlay_style = (
"background: rgba(20, 20, 20, 180); color: white; "
"font-family: Consolas, monospace; font-size: 11px; "
"padding: 8px; border-radius: 4px;"
)
# ── Info overlay (bottom-left) ────────────────
self._info_overlay = QtWidgets.QLabel(canvas_widget)
self._info_overlay.setStyleSheet(overlay_style)
self._info_overlay.setWordWrap(True)
self._info_overlay.setTextFormat(QtCore.Qt.PlainText)
self._info_overlay.move(10, 10)
self._info_overlay.setMaximumWidth(360)
self._info_overlay.setText("")
self._info_overlay.adjustSize()
self._info_overlay.show()
# ── Point info overlay (bottom-center) ────────
self._point_overlay = QtWidgets.QFrame(canvas_widget)
self._point_overlay.setStyleSheet(
"background: rgba(30, 30, 30, 220); border-radius: 8px; padding: 0px;"
)
point_layout = QtWidgets.QVBoxLayout(self._point_overlay)
point_layout.setContentsMargins(10, 8, 10, 8)
point_layout.setSpacing(4)
# Header row with close button
header = QtWidgets.QHBoxLayout()
self._point_header_label = QtWidgets.QLabel("")
self._point_header_label.setStyleSheet("color: #FF6B35; font-weight: bold; font-size: 12px;")
header.addWidget(self._point_header_label)
header.addStretch()
btn_x = QtWidgets.QPushButton("X")
btn_x.setFixedSize(20, 20)
btn_x.setStyleSheet(
"background: #555; color: white; border-radius: 10px; "
"font-size: 10px; padding: 0px;"
)
btn_x.clicked.connect(lambda: self._point_overlay.setVisible(False))
header.addWidget(btn_x)
point_layout.addLayout(header)
self._point_text_label = QtWidgets.QLabel("")
self._point_text_label.setStyleSheet("color: #E0E0E0; font-size: 11px;")
self._point_text_label.setWordWrap(True)
self._point_text_label.setMaximumWidth(400)
point_layout.addWidget(self._point_text_label)
self._point_overlay.adjustSize()
self._point_overlay.setVisible(False)
# ── Hint overlay (center-bottom, orange text) ───────
self._hint_overlay = QtWidgets.QLabel(canvas_widget)
self._hint_overlay.setStyleSheet(
"background: rgba(15, 15, 15, 200); color: #FF8A3D; "
"font-family: Consolas, monospace; font-size: 12px; font-weight: bold; "
"padding: 10px 14px; border-radius: 6px;"
)
self._hint_overlay.setWordWrap(True)
self._hint_overlay.setTextFormat(QtCore.Qt.PlainText)
self._hint_overlay.setMaximumWidth(520)
self._hint_overlay.setText("")
self._hint_overlay.setAlignment(QtCore.Qt.AlignCenter)
self._hint_overlay.adjustSize()
self._hint_overlay.setVisible(False)
# ── Dataset name overlay (top-center, optional) ────
self._name_overlay = QtWidgets.QLabel(canvas_widget)
self._name_overlay.setStyleSheet(
"background: transparent; color: rgba(255,255,255,180); "
"font-family: Consolas, monospace; font-size: 16px; font-weight: bold;"
)
self._name_overlay.setAlignment(QtCore.Qt.AlignCenter)
if self._dataset_name:
self._name_overlay.setText(self._dataset_name)
self._name_overlay.adjustSize()
self._name_overlay.setVisible(True)
else:
self._name_overlay.setVisible(False)
# ── Explanation overlay (bottom-center, bold, larger) ──
self._explain_overlay = QtWidgets.QLabel(canvas_widget)
self._explain_overlay.setStyleSheet(
"background: rgba(15, 15, 15, 200); color: white; "
"font-family: Consolas, monospace; font-size: 13px; font-weight: bold; "
"padding: 12px 16px; border-radius: 6px;"
)
self._explain_overlay.setWordWrap(True)
self._explain_overlay.setTextFormat(QtCore.Qt.PlainText)
self._explain_overlay.setMaximumWidth(500)
self._explain_overlay.setText("")
self._explain_overlay.adjustSize()
self._explain_overlay.setVisible(False)
self._explain_full_text = "" # backing text for the fullscreen dialog
# Click to open fullscreen viewer
self._explain_overlay.setCursor(QtCore.Qt.PointingHandCursor)
self._explain_overlay.mousePressEvent = lambda e: self._open_explain_fullscreen()
# Connect canvas resize to reposition overlays
self.canvas.events.resize.connect(self._reposition_overlays)
# Default window dimensions for font scaling reference
_DEFAULT_WINDOW_W = 1400
_DEFAULT_WINDOW_H = 800
def _reposition_overlays(self, event=None):
"""Reposition overlays on canvas resize and scale fonts proportionally.
Stylesheet updates (expensive) are only applied when the window scale
actually changes. Repositioning (cheap) runs every call.
"""
if not hasattr(self, '_info_overlay'):
return
w = self.canvas.native.width()
h = self.canvas.native.height()
# Scale fonts relative to default window size (geometric mean of both axes)
scale = max(0.7, min(1.5, (w * h) ** 0.5 / (self._DEFAULT_WINDOW_W * self._DEFAULT_WINDOW_H) ** 0.5))
# Only rebuild stylesheets when scale actually changes (setStyleSheet
# triggers expensive Qt style recalculation — must NOT run every frame).
if getattr(self, '_last_qss_scale', None) != scale:
if hasattr(self, 'window') and self.window is not None:
self.window.setStyleSheet(_build_dark_qss(scale))
if hasattr(self, '_controls_scroll'):
self._controls_scroll.setFixedWidth(
int(round(self._BASE_PANEL_WIDTH * scale))
)
info_fs = max(9, int(11 * scale))
point_hdr_fs = max(10, int(12 * scale))
point_txt_fs = max(9, int(11 * scale))
explain_fs = max(10, int(13 * scale))
self._info_overlay.setStyleSheet(
f"background: rgba(20, 20, 20, 180); color: white; "
f"font-family: Consolas, monospace; font-size: {info_fs}px; "
f"padding: 8px; border-radius: 4px;"
)
self._point_header_label.setStyleSheet(
f"color: #FF6B35; font-weight: bold; font-size: {point_hdr_fs}px;"
)
self._point_text_label.setStyleSheet(
f"color: #E0E0E0; font-size: {point_txt_fs}px;"
)
if hasattr(self, '_explain_overlay'):
self._explain_overlay.setStyleSheet(
f"background: rgba(15, 15, 15, 200); color: white; "
f"font-family: Consolas, monospace; font-size: {explain_fs}px; font-weight: bold; "
f"padding: 12px 16px; border-radius: 6px;"
)
if hasattr(self, '_hint_overlay'):
hint_fs = max(10, int(12 * scale))
self._hint_overlay.setStyleSheet(
f"background: rgba(15, 15, 15, 200); color: #FF8A3D; "
f"font-family: Consolas, monospace; font-size: {hint_fs}px; font-weight: bold; "
f"padding: 10px 14px; border-radius: 6px;"
)
if hasattr(self, '_name_overlay') and self._name_overlay.isVisible():
name_fs = max(12, int(16 * scale))
self._name_overlay.setStyleSheet(
f"background: transparent; color: rgba(255,255,255,180); "
f"font-family: Consolas, monospace; font-size: {name_fs}px; font-weight: bold;"
)
self._last_qss_scale = scale
# Info overlay: bottom-left
self._info_overlay.adjustSize()
self._info_overlay.move(10, h - self._info_overlay.height() - 10)
# Point overlay: bottom-center
self._point_overlay.adjustSize()
pw = self._point_overlay.width()
self._point_overlay.move((w - pw) // 2, h - self._point_overlay.height() - 10)
# Explain overlay: bottom-center, above point overlay
if hasattr(self, '_explain_overlay') and self._explain_overlay.isVisible():
self._explain_overlay.adjustSize()
ew = self._explain_overlay.width()
self._explain_overlay.move(
(w - ew) // 2,
h - self._explain_overlay.height() - 20
)
# Hint overlay: bottom-center, stacked above explain/point overlays
if hasattr(self, '_hint_overlay') and self._hint_overlay.isVisible():
self._hint_overlay.adjustSize()
hw = self._hint_overlay.width()
# Stack above whichever bottom overlay is tallest
y_offset = 20
if (hasattr(self, '_explain_overlay')
and self._explain_overlay.isVisible()):
y_offset = self._explain_overlay.height() + 30
elif self._point_overlay.isVisible():
y_offset = self._point_overlay.height() + 24
self._hint_overlay.move(
(w - hw) // 2,
h - self._hint_overlay.height() - y_offset
)
# Dataset name overlay: top-center
if hasattr(self, '_name_overlay') and self._name_overlay.isVisible():
self._name_overlay.adjustSize()
nw = self._name_overlay.width()
self._name_overlay.move((w - nw) // 2, 12)
def _sync_path_visibility(self):
"""Update tube/line path visibility and alpha based on current flags."""
self.vis_path_tube.visible = self.show_path and self._spline_path
self.vis_path_line.visible = self.show_path and not self._spline_path
# When flow is active alongside paths, make paths more transparent
if self.show_path and self.flow_active:
alpha = self._path_base_alpha - 0.20 # -20% when flow is visible
else:
alpha = self._path_base_alpha
self._update_path_alpha(alpha)
def _update_path_alpha(self, alpha):
"""Update alpha on whichever path visual is active."""
# For the simple line visual — update color array alpha
if hasattr(self, 'vis_path_line') and self.vis_path_line.visible:
straight_pts, straight_colors = self._compute_straight_path()
straight_colors[:, 3] = alpha
self.vis_path_line.set_data(pos=straight_pts, color=straight_colors)
# Tube doesn't support easy alpha updates (mesh), so we rebuild only
# if needed — for now, tube alpha is set at build time
def _qt_info_overlay_toggle(self, checked):
if hasattr(self, '_info_overlay'):
self._info_overlay.setVisible(checked)
def _qt_confidence(self, value, label):
self._confidence_strength = value / 100.0
if self.flow is not None:
self.flow.confidence_strength = self._confidence_strength
if value == 0:
label.setText("Confidence fade: OFF")
else:
label.setText(f"Confidence fade: {value}%")
def _qt_attractors_toggle(self, checked):
if checked:
# Cap flow opacity at 50% so attractors stand out
self._pre_attractor_opacity = self._flow_opacity
if self._flow_opacity > 0.5:
self._flow_opacity = 0.5
self._compute_and_show_attractors()
else:
# Restore previous flow opacity
if hasattr(self, '_pre_attractor_opacity'):
self._flow_opacity = self._pre_attractor_opacity
self._hide_attractors()
self._update_contextual_hint()
# Show/hide sensitivity slider
if hasattr(self, '_sensitivity_row'):
self._sensitivity_row.setVisible(checked)
def _qt_sensitivity_label_update(self, value):
"""Update label in real-time while dragging (no recompute)."""
pct = value / 10.0
self._lbl_sensitivity.setText(f"Sensitivity: {pct:.1f}%")
def _qt_sensitivity_released(self):
"""Recompute attractors when the user releases the slider."""
value = self._sl_sensitivity.value()
self._attractor_sensitivity = value / 1000.0
if not self.chk_attractors.isChecked():
return
pct = value / 10.0
self._sl_sensitivity.setEnabled(False)
self._lbl_sensitivity.setText(f"Sensitivity: {pct:.1f}% (recomputing...)")
QtCore.QTimer.singleShot(50, self._recompute_attractors_async)
def _recompute_attractors_async(self):
"""Recompute attractors with current sensitivity, then re-enable slider."""
try:
self._compute_and_show_attractors()
finally:
self._sl_sensitivity.setEnabled(True)
pct = self._attractor_sensitivity * 100
self._lbl_sensitivity.setText(f"Sensitivity: {pct:.1f}%")
def _compute_and_show_attractors(self):
"""Detect attractors and render each basin as a vibrant isosurface mesh.
Each attractor's boolean basin_mask is upsampled 2× for smoother
mesh quality, then gaussian-smoothed and rendered as a semi-transparent
isosurface mesh via vispy.
"""
from scipy.ndimage import gaussian_filter, zoom
if self.flow is None:
return
score_grid = self.flow._score_grid if self.flow._score_grid is not None else None
_cache = getattr(self.result, 'cache_path', None)
_sens = getattr(self, '_attractor_sensitivity', 0.7)
attractors = self.flow.find_attractors(
score_grid=score_grid, cache_path=_cache, sensitivity=_sens,
)
self._attractor_data = attractors
self._hide_attractors()
if not attractors:
print("[ATTRACTORS] No attractors found in flow field")
return
G = self.flow.grid_size
att_colors = self._get_attractor_colors()
# Upsample factor for smoother meshes (3× = 118³ from 40³)
up = 3
G_up = (G - 1) * up + 1
# Transform: map UPSAMPLED grid indices → world coordinates
scale = self.flow.span / (G_up - 1)
translate = self.flow.axis_min.copy()
# Build a convergence-weighted volume for more detailed meshes.
# Instead of a binary mask, use basin_score (occupancy × convergence)
# so the isosurface shape reflects actual flow intensity.
vg = self.flow.velocity_grid
spd = np.linalg.norm(vg, axis=-1)
dvx_dx = np.gradient(vg[:, :, :, 0], axis=0)
dvy_dy = np.gradient(vg[:, :, :, 1], axis=1)
dvz_dz = np.gradient(vg[:, :, :, 2], axis=2)
div_grid = dvx_dx + dvy_dy + dvz_dz
# Convergence: 1 where div is most negative, 0 at neutral/positive
div_ref = max(float(np.percentile(np.abs(div_grid[spd > 1e-12]), 90)), 1e-8)
conv_grid = np.clip(-div_grid / div_ref, 0.0, 1.0)
for i, att in enumerate(attractors):
basin_mask = att['basin_mask']
if np.sum(basin_mask) == 0:
continue
base_rgb = att_colors[i] if i < len(att_colors) else np.array([0.5, 0.8, 1.0])
# Build flow-shaped volume: binary mask weighted by convergence
# strength. This makes the isosurface follow flow structure
# (indentations where convergence is weaker, bulges where stronger)
# rather than being a uniform blob.
weighted = np.zeros_like(basin_mask, dtype=np.float32)
weighted[basin_mask] = 0.3 + 0.7 * conv_grid[basin_mask]
volume_hi = zoom(weighted, up, order=1)
volume = gaussian_filter(volume_hi, sigma=0.8)
try:
with warnings.catch_warnings():
warnings.filterwarnings("ignore", category=RuntimeWarning)
iso = scene.visuals.Isosurface(
volume, level=0.45,
color=(*base_rgb.tolist(), 0.55),
shading='smooth',
parent=self._render_root,
)
iso.transform = STTransform(
scale=scale.tolist(),
translate=translate.tolist(),
)
iso.set_gl_state(
depth_test=True, cull_face=False, blend=True,
blend_func=('src_alpha', 'one_minus_src_alpha'),
)
iso.order = 1
self._attractor_clouds.append(iso)
except Exception as e:
# Fallback to point cloud if isosurface fails
print(f"[ATTRACTORS] Isosurface failed for A{i+1}, "
f"falling back to points: {e}")
indices = np.argwhere(basin_mask)
pts = np.zeros((len(indices), 3), dtype=np.float32)
for a in range(3):
pts[:, a] = (self.flow.axis_min[a]
+ indices[:, a] / (G - 1) * self.flow.span[a])
colors = np.empty((len(pts), 4), dtype=np.float32)
colors[:, :3] = base_rgb
colors[:, 3] = 0.30
cloud = ClusterPoint(point_size=6.0, parent=self._render_root)
cloud.order = 1
cloud.set_data(pts, colors)
self._attractor_clouds.append(cloud)
# Label — show relative strength (normalized so strongest = 100%)
label_text = f"A{i + 1} ({att['strength'] * 100:.0f}%)"
center = att['position'].copy()
center[2] += self.flow.span[2] * 0.06
label = scene.visuals.Text(
text=label_text, pos=center,
color=(1, 1, 1, 0.95),
font_size=self.ATTRACTOR_LABEL_SIZE,
bold=True,
parent=self._render_root,
)
label.order = 1
self._attractor_labels.append(label)
self._attractors_visible = True
print(f"[ATTRACTORS] Found {len(attractors)} attractor(s):")
for i, att in enumerate(attractors):
score_str = (f", score={att['mean_score']:.2f}"
if att['mean_score'] is not None else "")
print(f" A{i + 1}: pos=({att['position'][0]:.2f}, "
f"{att['position'][1]:.2f}, {att['position'][2]:.2f}), "
f"strength={att['strength']:.2f}, "
f"basin={att['basin_fraction']:.1%}, "
f"div={att['divergence']:.4f}{score_str}")
def _hide_attractors(self):
"""Remove attractor visuals from scene."""
for cloud in self._attractor_clouds:
cloud.parent = None
for label in self._attractor_labels:
label.parent = None
if self._attractor_highlight_border is not None:
self._attractor_highlight_border.parent = None
self._attractor_highlight_border = None
self._attractor_clouds.clear()
self._attractor_labels.clear()
self._attractors_visible = False
self._highlighted_attractor = None
def _on_attractor_click(self, event):
"""Click to highlight the nearest attractor or saved path.
Fires on mouse_release. Only acts on plain clicks (no drag/orbit)
so camera rotation is not affected. Always checks both attractors
and saved paths and picks whichever is closest in screen space so
paths inside/near attractors are still clickable.
"""
if event.button != 1:
return
# Only act on plain clicks — skip if user dragged (camera orbit)
if self._click_track_moved:
return
# Don't interfere with active gizmo drag
if self._gizmo_dragging is not None:
return
click = np.array([event.pos[0], event.pos[1]], dtype=np.float64)
# Distance to probe in screen space
probe_pos = self._probe_pos_from_sliders()
probe_sc = self._vispy_project(probe_pos)
probe_dist = float(np.linalg.norm(click - probe_sc))
# ── Find nearest attractor ──
att_idx = None
att_dist = float('inf')
if self._attractors_visible and self._attractor_data:
for i, att in enumerate(self._attractor_data):
sc = self._vispy_project(att['position'])
dist = float(np.linalg.norm(click - sc))
if dist < att_dist:
att_dist = dist
att_idx = i
# Cap: attractor must be within 200px
if att_dist > 200:
att_idx = None
att_dist = float('inf')
# ── Find nearest saved path ──
path_idx, path_dist = self._find_clicked_path(click, return_dist=True)
# ── Probe wins only when very close (<30px) AND closer than both ──
best_target_dist = min(att_dist, path_dist)
if probe_dist < 30 and probe_dist < best_target_dist * 0.5:
return
# ── Nothing close → deselect everything ──
if att_idx is None and path_idx is None:
if hasattr(self, '_explain_overlay'):
self._explain_overlay.setVisible(False)
self._set_highlighted_attractor(None)
self._highlighted_path = None
self._update_contextual_hint()
return
# ── Pick closest: path vs attractor ──
# Attractor meshes are large visual targets that users click "on",
# whereas path splines are thin lines. Give attractors a preference
# margin so clicking in the attractor mesh area selects the attractor
# even when a path spline passes through it. Only pick path when
# it is clearly closer than any attractor (by >30px margin).
if hasattr(self, '_explain_overlay'):
self._explain_overlay.setVisible(False)
ATTRACTOR_MARGIN = 30 # px — attractor wins unless path is 30px closer
if (path_idx is not None and att_idx is not None
and path_dist < att_dist - ATTRACTOR_MARGIN):
# Path is clearly closer — select path, deselect attractor
self._set_highlighted_attractor(None)
self._highlight_saved_path(path_idx)
elif att_idx is not None:
# Attractor wins (or tied / within margin) — select attractor
self._highlighted_path = None
self._set_highlighted_attractor(att_idx)
elif path_idx is not None:
# Only path available — select path
self._set_highlighted_attractor(None)
self._highlight_saved_path(path_idx)
def _set_highlighted_attractor(self, idx):
"""Highlight attractor with thick white contour lines around the mesh.
Extracts a wireframe from the isosurface mesh edges and renders
as thick white lines to clearly indicate selection.
"""
from scipy.ndimage import gaussian_filter, zoom
self._highlighted_attractor = idx
# Remove previous highlight visuals
if hasattr(self, '_attractor_highlight_border') and self._attractor_highlight_border is not None:
self._attractor_highlight_border.parent = None
self._attractor_highlight_border = None
if idx is not None and idx < len(self._attractor_data):
att = self._attractor_data[idx]
basin_mask = att['basin_mask']
G = self.flow.grid_size
# Build the same upsampled isosurface as in _compute_and_show_attractors
up = 3
G_up = (G - 1) * up + 1
scale = self.flow.span / (G_up - 1)
translate = self.flow.axis_min.copy()
# Convergence-weighted volume (same as main rendering)
vg = self.flow.velocity_grid
spd = np.linalg.norm(vg, axis=-1)
dvx_dx = np.gradient(vg[:, :, :, 0], axis=0)
dvy_dy = np.gradient(vg[:, :, :, 1], axis=1)
dvz_dz = np.gradient(vg[:, :, :, 2], axis=2)
div_g = dvx_dx + dvy_dy + dvz_dz
div_ref = max(float(np.percentile(
np.abs(div_g[spd > 1e-12]), 90)), 1e-8)
conv_g = np.clip(-div_g / div_ref, 0.0, 1.0)
weighted = np.zeros_like(basin_mask, dtype=np.float32)
weighted[basin_mask] = 0.3 + 0.7 * conv_g[basin_mask]
volume_hi = zoom(weighted, up, order=1)
volume = gaussian_filter(volume_hi, sigma=0.8)
# Extract mesh for the contour outline
with warnings.catch_warnings():
warnings.filterwarnings("ignore", category=RuntimeWarning)
try:
from skimage.measure import marching_cubes
verts, faces, _, _ = marching_cubes(volume, level=0.45)
except ImportError:
from vispy.geometry.isosurface import isosurface as _vispy_iso
verts, faces = _vispy_iso(volume, level=0.45)
if len(verts) > 0 and len(faces) > 0:
# Transform vertices from grid to world coordinates
world_verts = verts * scale[np.newaxis, :] + translate[np.newaxis, :]
# Extract unique edges from faces for wireframe
edges = set()
for f in faces:
for e in [(f[0], f[1]), (f[1], f[2]), (f[2], f[0])]:
edges.add((min(e), max(e)))
# Subsample edges for performance (keep ~2000 max)
edge_list = list(edges)
if len(edge_list) > 2000:
rng = np.random.default_rng(0)
indices = rng.choice(len(edge_list), 2000, replace=False)
edge_list = [edge_list[i] for i in indices]
# Build line segments: pairs of vertices
line_pts = np.zeros((len(edge_list) * 2, 3), dtype=np.float32)
for j, (a, b) in enumerate(edge_list):
line_pts[j * 2] = world_verts[a]
line_pts[j * 2 + 1] = world_verts[b]
connect = np.zeros(len(edge_list) * 2, dtype=bool)
for j in range(len(edge_list)):
connect[j * 2] = True # connect first to second in each pair
# connect[j*2+1] = False # break between pairs (already False)
border_vis = scene.visuals.Line(
pos=line_pts,
connect=connect,
color=(1.0, 1.0, 1.0, 0.85),
width=3.0,
parent=self._render_root,
)
border_vis.order = 0
self._attractor_highlight_border = border_vis
self._show_attractor_info(idx)
# Show cached explanation if available
cached_key = str(idx)
if cached_key in self._attractor_explanations:
self._show_explain(
self._attractor_explanations[cached_key]
+ "\n\n(Cached · Press Shift+E to re-explain)"
)
else:
# Clear attractor info — allow probe to update again
if hasattr(self, '_info_overlay'):
self._update_info(self._probe_pos_from_sliders())
def _get_attractor_colors(self):
"""Return list of (R,G,B) arrays, one per attractor, matching the
current flow color mode palette. Colors are evenly spaced across
the active colormap so attractors are always visually distinct even
when their physical values are similar."""
from tracescope.visualization.flow_field import turbo_colormap, diverging_colormap, score_colormap
n = len(self._attractor_data)
if n == 0:
return []
color_mode = getattr(self, '_flow_color_mode', 'speed')
# Evenly spaced parameter values so each attractor gets a distinct hue
t_vals = np.linspace(0.1, 0.9, n, dtype=np.float32) if n > 1 else np.array([0.5], dtype=np.float32)
if color_mode == 'entropy':
# Diverging colormap expects [-1, 1]
t_div = t_vals * 2.0 - 1.0
rgb = diverging_colormap(t_div).astype(np.float32)
elif color_mode == 'cluster':
# Assign each attractor the color of its nearest cluster centroid
colors_list = []
centroids = self._cluster_centroids
for att in self._attractor_data:
dists = np.linalg.norm(centroids - att['position'], axis=1)
nearest_c = int(np.argmin(dists))
colors_list.append(self._cluster_colors_arr[nearest_c].copy())
# If multiple attractors map to same cluster, shift them slightly
return colors_list
elif color_mode.startswith('score:'):
# Score colormap: red→green, use mean_score if available
score_vals = np.array([
att['mean_score'] if att['mean_score'] is not None else 0.5
for att in self._attractor_data
], dtype=np.float32)
# If scores are too similar, spread them for visual distinction
if n > 1 and (score_vals.max() - score_vals.min()) < 0.15:
score_vals = t_vals
rgb = score_colormap(score_vals).astype(np.float32)
else:
# Default: turbo colormap (velocity-like), evenly spaced
rgb = turbo_colormap(t_vals).astype(np.float32)
return [rgb[i] for i in range(n)]
def _refresh_attractor_colors(self):
"""Recolor existing attractor isosurfaces to match the current flow color mode.
Each attractor has ONE isosurface mesh (1:1 mapping with _attractor_data).
"""
if not self._attractors_visible or not self._attractor_clouds:
return
att_colors = self._get_attractor_colors()
for ai in range(len(self._attractor_data)):
if ai >= len(self._attractor_clouds):
break
base_rgb = att_colors[ai] if ai < len(att_colors) else np.array([0.5, 0.8, 1.0])
cloud = self._attractor_clouds[ai]
# Isosurface: update color via mesh_data
try:
cloud.color = (*base_rgb.tolist(), 0.45)
except Exception:
# Fallback for ClusterPoint (if isosurface failed)
pass
# Refresh highlight border if one is active
if self._highlighted_attractor is not None:
self._set_highlighted_attractor(self._highlighted_attractor)
def _show_attractor_info(self, idx):
"""Show detailed info about the highlighted attractor."""
if not hasattr(self, '_info_overlay'):
return
att = self._attractor_data[idx]
pos = att['position']
pts = self.result.projected_3d
axis_labels = getattr(self.result.axis_info, 'labels', ['X', 'Y', 'Z'])
lines = [f"— Attractor A{idx + 1} —"]
# Location as axis percentages
for i in range(3):
mn, mx = pts[:, i].min(), pts[:, i].max()
span = mx - mn
pct = ((pos[i] - mn) / span * 100) if span > 0 else 50
lines.append(f" {axis_labels[i]}: {pct:.0f}%")
# Strength and basin
lines.append(f" Strength: {att['strength']:.0%}")
lines.append(f" Basin: {att['basin_fraction']:.0%} of field")
lines.append(f" Divergence: {att['divergence']:.4f}")
# Score
if att['mean_score'] is not None:
score = att['mean_score']
interp = "positive" if score > 0.6 else "negative" if score < 0.4 else "neutral"
lines.append(f" Score: {score:.2f} ({interp})")
# Nearest data point — only one, and only if short enough to fit
_MAX_NEAREST_LEN = 70
dists = np.linalg.norm(pts - pos, axis=1)
for ni in np.argsort(dists)[:3]:
entry = self.result.session.entries[int(ni)]
if len(entry.text) <= _MAX_NEAREST_LEN:
lines.append("")
lines.append("— Nearest Point —")
lines.append(f" {entry.text}")
break
self._info_overlay.setText("\n".join(lines))
self._info_overlay.adjustSize()
self._update_contextual_hint()
self._reposition_overlays()
def _simulate_probe_to_attractor(self, start_pos, attractor_pos, n_marks=4,
max_steps=500):
"""Simulate a probe flowing from start_pos toward attractor_pos.
Returns a list of n_marks evenly-spaced waypoints along the trajectory,
including the starting point and ending near the attractor.
"""
if self.flow is None:
return [start_pos.copy()]
DT = self.flow.DT
speed_mult = self.flow.speed_multiplier
pos = start_pos.copy().astype(np.float32)
trajectory = [pos.copy()]
for _ in range(max_steps):
vel = self.flow.sample_velocity(float(pos[0]), float(pos[1]), float(pos[2]))
pos += vel * DT * speed_mult
trajectory.append(pos.copy())
# Stop if very close to attractor
if np.linalg.norm(pos - attractor_pos) < 0.3:
break
# Sample n_marks evenly spaced waypoints
trajectory = np.array(trajectory)
total = len(trajectory)
if total <= n_marks:
return list(trajectory)
indices = np.linspace(0, total - 1, n_marks, dtype=int)
return [trajectory[i] for i in indices]
def _find_distant_start_points(self, attractor_pos, basin_mask, n=3):
"""Find n starting positions far from the attractor that will converge to it.
Strategy: pick points from the data cloud that are far away from the
attractor center and spread in different angular directions.
"""
pts = self.result.projected_3d
center = attractor_pos
dists = np.linalg.norm(pts - center, axis=1)
# Get the far-away half of points
median_dist = np.median(dists)
far_mask = dists > median_dist
far_pts = pts[far_mask]
if len(far_pts) < n:
# Fallback: use the farthest n points
far_idx = np.argsort(-dists)[:n]
return [pts[idx].copy() for idx in far_idx]
# Spread angular directions: pick points far from each other
# Start with the farthest point
selected = []
far_dists = dists[far_mask]
candidates = far_pts.copy()
cand_dists = far_dists.copy()
# First: farthest from attractor
best = np.argmax(cand_dists)
selected.append(candidates[best].copy())
for _ in range(n - 1):
# Pick the candidate that maximizes minimum distance to all selected
min_dists = np.full(len(candidates), np.inf)
for sel in selected:
d = np.linalg.norm(candidates - sel, axis=1)
min_dists = np.minimum(min_dists, d)
# Also weight by distance from attractor to avoid picking nearby points
score = min_dists * (cand_dists / cand_dists.max())
best = np.argmax(score)
selected.append(candidates[best].copy())
return selected
def _explain_highlighted_attractor(self, deep=False, force=False):
"""Generate LLM explanation for the currently highlighted attractor.
Args:
deep: If True, runs the full multi-stage process.
force: If True, ignores cached explanation and regenerates.
"""
if self._highlighted_attractor is None:
return
if self._explainer is None:
self._show_explain("No explainer configured.\nPass explainer= to launch_renderer().")
return
idx = self._highlighted_attractor
# Show cached explanation if available (unless forcing re-explain)
cached_key = str(idx)
if not force and cached_key in self._attractor_explanations:
cached = self._attractor_explanations[cached_key]
self._show_explain(cached + "\n\n(Cached · Press Shift+E to re-explain)")
return
att = self._attractor_data[idx]
pos = att['position']
debug = getattr(self, '_debug_prompts', False)
self._explain_pending_attractor_idx = idx
if deep:
self._show_explain(
f"Explaining attractor A{idx + 1}...\n\n"
"Stage 1/3: Simulating convergence probes..."
)
else:
self._show_explain(f"Explaining attractor A{idx + 1}...")
# Pre-compute context on main thread (fast)
pts = self.result.projected_3d
axis_labels = getattr(self.result.axis_info, 'labels', ['X', 'Y', 'Z'])
# Axis percentages
axis_pcts = []
for i in range(3):
mn, mx = pts[:, i].min(), pts[:, i].max()
span = mx - mn
pct = int((pos[i] - mn) / span * 100) if span > 0 else 50
axis_pcts.append(pct)
# Cluster distances
cluster_distances = []
centroids = self.result.cluster_centroids_3d
max_dist = self.result.max_cluster_distance
if centroids is not None and max_dist > 0:
for ci in range(len(centroids)):
d = float(np.linalg.norm(pos - centroids[ci]))
closeness = max(0, int((1.0 - d / max_dist) * 100))
label = (self.result.cluster_labels[ci]
if ci < len(self.result.cluster_labels)
else f"Cluster {ci}")
cluster_distances.append((label, closeness))
# Nearest texts
dists = np.linalg.norm(pts - pos, axis=1)
nearest_idxs = np.argsort(dists)[:5]
nearest_texts = [self.result.session.entries[ni].text for ni in nearest_idxs]
# Score context
score_info = None
active_score = getattr(self, '_flow_color_mode', 'speed')
if active_score.startswith('score:') and att['mean_score'] is not None:
ch = active_score[len('score:'):]
raw = att['mean_score']
interp = "positive" if raw > 0.6 else "negative" if raw < 0.4 else "neutral"
score_info = {"channel": ch, "mean_score_raw": raw, "interpretation": interp}
strength = att['strength']
basin_fraction = att['basin_fraction']
divergence = att['divergence']
# Deep mode: find 3 distant starting points + simulate trajectories
trajectories = []
if deep:
start_points = self._find_distant_start_points(pos, att['basin_mask'], n=3)
for sp in start_points:
waypoints = self._simulate_probe_to_attractor(sp, pos, n_marks=4)
trajectories.append(waypoints)
def _run():
try:
trajectory_explanations = None
if deep:
# Stage 2: Explain each convergence trajectory
self._explain_pending_stage = "Stage 2/3: Explaining convergence trajectories..."
trajectory_explanations = []
for ti, waypoints in enumerate(trajectories):
self._explain_pending_stage = (
f"Stage 2/3: Explaining trajectory {ti + 1}/3..."
)
# Build control points for path explain
cp_for_llm = []
for wp in waypoints:
info = probe_point(self.result, float(wp[0]), float(wp[1]), float(wp[2]))
pcts = info["axis_percentages"]
cdists = info["cluster_distances"]
cp_for_llm.append({
"axis_pcts": [int(v) for v in pcts.values()],
"cluster_distances": [(k, int(v)) for k, v in cdists.items()],
})
traj_text = self._explainer.explain_probe_multi(
axis_labels=axis_labels,
control_points=cp_for_llm,
debug=debug,
)
trajectory_explanations.append(traj_text)
if debug:
print(f"[DEBUG] Trajectory {ti+1} explanation: {traj_text}")
# Final attractor explanation (with or without trajectory context)
if deep:
self._explain_pending_stage = "Stage 3/3: Generating attractor explanation..."
text = self._explainer.explain_attractor(
axis_labels=axis_labels,
axis_pcts=axis_pcts,
cluster_distances=cluster_distances,
nearest_texts=nearest_texts,
strength=strength,
basin_fraction=basin_fraction,
divergence=divergence,
score_info=score_info,
trajectory_explanations=trajectory_explanations,
debug=debug,
)
explanation = f"Attractor A{idx + 1} Explanation:\n\n{text}"
if score_info:
explanation += (f"\n\nScore ({score_info['channel']}): "
f"{score_info['mean_score_raw']:.2f} "
f"({score_info['interpretation']})")
self._explain_pending = explanation
except Exception as e:
import traceback
traceback.print_exc()
self._explain_pending = f"Explain error: {e}"
thread = threading.Thread(target=_run, daemon=True)
thread.start()
def _qt_blob_toggle(self, checked):
if self.flow is not None:
self.flow.blob_enabled = checked
# Reinit particles when toggling blob
if self.flow._blob_opacity is not None:
self.flow.set_particle_grid(self.flow.particle_grid)
def _qt_flow_opacity(self, value, label):
self._flow_opacity = value / 100.0
label.setText(f"Opacity: {value}%")
def _qt_flow_speed(self, value, label):
speed = value / 100.0
label.setText(f"Speed: {speed:.1f}x")
if self.flow is not None:
self.flow.speed_multiplier = speed
def _qt_particle_count(self, value, label):
count = value ** 3
label.setText(f"Particles: {count:,} ({value}\u00b3)")
self._particle_grid = value
if self.flow is not None:
self.flow.set_particle_grid(value)
self._flow_rgba = np.empty((self.flow.particle_count, 4), dtype=np.float32)
def _qt_spline_path(self, checked):
self._spline_path = checked
self._sync_path_visibility()
def _qt_entropy_colors(self, checked):
if checked:
self._flow_color_mode = 'entropy'
self._chk_cluster_colors.setChecked(False)
elif self._flow_color_mode == 'entropy':
self._flow_color_mode = 'speed'
self._refresh_attractor_colors()
def _qt_cluster_colors(self, checked):
if checked:
self._flow_color_mode = 'cluster'
self._chk_entropy.setChecked(False)
for _, chk in getattr(self, '_score_color_checkboxes', []):
chk.setChecked(False)
elif self._flow_color_mode == 'cluster':
self._flow_color_mode = 'speed'
self._refresh_attractor_colors()
def _qt_score_colors(self, channel, checked):
if checked:
self._flow_color_mode = f'score:{channel}'
self._chk_entropy.setChecked(False)
self._chk_cluster_colors.setChecked(False)
for ch, chk in getattr(self, '_score_color_checkboxes', []):
if ch != channel:
chk.setChecked(False)
# Precompute score grid for fast per-frame sampling
if self.flow is not None:
self._precompute_score_grid(channel)
elif self._flow_color_mode == f'score:{channel}':
self._flow_color_mode = 'speed'
self._refresh_attractor_colors()
def _gather_scores_normalized(self, channel: str) -> np.ndarray:
"""Gather per-entry score values and normalize to [0, 1].
Raw scores can have arbitrary ranges (e.g. reliability 1–5,
error_rate 0–0.3). We use percentile-based normalization
(5th–95th percentile) rather than min-max so that skewed
distributions with outliers still produce a meaningful color
spread instead of collapsing most points to one end of the
colormap. Binary data (only 2 unique values) falls back to
min-max so that the two values map cleanly to 0 and 1.
"""
entry_scores = self.result.get_entry_scores(channel)
path_score_map = self.result.get_path_scores(channel)
raw = np.array([
(entry_scores[i] if entry_scores[i] is not None
else path_score_map.get(self.result.session.entries[i].path_id)
if self.result.session.entries[i].path_id is not None else None)
for i in range(len(self.result.projected_3d))
], dtype=object)
# Convert to float, replacing None with NaN
vals = np.array([float(v) if v is not None else np.nan for v in raw],
dtype=np.float32)
# Normalize to [0, 1] — use percentile clipping for graded
# distributions, min-max for binary so the two values stay at
# the extremes of the colormap.
valid = ~np.isnan(vals)
if valid.any():
valid_vals = vals[valid]
unique_count = len(np.unique(valid_vals))
if unique_count <= 2:
# Binary: preserve 0/1 extremes
lo = float(valid_vals.min())
hi = float(valid_vals.max())
else:
# Graded: clip to 5-95 percentile so outliers don't
# squash the main distribution against one color
lo = float(np.percentile(valid_vals, 5))
hi = float(np.percentile(valid_vals, 95))
if hi - lo > 1e-8:
vals[valid] = np.clip(
(valid_vals - lo) / (hi - lo), 0.0, 1.0
)
else:
vals[valid] = 0.5 # all same value → neutral
vals[~valid] = 0.5 # missing → neutral
return vals
def _precompute_score_grid(self, channel: str):
"""Build the score grid on the flow system for fast particle coloring."""
data_pts = self.result.projected_3d
data_scores = self._gather_scores_normalized(channel)
self.flow.build_score_grid(data_pts, data_scores)
def _qt_score_point_coloring(self, channel, checked):
if checked:
self._point_color_mode = f'score:{channel}'
for ch, chk in getattr(self, '_score_point_checkboxes', []):
if ch != channel:
chk.setChecked(False)
self._apply_score_point_colors(channel)
else:
if getattr(self, '_point_color_mode', 'cluster') == f'score:{channel}':
self._point_color_mode = 'cluster'
self._setup_cluster_data()
def _apply_score_point_colors(self, channel):
from tracescope.visualization.flow_field import score_colormap
pts = np.ascontiguousarray(self.result.projected_3d, dtype=np.float32)
normalized = self._gather_scores_normalized(channel)
rgb = score_colormap(normalized).astype(np.float32)
colors = np.ones((len(pts), 4), dtype=np.float32)
colors[:, :3] = rgb
self.vis_clusters.set_data(pts, colors)
# ═══════════════════════════════════════════════════
# Qt signal handlers
# ═══════════════════════════════════════════════════
def _qt_flow_toggle(self, checked):
self.flow_active = checked
self.vis_flow.visible = checked
self._sync_path_visibility() # update path transparency
def _qt_ball_toggle(self, checked):
self.ball_flowing = checked
if self.flow is not None:
if checked:
self._auto_mark_start_point()
self.flow.start_ball_flow()
self._show_gizmo(False)
else:
self.flow.stop_ball_flow()
self.vis_ball.visible = False
self.vis_trail.visible = False
if hasattr(self, '_gizmo_hint'):
self._gizmo_hint.setVisible(not checked)
self._update_contextual_hint()
def _auto_mark_start_point(self):
"""Add the current probe position as a control point (skip if duplicate)."""
pos = self._probe_pos_from_sliders()
if self._control_points:
last = self._control_points[-1]
if float(np.linalg.norm(pos - last)) < 1e-4:
return
self._control_points.append(pos.copy())
self._refresh_control_points()
def _qt_path_toggle(self, checked):
self.show_path = checked
self._sync_path_visibility()
def _qt_points_toggle(self, checked):
self.show_points = checked
self.vis_clusters.visible = checked
def _qt_slider_changed(self, axis, value):
if self._updating_sliders:
return
labels = getattr(self.result.axis_info, 'labels', ['X', 'Y', 'Z'])
self._slider_labels[axis].setText(f"{labels[axis]}: {value / 10:.0f}%")
pos = self._probe_pos_from_sliders()
self.vis_probe.set_data(pos.reshape(1, 3), self.PROBE_COLOR)
if self._gizmo_visible:
self._update_gizmo(pos)
if self.flow is not None and (not self.ball_flowing or self._manual_slider_override):
self.flow.set_ball_position(*pos)
self._update_info(pos)
def _qt_mark(self):
pos = self._probe_pos_from_sliders()
self._control_points.append(pos.copy())
self._refresh_control_points()
def _qt_clear(self):
self._control_points.clear()
self._refresh_control_points()
def _qt_explain(self):
if self._explainer is None:
self._show_explain("No explainer configured.\nPass explainer= to launch_renderer().")
return
# Stop ball flow so probe stays put during explanation
if self.ball_flowing:
self.ball_flowing = False
if self.flow is not None:
self.flow.stop_ball_flow()
self.vis_ball.visible = False
self.vis_trail.visible = False
if hasattr(self, 'chk_ball'):
self.chk_ball.setChecked(False)
if hasattr(self, '_gizmo_hint'):
self._gizmo_hint.setVisible(True)
pos = self._probe_pos_from_sliders()
px, py, pz = float(pos[0]), float(pos[1]), float(pos[2])
control_points = list(self._control_points) # snapshot
# Include current probe position if no marks yet
if not control_points:
control_points = [pos.copy()]
self._show_explain("Generating explanation...")
self._explain_pending = None # will be set by background thread
self._explain_pending_path_points = [p.copy() for p in control_points]
def _run():
import logging
logger = logging.getLogger(__name__)
try:
if len(control_points) > 1:
text = self._build_multi_explain()
else:
info = probe_with_explanation(
self.result, self._explainer, px, py, pz)
lines = [f"LLM Explanation:\n{info['explanation']}\n"]
lines.append("Nearest messages:")
for item in info["nearest_texts"][:3]:
lines.append(f" [{item['role']}] {item['text'][:100]}...")
text = "\n".join(lines)
logger.info("Explain completed successfully")
self._explain_pending = text
except Exception as e:
logger.error(f"Explain failed: {e}", exc_info=True)
self._explain_pending = f"Explain error: {e}"
self._explain_pending_path_points = None # don't save on error
thread = threading.Thread(target=_run, daemon=True)
thread.start()
def _show_hint(self, text: str):
"""Show a centered orange hint on the canvas. Hide if text is empty."""
if not hasattr(self, '_hint_overlay'):
return
if not text:
self._hint_overlay.setVisible(False)
return
self._hint_overlay.setText(text)
self._hint_overlay.adjustSize()
self._hint_overlay.setVisible(True)
self._reposition_overlays()
def _update_contextual_hint(self):
"""Pick the right hint based on current probe / flow / attractor state."""
if not hasattr(self, '_hint_overlay'):
return
# Highlighted saved path
if self._highlighted_path is not None:
self._show_hint(
"Press Delete to remove this path · "
"Click elsewhere to deselect"
)
return
# Attractor highlighted takes priority
if self._attractors_visible and self._highlighted_attractor is not None:
idx = self._highlighted_attractor
cached = str(idx) in self._attractor_explanations
if cached:
self._show_hint(
"Press E to show explanation · "
"Shift+E to re-explain"
)
else:
self._show_hint(
"Press E to explain · "
"Shift+E for deeper explanation (slower)"
)
return
# Probe being dragged by flow
if self.ball_flowing and self._has_flow:
if getattr(self, '_ball_is_stuck', False):
self._show_hint("Click on the probe to move it")
else:
self._show_hint("Press M to mark point · Press E to explain path")
return
# Gizmo visible → how to drive it + how to resume
if self._gizmo_visible:
self._show_hint(
"Drag the arrows to move the probe · "
"Press Space or enable 'Drag probe by the flow' to resume"
)
return
# Ball flow off, gizmo not visible → how to start editing
if self._has_flow and not self.ball_flowing:
self._show_hint(
"Click on the probe to move it · "
"Press Space or enable 'Drag probe by the flow' to resume"
)
return
self._hint_overlay.setVisible(False)
def _show_explain(self, text: str):
"""Show text in both the sidebar panel and the canvas overlay."""
if hasattr(self, '_explain_text'):
self._explain_text.setPlainText(text)
self._explain_group.setVisible(True)
# Also show on canvas overlay (bold, bottom-center)
if hasattr(self, '_explain_overlay'):
self._explain_full_text = text
# Truncate for overlay display (max ~300 chars)
display = text
if len(display) > 300:
display = display[:300] + "… (click to expand)"
self._explain_overlay.setText(display)
self._explain_overlay.adjustSize()
self._explain_overlay.setVisible(True)
self._reposition_overlays()
def _open_explain_fullscreen(self):
"""Open the full explanation in a large modal dialog with scroll."""
if not hasattr(self, '_explain_full_text') or not self._explain_full_text:
self._explain_overlay.setVisible(False)
return
dlg = QtWidgets.QDialog(self.window)
dlg.setWindowTitle("Explanation")
# Size ~80% of screen so the dialog is large regardless of window size
screen_geo = None
try:
screen_geo = QtWidgets.QApplication.primaryScreen().availableGeometry()
except Exception:
pass
if screen_geo is not None:
dlg_w = int(screen_geo.width() * 0.65)
dlg_h = int(screen_geo.height() * 0.65)
elif self.window is not None:
ws = self.window.size()
dlg_w = int(ws.width() * 0.7)
dlg_h = int(ws.height() * 0.7)
else:
dlg_w, dlg_h = 900, 650
dlg.resize(dlg_w, dlg_h)
# Scale font with dialog height so text stays readable at any size
base_font_px = max(20, min(28, int(dlg_h * 0.038)))
btn_font_px = max(16, base_font_px - 2)
dlg.setStyleSheet(
"QDialog { background: #1E1E1E; } "
"QLabel { background: transparent; color: #E0E0E0; "
f"font-family: Consolas, monospace; font-size: {base_font_px}px; "
"line-height: 1.5; } "
"QScrollArea { background: #1E1E1E; border: none; } "
"QPushButton { background: #FF6B35; color: white; border: none; "
f"border-radius: 4px; padding: 10px 22px; font-size: {btn_font_px}px; "
"} QPushButton:hover { background: #FF8555; }"
)
lay = QtWidgets.QVBoxLayout(dlg)
lay.setContentsMargins(0, 0, 0, 0)
lay.setSpacing(0)
# Scrollable text area
scroll = QtWidgets.QScrollArea()
scroll.setWidgetResizable(True)
scroll.setHorizontalScrollBarPolicy(QtCore.Qt.ScrollBarAlwaysOff)
text_label = QtWidgets.QLabel(self._explain_full_text)
text_label.setWordWrap(True)
text_label.setContentsMargins(28, 24, 28, 24)
text_label.setTextInteractionFlags(
QtCore.Qt.TextSelectableByMouse | QtCore.Qt.TextSelectableByKeyboard
)
scroll.setWidget(text_label)
lay.addWidget(scroll, stretch=1)
btn_row = QtWidgets.QHBoxLayout()
btn_row.setContentsMargins(12, 8, 12, 12)
btn_row.addStretch()
btn_close = QtWidgets.QPushButton("Close")
btn_close.clicked.connect(dlg.accept)
btn_row.addWidget(btn_close)
lay.addLayout(btn_row)
dlg.exec_()
def _build_multi_explain(self) -> str:
"""Build multi-point path explanation via LLM."""
all_pcts = []
all_dists = []
axis_labels = None
for cp in self._control_points:
info = probe_point(self.result, cp[0], cp[1], cp[2])
pcts = info["axis_percentages"]
dists = info["cluster_distances"]
if axis_labels is None:
axis_labels = list(pcts.keys())
all_pcts.append(list(pcts.values()))
all_dists.append(dists)
control_points_for_llm = []
for pcts_vals, dists_dict in zip(all_pcts, all_dists):
control_points_for_llm.append({
"axis_pcts": [int(v) for v in pcts_vals],
"cluster_distances": [(k, int(v)) for k, v in dists_dict.items()],
})
# Gather score context at each control point (if scores exist)
score_context = None
channels = self.result.score_channels
if channels:
score_context = []
pts = self.result.projected_3d
for cp in self._control_points:
probe = np.array([cp[0], cp[1], cp[2]])
dists_to_data = np.linalg.norm(pts - probe, axis=1)
# Weighted average of nearby scores (5 nearest points)
nearest_5 = np.argsort(dists_to_data)[:5]
cp_scores = {}
for ch in channels:
vals = []
for idx in nearest_5:
entry = self.result.session.entries[idx]
s = entry.scores.get(ch)
if s is None and entry.path_id is not None:
s = self.result.session.path_scores.get(
entry.path_id, {}).get(ch)
if s is not None:
vals.append(s)
if vals:
cp_scores[ch] = round(sum(vals) / len(vals), 2)
score_context.append(cp_scores)
explanation = self._explainer.explain_probe_multi(
axis_labels=axis_labels,
control_points=control_points_for_llm,
score_context=score_context,
)
return explanation
# ═══════════════════════════════════════════════════
# Persistent explained paths & attractor explanations
# ═══════════════════════════════════════════════════
def _explanations_cache_path(self):
"""Return base path for explanation cache files, or None."""
cp = getattr(self.result, 'cache_path', None)
return cp
def _load_saved_paths(self):
"""Load saved explained paths from cache."""
import json
cp = self._explanations_cache_path()
if cp is None:
return
path = f"{cp}_explained_paths.json"
try:
with open(path, 'r', encoding='utf-8') as f:
self._saved_paths = json.load(f)
# Convert control_points back to numpy arrays
for sp in self._saved_paths:
sp['control_points'] = [np.array(p, dtype=np.float32)
for p in sp['control_points']]
except (FileNotFoundError, json.JSONDecodeError):
self._saved_paths = []
def _save_paths_to_cache(self):
"""Persist saved paths to JSON cache."""
import json
cp = self._explanations_cache_path()
if cp is None:
return
path = f"{cp}_explained_paths.json"
data = []
for sp in self._saved_paths:
data.append({
'control_points': [p.tolist() for p in sp['control_points']],
'explanation': sp['explanation'],
})
with open(path, 'w', encoding='utf-8') as f:
json.dump(data, f, indent=2)
def _load_attractor_explanations(self):
"""Load cached attractor explanations."""
import json
cp = self._explanations_cache_path()
if cp is None:
return
path = f"{cp}_attractor_explanations.json"
try:
with open(path, 'r', encoding='utf-8') as f:
self._attractor_explanations = json.load(f)
except (FileNotFoundError, json.JSONDecodeError):
self._attractor_explanations = {}
def _save_attractor_explanations_to_cache(self):
"""Persist attractor explanations to JSON cache."""
import json
cp = self._explanations_cache_path()
if cp is None:
return
path = f"{cp}_attractor_explanations.json"
with open(path, 'w', encoding='utf-8') as f:
json.dump(self._attractor_explanations, f, indent=2)
def _add_saved_path(self, control_points, explanation):
"""Save an explained path and render it."""
self._saved_paths.append({
'control_points': [p.copy() for p in control_points],
'explanation': explanation,
})
self._save_paths_to_cache()
self._render_saved_path(len(self._saved_paths) - 1)
self._update_paths_button()
def _render_saved_path(self, idx):
"""Create visuals for one saved path."""
sp = self._saved_paths[idx]
pts = np.array(sp['control_points'], dtype=np.float32)
# Cycle through distinct colors for saved paths
PATH_COLORS = [
(0.2, 0.8, 1.0, 0.9), # cyan
(0.2, 1.0, 0.4, 0.9), # green
(1.0, 0.6, 0.2, 0.9), # orange
(0.8, 0.4, 1.0, 0.9), # purple
(1.0, 1.0, 0.2, 0.9), # yellow
(1.0, 0.4, 0.6, 0.9), # pink
]
color = PATH_COLORS[idx % len(PATH_COLORS)]
# Markers at control points
markers = ClusterPoint(point_size=8.0, parent=self._render_root)
markers.order = 2
marker_colors = np.tile(np.array(color, dtype=np.float32), (len(pts), 1))
markers.set_data(pts, marker_colors)
markers.visible = self._saved_paths_visible
# Spline line
line_vis = None
if len(pts) >= 2:
spline = catmull_rom_spline(pts, 10).astype(np.float32)
line_vis = scene.visuals.Line(
pos=spline, color=color, width=3,
parent=self._render_root, antialias=True,
)
line_vis.order = 2
line_vis.visible = self._saved_paths_visible
# Path label at midpoint
mid_idx = len(pts) // 2
mid = pts[mid_idx].copy()
mid[2] += self.flow.span[2] * 0.04 if self.flow else 0.2
label = scene.visuals.Text(
text=f"P{idx + 1}", pos=mid,
color=color[:3] + (0.95,),
font_size=self.ATTRACTOR_LABEL_SIZE * 0.8,
bold=True, parent=self._render_root,
)
label.order = 2
label.visible = self._saved_paths_visible
self._saved_path_visuals.append({
'markers': markers,
'line': line_vis,
'label': label,
'color': color,
})
def _render_all_saved_paths(self):
"""Render all loaded saved paths."""
self._clear_saved_path_visuals()
for i in range(len(self._saved_paths)):
self._render_saved_path(i)
self._update_paths_button()
def _clear_saved_path_visuals(self):
"""Remove all saved path visuals from scene."""
for vis in self._saved_path_visuals:
vis['markers'].parent = None
if vis['line']:
vis['line'].parent = None
vis['label'].parent = None
self._saved_path_visuals.clear()
self._highlighted_path = None
def _toggle_saved_paths_visibility(self):
"""Show/hide all saved path visuals."""
self._saved_paths_visible = not self._saved_paths_visible
for vis in self._saved_path_visuals:
vis['markers'].visible = self._saved_paths_visible
if vis['line']:
vis['line'].visible = self._saved_paths_visible
vis['label'].visible = self._saved_paths_visible
self._update_paths_button()
def _update_paths_button(self):
"""Update the paths toggle button text."""
if not hasattr(self, '_btn_toggle_paths'):
return
n = len(self._saved_paths)
if n == 0:
self._btn_toggle_paths.setVisible(False)
return
self._btn_toggle_paths.setVisible(True)
vis = "Hide" if self._saved_paths_visible else "Show"
self._btn_toggle_paths.setText(f"{vis} {n} Saved Path(s)")
def _highlight_saved_path(self, idx):
"""Highlight a saved path and show its explanation."""
# Unhighlight previous
if self._highlighted_path is not None and self._highlighted_path < len(self._saved_path_visuals):
vis = self._saved_path_visuals[self._highlighted_path]
vis['markers'].set_gl_state(depth_test=True)
if vis['line']:
vis['line'].set_gl_state(depth_test=True)
self._highlighted_path = idx
if idx is not None and idx < len(self._saved_path_visuals):
vis = self._saved_path_visuals[idx]
# Make markers bigger for highlight
sp = self._saved_paths[idx]
pts = np.array(sp['control_points'], dtype=np.float32)
white = np.ones((len(pts), 4), dtype=np.float32)
vis['markers'].set_data(pts, white)
# Show explanation
self._show_explain(f"Path P{idx + 1} Explanation:\n\n{sp['explanation']}")
self._update_contextual_hint()
# Reposition so hint stacks above the explain overlay
self._reposition_overlays()
else:
self._highlighted_path = None
def _delete_highlighted_path(self):
"""Delete the currently highlighted saved path."""
if self._highlighted_path is None:
return
idx = self._highlighted_path
# Remove visuals
if idx < len(self._saved_path_visuals):
vis = self._saved_path_visuals[idx]
vis['markers'].parent = None
if vis['line']:
vis['line'].parent = None
vis['label'].parent = None
# Remove from lists
if idx < len(self._saved_paths):
self._saved_paths.pop(idx)
if idx < len(self._saved_path_visuals):
self._saved_path_visuals.pop(idx)
self._highlighted_path = None
self._save_paths_to_cache()
# Re-render all paths (to fix indices/labels)
self._render_all_saved_paths()
# Hide explanation
if hasattr(self, '_explain_overlay'):
self._explain_overlay.setVisible(False)
self._show_hint("")
def _find_clicked_path(self, click_pos, return_dist=False):
"""Find which saved path is nearest to a screen click position.
Returns path index or None. When *return_dist* is True, returns
(index, distance) tuple — (None, inf) when nothing found."""
if not self._saved_paths or not self._saved_paths_visible:
return (None, float('inf')) if return_dist else None
best_idx = None
best_dist = 60 # max 60px click distance
try:
for i, sp in enumerate(self._saved_paths):
pts = np.array(sp['control_points'], dtype=np.float32)
if len(pts) >= 2:
spline = catmull_rom_spline(pts, 20).astype(np.float32)
else:
spline = pts
# Project to screen (apply scene scale like _vispy_project)
s = self._scene_scale
scaled = spline * np.array([s, s, s], dtype=np.float32)
pts_h = np.hstack([scaled, np.ones((len(scaled), 1))]).astype(np.float32)
mapped = self.view.scene.transform.map(pts_h)
w_vals = mapped[:, 3:4]
w_vals = np.where(np.abs(w_vals) < 1e-8, 1.0, w_vals)
screen = mapped[:, :2] / w_vals
# Point-to-segment distance along the spline
min_d = float('inf')
for j in range(len(screen) - 1):
d = self._point_to_segment_dist_2d(
click_pos, screen[j], screen[j + 1])
if d < min_d:
min_d = d
if min_d < best_dist:
best_dist = min_d
best_idx = i
except Exception:
pass
if return_dist:
return (best_idx, best_dist if best_idx is not None else float('inf'))
return best_idx
# ═══════════════════════════════════════════════════
# Helpers
# ═══════════════════════════════════════════════════
def _slider_to_raw(self, val, axis):
pts = self.result.projected_3d
mn, mx = pts[:, axis].min(), pts[:, axis].max()
return mn + (val / 1000.0) * (mx - mn)
def _raw_to_slider(self, raw, axis):
pts = self.result.projected_3d
mn, mx = pts[:, axis].min(), pts[:, axis].max()
span = mx - mn
if span == 0:
return 500
return int(np.clip((raw - mn) / span * 1000, 0, 1000))
def _probe_pos_from_sliders(self):
return np.array([
self._slider_to_raw(self._sliders[i].value(), i) for i in range(3)
], dtype=np.float32)
def _sync_sliders_to_ball(self, bp):
"""Push ball position into sliders without triggering callbacks."""
self._updating_sliders = True
labels = getattr(self.result.axis_info, 'labels', ['X', 'Y', 'Z'])
for i in range(3):
sv = self._raw_to_slider(bp[i], i)
self._sliders[i].setValue(sv)
self._slider_labels[i].setText(f"{labels[i]}: {sv / 10:.0f}%")
self._updating_sliders = False
def _update_info(self, pos):
if not hasattr(self, '_info_overlay'):
return
# Don't overwrite attractor info — it has priority
if self._highlighted_attractor is not None:
return
try:
info = probe_point(self.result, float(pos[0]), float(pos[1]), float(pos[2]))
lines = []
# Warn if probe is outside the semantic blob
if self.flow is not None and self.flow.is_outside_blob(
float(pos[0]), float(pos[1]), float(pos[2])):
lines.append("!! OUTSIDE SEMANTIC REGION !!")
lines.append("(sparse data — flow may be unreliable)")
lines.append("")
lines.append("— Probe Location —")
for name, pct in info['axis_percentages'].items():
lines.append(f" {name}: {pct:.1f}%")
lines.append("")
lines.append("— Distance to Clusters —")
for name, d in info['cluster_distances'].items():
lines.append(f" {name}: {d:.1f}%")
self._info_overlay.setText("\n".join(lines))
self._info_overlay.adjustSize()
self._reposition_overlays()
except Exception:
pass
def _refresh_control_points(self):
if not self._control_points:
self.vis_markers.visible = False
self.vis_marked_path.visible = False
return
pts = np.array(self._control_points, dtype=np.float32)
white = np.ones((len(pts), 4), dtype=np.float32)
self.vis_markers.set_data(pts, white)
self.vis_markers.visible = True
if len(pts) >= 2:
spline = catmull_rom_spline(pts, 10).astype(np.float32)
self.vis_marked_path.set_data(pos=spline, color=(1.0, 0.5, 0.2, 0.8))
self.vis_marked_path.visible = True
else:
self.vis_marked_path.visible = False
# ═══════════════════════════════════════════════════
# Animation loop
# ═══════════════════════════════════════════════════
def _on_timer(self, event):
now = event.elapsed
dt = now - self._last_time if self._last_time is not None else 1.0 / 60
self._last_time = now
self._frame_count += 1
# Compensate for variable frame rate: if frames arrive slower than
# 60 Hz, scale the physics step proportionally so animation speed
# stays consistent regardless of window size or GPU/DWM throttling.
dt_scale = min(4.0, dt * 60.0) # cap at 4x to avoid huge jumps
# Check for async explain stage update (intermediate progress)
stage = getattr(self, '_explain_pending_stage', None)
if stage is not None:
self._explain_pending_stage = None
self._show_explain(f"Explaining attractor...\n\n{stage}")
# Check for async explain result (final)
pending = getattr(self, '_explain_pending', None)
if pending is not None:
self._explain_pending = None
self._explain_pending_stage = None
self._show_explain(pending)
# Save explained path if this was a path explanation (not error)
path_pts = getattr(self, '_explain_pending_path_points', None)
if path_pts is not None and not pending.startswith("Explain error:"):
self._explain_pending_path_points = None
self._add_saved_path(path_pts, pending)
# Clear control points so next marking starts fresh
self._control_points.clear()
self._refresh_control_points()
# Save attractor explanation if this was an attractor explain
att_idx = getattr(self, '_explain_pending_attractor_idx', None)
if att_idx is not None and not pending.startswith("Explain error:"):
self._explain_pending_attractor_idx = None
self._attractor_explanations[str(att_idx)] = pending
self._save_attractor_explanations_to_cache()
# --- Auto-rotation disabled (kept for future use) ---
# if self.auto_rotate:
# cam = self.view.camera
# cam.azimuth = (cam.azimuth or 0) + self.AUTO_ROTATE_SPEED * dt
# Flow step (uses pre-allocated buffer for performance)
if self.flow_active and self.flow is not None:
pos, colors, alphas, speeds = self.flow.step(dt_scale=dt_scale)
# Color mode selection
color_mode = getattr(self, '_flow_color_mode', 'speed')
if color_mode == 'entropy':
from tracescope.visualization.flow_field import diverging_colormap
max_speed = speeds.max() if speeds.max() > 0 else 1.0
t = (speeds / max_speed) * 2.0 - 1.0
colors = diverging_colormap(t).astype(np.float32)
elif color_mode == 'cluster':
# Color by inverse-distance-weighted blend of cluster colors.
# Uses squared distances (avoids sqrt) and einsum to
# reduce allocations on the hot path.
centroids = self._cluster_centroids # (K, 3)
diff = pos[:, None, :] - centroids[None, :, :] # (N, K, 3)
dist_sq = np.einsum('nkd,nkd->nk', diff, diff) # (N, K)
eps = 1e-12
inv_dists = 1.0 / (dist_sq + eps) ** 1.5 # power 3 on dist
weights = inv_dists / inv_dists.sum(axis=1, keepdims=True)
colors = (weights @ self._cluster_colors_arr).astype(np.float32)
elif color_mode.startswith('score:'):
# Color flow particles by precomputed score grid (fast)
from tracescope.visualization.flow_field import score_colormap
particle_scores = self.flow.sample_score_batch(pos)
colors = score_colormap(particle_scores).astype(np.float32)
rgba = self._flow_rgba
if rgba is None or len(rgba) != len(pos):
rgba = np.empty((len(pos), 4), dtype=np.float32)
self._flow_rgba = rgba
rgba[:, :3] = colors
rgba[:, 3] = alphas
opacity = getattr(self, '_flow_opacity', 1.0)
if opacity < 1.0:
rgba[:, 3] *= opacity
# Confidence fading: slider controls how much the density
# confidence affects particle opacity.
# fade = (1 - slider) + slider * conf^exponent
# At slider=0%: fade=1 (no change).
# At slider=1%: fade ≈ 0.99 + 0.01*conf (barely visible).
# At slider=100%: fade = conf^exponent (full effect).
# The power curve (exponent>1) makes high-conf particles stay
# bright while low-conf ones drop faster.
conf_str = getattr(self, '_confidence_strength', 0.0)
if conf_str > 0 and self.flow is not None and self.flow._confidence_grid is not None:
conf = self.flow.sample_confidence_batch(pos)
exponent = 3.0 # nonlinear: conf=0.8→0.51, conf=0.2→0.008
conf_powered = np.power(conf, exponent)
fade = (1.0 - conf_str) + conf_str * conf_powered
rgba[:, 3] *= fade
# Skip rendering particles with near-zero alpha
visible = rgba[:, 3] > 0.01
if not np.all(visible):
pos = pos[visible]
rgba = rgba[visible]
self.vis_flow.set_data(pos, rgba)
# Ball flow
if self.ball_flowing and self.flow is not None:
prev_bp = self._last_ball_pos
bp = self.flow.advance_ball(dt_scale=dt_scale)
# Track whether the ball is actually moving (or stuck in a zero-flow region)
if prev_bp is not None:
step = float(np.linalg.norm(bp - prev_bp))
if step < 1e-4:
self._ball_stuck_frames += 1
self._ball_motion_frames = 0
else:
self._ball_stuck_frames = 0
self._ball_motion_frames = getattr(self, '_ball_motion_frames', 0) + 1
self._last_ball_pos = bp.copy()
# Refresh contextual hint on stuck/unstuck transitions (~every 30 frames)
if self._frame_count % 30 == 0:
stuck_frames = self._ball_stuck_frames
motion_frames = getattr(self, '_ball_motion_frames', 0)
if stuck_frames >= 30:
new_stuck = True
elif motion_frames >= 60:
new_stuck = False
else:
new_stuck = self._ball_is_stuck # keep current (initial state)
if new_stuck != self._ball_is_stuck:
self._ball_is_stuck = new_stuck
self._update_contextual_hint()
self.vis_ball.transform = scene.transforms.STTransform(translate=bp.tolist())
self.vis_ball.visible = True
trail = self.flow.ball_trail
if len(trail) >= 2:
self.vis_trail.set_data(
pos=np.array(trail, dtype=np.float32),
color=self.TRAIL_COLOR)
self.vis_trail.visible = True
# Update probe to follow ball
self.vis_probe.set_data(bp.reshape(1, 3).astype(np.float32), self.PROBE_COLOR)
if self._gizmo_visible:
self._update_gizmo(bp.astype(np.float32))
# Sync sliders + info (throttled to every 6 frames, skip when user is dragging)
if QtWidgets is not None and self._frame_count % 6 == 0 and not self._manual_slider_override:
self._sync_sliders_to_ball(bp)
self._update_info(bp)
self.canvas.update()
# ═══════════════════════════════════════════════════
# Keyboard (fallback when canvas has focus)
# ═══════════════════════════════════════════════════
def _on_key(self, event):
key = event.key
if key == 'Space' and self._has_flow and self.flow:
# Space toggles "drag probe by the flow" (ball_flowing)
self.ball_flowing = not self.ball_flowing
if self.ball_flowing:
self._auto_mark_start_point()
self.flow.start_ball_flow()
self._show_gizmo(False)
else:
self.flow.stop_ball_flow()
self.vis_ball.visible = False
self.vis_trail.visible = False
if QtWidgets and hasattr(self, 'chk_ball'):
self.chk_ball.blockSignals(True)
self.chk_ball.setChecked(self.ball_flowing)
self.chk_ball.blockSignals(False)
if hasattr(self, '_gizmo_hint'):
self._gizmo_hint.setVisible(not self.ball_flowing)
self._update_contextual_hint()
elif key == 'B' and self._has_flow and self.flow:
self.ball_flowing = not self.ball_flowing
if self.ball_flowing:
self._auto_mark_start_point()
self.flow.start_ball_flow()
self._show_gizmo(False)
else:
self.flow.stop_ball_flow()
self.vis_ball.visible = False
self.vis_trail.visible = False
if QtWidgets and hasattr(self, 'chk_ball'):
self.chk_ball.blockSignals(True)
self.chk_ball.setChecked(self.ball_flowing)
self.chk_ball.blockSignals(False)
if hasattr(self, '_gizmo_hint'):
self._gizmo_hint.setVisible(not self.ball_flowing)
self._update_contextual_hint()
elif key == 'M':
# Mark current probe position
self._qt_mark()
elif key == 'F' and self._has_flow:
# F toggles the flow particles (moved from Space)
self.flow_active = not self.flow_active
self.vis_flow.visible = self.flow_active
if QtWidgets and hasattr(self, 'chk_flow'):
self.chk_flow.setChecked(self.flow_active)
elif key == 'P':
self.show_points = not self.show_points
self.vis_clusters.visible = self.show_points
if QtWidgets and hasattr(self, 'chk_points'):
self.chk_points.setChecked(self.show_points)
elif key == 'L':
self.show_path = not self.show_path
self._sync_path_visibility()
if QtWidgets and hasattr(self, 'chk_path'):
self.chk_path.setChecked(self.show_path)
# --- Auto-rotate key disabled (kept for future use) ---
# elif key == 'A':
# self.auto_rotate = not self.auto_rotate
# if QtWidgets and hasattr(self, 'chk_rotate'):
# self.chk_rotate.setChecked(self.auto_rotate)
elif key == 'R':
self.view.camera.reset()
self.view.camera.azimuth = 0
self.view.camera.elevation = 20
self.view.camera.distance = 5.0
self.view.camera.center = tuple(self._data_center)
elif key in ('+', '='):
self.base_size *= 1.2
self.vis_flow.set_base_size(self.base_size)
elif key == '-':
self.base_size /= 1.2
self.vis_flow.set_base_size(self.base_size)
elif key == 'E':
# Context-sensitive: attractor explain takes priority, else path explain
if self._attractors_visible and self._highlighted_attractor is not None:
shift = 'Shift' in event.modifiers if hasattr(event, 'modifiers') else False
idx = self._highlighted_attractor
cached_key = str(idx)
has_cached = cached_key in self._attractor_explanations
if shift and has_cached:
# Shift+E with cached = force re-explain (deep)
self._explain_highlighted_attractor(deep=True, force=True)
elif shift:
self._explain_highlighted_attractor(deep=True)
else:
self._explain_highlighted_attractor(deep=False)
else:
self._qt_explain()
elif key == 'Delete':
# Delete highlighted saved path
if self._highlighted_path is not None:
self._delete_highlighted_path()
elif key == 'D':
# Toggle debug blob visualization
self._debug_blob = not self._debug_blob
self.vis_blob_debug.visible = self._debug_blob
elif key == 'Escape':
self.close()
def _on_double_click(self, event):
"""Double-click on 3D canvas to jump sliders to nearest data point."""
if event.button != 1: # left button only
return
# Project data points to screen using vispy's own transform
try:
pts = self.result.projected_3d
pts_h = np.hstack([pts, np.ones((len(pts), 1))]).astype(np.float32)
mapped = self.view.scene.transform.map(pts_h)
w_vals = mapped[:, 3:4]
w_vals = np.where(np.abs(w_vals) < 1e-8, 1.0, w_vals)
screen = mapped[:, :2] / w_vals # perspective divide → canvas px
click_pos = np.array([event.pos[0], event.pos[1]], dtype=np.float64)
dists = np.linalg.norm(screen - click_pos, axis=1)
nearest_idx = int(np.argmin(dists))
# Only snap if click is within 50 canvas pixels
if dists[nearest_idx] > 50:
return
# Jump sliders to that point's 3D position
target = pts[nearest_idx].astype(np.float32)
self._updating_sliders = True
labels = getattr(self.result.axis_info, 'labels', ['X', 'Y', 'Z'])
for i in range(3):
sv = self._raw_to_slider(float(target[i]), i)
self._sliders[i].setValue(sv)
self._slider_labels[i].setText(f"{labels[i]}: {sv / 10:.0f}%")
self._updating_sliders = False
# Update probe + info
self.vis_probe.set_data(target.reshape(1, 3), self.PROBE_COLOR)
if self._gizmo_visible:
self._update_gizmo(target)
if not self.ball_flowing and self.flow is not None:
self.flow.set_ball_position(*target)
self._update_info(target)
# Show point info overlay
self._show_point_info(nearest_idx)
except Exception:
pass
# ═══════════════════════════════════════════════════
# Gizmo — Blender-style axis drag for probe
# ═══════════════════════════════════════════════════
def _update_gizmo(self, center):
"""Reposition the 3 axis arrows with arrowheads around *center*."""
c = np.asarray(center, dtype=np.float32)
head_frac = 0.075 # arrowhead length as fraction of shaft
head_spread = 0.105 # arrowhead width as fraction of shaft length
for i in range(3):
tip = c.copy()
tip[i] += self._gizmo_arrow_len
self._gizmo_lines[i].set_data(
pos=np.array([c, tip], dtype=np.float32),
color=self._gizmo_colors[i],
)
# Arrowhead: two barbs from tip pointing back along shaft + sideways
back = c.copy()
back[i] = tip[i] - self._gizmo_arrow_len * head_frac
perp1 = (i + 1) % 3
perp2 = (i + 2) % 3
barb_offset = self._gizmo_arrow_len * head_spread
b1 = back.copy()
b1[perp1] += barb_offset
b2 = back.copy()
b2[perp2] += barb_offset
head_pts = np.array([tip, b1, tip, b2], dtype=np.float32)
self._gizmo_heads[i].set_data(
pos=head_pts,
color=self._gizmo_colors[i],
)
def _show_gizmo(self, show=True, persistent=False):
"""Show/hide the gizmo. When persistent=True, Ctrl-release won't hide it."""
self._gizmo_visible = show
for line in self._gizmo_lines:
line.visible = show
for head in self._gizmo_heads:
head.visible = show
if show:
if persistent:
self._gizmo_persistent = True
pos = self._probe_pos_from_sliders()
self._update_gizmo(pos)
else:
self._gizmo_persistent = False
if hasattr(self, '_hint_overlay'):
self._update_contextual_hint()
def _on_gizmo_key(self, event):
"""Show gizmo when Ctrl is pressed (not during ball flow)."""
if event.key == 'Control' and not self.ball_flowing:
if not self._gizmo_visible:
self._show_gizmo(True)
def _on_gizmo_key_release(self, event):
"""Hide gizmo when Ctrl is released, unless persistent or mid-drag."""
if (event.key == 'Control'
and self._gizmo_dragging is None
and not getattr(self, '_gizmo_persistent', False)):
self._show_gizmo(False)
@staticmethod
def _point_to_segment_dist_2d(p, a, b):
"""Shortest distance from point *p* to line segment *a*–*b* in 2D."""
ab = b - a
ab_sq = float(np.dot(ab, ab))
if ab_sq < 1e-8:
return float(np.linalg.norm(p - a))
t = float(np.dot(p - a, ab)) / ab_sq
t = max(0.0, min(1.0, t))
closest = a + t * ab
return float(np.linalg.norm(p - closest))
def _vispy_project(self, point_3d):
"""Project a 3D point (in raw data coords) to 2D canvas pixel coords.
Applies the render-root scale (normalizes data extent) then the
vispy scene transform chain, giving canvas-pixel coordinates.
"""
s = self._scene_scale
pt = np.array([[point_3d[0] * s, point_3d[1] * s, point_3d[2] * s, 1.0]],
dtype=np.float32)
mapped = self.view.scene.transform.map(pt)[0]
w = mapped[3]
if abs(w) < 1e-8:
w = 1.0
return np.array([mapped[0] / w, mapped[1] / w], dtype=np.float64)
def _on_click_track_press(self, event):
"""Track press start to differentiate plain click from drag/orbit."""
if event.button != 1:
return
self._click_track_pos = np.array([event.pos[0], event.pos[1]], dtype=np.float64)
self._click_track_moved = False
def _on_click_track_move(self, event):
if self._click_track_pos is None:
return
cur = np.array([event.pos[0], event.pos[1]], dtype=np.float64)
if float(np.linalg.norm(cur - self._click_track_pos)) > 4.0:
self._click_track_moved = True
def _on_click_track_release(self, event):
"""On plain click (no drag) near the probe, spawn the gizmo persistently
and auto-disable ball flow."""
if event.button != 1:
return
start = self._click_track_pos
moved = self._click_track_moved
self._click_track_pos = None
self._click_track_moved = False
if start is None or moved:
return
# Don't interfere with existing gizmo drag
if self._gizmo_dragging is not None:
return
# If gizmo is already visible (transient, not persistent), skip
if self._gizmo_visible and not getattr(self, '_gizmo_persistent', False):
return
# Check proximity to the probe in screen space
probe_pos = self._probe_pos_from_sliders()
probe_sc = self._vispy_project(probe_pos)
click = np.array([event.pos[0], event.pos[1]], dtype=np.float64)
probe_dist = float(np.linalg.norm(click - probe_sc))
if probe_dist > 60.0:
return
# When attractors are visible, only grab the probe if the click is
# really close (<30px) — otherwise let the attractor handler win.
if self._attractors_visible and probe_dist > 30.0:
return
# Dismiss explain overlay when user starts editing the probe
if hasattr(self, '_explain_overlay'):
self._explain_overlay.setVisible(False)
# Auto-disable ball flow and spawn persistent gizmo
if self.ball_flowing:
self.ball_flowing = False
if self.flow is not None:
self.flow.stop_ball_flow()
self.vis_ball.visible = False
self.vis_trail.visible = False
if hasattr(self, 'chk_ball'):
self.chk_ball.blockSignals(True)
self.chk_ball.setChecked(False)
self.chk_ball.blockSignals(False)
if hasattr(self, '_gizmo_hint'):
self._gizmo_hint.setVisible(True)
self._show_gizmo(True, persistent=True)
def _on_gizmo_press(self, event):
"""Ctrl+click: pick the axis whose screen-space line segment is
closest to the click — pure 2D in canvas pixel coordinates."""
if event.button != 1:
return
if not self._gizmo_visible:
return
probe_pos = self._probe_pos_from_sliders()
click = np.array([event.pos[0], event.pos[1]], dtype=np.float64)
# Project gizmo center and tips to canvas pixels (W-divided)
center_sc = self._vispy_project(probe_pos)
axis_names = ['X', 'Y', 'Z']
best_axis = None
best_dist = float('inf')
debug_dists = []
for i in range(3):
tip_3d = probe_pos.copy().astype(np.float64)
tip_3d[i] += self._gizmo_arrow_len
tip_sc = self._vispy_project(tip_3d)
dist = self._point_to_segment_dist_2d(click, center_sc, tip_sc)
debug_dists.append((axis_names[i], dist, tip_sc))
if dist < best_dist:
best_dist = dist
best_axis = i
# Debug output — keep until gizmo confirmed working
print(f"[GIZMO] click=({click[0]:.0f},{click[1]:.0f}) "
f"center=({center_sc[0]:.0f},{center_sc[1]:.0f})")
for name, d, tip in debug_dists:
marker = " <<<" if name == axis_names[best_axis] else ""
print(f" {name}: tip=({tip[0]:.0f},{tip[1]:.0f}) dist={d:.1f}px{marker}")
if best_axis is None or best_dist > 150:
print(f" → no axis picked (best_dist={best_dist:.0f} > 150px)")
return
print(f" → picked {axis_names[best_axis]} axis (dist={best_dist:.1f}px)")
# Disable camera so it doesn't rotate during drag
self.view.camera.interactive = False
# Screen-space drag setup: project +1 world unit along the
# chosen axis to find the screen direction and scale factor.
tip_3d = probe_pos.copy().astype(np.float64)
tip_3d[best_axis] += 1.0
tip_sc = self._vispy_project(tip_3d)
axis_screen_dir = tip_sc - center_sc
px_per_unit = float(np.linalg.norm(axis_screen_dir))
if px_per_unit < 1e-3:
px_per_unit = 1.0
axis_screen_n = axis_screen_dir / px_per_unit
self._gizmo_dragging = best_axis
self._gizmo_drag_start_pos = probe_pos.copy()
self._gizmo_drag_start_click = click.copy()
self._gizmo_drag_axis_screen_n = axis_screen_n
self._gizmo_drag_px_per_unit = px_per_unit
# Highlight the active arrow, dim the others
for j in range(3):
c = list(self._gizmo_colors[j])
c[3] = 1.0 if j == best_axis else 0.3
self._gizmo_lines[j].set_data(color=c)
self._gizmo_heads[j].set_data(color=c)
def _on_gizmo_move(self, event):
"""Drag: project mouse movement along the axis in screen space,
convert to world units using the pixels-per-unit ratio."""
if self._gizmo_dragging is None:
return
axis = self._gizmo_dragging
current = np.array([event.pos[0], event.pos[1]], dtype=np.float64)
mouse_delta = current - self._gizmo_drag_start_click
# Project mouse movement onto the screen-space axis direction
along_px = float(np.dot(mouse_delta, self._gizmo_drag_axis_screen_n))
world_delta = along_px / self._gizmo_drag_px_per_unit
new_pos = self._gizmo_drag_start_pos.copy()
new_pos[axis] += world_delta
# Clamp to data range with margin
pts = self.result.projected_3d
for i in range(3):
mn, mx = pts[:, i].min(), pts[:, i].max()
margin = (mx - mn) * 0.15
new_pos[i] = np.clip(new_pos[i], mn - margin, mx + margin)
# Update sliders
self._updating_sliders = True
labels = getattr(self.result.axis_info, 'labels', ['X', 'Y', 'Z'])
for i in range(3):
sv = self._raw_to_slider(float(new_pos[i]), i)
sv = int(np.clip(sv, 0, 1000))
self._sliders[i].setValue(sv)
self._slider_labels[i].setText(f"{labels[i]}: {sv / 10:.0f}%")
self._updating_sliders = False
# Update visuals
self.vis_probe.set_data(new_pos.reshape(1, 3), self.PROBE_COLOR)
self._update_gizmo(new_pos)
if self.flow is not None and not self.ball_flowing:
self.flow.set_ball_position(*new_pos)
def _on_gizmo_release(self, event):
"""End axis drag, re-enable camera."""
if self._gizmo_dragging is None:
return
# Re-enable camera interaction
self.view.camera.interactive = True
# Final position
pos = self._probe_pos_from_sliders()
self._update_info(pos)
# Reset arrow colors
for j in range(3):
c = list(self._gizmo_colors[j])
c[3] = 0.9
self._gizmo_lines[j].set_data(color=c)
self._gizmo_heads[j].set_data(color=c)
self._gizmo_dragging = None
self._gizmo_drag_start_pos = None
self._gizmo_drag_start_click = None
self._gizmo_drag_axis_screen_n = None
def _show_point_info(self, idx: int):
"""Show text description of a selected data point."""
if not hasattr(self, '_point_overlay'):
return
entry = self.result.session.entries[idx]
cluster_id = self.result.clusters.labels[idx]
cluster_name = (self.result.cluster_labels[cluster_id]
if cluster_id < len(self.result.cluster_labels)
else f"Cluster {cluster_id}")
self._point_header_label.setText(f"Point #{idx} | {cluster_name}")
text = entry.text
if len(text) > 200:
text = text[:200] + "..."
role = entry.role
self._point_text_label.setText(f"[{role}] {text}")
self._point_overlay.adjustSize()
self._point_overlay.setVisible(True)
self._reposition_overlays()
# ═══════════════════════════════════════════════════
# Public API
# ═══════════════════════════════════════════════════
def _apply_initial_state(self):
"""Apply optional initial UI state overrides from self._initial_state."""
state = self._initial_state
if not state:
return
# Speed multiplier (slider value = speed * 100)
if 'speed' in state and hasattr(self, '_sl_speed'):
speed_val = int(state['speed'] * 100)
self._sl_speed.setValue(speed_val)
# Attractor sensitivity (set BEFORE show_attractors so first
# computation uses the correct value)
if 'sensitivity' in state and hasattr(self, '_sl_sensitivity'):
self._attractor_sensitivity = state['sensitivity']
slider_val = int(max(0, min(1000, state['sensitivity'] * 1000)))
self._sl_sensitivity.setValue(slider_val)
pct = state['sensitivity'] * 100
self._lbl_sensitivity.setText(f"Sensitivity: {pct:.1f}%")
# Show attractors
if state.get('show_attractors') and hasattr(self, 'chk_attractors'):
self.chk_attractors.setChecked(True)
# Flow color mode
if 'flow_color' in state:
self._flow_color_mode = state['flow_color']
if state['flow_color'] == 'cluster':
if hasattr(self, '_chk_cluster_colors'):
self._chk_cluster_colors.setChecked(True)
elif state['flow_color'] == 'entropy':
if hasattr(self, '_chk_entropy'):
self._chk_entropy.setChecked(True)
elif state['flow_color'].startswith('score:'):
channel = state['flow_color'].split(':', 1)[1]
for ch, chk in getattr(self, '_score_color_checkboxes', []):
chk.setChecked(ch == channel)
# Show data points
if state.get('show_points') and hasattr(self, 'chk_points'):
self.chk_points.setChecked(True)
def show(self):
# Initial flow step
if self.flow_active and self.flow is not None:
pos, colors, alphas, speeds = self.flow.step()
rgba = np.empty((len(pos), 4), dtype=np.float32)
rgba[:, :3] = colors.astype(np.float32)
rgba[:, 3] = alphas.astype(np.float32)
self.vis_flow.set_data(pos.astype(np.float32), rgba)
# Start ball flow if enabled by default
if self.ball_flowing and self.flow is not None:
self.flow.start_ball_flow()
# Apply optional initial UI state overrides
self._apply_initial_state()
# Load cached explained paths and attractor explanations
self._load_saved_paths()
self._load_attractor_explanations()
if self._saved_paths:
self._render_all_saved_paths()
if self.window is not None:
self.window.show()
# Workaround: some GPU drivers render specific framebuffer
# widths much slower than adjacent ones (observed: widths
# where width%9==8 on some NVIDIA cards drop from 28 to 12
# FPS). A +2px jog after first paint nudges the canvas onto
# a fast alignment without visible change to the layout.
def _jog_resize():
self.window.resize(
self.window.width() + 2,
self.window.height(),
)
QtCore.QTimer.singleShot(100, _jog_resize)
else:
self.canvas.show()
self._timer.start()
# Show initial contextual hint
if hasattr(self, '_hint_overlay'):
self._update_contextual_hint()
def close(self):
self._timer.stop()
if self.window is not None:
self.window.close()
else:
self.canvas.close()
def run(self):
self.show()
app.run()
# ═══════════════════════════════════════════════════════════════════
# Public API
# ═══════════════════════════════════════════════════════════════════
def launch_renderer(result, particle_grid=40, base_size=28.0,
window_size=(1400, 800), explainer=None,
dataset_name=None, initial_state=None) -> FlowRenderer:
"""Launch the GPU-accelerated 3D flow renderer with interactive controls.
Opens a native OpenGL window matching Android's My3DScatterRenderer quality,
with a side panel providing all dashboard features: sliders, toggles,
cluster legend, probe info, mark/clear buttons, and LLM explain.
Falls back to software rendering automatically if no GPU is available.
Args:
result: AnalysisResult from pipeline.analyze()
particle_grid: 40 = 64k particles (Android default), 20 = 8k (lighter)
base_size: Particle size for perspective scaling (40.0 for desktop)
window_size: Window dimensions (width, height)
explainer: SemanticExplainer instance for LLM explanations (optional)
dataset_name: Optional display name shown as title on the renderer
initial_state: Optional dict to override default UI state on launch.
Supported keys (all optional):
speed (float): flow speed multiplier (default 1.0)
show_attractors (bool): show attractor meshes
flow_color (str): 'speed'|'cluster'|'entropy' or 'score:'
show_points (bool): show data point markers
"""
from tracescope.models.analysis import AnalysisResult
if not isinstance(result, AnalysisResult):
raise TypeError(
f"launch_renderer() requires an AnalysisResult from pipeline.analyze(), "
f"got {type(result).__name__}."
)
_ensure_viable_backend()
renderer = FlowRenderer(result, particle_grid=particle_grid,
base_size=base_size, window_size=window_size,
explainer=explainer, dataset_name=dataset_name,
initial_state=initial_state)
renderer.run()
return renderer