diff --git a/AGENTS.md b/AGENTS.md
index 1eb5f24..2ca6f86 100644
Binary files a/AGENTS.md and b/AGENTS.md differ
diff --git a/NOTICE b/NOTICE
index 24b2dd1..7264cda 100644
--- a/NOTICE
+++ b/NOTICE
@@ -51,8 +51,11 @@ The canvas element colour palette in `src/otko/views/canvas3d/style.py`
(per-family element colours and the diverging response colour scale) and the
resulting diagram colouring in `views/canvas3d/diagram_renderer.py` were
adapted from the `opstool` project, which is distributed under the **GNU
-General Public License v3.0**. opstool is Copyright © Yexiang Yan and
-contributors.
+General Public License v3.0**. The support (boundary-condition) glyph
+geometry in `views/canvas_plotly/trace_builder.py` (`_support_loops`) is
+ported and modified from opstool's `_get_bc_points_3d` / `_get_bc_points_2d`,
+and the plotly response-colour and load-pattern presentation follows
+opstool's plotly recipes. opstool is Copyright © Yexiang Yan and contributors.
In accordance with GPLv3 §5(a)/(b) this notice records that the material was
modified and adapted for OTKO. Combining the GPLv3-covered material with
diff --git a/docs/QUICK_GUIDE.md b/docs/QUICK_GUIDE.md
index 0bc4b8c..a6ff736 100644
--- a/docs/QUICK_GUIDE.md
+++ b/docs/QUICK_GUIDE.md
@@ -66,7 +66,9 @@ correctly.
periods, frequencies, and participation factors per mode.
4. **Display → Animate Mode Shape** to view each mode. Use the mode
selector and the animation controls, and **Export…** if you want a
- video of the mode shape.
+ video of the mode shape. On the Plotly backend the **Play** button runs
+ the animation inside the viewport (plotly frames); on PyVista it is
+ driven from Python.
5. Modal results also feed the response-spectrum case: define a response
spectrum, then run the SRSS or CQC combination and open
**Display → Show Response Spectrum**.
@@ -77,12 +79,20 @@ After a run, the results/report panel shows a summary for the active case
(static reactions and forces, modal periods, and so on). Use the display
actions to inspect the model visually:
-- **Display → Show Deformed Shape** — with a scale slider.
+- **Display → Show Deformed Shape** — with a scale slider. The deformed
+ shape is coloured by displacement magnitude with a colourbar, and
+ **Display → Show Undeformed Reference** overlays the original shape for
+ comparison.
- **Display → Show Force Diagram…** — axial (P), shear (V2/V3), moment
(M2/M3) diagrams.
- **Display → Show Pushover Curve**, **Show Time-History**, **Show
Hysteresis** as applicable.
+Nodal and distributed loads are drawn as arrows whose length scales with the
+load magnitude; each load pattern gets its own colour and hovering an arrow
+shows its value. Support symbols show which translation directions are
+restrained.
+
To hand the analysis to someone else, or to archive exactly what was run,
export a script:
@@ -122,6 +132,23 @@ wrapped in a single macro, so one undo removes the whole step. File
loads, analysis runs, and display-only changes are not model mutations and
are not undoable.
+## 6. Navigating the 3D view
+
+Both canvas backends (**Options → Canvas Backend**) use the same VTK-style mouse
+bindings, and **Help → Mouse Controls** lists them in the app:
+
+- **Rotate** — left-drag.
+- **Pan** — Shift + left-drag, or middle-drag.
+- **Zoom** — right-drag, or the mouse wheel.
+- **Spin (roll)** — Ctrl + left-drag.
+- **Select** — left-click a node or element; Ctrl+click or Shift+click adds
+ to the selection. A drag moves the view; only a click without movement
+ changes the selection.
+
+View presets: **Ctrl+1** isometric, **Ctrl+2** top (XY), **Ctrl+3** front
+(XZ), **Ctrl+4** right (YZ), **Ctrl+E** zoom extents. The camera keeps Z up,
+so the horizon stays level while you orbit.
+
## Where to go next
- [`architecture.md`](architecture.md) — MVVM layering and command order.
diff --git a/src/otko/services/deformation.py b/src/otko/services/deformation.py
index 8c60f7b..084e2ab 100644
--- a/src/otko/services/deformation.py
+++ b/src/otko/services/deformation.py
@@ -36,6 +36,19 @@ class DeformationSource:
out[i] += self.scale * self.displacements[row]
return out
+ def magnitudes(self, node_ids: list[int]) -> np.ndarray:
+ """Per-node displacement magnitude (scaled) in ``node_ids`` order.
+
+ Used to colour a deformed / modal shape by response value through
+ plotly's colour axis (the contour recipe adapted from opstool).
+ """
+ out = np.zeros(len(node_ids), dtype=float)
+ for i, nid in enumerate(node_ids):
+ row = self.node_id_to_row.get(nid)
+ if row is not None:
+ out[i] = self.scale * float(np.linalg.norm(self.displacements[row]))
+ return out
+
def static_to_deformation(
project: Project,
diff --git a/src/otko/views/action_handlers.py b/src/otko/views/action_handlers.py
index 4352b00..f699036 100644
--- a/src/otko/views/action_handlers.py
+++ b/src/otko/views/action_handlers.py
@@ -53,6 +53,7 @@ from otko.views.dialogs import (
MaterialLibraryDialog,
MaterialTesterDialog,
MirrorDialog,
+ MouseControlsDialog,
MoveDialog,
PathTimeSeriesDialog,
PatternLoadsDialog,
@@ -987,6 +988,19 @@ class ActionHandlers:
dlg.raise_()
dlg.activateWindow()
+ def _on_mouse_controls(self) -> None:
+ """Help → Mouse Controls — modeless viewport navigation reference.
+
+ Cached like the Quick Guide so re-invoking raises the same window.
+ """
+ dlg = getattr(self, "_mouse_controls_dialog", None)
+ if dlg is None:
+ dlg = MouseControlsDialog(self) # type: ignore[arg-type]
+ self._mouse_controls_dialog = dlg
+ dlg.show()
+ dlg.raise_()
+ dlg.activateWindow()
+
def _on_set_units(self) -> None:
"""Options → Set Display Units — SAP2000 parity.
diff --git a/src/otko/views/canvas3d/model_canvas.py b/src/otko/views/canvas3d/model_canvas.py
index 3e00425..b6301a6 100644
--- a/src/otko/views/canvas3d/model_canvas.py
+++ b/src/otko/views/canvas3d/model_canvas.py
@@ -342,6 +342,11 @@ class ModelCanvas(QtInteractor): # type: ignore[misc]
self._renderer.set_show_local_axes(enabled)
self.render()
+ def set_show_undeformed(self, enabled: bool) -> None:
+ """Show a faint undeformed reference behind a deformed / modal shape."""
+ self._renderer.set_show_undeformed(enabled)
+ self.render()
+
def set_style(self, style: RenderStyle) -> None:
"""Swap the visual style and repaint the scene.
diff --git a/src/otko/views/canvas3d/model_renderer.py b/src/otko/views/canvas3d/model_renderer.py
index 12c88cb..70babee 100644
--- a/src/otko/views/canvas3d/model_renderer.py
+++ b/src/otko/views/canvas3d/model_renderer.py
@@ -12,7 +12,6 @@ from __future__ import annotations
import contextlib
import enum
-from dataclasses import dataclass
from typing import Any
import numpy as np
@@ -33,6 +32,7 @@ from otko.core import (
ZeroLengthElement,
ZeroLengthSectionElement,
)
+from otko.services.deformation import DeformationSource
from otko.views.canvas3d.style import (
SELECTED_STATE,
RenderStyle,
@@ -165,23 +165,6 @@ def _dof_indices(ndf: int) -> tuple[int, ...]:
return tuple(range(ndf))
-@dataclass
-class DeformationSource:
- """Per-node displacement vectors used to draw deformed shapes."""
-
- displacements: np.ndarray # shape (n_nodes, 3) — x, y, z components
- node_id_to_row: dict[int, int]
- scale: float = 1.0
-
- def shifted(self, original_points: np.ndarray, node_ids: list[int]) -> np.ndarray:
- out = original_points.copy()
- for i, nid in enumerate(node_ids):
- row = self.node_id_to_row.get(nid)
- if row is not None:
- out[i] += self.scale * self.displacements[row]
- return out
-
-
class ModelRenderer:
"""Glyphed-PolyData renderer with mode-aware deformation support."""
@@ -219,6 +202,8 @@ class ModelRenderer:
self._hover_actor: Any = None # single yellow-ring snap marker
self._show_section_extrusions: bool = False
self._show_local_axes: bool = False
+ self._show_undeformed: bool = False
+ self._undeformed_actor: Any = None
# SAP2000-style working plane: when set, the grid renders ONLY
# the lines / intersections lying on this plane so a user in
# plan view at Z=3 doesn't see the Z=0 grid cluttering the view.
@@ -282,6 +267,13 @@ class ModelRenderer:
if self._project is not None:
self.render(self._project)
+ def set_show_undeformed(self, on: bool) -> None:
+ """Toggle the faint undeformed-shape reference in deformed/modal views."""
+ if self._show_undeformed == on:
+ return
+ self._show_undeformed = on
+ self._refresh_undeformed_overlay()
+
def set_style(self, style: RenderStyle) -> None:
"""Swap the visual style and rebuild the scene it colours.
@@ -1114,8 +1106,39 @@ class ModelRenderer:
if self._frame_pd is not None:
self._frame_pd.points = new_pts
self._frame_pd.Modified()
+ self._refresh_undeformed_overlay()
self._rebuild_labels()
+ def _refresh_undeformed_overlay(self) -> None:
+ """Faint undeformed wireframe shown behind a deformed / modal shape."""
+ if self._undeformed_actor is not None:
+ with contextlib.suppress(Exception):
+ self._plotter.remove_actor(self._undeformed_actor, render=False)
+ self._undeformed_actor = None
+ if (
+ not self._show_undeformed
+ or self._mode == RendererMode.MODEL
+ or self._deformation is None
+ or self._frame_pd is None
+ or self._node_original_points is None
+ ):
+ self._plotter.render()
+ return
+ import pyvista as pv
+
+ ghost = pv.PolyData()
+ ghost.points = self._node_original_points
+ ghost.lines = np.asarray(self._frame_pd.lines).copy()
+ self._undeformed_actor = self._plotter.add_mesh(
+ ghost,
+ color="#9aa3ad",
+ opacity=0.45,
+ line_width=1,
+ lighting=False,
+ pickable=False,
+ )
+ self._plotter.render()
+
# ── helpers ─────────────────────────────────────────────────────
def _teardown_all(self) -> None:
self._clear_label_actors()
@@ -1126,6 +1149,10 @@ class ModelRenderer:
for a in self._aux_actors:
with contextlib.suppress(Exception):
self._plotter.remove_actor(a, render=False)
+ if self._undeformed_actor is not None:
+ with contextlib.suppress(Exception):
+ self._plotter.remove_actor(self._undeformed_actor, render=False)
+ self._undeformed_actor = None
self._node_actor = None
self._frame_actor = None
self._aux_actors.clear()
diff --git a/src/otko/views/canvas_base.py b/src/otko/views/canvas_base.py
index 0352961..544985f 100644
--- a/src/otko/views/canvas_base.py
+++ b/src/otko/views/canvas_base.py
@@ -45,6 +45,9 @@ class CanvasCapabilities:
labels: bool = True
#: Off-screen frame capture (mode-shape / time-history video export).
animation_export: bool = True
+ #: In-page animation playback (plotly frames) instead of Python-driven
+ #: per-frame re-renders.
+ in_page_animation: bool = False
class CanvasBackend(Protocol):
@@ -87,6 +90,8 @@ class CanvasBackend(Protocol):
def set_show_local_axes(self, enabled: bool) -> None: ...
+ def set_show_undeformed(self, enabled: bool) -> None: ...
+
def set_display_options(self, *, show_node_labels: bool, show_element_labels: bool) -> None: ...
def set_default_selection_enabled(self, enabled: bool) -> None: ...
diff --git a/src/otko/views/canvas_plotly/html.py b/src/otko/views/canvas_plotly/html.py
index 12c9bc8..80b4a88 100644
--- a/src/otko/views/canvas_plotly/html.py
+++ b/src/otko/views/canvas_plotly/html.py
@@ -13,9 +13,21 @@ The JS side exposes three entry points to Python (called via
- ``otkoSetCamera(cameraJson)`` — apply a camera alone (view presets,
parallel-projection toggle).
- ``otkoSetSnapEnabled(bool)`` — arm/disarm the hover snap-target preview.
+- ``otkoAnimate(payloadJson, durationMs, loops, preserveView)`` /
+ ``otkoStopAnimation()`` — push a pre-built frame list and let plotly play
+ it in-page (mode-shape / time-history animation).
Clicks travel the other way through the ``otkoBridge`` QWebChannel object:
entity picks carry the trace ``meta.kind`` and the point ``customdata``.
+
+There is also an in-page mouse-gesture layer. plotly's built-in drag bindings
+disagree with the PyVista backend's VTK trackball style (plotly's shift+left
+rotates, ctrl+left pans, middle zooms), so both backends would feel different.
+The scene stays in ``turntable`` mode (Z-up, level horizon) and the
+non-default gestures are re-implemented in JS against the same gl-plot3d
+camera object plotly exposes, matching VTK: shift+left pan, ctrl+left spin,
+ctrl+shift+left / right dolly, middle pan. Plain left drag and the wheel stay
+on plotly's native path.
"""
from __future__ import annotations
@@ -108,9 +120,14 @@ _PAGE = """
var gd = document.getElementById('plot');
var scene = gd && gd._fullLayout ? gd._fullLayout.scene._scene : null;
var params = scene && scene.glplot ? scene.glplot.cameraParams : null;
- if (!params) return null;
+ var camera = scene && scene.camera ? scene.camera : null;
+ if (!params || !camera) return null;
+ // gl-plot3d only refreshes ``params.view`` on the render loop, so after a
+ // camera jump (view preset / relayout) it can be a frame behind. Recompute
+ // the live view matrix first so the marker lands on the settled camera.
+ camera.view.recalcMatrix(camera.view.lastT());
var matrix = mat4Multiply(
- mat4Multiply(params.projection, params.view), params.model
+ mat4Multiply(params.projection, camera.view.computedMatrix), params.model
);
var x = point[0], y = point[1], z = point[2];
var clipW = matrix[3] * x + matrix[7] * y + matrix[11] * z + matrix[15];
@@ -285,12 +302,148 @@ _PAGE = """
if (!snapEnabled) return;
setSnapMarker(null);
});
+
+ installGestureHandlers(gd);
+ }
+
+ // --- mouse gestures (VTK/PyVista parity) -------------------------------
+ // plotly's built-in drag bindings clash with the PyVista backend's VTK
+ // trackball style, so both backends would feel different. We keep the
+ // turntable scene (Z-up, level horizon) and re-implement the non-default
+ // gestures, driving the same gl-plot3d camera object plotly exposes. Plain
+ // left drag and the wheel stay on plotly's native path.
+ var gesture = null;
+ var gesturesReady = false;
+
+ function plotCamera() {
+ var gd = document.getElementById('plot');
+ var scene = gd && gd._fullLayout ? gd._fullLayout.scene._scene : null;
+ return scene && scene.camera ? scene.camera : null;
+ }
+
+ function nowMs() {
+ return window.performance && window.performance.now ? window.performance.now() : Date.now();
+ }
+
+ function gestureModeFor(button, mods) {
+ // button: 0 left, 1 middle, 2 right.
+ if (button === 1) return 'pan';
+ if (button === 2) return mods.shift ? 'rotate' : 'zoom';
+ if (button !== 0) return null;
+ if (mods.ctrl && mods.shift) return 'zoom';
+ if (mods.ctrl) return 'roll'; // VTK spin
+ if (mods.shift) return 'pan';
+ if (mods.alt) return 'rotate'; // VTK ignores Alt: falls back to rotate
+ return null; // plain left drag -> plotly's native rotate
+ }
+
+ function applyGesture(camera, mode, dx, dy) {
+ // Mirror the maths gl-plot3d uses for its own mouse handler so the feel
+ // matches; dx/dy are normalised by the viewport height.
+ var view = camera.view;
+ var t = nowMs();
+ var distance = Math.exp(view.computedRadius[0]);
+ var speed = camera.translateSpeed || 1;
+ var drot = Math.PI * (camera.rotateSpeed || 1);
+ if (mode === 'rotate') {
+ view.rotate(t, -drot * dx, drot * dy, 0);
+ } else if (mode === 'pan') {
+ view.pan(t, -speed * dx * distance, speed * dy * distance, 0);
+ } else if (mode === 'zoom') {
+ view.pan(t, 0, 0, distance * (Math.exp(-3.0 * dy) - 1));
+ } else if (mode === 'roll') {
+ view.rotate(t, 0, 0, drot * dx);
+ }
+ }
+
+ function installGestureHandlers(gd) {
+ if (gesturesReady) return;
+ gesturesReady = true;
+
+ // Capture phase: run before plotly's own (bubble-phase) camera listener
+ // on the scene container, so keyBindingMode is already off when it sees
+ // the event and it no-ops for this gesture.
+ gd.addEventListener('mousedown', function (ev) {
+ if (ev.button !== 0 && ev.button !== 1 && ev.button !== 2) return;
+ var mode = gestureModeFor(ev.button, {
+ ctrl: ev.ctrlKey, alt: ev.altKey, shift: ev.shiftKey
+ });
+ if (!mode) return;
+ var camera = plotCamera();
+ if (!camera) return;
+ camera.keyBindingMode = false;
+ gesture = { mode: mode, x: ev.clientX, y: ev.clientY };
+ }, true);
+
+ window.addEventListener('mousemove', function (ev) {
+ if (!gesture) return;
+ var camera = plotCamera();
+ if (!camera) { gesture = null; return; }
+ // A Plotly.react mid-gesture re-enables plotly's handler; keep it off.
+ camera.keyBindingMode = false;
+ var height = camera.element.clientHeight || 1;
+ var dx = (ev.clientX - gesture.x) / height;
+ var dy = (ev.clientY - gesture.y) / height;
+ gesture.x = ev.clientX;
+ gesture.y = ev.clientY;
+ applyGesture(camera, gesture.mode, dx, dy);
+ }, true);
+
+ window.addEventListener('mouseup', function () {
+ if (!gesture) return;
+ var camera = plotCamera();
+ gesture = null;
+ // Restore plotly's rotate binding. Its mouseup runs with buttons === 0,
+ // so it only refreshes its bookkeeping and never jumps the camera.
+ if (camera) camera.keyBindingMode = 'rotate';
+ }, true);
}
window.otkoSetCamera = function (cameraJson) {
Plotly.relayout('plot', { 'scene.camera': JSON.parse(cameraJson) });
};
+ // --- frame animation ---------------------------------------------------
+ // A pre-built frame list is pushed once and played by plotly itself, so a
+ // mode shape / time history animates in-page instead of re-reacting the
+ // whole figure ~30x per second from Python.
+ window.otkoAnimate = function (payloadJson, durationMs, loops, preserveView) {
+ var payload;
+ try { payload = JSON.parse(payloadJson); } catch (err) {
+ if (window.console) console.error('otko: bad animation payload', err);
+ return;
+ }
+ pendingUpdate = null; // the animation owns the graph div
+ var names = payload.frames.map(function (frame, index) {
+ frame.name = 'otko-' + index;
+ return frame.name;
+ });
+ var sequence = [];
+ var repeat = Math.max(1, loops || 1);
+ for (var i = 0; i < repeat; i++) { sequence = sequence.concat(names); }
+ mergeView(payload, preserveView ? currentView() : null);
+ Plotly.react('plot', payload.data, payload.layout, config).then(function () {
+ return Plotly.addFrames('plot', payload.frames);
+ }).then(function () {
+ return Plotly.animate('plot', sequence, {
+ frame: { duration: durationMs, redraw: true },
+ transition: { duration: 0 },
+ fromcurrent: false,
+ mode: 'immediate'
+ });
+ }).then(function () {
+ installHandlers();
+ }, function (err) {
+ // An interrupt (a newer animate call, or otkoStopAnimation) rejects with
+ // no reason; only surface real failures.
+ if (err && window.console) console.error('otko: animate failed', err);
+ });
+ };
+
+ window.otkoStopAnimation = function () {
+ Plotly.animate('plot', [], { mode: 'immediate', transition: { duration: 0 } });
+ };
+
window.otkoSetSnapEnabled = function (on) {
snapEnabled = !!on;
if (!snapEnabled) setSnapMarker(null);
diff --git a/src/otko/views/canvas_plotly/plotly_canvas.py b/src/otko/views/canvas_plotly/plotly_canvas.py
index ddecb15..1ea3306 100644
--- a/src/otko/views/canvas_plotly/plotly_canvas.py
+++ b/src/otko/views/canvas_plotly/plotly_canvas.py
@@ -38,6 +38,7 @@ from otko.views.canvas_plotly.trace_builder import (
PlotlyTraceBuilder,
Scene,
SceneOptions,
+ framed_camera_distance,
)
#: View preset directions (unit-ish vectors from the scene centre to the eye).
@@ -149,7 +150,9 @@ class PlotlyCanvas(QWidget):
#: Force diagrams and off-screen video capture are not implemented on
#: this backend yet (both are PyVista-specific today).
- capabilities = CanvasCapabilities(diagrams=False, animation_export=False)
+ capabilities = CanvasCapabilities(
+ diagrams=False, animation_export=False, in_page_animation=True
+ )
def __init__(
self,
@@ -170,6 +173,7 @@ class PlotlyCanvas(QWidget):
self._parallel = False
self._view_preset = "iso"
self._snap_enabled = False
+ self._show_undeformed = False
self._default_selection_enabled = True
self._working_plane: tuple[str, float] | None = None
self._camera = _CameraShim(self)
@@ -308,6 +312,45 @@ class PlotlyCanvas(QWidget):
self._options = replace(self._options, show_local_axes=bool(enabled))
self.render()
+ def set_show_undeformed(self, enabled: bool) -> None:
+ """Faint undeformed reference behind a deformed / modal shape."""
+ self._show_undeformed = bool(enabled)
+ self.render()
+
+ def base_scene_options(self) -> SceneOptions:
+ """The current display options, for callers building animation frames."""
+ return replace(self._options, show_undeformed=self._show_undeformed)
+
+ def animate(
+ self,
+ options: list[SceneOptions],
+ *,
+ duration_ms: int = 40,
+ loops: int = 100,
+ ) -> None:
+ """Play a pre-built list of scenes as an in-page plotly animation.
+
+ Each entry's traces are built once and handed to plotly's frame
+ machinery, so playback does not round-trip through Python per frame.
+ """
+ if not self._ready or not options:
+ return
+ frames = [self._builder.build(self._project, opts).data for opts in options]
+ payload = json.dumps(
+ {
+ "data": frames[0],
+ "frames": [{"data": frame} for frame in frames],
+ "layout": dict(self._scene.layout),
+ }
+ )
+ self._eval(
+ f"window.otkoAnimate({json.dumps(payload)}, {int(duration_ms)}, {int(loops)}, true)"
+ )
+
+ def stop_animation(self) -> None:
+ """Stop any in-page plotly animation."""
+ self._eval("window.otkoStopAnimation()")
+
def set_style(self, style: RenderStyle) -> None:
"""Swap the visual style and repaint the figure.
@@ -344,7 +387,10 @@ class PlotlyCanvas(QWidget):
``reset_camera``) sends the computed framing. Style changes are
non-framing: they re-colour in place.
"""
- self._scene = self._builder.build(self._project, self._options)
+ self._scene = self._builder.build(
+ self._project,
+ replace(self._options, show_undeformed=self._show_undeformed),
+ )
if not self._ready:
# Nothing to push yet; crucially this must come *before* the
# framing flag is consumed, or the framing scheduled before
@@ -363,20 +409,31 @@ class PlotlyCanvas(QWidget):
self._eval(f"window.otkoUpdate({json.dumps(payload)}, {_js_bool(not re_framed)})")
def _camera_dict(self, scene: Scene) -> dict[str, Any]:
- cx, cy, cz = scene.center
- distance = max(scene.diagonal, 1e-6) * 1.6
+ """A framing camera in plotly's normalized scene coordinates.
+
+ plotly does not use data units for ``scene.camera``: gl-plot3d scales
+ the scene box by the trace extents and re-centres it on the origin, so
+ the camera lives in a normalized space (the origin is the model centre
+ and the default eye is only ~1.25 away). Passing a data-unit eye — the
+ old ``diagonal * 1.6`` — parked the camera hundreds of normalized units
+ out and rendered the model as a speck. So: centre on the origin, and
+ take the eye distance from the model's *normalized* bounding sphere.
+ """
+ distance = framed_camera_distance(scene)
direction = _VIEW_DIRECTIONS.get(self._view_preset, _VIEW_DIRECTIONS["iso"])
norm = math.sqrt(sum(component * component for component in direction)) or 1.0
eye = (
- cx + direction[0] / norm * distance,
- cy + direction[1] / norm * distance,
- cz + direction[2] / norm * distance,
+ direction[0] / norm * distance,
+ direction[1] / norm * distance,
+ direction[2] / norm * distance,
)
- # Looking straight down the Z axis needs a non-degenerate up vector.
- up = (0.0, 1.0, 0.0) if self._view_preset == "xy" else (0.0, 0.0, 1.0)
+ # Turntable dragmode pins up to +Z; the turntable controller derives a
+ # well-defined screen-up from the view angle even for the straight-down
+ # Top (XY) preset, so no special-case up vector is needed.
+ up = (0.0, 0.0, 1.0)
return {
"eye": {"x": eye[0], "y": eye[1], "z": eye[2]},
- "center": {"x": cx, "y": cy, "z": cz},
+ "center": {"x": 0.0, "y": 0.0, "z": 0.0},
"up": {"x": up[0], "y": up[1], "z": up[2]},
"projection": {"type": "orthographic" if self._parallel else "perspective"},
}
diff --git a/src/otko/views/canvas_plotly/trace_builder.py b/src/otko/views/canvas_plotly/trace_builder.py
index ebe5e13..37c0577 100644
--- a/src/otko/views/canvas_plotly/trace_builder.py
+++ b/src/otko/views/canvas_plotly/trace_builder.py
@@ -24,7 +24,9 @@ tagged ``meta={"kind": "node" | "element" | "snap"}`` and the JS side reads
from __future__ import annotations
-from dataclasses import dataclass, field
+import math
+from dataclasses import dataclass, field, replace
+from itertools import pairwise
from typing import Any
import numpy as np
@@ -76,7 +78,7 @@ _BOX_TRIS = (
(1, 6, 5),
)
-#: Support kind → plotly 3D marker symbol.
+#: Support kind → plotly 3D marker symbol (fallback for rotation-only supports).
_SUPPORT_SYMBOLS = {
"fix": "square",
"pin": "triangle-up",
@@ -88,6 +90,18 @@ _NODE_MARKER_SIZE = 7.0
_SUPPORT_MARKER_SIZE = 11.0
_SNAP_MARKER_SIZE = 8.0
+#: Distinct colours cycled across load patterns (opstool tints each pattern).
+_PATTERN_PALETTE = (
+ "#1f77b4",
+ "#ff7f0e",
+ "#2ca02c",
+ "#d62728",
+ "#9467bd",
+ "#8c564b",
+ "#e377c2",
+ "#17becf",
+)
+
@dataclass(frozen=True)
class SceneOptions:
@@ -102,6 +116,13 @@ class SceneOptions:
show_element_labels: bool = False
show_extrusions: bool = False
show_local_axes: bool = False
+ #: Draw the undeformed shape faintly behind a deformed / modal shape.
+ show_undeformed: bool = False
+ #: Per-node scalar response (aligned with ``project.nodes``), coloured
+ #: through a shared colour axis with a colorbar — opstool's contour recipe.
+ scalars: Any = None
+ scalar_label: str = ""
+ scalar_clim: tuple[float, float] | None = None
@dataclass
@@ -114,6 +135,9 @@ class Scene:
diagonal: float = 1.0
#: Padded ``(min, max)`` per axis, used to frame the camera deterministically.
axis_bounds: dict[str, tuple[float, float]] = field(default_factory=dict)
+ #: Unpadded model ``(min, max)`` per axis (no grid), used to normalise the
+ #: camera the same way plotly normalises the scene box.
+ data_bounds: dict[str, tuple[float, float]] = field(default_factory=dict)
def to_payload(self) -> dict[str, Any]:
"""Figure dict without the camera — camera is owned by the widget."""
@@ -213,6 +237,54 @@ def _diag_of_bounds(bounds: dict[str, tuple[float, float]]) -> float:
return diagonal if diagonal > 0 else 1.0
+def _raw_axis_bounds(pts: np.ndarray | None) -> dict[str, tuple[float, float]]:
+ """Unpadded model ``(min, max)`` per axis.
+
+ plotly scales the scene box by the *trace* extents, so the camera frame
+ distance has to be computed from these (grid-free, unpadded) bounds.
+ Degenerate axes keep a zero extent; callers substitute a unit scale.
+ """
+ if pts is None or len(pts) == 0:
+ return {name: (0.0, 0.0) for name in ("x", "y", "z")}
+ lower = np.asarray(pts, dtype=float).min(axis=0)
+ upper = np.asarray(pts, dtype=float).max(axis=0)
+ return {
+ name: (float(lower[index]), float(upper[index]))
+ for index, name in enumerate(("x", "y", "z"))
+ }
+
+
+#: gl-plot3d's fixed vertical field of view (radians).
+_FOV_Y = math.pi / 4
+#: How much of the viewport the model's bounding sphere should span.
+_FRAME_MARGIN = 1.25
+
+
+def framed_camera_distance(scene: Scene) -> float:
+ """Eye distance, in plotly's normalized scene units, that fits the model.
+
+ ``layout.scene.camera`` is not in data units: gl-plot3d re-centres the
+ scene on the origin and, with ``aspectmode`` ``data``, scales each axis by
+ ``product(data_scale) ** (1/3) / data_scale`` (plotly's ``scene.js``) — so
+ the default eye is only ~1.25 away. Mirror that to get the model's
+ bounding-sphere radius in the camera's own units, then back off by half the
+ field of view so the model fills the viewport with a small margin.
+ """
+ bounds = scene.data_bounds or scene.axis_bounds
+ if len(bounds) < 3:
+ return 1.6
+ scales = []
+ for low, high in bounds.values():
+ extent = high - low
+ scales.append(1.0 / extent if extent > 1e-12 else 1.0)
+ axis_scale = (scales[0] * scales[1] * scales[2]) ** (1.0 / 3.0)
+ aspect = [axis_scale / scale for scale in scales]
+ radius = 0.5 * math.sqrt(sum(value * value for value in aspect))
+ if radius <= 1e-12:
+ return 1.6
+ return radius / math.sin(_FOV_Y / 2.0) * _FRAME_MARGIN
+
+
def _frame_basis(el: Any, x_local: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
"""Local (y, z) basis — mirrors ``ModelRenderer._frame_basis``."""
x = x_local / float(np.linalg.norm(x_local))
@@ -262,6 +334,104 @@ def _classify_support(restraint: tuple[bool, ...], dof_idx: tuple[int, ...]) ->
return "custom"
+def _scalar_clim(scalars: Any, clim: tuple[float, float] | None) -> tuple[float, float]:
+ """Colour limits for a scalar array, falling back to its finite range."""
+ if clim is not None:
+ return float(clim[0]), float(clim[1])
+ values = np.asarray(scalars, dtype=float).ravel()
+ values = values[np.isfinite(values)]
+ if not len(values):
+ return 0.0, 1.0
+ low, high = float(values.min()), float(values.max())
+ if high <= low:
+ high = low + 1.0
+ return low, high
+
+
+def _support_loops(
+ coord: tuple[float, float, float],
+ restraint: tuple[bool, ...],
+ size: float,
+ ndm: int,
+) -> list[list[tuple[float, float, float]]]:
+ """Closed polylines for a support's restrained translation DOFs.
+
+ Adapted from opstool's ``_get_bc_points_3d`` / ``_get_bc_points_2d``
+ (GPL-3.0; see ``NOTICE``). Each fixed translation axis gets a plate
+ perpendicular to it; a 2D roller gets a circle. Returns an empty list when
+ only rotations are restrained (the caller falls back to a marker).
+ """
+ x, y, z = coord
+ s = size
+ loops: list[list[tuple[float, float, float]]] = []
+ if ndm >= 3:
+ if restraint[0]:
+ loops.append(
+ [
+ (x, y - s / 2, z - s / 2),
+ (x, y + s / 2, z - s / 2),
+ (x, y + s / 2, z + s / 2),
+ (x, y - s / 2, z + s / 2),
+ (x, y - s / 2, z - s / 2),
+ ]
+ )
+ if restraint[1]:
+ loops.append(
+ [
+ (x - s / 2, y, z - s / 2),
+ (x + s / 2, y, z - s / 2),
+ (x + s / 2, y, z + s / 2),
+ (x - s / 2, y, z + s / 2),
+ (x - s / 2, y, z - s / 2),
+ ]
+ )
+ if restraint[2]:
+ loops.append(
+ [
+ (x - s / 2, y - s / 2, z),
+ (x + s / 2, y - s / 2, z),
+ (x + s / 2, y + s / 2, z),
+ (x - s / 2, y + s / 2, z),
+ (x - s / 2, y - s / 2, z),
+ ]
+ )
+ elif restraint[2]:
+ yb = y - s / 2
+ loops.append(
+ [
+ (x - s / 2, yb - s / 2, z),
+ (x + s / 2, yb - s / 2, z),
+ (x + s / 2, yb + s / 2, z),
+ (x - s / 2, yb + s / 2, z),
+ (x - s / 2, yb - s / 2, z),
+ ]
+ )
+ elif restraint[0] and restraint[1]:
+ loops.append(
+ [
+ (x - s * 0.5, y - s, z),
+ (x + s * 0.5, y - s, z),
+ (x, y, z),
+ (x - s * 0.5, y - s, z),
+ ]
+ )
+ elif restraint[0] or restraint[1]:
+ angles = np.linspace(0.0, 2.0 * np.pi, 17)
+ ox = x - s / 2 if restraint[0] else x
+ oy = y - s / 2 if restraint[1] else y
+ loops.append(
+ [
+ (
+ float(ox + 0.5 * s * math.cos(angle)),
+ float(oy + 0.5 * s * math.sin(angle)),
+ z,
+ )
+ for angle in angles
+ ]
+ )
+ return loops
+
+
def _line_trace(
segments: list[tuple[tuple[float, float, float], tuple[float, float, float]]],
*,
@@ -318,12 +488,28 @@ class PlotlyTraceBuilder:
nodes = list(project.nodes)
node_ids = [n.id for n in nodes]
points = np.array([n.coords for n in nodes], dtype=float) if nodes else np.empty((0, 3))
+ original_points = points.copy()
if opts.deformation is not None and len(points):
points = np.asarray(opts.deformation.shifted(points, node_ids), dtype=float)
node_row = {nid: i for i, nid in enumerate(node_ids)}
+ # Response colouring: auto-derive a per-node scalar from the deformation
+ # source (displacement magnitude) unless the caller supplied one.
+ if opts.scalars is None and opts.deformation is not None:
+ get_magnitudes = getattr(opts.deformation, "magnitudes", None)
+ if callable(get_magnitudes) and len(node_ids):
+ opts = replace(
+ opts,
+ scalars=get_magnitudes(node_ids),
+ scalar_label=opts.scalar_label or "|u|",
+ )
+ elif opts.scalars is not None:
+ opts = replace(opts, scalars=np.asarray(opts.scalars, dtype=float))
+
data: list[dict[str, Any]] = []
grid_pts = self._build_grid(project, data, opts)
+ if opts.show_undeformed and opts.deformation is not None and len(points):
+ self._build_undeformed_reference(project, data, original_points, node_row)
self._build_extrusions(project, data, opts)
self._build_local_axes(project, data, opts)
self._build_loads(project, data, opts)
@@ -332,18 +518,24 @@ class PlotlyTraceBuilder:
self._build_nodes(data, opts, points, node_ids)
self._build_labels(project, data, opts, points, node_row)
- candidates = [points] if len(points) else []
- if grid_pts is not None:
- candidates.append(grid_pts)
- all_pts = np.vstack(candidates) if candidates else np.empty((0, 3))
- center = tuple(np.mean(all_pts, axis=0)) if len(all_pts) else (0.0, 0.0, 0.0)
- bounds = _padded_axis_bounds(all_pts)
+ # Frame the structure, not the (often much larger) reference grid:
+ # SAP-style "zoom extents" fits the model. The grid still draws, but
+ # does not shrink the model into a corner of the viewport.
+ if len(points):
+ frame_pts = points
+ elif grid_pts is not None:
+ frame_pts = grid_pts
+ else:
+ frame_pts = np.empty((0, 3))
+ center = tuple(np.mean(frame_pts, axis=0)) if len(frame_pts) else (0.0, 0.0, 0.0)
+ bounds = _padded_axis_bounds(frame_pts)
return Scene(
data=data,
layout=self._layout(),
center=(float(center[0]), float(center[1]), float(center[2])),
diagonal=_diag_of_bounds(bounds),
axis_bounds=bounds,
+ data_bounds=_raw_axis_bounds(frame_pts),
)
# ── layout ───────────────────────────────────────────────────────
@@ -376,7 +568,10 @@ class PlotlyTraceBuilder:
"scene": {
"bgcolor": style.background_bottom,
"aspectmode": "data",
- "dragmode": "orbit",
+ # Turntable (plotly's CAD-style orbit) locks ``camera.up`` to
+ # +Z, so the horizon stays level. plotly's ``orbit`` mode
+ # rotates the up vector instead and tips the model over.
+ "dragmode": "turntable",
"xaxis": axis(style.fix_color, "X"),
"yaxis": axis(style.load_color, "Y"),
"zaxis": axis(style.truss_color, "Z"),
@@ -526,12 +721,41 @@ class PlotlyTraceBuilder:
) -> None:
if not len(points):
return
- colors = [
- self._style.node_selected_color
- if nid in opts.selection_nodes
- else self._style.node_color
- for nid in node_ids
- ]
+ scalars = opts.scalars
+ if scalars is not None and len(scalars) == len(points):
+ low, high = _scalar_clim(scalars, opts.scalar_clim)
+ marker: dict[str, Any] = {
+ "color": [float(value) for value in scalars],
+ "colorscale": self._style.response_colorscale(),
+ "cmin": low,
+ "cmax": high,
+ "size": _NODE_MARKER_SIZE,
+ "line": {"color": "#4d4d4d", "width": 1},
+ "showscale": True,
+ "colorbar": {
+ "title": {"text": opts.scalar_label or "value", "side": "right"},
+ "thickness": 14,
+ "len": 0.6,
+ },
+ }
+ customdata: list[Any] = [
+ [int(nid), float(value)] for nid, value in zip(node_ids, scalars, strict=True)
+ ]
+ hovertemplate = "Node #%{customdata[0]}
%{customdata[1]:.4g}"
+ else:
+ colors = [
+ self._style.node_selected_color
+ if nid in opts.selection_nodes
+ else self._style.node_color
+ for nid in node_ids
+ ]
+ marker = {
+ "color": colors,
+ "size": _NODE_MARKER_SIZE,
+ "line": {"color": "#4d4d4d", "width": 1},
+ }
+ customdata = list(node_ids)
+ hovertemplate = "Node #%{customdata}"
data.append(
{
"type": "scatter3d",
@@ -539,16 +763,12 @@ class PlotlyTraceBuilder:
"x": [float(p[0]) for p in points],
"y": [float(p[1]) for p in points],
"z": [float(p[2]) for p in points],
- "marker": {
- "color": colors,
- "size": _NODE_MARKER_SIZE,
- "line": {"color": "#4d4d4d", "width": 1},
- },
- "customdata": list(node_ids),
+ "marker": marker,
+ "customdata": customdata,
"meta": {"kind": "node"},
# Engineering-notation hover (opstool's trace recipe) so a
# hover identifies the entity instead of showing the raw id.
- "hovertemplate": "Node #%{customdata}",
+ "hovertemplate": hovertemplate,
"name": "nodes",
"showlegend": False,
}
@@ -573,13 +793,16 @@ class PlotlyTraceBuilder:
"""
if not len(points):
return
+ scalar_values: np.ndarray | None = None
+ if opts.scalars is not None and len(opts.scalars) == len(points):
+ scalar_values = np.asarray(opts.scalars, dtype=float)
scale_colors = family_palette(self._style)
selected_index = len(scale_colors) - 1
x: list[float | None] = []
y: list[float | None] = []
z: list[float | None] = []
- color_index: list[float] = []
+ color_value: list[float | None] = []
customdata: list[Any] = []
for el in project.elements:
if not isinstance(el, _FRAME_CLASSES):
@@ -588,18 +811,40 @@ class PlotlyTraceBuilder:
j = node_row.get(el.nodes[1])
if i is None or j is None:
continue
- index = float(
- selected_index if el.id in opts.selection_elements else element_family_index(el)
- )
x.extend([float(points[i][0]), float(points[j][0]), None])
y.extend([float(points[i][1]), float(points[j][1]), None])
z.extend([float(points[i][2]), float(points[j][2]), None])
- color_index.extend([index, index, index])
+ if scalar_values is not None:
+ color_value.extend([float(scalar_values[i]), float(scalar_values[j]), None])
+ else:
+ index = float(
+ selected_index if el.id in opts.selection_elements else element_family_index(el)
+ )
+ color_value.extend([index, index, index])
customdata.extend([el.id, el.id, None])
if not x:
return
- count = len(scale_colors)
+ if scalar_values is not None:
+ low, high = _scalar_clim(scalar_values, opts.scalar_clim)
+ line: dict[str, Any] = {
+ "color": color_value,
+ "colorscale": self._style.response_colorscale(),
+ "cmin": low,
+ "cmax": high,
+ "width": 4,
+ }
+ else:
+ count = len(scale_colors)
+ line = {
+ "color": color_value,
+ "colorscale": [
+ (index / (count - 1), color) for index, color in enumerate(scale_colors)
+ ],
+ "cmin": 0,
+ "cmax": count - 1,
+ "width": 4,
+ }
data.append(
{
"type": "scatter3d",
@@ -607,15 +852,7 @@ class PlotlyTraceBuilder:
"x": x,
"y": y,
"z": z,
- "line": {
- "color": color_index,
- "colorscale": [
- (index / (count - 1), color) for index, color in enumerate(scale_colors)
- ],
- "cmin": 0,
- "cmax": count - 1,
- "width": 4,
- },
+ "line": line,
"customdata": customdata,
"meta": {"kind": "element"},
"hovertemplate": "Element #%{customdata}",
@@ -624,34 +861,103 @@ class PlotlyTraceBuilder:
}
)
+ def _build_undeformed_reference(
+ self,
+ project: Project,
+ data: list[dict[str, Any]],
+ original_points: np.ndarray,
+ node_row: dict[int, int],
+ ) -> None:
+ """Faint grey wireframe of the undeformed shape (opstool ``show_origin``)."""
+ x: list[float | None] = []
+ y: list[float | None] = []
+ z: list[float | None] = []
+ for el in project.elements:
+ if not isinstance(el, _FRAME_CLASSES):
+ continue
+ i = node_row.get(el.nodes[0])
+ j = node_row.get(el.nodes[1])
+ if i is None or j is None:
+ continue
+ x.extend([float(original_points[i][0]), float(original_points[j][0]), None])
+ y.extend([float(original_points[i][1]), float(original_points[j][1]), None])
+ z.extend([float(original_points[i][2]), float(original_points[j][2]), None])
+ if not x:
+ return
+ data.append(
+ {
+ "type": "scatter3d",
+ "mode": "lines",
+ "x": x,
+ "y": y,
+ "z": z,
+ "line": {"color": "#9aa3ad", "width": 1},
+ "opacity": 0.45,
+ "hoverinfo": "skip",
+ "name": "undeformed-reference",
+ "showlegend": False,
+ }
+ )
+
def _build_supports(
self, project: Project, data: list[dict[str, Any]], opts: SceneOptions
) -> None:
+ """Oriented support glyphs for each restrained translation DOF.
+
+ Ported and modified from opstool's ``_get_bc_points_3d/_2d`` (GPL-3.0;
+ see ``NOTICE``): a fixed axis is drawn as a plate perpendicular to it,
+ a roller as a circle, so the restrained directions are legible instead
+ of a generic square/triangle marker.
+ """
if not project.nodes:
return
+ pts = np.array([n.coords for n in project.nodes], dtype=float)
+ size = max(_diag_of_points(pts) * 0.03, 1e-6)
+ ndm = int(getattr(project, "ndm", 3))
+ segments: list[tuple[tuple[float, float, float], tuple[float, float, float]]] = []
+ markers: list[Any] = []
dof_idx = _dof_indices(project.ndf)
- groups: dict[str, list[Any]] = {}
for node in project.nodes:
- if not any(node.restraint[i] for i in dof_idx):
+ restraint = tuple(bool(flag) for flag in node.restraint)
+ if not any(restraint[index] for index in dof_idx):
continue
- kind = _classify_support(node.restraint, dof_idx)
- groups.setdefault(kind, []).append(node)
- for kind, nodes in groups.items():
+ loops = _support_loops(
+ (float(node.coords[0]), float(node.coords[1]), float(node.coords[2])),
+ restraint,
+ size,
+ ndm,
+ )
+ if loops:
+ for loop in loops:
+ for a, b in pairwise(loop):
+ segments.append((a, b))
+ else:
+ markers.append(node)
+ if segments:
+ data.append(
+ _line_trace(
+ segments,
+ color=self._style.support_color,
+ width=3,
+ name="supports",
+ )
+ )
+ if markers:
data.append(
{
"type": "scatter3d",
"mode": "markers",
- "x": [float(n.coords[0]) for n in nodes],
- "y": [float(n.coords[1]) for n in nodes],
- "z": [float(n.coords[2]) for n in nodes],
+ "x": [float(n.coords[0]) for n in markers],
+ "y": [float(n.coords[1]) for n in markers],
+ "z": [float(n.coords[2]) for n in markers],
"marker": {
"color": self._style.support_color,
"size": _SUPPORT_MARKER_SIZE,
- "symbol": _SUPPORT_SYMBOLS[kind],
+ "symbol": "square",
"line": {"color": "#7f3f00", "width": 1},
},
"hoverinfo": "skip",
- "name": f"support-{kind}",
+ "name": "supports",
"showlegend": False,
}
)
@@ -660,6 +966,12 @@ class PlotlyTraceBuilder:
def _build_loads(
self, project: Project, data: list[dict[str, Any]], opts: SceneOptions
) -> None:
+ """Arrow glyphs for nodal and distributed loads.
+
+ Arrow length is proportional to the load magnitude (opstool scales by
+ ``|F| / max|F|``), so a 1 kN and a 10 kN load no longer look identical,
+ and each load pattern gets its own colour plus a hover readout.
+ """
if not project.load_patterns or not project.nodes:
return
node_by_id = {n.id: n for n in project.nodes}
@@ -667,22 +979,16 @@ class PlotlyTraceBuilder:
pts = np.array([n.coords for n in project.nodes], dtype=float)
scale = max(_diag_of_points(pts) * 0.05, 1e-6)
- nodal_x: list[float] = []
- nodal_y: list[float] = []
- nodal_z: list[float] = []
- nodal_u: list[float] = []
- nodal_v: list[float] = []
- nodal_w: list[float] = []
- dist_x: list[float] = []
- dist_y: list[float] = []
- dist_z: list[float] = []
- dist_u: list[float] = []
- dist_v: list[float] = []
- dist_w: list[float] = []
+ patterns = [
+ pattern for pattern in project.load_patterns if isinstance(pattern, PlainLoadPattern)
+ ]
+ if not patterns:
+ return
- for pattern in project.load_patterns:
- if not isinstance(pattern, PlainLoadPattern):
- continue
+ # (pattern index, tail, unit direction, magnitude, subject label)
+ nodal: list[tuple[int, np.ndarray, np.ndarray, float, str]] = []
+ dist: list[tuple[int, np.ndarray, np.ndarray, float, str]] = []
+ for pat_idx, pattern in enumerate(patterns):
for nload in pattern.nodal_loads:
if not isinstance(nload, NodalLoad):
continue
@@ -693,15 +999,15 @@ class PlotlyTraceBuilder:
mag = float(np.linalg.norm(f))
if mag < 1e-12:
continue
- direction = f / mag
- tail = np.asarray(node.coords, dtype=float) - direction * scale
- nodal_x.append(float(tail[0]))
- nodal_y.append(float(tail[1]))
- nodal_z.append(float(tail[2]))
- nodal_u.append(float(direction[0]))
- nodal_v.append(float(direction[1]))
- nodal_w.append(float(direction[2]))
-
+ nodal.append(
+ (
+ pat_idx,
+ np.asarray(node.coords, dtype=float),
+ f / mag,
+ mag,
+ f"N{nload.node_id}",
+ )
+ )
for eload in pattern.element_loads:
if not isinstance(eload, UniformElementLoad):
continue
@@ -730,45 +1036,60 @@ class PlotlyTraceBuilder:
if mag < 1e-12:
continue
direction = load_vec / mag
- n_arrows = 5
- for k in range(n_arrows):
- t = (k + 0.5) / n_arrows
- tail = pi + t * axis - direction * (0.4 * scale)
- dist_x.append(float(tail[0]))
- dist_y.append(float(tail[1]))
- dist_z.append(float(tail[2]))
- dist_u.append(float(direction[0]))
- dist_v.append(float(direction[1]))
- dist_w.append(float(direction[2]))
+ for k in range(5):
+ t = (k + 0.5) / 5.0
+ dist.append((pat_idx, pi + t * axis, direction, mag, f"E{eload.element_id}"))
- if nodal_x:
- data.append(
- _cone_trace(
- nodal_x,
- nodal_y,
- nodal_z,
- nodal_u,
- nodal_v,
- nodal_w,
- color=self._style.nodal_load_color,
- name="nodal-loads",
- size=scale,
+ max_mag = max((entry[3] for entry in (*nodal, *dist)), default=0.0)
+ if max_mag <= 0.0:
+ return
+ colors = self._pattern_colors(len(patterns))
+ # With a single pattern there is nothing to distinguish, so keep the
+ # per-type default tints (nodal vs element loads).
+ single = len(patterns) == 1
+
+ def _arrow_len(mag: float) -> float:
+ return max(scale * mag / max_mag, 0.15 * scale)
+
+ for pat_idx, pattern in enumerate(patterns):
+ label = getattr(pattern, "name", "") or f"Pattern {pat_idx + 1}"
+ for group, name, width, default in (
+ (nodal, "nodal-loads", 0.12, self._style.nodal_load_color),
+ (dist, "element-loads", 0.12, self._style.element_load_color),
+ ):
+ entries = [entry for entry in group if entry[0] == pat_idx]
+ if not entries:
+ continue
+ color = default if single else colors[pat_idx]
+ x, y, z, u, v, w, hovers = [], [], [], [], [], [], []
+ for _idx, tail, direction, mag, subject in entries:
+ length = _arrow_len(mag)
+ x.append(float(tail[0]))
+ y.append(float(tail[1]))
+ z.append(float(tail[2]))
+ u.append(float(direction[0] * length))
+ v.append(float(direction[1] * length))
+ w.append(float(direction[2] * length))
+ hovers.append(f"{label} · {subject}
|F| = {mag:.4g}")
+ data.append(
+ _cone_trace(
+ x,
+ y,
+ z,
+ u,
+ v,
+ w,
+ color=color,
+ name=name,
+ size=width,
+ customdata=hovers,
+ )
)
- )
- if dist_x:
- data.append(
- _cone_trace(
- dist_x,
- dist_y,
- dist_z,
- dist_u,
- dist_v,
- dist_w,
- color=self._style.element_load_color,
- name="element-loads",
- size=0.6 * scale,
- )
- )
+
+ def _pattern_colors(self, count: int) -> list[str]:
+ """One palette colour per load pattern (used only when count > 1)."""
+ palette = _PATTERN_PALETTE
+ return [palette[index % len(palette)] for index in range(count)]
def _build_local_axes(
self, project: Project, data: list[dict[str, Any]], opts: SceneOptions
@@ -814,9 +1135,10 @@ class PlotlyTraceBuilder:
bucket["x"].append(float(mid[0]))
bucket["y"].append(float(mid[1]))
bucket["z"].append(float(mid[2]))
- bucket["u"].append(float(direction[0]))
- bucket["v"].append(float(direction[1]))
- bucket["w"].append(float(direction[2]))
+ # Cone length = (u, v, w) magnitude: scale to the model.
+ bucket["u"].append(float(direction[0] * cap))
+ bucket["v"].append(float(direction[1] * cap))
+ bucket["w"].append(float(direction[2] * cap))
for key, color in (("x", "#ff0000"), ("y", "#00bf00"), ("z", "#3366ff")):
bucket = axes[key]
if bucket["x"]:
@@ -830,7 +1152,7 @@ class PlotlyTraceBuilder:
bucket["w"],
color=color,
name=f"local-{key}",
- size=cap,
+ size=0.12,
)
)
@@ -958,9 +1280,17 @@ def _cone_trace(
*,
color: str,
name: str,
- size: float,
+ size: float = 0.4,
+ customdata: list[Any] | None = None,
) -> dict[str, Any]:
- return {
+ """A cone/arrow trace.
+
+ ``sizemode`` stays ``"scaled"``: cone size is then proportional to the
+ vector norm times the unitless ``sizeref``, so every arrow keeps the same
+ aspect ratio. ``"absolute"`` interprets ``sizeref`` against the vector
+ norm in *normalized* scene units, which rendered fat fins on large models.
+ """
+ trace: dict[str, Any] = {
"type": "cone",
"x": x,
"y": y,
@@ -969,7 +1299,7 @@ def _cone_trace(
"v": v,
"w": w,
"anchor": "tail",
- "sizemode": "absolute",
+ "sizemode": "scaled",
"sizeref": float(size),
"colorscale": [[0, color], [1, color]],
"showscale": False,
@@ -977,6 +1307,11 @@ def _cone_trace(
"name": name,
"showlegend": False,
}
+ if customdata is not None:
+ trace["customdata"] = customdata
+ trace["hovertemplate"] = "%{customdata}"
+ trace["hoverinfo"] = "text"
+ return trace
def _text_trace(
diff --git a/src/otko/views/dialogs/__init__.py b/src/otko/views/dialogs/__init__.py
index e4dff02..59bfb83 100644
--- a/src/otko/views/dialogs/__init__.py
+++ b/src/otko/views/dialogs/__init__.py
@@ -30,6 +30,7 @@ from otko.views.dialogs.locate_origin import (
from otko.views.dialogs.material_library import MaterialLibraryDialog
from otko.views.dialogs.material_tester import MaterialTesterDialog
from otko.views.dialogs.mirror import MirrorDialog
+from otko.views.dialogs.mouse_controls import MouseControlsDialog
from otko.views.dialogs.move import MoveDialog
from otko.views.dialogs.path_time_series import PathTimeSeriesDialog
from otko.views.dialogs.pattern_loads import PatternLoadsDialog
@@ -66,6 +67,7 @@ __all__ = [
"MaterialLibraryDialog",
"MaterialTesterDialog",
"MirrorDialog",
+ "MouseControlsDialog",
"MoveDialog",
"PathTimeSeriesDialog",
"PatternLoadsDialog",
diff --git a/src/otko/views/dialogs/mouse_controls.py b/src/otko/views/dialogs/mouse_controls.py
new file mode 100644
index 0000000..c3e9340
--- /dev/null
+++ b/src/otko/views/dialogs/mouse_controls.py
@@ -0,0 +1,68 @@
+"""Modeless Mouse Controls reference for the 3D viewport.
+
+Both canvas backends share the VTK trackball convention: the PyVista canvas
+uses it natively and the Plotly canvas re-implements it in JS, so the table
+below holds whichever backend is active.
+"""
+
+from __future__ import annotations
+
+from PySide6.QtWidgets import (
+ QDialog,
+ QDialogButtonBox,
+ QTextBrowser,
+ QVBoxLayout,
+ QWidget,
+)
+
+_MOUSE_HTML = """Mouse Controls
+The 3D viewport follows the VTK trackball convention on both canvas
+backends (Options → Canvas Backend).
+
+Navigate the view
+
+| Rotate | Left-drag |
+| Pan | Shift + left-drag, or middle-drag |
+| Zoom | Right-drag, or mouse wheel |
+| Spin (roll) | Ctrl + left-drag |
+| Zoom (from key) | Ctrl + Shift + left-drag |
+| Environment rotate | Shift + right-drag |
+
+Alt is not used for view navigation. Horizontal-wheel input rolls the
+Plotly view; on PyVista it has no effect.
+
+Select
+
+| Select | Left-click a node or element |
+| Add / toggle | Ctrl+click or Shift+click |
+
+A drag rotates the view; only a press-and-release without movement counts
+as a click, so panning never changes the selection.
+
+View presets
+
+| Isometric | Ctrl+1 |
+| Top (XY) | Ctrl+2 |
+| Front (XZ) | Ctrl+3 |
+| Right (YZ) | Ctrl+4 |
+| Zoom Extents | Ctrl+E |
+
+"""
+
+
+class MouseControlsDialog(QDialog):
+ """Modeless reference for viewport mouse navigation and selection."""
+
+ def __init__(self, parent: QWidget | None = None) -> None:
+ super().__init__(parent)
+ self.setWindowTitle("Mouse Controls")
+ self.setMinimumSize(460, 520)
+ layout = QVBoxLayout(self)
+ browser = QTextBrowser(self)
+ browser.setReadOnly(True)
+ browser.setOpenExternalLinks(False)
+ browser.setHtml(_MOUSE_HTML)
+ layout.addWidget(browser)
+ buttons = QDialogButtonBox(QDialogButtonBox.StandardButton.Close, parent=self)
+ buttons.rejected.connect(self.close)
+ layout.addWidget(buttons)
diff --git a/src/otko/views/dialogs/quick_guide.py b/src/otko/views/dialogs/quick_guide.py
index 9b0c424..3e1af3e 100644
--- a/src/otko/views/dialogs/quick_guide.py
+++ b/src/otko/views/dialogs/quick_guide.py
@@ -50,6 +50,10 @@ or Assign → Frame: Section…, Material…,
Show Force Diagram… and the other plot actions;
Display → Show Undeformed Shape, Clear Display or
Back to Model View (Ctrl+Shift+B) to return to the model.
+
+8 — Navigate the 3D view
+Left-drag rotates, Shift+left-drag (or middle-drag) pans, right-drag or the
+wheel zooms, Ctrl+left-drag spins. Full list under Help → Mouse Controls.
"""
diff --git a/src/otko/views/dock_manager.py b/src/otko/views/dock_manager.py
index cd34449..118da67 100644
--- a/src/otko/views/dock_manager.py
+++ b/src/otko/views/dock_manager.py
@@ -197,11 +197,44 @@ class DockManager:
animator.frameChanged.connect(_apply)
animator.closed.connect(self._on_back_to_model)
+ if self._canvas.capabilities.in_page_animation:
+ animator.playToggled.connect(
+ lambda playing: self._animate_mode_in_page(animator, playing)
+ )
animator.exportRequested.connect(
lambda: self._on_export_mode_shape(animator, _apply),
)
# Animator emits an initial frame in its constructor; nothing to do.
+ def _animate_mode_in_page(self, animator: object, playing: bool) -> None:
+ """Play the current mode shape with plotly's own frame animation."""
+ if not playing:
+ self._canvas.stop_animation()
+ return
+ if not isinstance(self._latest_results, ModalResults) or self._vm.project is None:
+ return
+ import math
+ from dataclasses import replace
+
+ n_frames = 36
+ period = max(float(animator.period_seconds()), 0.1) # type: ignore[attr-defined]
+ mode = int(animator.current_mode()) # type: ignore[attr-defined]
+ scale = float(animator.current_scale()) # type: ignore[attr-defined]
+ base = self._canvas.base_scene_options() # type: ignore[attr-defined]
+ options = []
+ for k in range(n_frames):
+ phase = math.sin(2.0 * math.pi * k / n_frames)
+ src = modal_to_deformation(
+ self._vm.project, self._latest_results, mode=mode, scale=scale, phase=phase
+ )
+ options.append(replace(base, deformation=src))
+ animator.set_in_page_mode(True) # type: ignore[attr-defined]
+ self._canvas.animate( # type: ignore[attr-defined]
+ options,
+ duration_ms=int(period * 1000 / n_frames),
+ loops=100,
+ )
+
def _on_export_mode_shape(self, animator, apply_callable) -> None: # type: ignore[no-untyped-def]
"""Capture one period of the current mode shape to MP4/GIF.
diff --git a/src/otko/views/docks/mode_shape_animator.py b/src/otko/views/docks/mode_shape_animator.py
index 4ecfc89..df40c93 100644
--- a/src/otko/views/docks/mode_shape_animator.py
+++ b/src/otko/views/docks/mode_shape_animator.py
@@ -28,6 +28,7 @@ class ModeShapeAnimator(QWidget):
"""
frameChanged = Signal(int, float, float)
+ playToggled = Signal(bool)
closed = Signal()
exportRequested = Signal()
@@ -41,6 +42,7 @@ class ModeShapeAnimator(QWidget):
self._n_modes = n_modes
self._freqs = frequencies_hz
self._t = 0.0
+ self._in_page = False
self._timer = QTimer(self)
self._timer.timeout.connect(self._on_tick)
self._timer.setInterval(int(1000 / self._FPS))
@@ -111,6 +113,17 @@ class ModeShapeAnimator(QWidget):
def current_scale(self) -> float:
return float(self._scale.value())
+ def period_seconds(self) -> float:
+ return float(self._period.value())
+
+ def set_in_page_mode(self, on: bool) -> None:
+ """While an in-page (plotly) animation plays, stop emitting frames.
+
+ The canvas animates itself; the Python timer keeps the scrubber in
+ sync but must not drive per-frame re-renders.
+ """
+ self._in_page = bool(on)
+
def set_results(self, results: object | None) -> None:
"""Rebind to a new modal run while the dock stays open.
@@ -174,6 +187,8 @@ class ModeShapeAnimator(QWidget):
self._play_btn.setText("▶ Play")
self._timer.stop()
self._scrubber.setEnabled(True)
+ self._in_page = False
+ self.playToggled.emit(playing)
def _on_stop(self) -> None:
self._timer.stop()
@@ -201,6 +216,8 @@ class ModeShapeAnimator(QWidget):
self._scrubber.blockSignals(True)
self._scrubber.setValue(int(round(phase * 100)))
self._scrubber.blockSignals(False)
+ if self._in_page:
+ return # the canvas is animating itself; don't re-render per tick
self.frameChanged.emit(self._mode_combo.currentData(), self._scale.value(), phase)
def _emit_static_frame(self) -> None:
diff --git a/src/otko/views/main_window.py b/src/otko/views/main_window.py
index 5241869..6e7a054 100644
--- a/src/otko/views/main_window.py
+++ b/src/otko/views/main_window.py
@@ -230,6 +230,7 @@ class MainWindow(
# Re-apply the overlays whose state lives on the toolbar actions.
self._canvas.set_show_section_extrusions(self._act_show_extruded.isChecked())
self._canvas.set_show_local_axes(self._act_show_local_axes.isChecked())
+ self._canvas.set_show_undeformed(self._act_show_reference.isChecked())
self._canvas.set_display_options(
show_node_labels=self._show_node_labels,
show_element_labels=self._show_element_labels,
@@ -308,6 +309,7 @@ class MainWindow(
self._act_quit.triggered.connect(self.close)
self._act_about.triggered.connect(self._on_about)
self._act_quick_guide.triggered.connect(self._on_quick_guide)
+ self._act_mouse_controls.triggered.connect(self._on_mouse_controls)
self._act_set_units.triggered.connect(self._on_set_units)
self._act_plot_properties.triggered.connect(self._on_plot_properties)
@@ -386,6 +388,9 @@ class MainWindow(
self._act_toggle_parallel.toggled.connect(self._on_toggle_parallel)
self._act_show_extruded.toggled.connect(self._canvas.set_show_section_extrusions)
self._act_show_local_axes.toggled.connect(self._canvas.set_show_local_axes)
+ # Resolve the active canvas at signal time so a backend swap still
+ # routes to the canvas on screen.
+ self._act_show_reference.toggled.connect(lambda on: self._canvas.set_show_undeformed(on))
# ViewModel — projectChanged / modelMutated survive the split.
self._vm.projectChanged.connect(self._on_project_changed)
diff --git a/src/otko/views/menu_builder.py b/src/otko/views/menu_builder.py
index 5e7a271..bd8fc69 100644
--- a/src/otko/views/menu_builder.py
+++ b/src/otko/views/menu_builder.py
@@ -141,6 +141,11 @@ class MenuBuilder:
"Exit any deformed / mode-shape / force-diagram view back to "
"the model geometry. Result data is kept."
)
+ self._act_show_reference = QAction("Show Undeformed &Reference", self, checkable=True)
+ self._act_show_reference.setToolTip(
+ "Faintly overlay the undeformed shape behind a deformed / mode-shape "
+ "view so displacements are easy to judge."
+ )
self._act_clear_display = QAction("&Clear Display", self)
self._act_clear_display.setToolTip(
"Neutral canvas: undeformed geometry, no overlays, selection "
@@ -191,6 +196,7 @@ class MenuBuilder:
self._act_about = QAction("&About OTKO…", self)
# No shortcut: F1/F2/F3/F5 are taken by the draw tools and Run.
self._act_quick_guide = QAction("&Quick Guide", self)
+ self._act_mouse_controls = QAction("&Mouse Controls…", self)
self._act_set_units = QAction("Set Display &Units…", self)
self._act_plot_properties = QAction("&Plot Properties…", self)
self._act_plot_properties.setToolTip(
@@ -481,6 +487,7 @@ class MenuBuilder:
m_display.addSeparator()
m_display.addAction(self._act_back_to_model)
m_display.addAction(self._act_show_undeformed)
+ m_display.addAction(self._act_show_reference)
m_display.addAction(self._act_clear_display)
m_view = mb.addMenu("&View")
@@ -524,6 +531,7 @@ class MenuBuilder:
m_help = mb.addMenu("&Help")
m_help.addAction(self._act_quick_guide)
+ m_help.addAction(self._act_mouse_controls)
m_help.addAction(self._act_about)
def _build_view_toolbar(self) -> None:
diff --git a/src/otko/views/render_controls.py b/src/otko/views/render_controls.py
index 06db479..01886d3 100644
--- a/src/otko/views/render_controls.py
+++ b/src/otko/views/render_controls.py
@@ -84,9 +84,22 @@ class RenderControls:
self._tear_down_post_dock()
if self._diagram_renderer is not None:
self._diagram_renderer.clear()
+ self._reset_reference_overlay()
+ stop_animation = getattr(self._canvas, "stop_animation", None)
+ if callable(stop_animation):
+ stop_animation()
self._canvas._renderer.set_mode(RendererMode.MODEL)
self._canvas.render()
+ def _reset_reference_overlay(self) -> None:
+ """Drop the undeformed-reference overlay and uncheck its action."""
+ self._act_show_reference.blockSignals(True)
+ try:
+ self._act_show_reference.setChecked(False)
+ finally:
+ self._act_show_reference.blockSignals(False)
+ self._canvas.set_show_undeformed(False)
+
def _on_clear_display(self) -> None:
"""Clear Display: neutral canvas — undeformed MODEL, no selection.
@@ -513,6 +526,7 @@ class RenderControls:
# Undeformed exits any post view (dock, renderer mode or diagram
# overlay); Clear just needs a project — both keep result data.
self._act_show_undeformed.setEnabled(has_project and self._in_post_view())
+ self._act_show_reference.setEnabled(has_project and self._in_post_view())
self._act_clear_display.setEnabled(has_project)
def _log(self, message: str) -> None:
diff --git a/tests/gui/test_main_window.py b/tests/gui/test_main_window.py
index a57a00f..9a8d023 100644
--- a/tests/gui/test_main_window.py
+++ b/tests/gui/test_main_window.py
@@ -39,3 +39,21 @@ def test_close_dirty_hidden_window_does_not_block(qtbot) -> None: # type: ignor
assert not window.isVisible()
assert window.close() is True
assert window._vm.is_dirty # unchanged: the prompt was skipped
+
+
+@pytest.mark.gui
+def test_mouse_controls_dialog_is_wired_and_reused(qtbot) -> None: # type: ignore[no-untyped-def]
+ from otko.views.dialogs.mouse_controls import MouseControlsDialog
+ from otko.views.main_window import MainWindow
+
+ window = MainWindow()
+ qtbot.addWidget(window)
+
+ window._on_mouse_controls()
+ dialog = window._mouse_controls_dialog
+ assert isinstance(dialog, MouseControlsDialog)
+ assert dialog.windowTitle() == "Mouse Controls"
+
+ # Raising the action again reuses the same modeless window.
+ window._on_mouse_controls()
+ assert window._mouse_controls_dialog is dialog
diff --git a/tests/gui/test_plotly_gestures.py b/tests/gui/test_plotly_gestures.py
new file mode 100644
index 0000000..e15d287
--- /dev/null
+++ b/tests/gui/test_plotly_gestures.py
@@ -0,0 +1,166 @@
+"""Regression tests for the Plotly canvas mouse-gesture layer.
+
+plotly's built-in drag bindings (shift+left rotates, ctrl+left pans, middle
+zooms, right pans) disagree with the PyVista backend's VTK trackball style, so
+the Plotly canvas re-implements them in JS to match VTK: shift+left pan,
+ctrl+left spin, middle pan, right zoom.
+
+The page runs offscreen under QtWebEngine, where gl-plot3d's render loop is
+throttled and camera animations do not advance, so these tests spy on the
+gl-plot3d camera's ``view.pan`` / ``view.rotate`` calls and assert the mapping
+(and that plotly's own handler is suppressed for the gesture) rather than the
+resulting camera position. A full-camera smoke check is unnecessary here;
+plotly owns the maths.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+pytest.importorskip("PySide6")
+pytest.importorskip("plotly")
+
+from otko.services import load_project
+
+EXAMPLES = Path(__file__).resolve().parents[2] / "examples"
+
+#: Install spies on the live camera, run one synthetic drag, report the calls.
+#: ``keyBindingMode`` distinguishes our layer (false) from plotly's native
+#: handler ('rotate'), which calls the same ``view`` methods.
+_SPY_DRAG = """(function(){
+ var gd = document.getElementById('plot');
+ var s = gd._fullLayout.scene._scene;
+ var cam = s.camera;
+ var el = s.glplot.canvas;
+ var r = el.getBoundingClientRect();
+ var x0 = r.left + r.width/2, y0 = r.top + r.height/2;
+ var calls = [];
+ var origPan = cam.view.pan;
+ var origRotate = cam.view.rotate;
+ cam.view.pan = function (t, dx, dy, dz) {
+ calls.push(['pan', cam.keyBindingMode, dx, dy, dz]);
+ };
+ cam.view.rotate = function (t, p, y, ro) {
+ calls.push(['rotate', cam.keyBindingMode, p, y, ro]);
+ };
+ function ev(t, x, y, b) {
+ el.dispatchEvent(new MouseEvent(t, {
+ bubbles: true, cancelable: true, view: window,
+ clientX: x, clientY: y, button: __BUTTON__, buttons: b,
+ shiftKey: __SHIFT__, ctrlKey: __CTRL__, altKey: __ALT__
+ }));
+ }
+ ev('mousedown', x0, y0, __BUTTONS__);
+ ev('mousemove', x0 + 60, y0 + 40, __BUTTONS__);
+ ev('mouseup', x0 + 60, y0 + 40, 0);
+ cam.view.pan = origPan;
+ cam.view.rotate = origRotate;
+ return JSON.stringify({calls: calls, kbm: cam.keyBindingMode});
+})()"""
+
+
+def _js_bool(value: bool) -> str:
+ return "true" if value else "false"
+
+
+def _open_canvas(qtbot): # type: ignore[no-untyped-def]
+ from otko.views.canvas_plotly import PlotlyCanvas
+
+ canvas = PlotlyCanvas()
+ qtbot.addWidget(canvas)
+ canvas.show_project(load_project(EXAMPLES / "basic_truss.osmodel"))
+ qtbot.waitUntil(lambda: canvas._ready, timeout=30000)
+ qtbot.wait(1500) # let the first Plotly.react settle
+ return canvas
+
+
+def _run_js(canvas, qtbot, script: str, timeout: int = 15000): # type: ignore[no-untyped-def]
+ box: dict[str, object] = {}
+ canvas._web.page().runJavaScript(script, lambda value: box.update(value=value))
+ qtbot.waitUntil(lambda: "value" in box, timeout=timeout)
+ return box["value"]
+
+
+def _spy_drag(
+ canvas, # type: ignore[no-untyped-def]
+ qtbot,
+ *,
+ button: int,
+ buttons: int,
+ shift: bool = False,
+ ctrl: bool = False,
+ alt: bool = False,
+) -> dict[str, Any]:
+ script = (
+ _SPY_DRAG.replace("__BUTTON__", str(button))
+ .replace("__BUTTONS__", str(buttons))
+ .replace("__SHIFT__", _js_bool(shift))
+ .replace("__CTRL__", _js_bool(ctrl))
+ .replace("__ALT__", _js_bool(alt))
+ )
+ raw = _run_js(canvas, qtbot, script)
+ assert isinstance(raw, str)
+ return json.loads(raw)
+
+
+def _ours(calls: list[list[Any]], kind: str) -> list[list[Any]]:
+ return [c for c in calls if c[0] == kind and c[1] is False]
+
+
+@pytest.mark.gui
+def test_gesture_bindings_match_vtk(qtbot) -> None: # type: ignore[no-untyped-def]
+ """One page for all gestures: each QWebEngineView costs a WebGL context."""
+ canvas = _open_canvas(qtbot)
+
+ # Shift+left pans (not plotly's rotate).
+ result = _spy_drag(canvas, qtbot, button=0, buttons=1, shift=True)
+ pans = _ours(result["calls"], "pan")
+ assert pans and pans[0][3] != 0, result
+ assert not _ours(result["calls"], "rotate"), result
+ assert result["kbm"] == "rotate", "binding must be restored after the drag"
+
+ # Middle drag pans, not zooms.
+ result = _spy_drag(canvas, qtbot, button=1, buttons=4)
+ pans = _ours(result["calls"], "pan")
+ assert pans and pans[0][3] != 0 and pans[0][4] == 0, result
+ assert result["kbm"] == "rotate", result
+
+ # Right drag dollies (z pan), not plotly's pan.
+ result = _spy_drag(canvas, qtbot, button=2, buttons=2)
+ zooms = [c for c in _ours(result["calls"], "pan") if c[2] == 0 and c[3] == 0]
+ assert zooms and zooms[0][4] != 0, result
+ assert result["kbm"] == "rotate", result
+
+ # Ctrl+left spins (pure roll).
+ result = _spy_drag(canvas, qtbot, button=0, buttons=1, ctrl=True)
+ rolls = [c for c in _ours(result["calls"], "rotate") if c[2] == 0 and c[3] == 0]
+ assert rolls and rolls[0][4] != 0, result
+ assert result["kbm"] == "rotate", result
+
+ # Alt is not a VTK modifier: it falls back to a plain rotate.
+ result = _spy_drag(canvas, qtbot, button=0, buttons=1, alt=True)
+ rots = [c for c in _ours(result["calls"], "rotate") if c[4] == 0]
+ assert rots and (rots[0][2] != 0 or rots[0][3] != 0), result
+ assert result["kbm"] == "rotate", result
+
+ # Plain left drag stays on plotly's native path (keyBindingMode 'rotate').
+ result = _spy_drag(canvas, qtbot, button=0, buttons=1)
+ assert not _ours(result["calls"], "pan"), result
+ assert not _ours(result["calls"], "rotate"), result
+ assert any(c[1] == "rotate" for c in result["calls"]), result
+ assert result["kbm"] == "rotate", result
+
+ # In-page animation entry points are exposed to Python.
+ assert (
+ _run_js(
+ canvas,
+ qtbot,
+ "typeof window.otkoAnimate === 'function' && "
+ "typeof window.otkoStopAnimation === 'function'",
+ )
+ is True
+ )
diff --git a/tests/gui/test_plotly_hover.py b/tests/gui/test_plotly_hover.py
index 3033886..f1ff273 100644
--- a/tests/gui/test_plotly_hover.py
+++ b/tests/gui/test_plotly_hover.py
@@ -100,8 +100,15 @@ def test_snap_marker_shows_clears_and_tracks_the_camera(qtbot) -> None: # type:
assert float(shown["left"].rstrip("px")) > 0
assert float(shown["top"].rstrip("px")) > 0
- # Orbiting moves the target on screen without any plotly redraw.
- _run_js(canvas, qtbot, "Plotly.relayout('plot',{'scene.camera.eye':{x:-9,y:6,z:4}})")
+ # Orbiting moves the target on screen without any plotly redraw. A top
+ # view is used because a point near the scene centre projects to nearly
+ # the same pixel from opposite diagonal views.
+ _run_js(
+ canvas,
+ qtbot,
+ "Plotly.relayout('plot',{'scene.camera.eye':{x:0,y:0,z:40},"
+ "'scene.camera.up':{x:0,y:1,z:0}})",
+ )
qtbot.wait(600)
moved = _json_state(_run_js(canvas, qtbot, _MARKER_STATE))
assert moved["display"] == "block"
diff --git a/tests/gui/test_plotly_view_preservation.py b/tests/gui/test_plotly_view_preservation.py
index 97ef3ee..4bed58a 100644
--- a/tests/gui/test_plotly_view_preservation.py
+++ b/tests/gui/test_plotly_view_preservation.py
@@ -55,6 +55,14 @@ def test_framing_push_is_not_marked_preserve_view(qtbot) -> None: # type: ignor
assert "camera" in scene
assert "range" in scene["xaxis"]
assert scene["xaxis"]["autorange"] is False
+ # plotly's camera lives in normalized scene units: the model is centred on
+ # the origin and the eye is only a few units out (not a data-unit distance,
+ # which parked the camera hundreds of units away and shrank the model).
+ camera = scene["camera"]
+ assert camera["center"] == {"x": 0.0, "y": 0.0, "z": 0.0}
+ assert (
+ camera["eye"]["x"] ** 2 + camera["eye"]["y"] ** 2 + camera["eye"]["z"] ** 2
+ ) ** 0.5 < 20.0
@pytest.mark.gui
@@ -121,3 +129,67 @@ def test_js_console_messages_reach_the_log(qtbot) -> None: # type: ignore[no-un
("warning", "[web] plot.html:8 careful"),
("info", "[web] plotly:9 hello"),
]
+
+
+@pytest.mark.gui
+def test_deformed_push_colours_by_scalar_and_ghosts_the_reference(qtbot) -> None: # type: ignore[no-untyped-def]
+ """The canvas wiring drives the builder's contour + ghost overlays."""
+ import numpy as np
+
+ from otko.services.deformation import DeformationSource
+ from otko.views.canvas3d.model_renderer import RendererMode
+
+ canvas, calls = _canvas_with_captured_js(qtbot)
+ project = load_project(EXAMPLES / "cantilever.osmodel")
+ canvas.set_project(project)
+ ids = [node.id for node in project.nodes]
+ source = DeformationSource(
+ displacements=np.zeros((len(ids), 3)) + np.linspace(0, 1, len(ids))[:, None],
+ node_id_to_row={nid: i for i, nid in enumerate(ids)},
+ )
+
+ canvas.set_mode(RendererMode.DEFORMED, source)
+ canvas.set_show_undeformed(True)
+ calls.clear()
+ canvas.render()
+
+ payload, _preserve = _parse_call(calls[-1])
+ names = {trace.get("name") for trace in payload["data"]}
+ assert "undeformed-reference" in names
+ nodes = next(t for t in payload["data"] if t.get("name") == "nodes")
+ assert nodes["marker"]["showscale"] is True
+ assert nodes["marker"]["colorbar"]["title"]["text"] == "|u|"
+
+
+@pytest.mark.gui
+def test_animation_push_carries_prebuilt_frames(qtbot) -> None: # type: ignore[no-untyped-def]
+ """``animate`` must hand plotly a frame list, not drive Python re-renders."""
+ import numpy as np
+
+ from otko.services.deformation import DeformationSource
+ from otko.views.canvas_plotly.trace_builder import SceneOptions
+
+ canvas, calls = _canvas_with_captured_js(qtbot)
+ project = load_project(EXAMPLES / "cantilever.osmodel")
+ canvas.set_project(project)
+ canvas._scene = canvas._builder.build(project, SceneOptions())
+
+ ids = [node.id for node in project.nodes]
+ options = [
+ SceneOptions(
+ deformation=DeformationSource(
+ displacements=np.full((len(ids), 3), float(k)),
+ node_id_to_row={nid: i for i, nid in enumerate(ids)},
+ )
+ )
+ for k in (1.0, 2.0, 3.0)
+ ]
+ canvas.animate(options, duration_ms=25, loops=4)
+
+ assert calls and calls[-1].startswith("window.otkoAnimate(")
+ body = calls[-1][len("window.otkoAnimate(") :]
+ literal, end = json.JSONDecoder().raw_decode(body)
+ payload = json.loads(literal)
+ assert len(payload["frames"]) == 3
+ assert payload["frames"][0]["data"], "frames must carry trace data"
+ assert body[end:].startswith(", 25, 4, true")
diff --git a/tests/gui/test_undeformed_reference.py b/tests/gui/test_undeformed_reference.py
new file mode 100644
index 0000000..0277548
--- /dev/null
+++ b/tests/gui/test_undeformed_reference.py
@@ -0,0 +1,61 @@
+"""Smoke tests for the undeformed-reference overlay on both backends."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+pytest.importorskip("PySide6")
+
+from otko.core import ElasticBeamColumn, ElasticSection, Node, Project
+
+
+def _frame_project() -> Project:
+ b, h = 0.30, 0.50
+ return Project(
+ nodes=[
+ Node(id=1, coords=(0.0, 0.0, 0.0), restraint=(True, True, True, True, True, True)),
+ Node(id=2, coords=(6.0, 0.0, 0.0)),
+ ],
+ sections=[
+ ElasticSection(
+ id=1,
+ name="Rect",
+ E=200e9,
+ A=b * h,
+ Iz=b * h**3 / 12.0,
+ Iy=h * b**3 / 12.0,
+ G=80e9,
+ J=1e-6,
+ )
+ ],
+ elements=[ElasticBeamColumn(id=1, nodes=(1, 2), section_id=1)],
+ )
+
+
+@pytest.mark.gui
+def test_pyvista_undeformed_reference_overlay(qtbot) -> None: # type: ignore[no-untyped-def]
+ from otko.services.deformation import DeformationSource
+ from otko.views.canvas3d.model_canvas import ModelCanvas
+ from otko.views.canvas3d.model_renderer import RendererMode
+
+ canvas = ModelCanvas()
+ qtbot.addWidget(canvas)
+ canvas.show_project(_frame_project())
+
+ # In MODEL mode there is nothing to reference — the toggle must be a no-op.
+ canvas.set_show_undeformed(True)
+ assert canvas._renderer._undeformed_actor is None
+
+ # A deformed shape gets a ghost wireframe, removed again on toggle off.
+ src = DeformationSource(
+ displacements=np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 0.5]]),
+ node_id_to_row={1: 0, 2: 1},
+ )
+ canvas._renderer.set_mode(RendererMode.DEFORMED, src)
+ canvas.render()
+ canvas.set_show_undeformed(True)
+ assert canvas._renderer._undeformed_actor is not None
+
+ canvas.set_show_undeformed(False)
+ assert canvas._renderer._undeformed_actor is None
diff --git a/tests/unit/test_plotly_trace_builder.py b/tests/unit/test_plotly_trace_builder.py
index 1d20e4a..a33eb8e 100644
--- a/tests/unit/test_plotly_trace_builder.py
+++ b/tests/unit/test_plotly_trace_builder.py
@@ -13,6 +13,7 @@ from otko.views.canvas3d.style import RenderStyle
from otko.views.canvas_plotly.trace_builder import (
PlotlyTraceBuilder,
SceneOptions,
+ framed_camera_distance,
)
EXAMPLES = Path(__file__).resolve().parents[2] / "examples"
@@ -38,6 +39,32 @@ def test_builds_grid_nodes_and_frames() -> None:
assert all(trace.get("meta", {}).get("kind") != "hover" for trace in scene.data)
+def test_data_bounds_are_unpadded_model_extents() -> None:
+ """Camera framing uses raw model bounds, so they must exclude the padding."""
+ scene = PlotlyTraceBuilder().build(_load("cantilever"), SceneOptions())
+ assert scene.data_bounds["x"] == pytest.approx((0.0, 5.0))
+ assert scene.data_bounds["y"] == pytest.approx((0.0, 0.0))
+ assert scene.data_bounds["z"] == pytest.approx((0.0, 0.0))
+ # Padded frame bounds stay wider than the raw model bounds.
+ assert scene.axis_bounds["x"][0] < scene.data_bounds["x"][0]
+
+
+def test_framed_camera_distance_is_scale_invariant() -> None:
+ """plotly's camera is in normalized scene units, so framing must not grow
+ with the model's data-unit size (the old bug rendered models as specks)."""
+ project = _load("space_frame_3d")
+ small = PlotlyTraceBuilder().build(project, SceneOptions())
+ scaled = project.model_copy(deep=True)
+ for node in scaled.nodes:
+ x, y, z = node.coords
+ node.coords = (x * 1000.0, y * 1000.0, z * 1000.0)
+ large = PlotlyTraceBuilder().build(scaled, SceneOptions())
+
+ assert framed_camera_distance(large) == pytest.approx(framed_camera_distance(small), rel=1e-9)
+ # A normalized eye distance stays small (plotly's default eye is 1.25).
+ assert 1.0 < framed_camera_distance(small) < 20.0
+
+
def test_nodes_carry_ids_as_customdata() -> None:
project = _load("basic_truss")
scene = PlotlyTraceBuilder().build(project, SceneOptions())
@@ -182,6 +209,9 @@ def test_payload_is_json_serialisable() -> None:
payload = json.dumps(scene.to_payload())
assert '"data"' in payload and '"layout"' in payload
assert scene.layout["scene"]["aspectmode"] == "data"
+ # Turntable keeps camera.up pinned to +Z (a level horizon); plotly's
+ # ``orbit`` would rotate the up vector and tip the model over.
+ assert scene.layout["scene"]["dragmode"] == "turntable"
def test_empty_project_yields_no_traces() -> None:
@@ -256,3 +286,86 @@ def test_axis_outline_flag_toggles_grid_and_ticks() -> None:
assert on_axis["showgrid"] is True and on_axis["showticklabels"] is True
# The coloured axis lines stay visible either way (orientation cue).
assert off_axis["visible"] is True and on_axis["visible"] is True
+
+
+class _FakeDeformation:
+ """Minimal ``DeformationSource`` stand-in (keeps this test pyvista-free)."""
+
+ def __init__(self, rise: float = 0.0) -> None:
+ self._rise = rise
+
+ def shifted(self, points: np.ndarray, node_ids: list[int]) -> np.ndarray:
+ out = points.copy()
+ out[:, 2] += self._rise
+ return out
+
+ def magnitudes(self, node_ids: list[int]) -> np.ndarray:
+ return np.linspace(0.0, 1.0, len(node_ids)) if node_ids else np.zeros(0)
+
+
+def test_loads_scale_with_magnitude_and_colour_by_pattern() -> None:
+ scene = PlotlyTraceBuilder().build(_load("space_frame_3d"), SceneOptions())
+ cones = [trace for trace in scene.data if trace.get("name") == "nodal-loads"]
+ assert len(cones) == 2, "one cone trace per load pattern"
+ lengths = sorted(
+ float(np.hypot(np.hypot(u, v), w))
+ for trace in cones
+ for u, v, w in zip(trace["u"], trace["v"], trace["w"], strict=True)
+ )
+ # 2.5e4 vs 5e4 kN → the second arrow is twice as long.
+ assert lengths[0] > 0.0
+ assert lengths[-1] == pytest.approx(2.0 * lengths[0], rel=1e-6)
+ assert cones[0]["colorscale"][0][1] != cones[1]["colorscale"][0][1]
+ assert "Pattern" in cones[0]["customdata"][0] or "|F|" in cones[0]["customdata"][0]
+
+
+def test_supports_use_dof_glyphs_not_markers() -> None:
+ for name in ("space_frame_3d", "basic_truss"):
+ scene = PlotlyTraceBuilder().build(_load(name), SceneOptions())
+ (supports,) = _traces(scene, "supports")
+ assert supports["type"] == "scatter3d"
+ assert supports["mode"] == "lines"
+ assert len(supports["x"]) > 0
+
+
+def test_scalar_colouring_adds_arrays_and_colorbar() -> None:
+ project = _load("cantilever")
+ scalars = np.linspace(0.0, 3.0, len(project.nodes))
+ scene = PlotlyTraceBuilder().build(project, SceneOptions(scalars=scalars, scalar_label="|u|"))
+
+ (nodes,) = _traces(scene, "nodes")
+ assert isinstance(nodes["marker"]["color"], list)
+ assert nodes["marker"]["showscale"] is True
+ assert nodes["marker"]["colorbar"]["title"]["text"] == "|u|"
+ assert nodes["marker"]["cmin"] == pytest.approx(0.0)
+ assert nodes["marker"]["cmax"] == pytest.approx(3.0)
+
+ (frames,) = _traces(scene, "elements")
+ assert isinstance(frames["line"]["color"], list)
+ assert frames["line"]["cmin"] == pytest.approx(0.0)
+ # Scalar mode overrides the family palette.
+ assert "showscale" not in frames["line"]
+
+
+def test_deformation_auto_colours_by_magnitude() -> None:
+ project = _load("cantilever")
+ scene = PlotlyTraceBuilder().build(
+ project, SceneOptions(deformation=_FakeDeformation(rise=0.5))
+ )
+ (nodes,) = _traces(scene, "nodes")
+ assert isinstance(nodes["marker"]["color"], list)
+ assert nodes["marker"]["colorbar"]["title"]["text"] == "|u|"
+
+
+def test_undeformed_reference_overlay_is_opt_in() -> None:
+ project = _load("cantilever")
+ deformation = _FakeDeformation(rise=0.5)
+ without = PlotlyTraceBuilder().build(project, SceneOptions(deformation=deformation))
+ assert not _traces(without, "undeformed-reference")
+
+ with_ghost = PlotlyTraceBuilder().build(
+ project, SceneOptions(deformation=deformation, show_undeformed=True)
+ )
+ (ghost,) = _traces(with_ghost, "undeformed-reference")
+ assert ghost["mode"] == "lines"
+ assert ghost["opacity"] < 1.0
diff --git a/vis_improvement.md b/vis_improvement.md
new file mode 100644
index 0000000..d1ef9a7
--- /dev/null
+++ b/vis_improvement.md
@@ -0,0 +1,307 @@
+# Plotly visualisation improvements — handoff / working brief
+
+Status: **implemented and verified; uncommitted** on branch `fix/plotly-orbit-lag`.
+This file is a self-contained brief so a fresh LLM (or human) can continue the
+work without re-deriving context. Read it top to bottom before touching code.
+
+---
+
+## 1. Objective
+
+Make otko's **Plotly canvas** (`src/otko/views/canvas_plotly/`) feel and look
+like opstool's plotly visualisation, which the user considers the gold
+standard. Earlier in this session we already fixed the two foundational bugs:
+
+1. **Camera framing** — `layout.scene.camera` is *not* in data units; it lives
+ in gl-plot3d's normalized scene space. We now compute a normalized eye
+ distance (`framed_camera_distance`) and frame on the **model** bounds
+ (grid excluded).
+2. **Orbit / horizon** — scene uses `dragmode: "turntable"` (Z-up), and a JS
+ gesture layer matches the PyVista/VTK mouse bindings.
+
+With those done, the user asked for 5 opstool-inspired improvements. **All 5
+were selected and implemented in this session.** This document records what
+landed, design decisions, and what still needs doing (verification, docs,
+possible polish).
+
+---
+
+## 2. Reference: opstool source (read-only clone)
+
+Local clone (do **not** edit):
+
+```
+.slim/clonedeps/repos/yexiang92__opstool/opstool/vis/plotly/
+```
+
+Key files and what to read:
+
+| File | Relevant content |
+| --- | --- |
+| `plot_utils.py` | `PLOT_ARGS_DEFAULT` (colours, sizes), `_plot_points_cmap` (~679), `_plot_lines_cmap` (~747), `_plot_unstru_cmap` (~837), `_make_lines_plotly` (~628) |
+| `plot_resp_base.py` | `_get_plotly_dim_scene` (~220, camera/eye/2D recipe), `_make_lines_arrows` (~361), `_plot_bc` (~305), `_get_bc_points_3d/_2d` (~438–527) |
+| `vis_model.py` | `plot_node_load` (~462), `plot_ele_load` (~515), `plot_beam_local_axes` (~406), `update_fig` (~633, theme/title) |
+| `vis_nodal_resp.py` | `_create_mesh` (scalar contour + `show_origin` undeformed ghost ~57–169), `plot_anim` (~248), `_update_antimate_layout` / `_update_slider_layout` (~94, ~140) |
+| `vis_frame_resp.py` | frame force contour + animation methods |
+
+Important facts learned from the opstool source (do not re-litigate):
+
+- plotly `scatter3d.marker` **and** `scatter3d.line` accept `coloraxis`,
+ `colorscale`, `cmin`, `cmax`, `showscale`, `colorbar`, and array `color`.
+ `layout.coloraxis` exists (plotly.py 7.1.0; it is a valid layout key even
+ though `Layout()._valid_props` doesn't list it directly).
+- `mesh3d` supports `intensity`/`colorscale` but **not** `coloraxis`.
+- opstool's contour colouring uses a shared `coloraxis` + `cmin/cmax` from the
+ response peak, with a `colorbar` carrying the component/unit title.
+- opstool scales load arrows by `|F| * (min+max bound)/20 / max|F|` and tints
+ each load pattern (matplotlib `winter` / `turbo_r`).
+- opstool draws supports as oriented line loops (plates/circles/triangles) per
+ restrained translation DOF.
+
+---
+
+## 3. What was implemented (the 5 changes)
+
+### #1 Scalar contour colouring + colorbar
+
+**Where:** `src/otko/views/canvas_plotly/trace_builder.py`
+
+- `SceneOptions` gained `scalars`, `scalar_label`, `scalar_clim`.
+- `build()` auto-derives scalars when a deformation source exposes
+ `magnitudes(node_ids)` (see `DeformationSource.magnitudes` in
+ `src/otko/services/deformation.py`), label `"|u|"`.
+- `_build_nodes` colours `marker.color` by scalar array with
+ `colorscale=self._style.response_colorscale()`, `cmin/cmax`,
+ `showscale=True`, and a `colorbar` titled `scalar_label`; hover shows the
+ value.
+- `_build_frames` colours `line.color` per endpoint by scalar array.
+- Helper `_scalar_clim()`.
+
+**Effect:** deformed/modal views now show a displacement-magnitude contour with
+a colourbar (verified by screenshot).
+
+### #2 Undeformed "ghost" reference overlay
+
+**Where:** `trace_builder.py` (`_build_undeformed_reference`),
+`SceneOptions.show_undeformed`; `plotly_canvas.py`
+(`set_show_undeformed`, `_show_undeformed`, applied in `_push_scene`);
+`render_controls.py`; `menu_builder.py` (`_act_show_reference`, checkable,
+Display menu); `main_window.py` (wiring + re-apply on canvas swap);
+`canvas_base.py` (protocol method).
+
+- Plotly: faint grey line trace behind the deformed shape.
+- PyVista: `model_renderer.py` `_refresh_undeformed_overlay()` builds a grey
+ `pv.PolyData` wireframe from `_node_original_points` + frame connectivity;
+ `model_canvas.py` `set_show_undeformed`. (This made the previously duplicated
+ `DeformationSource` class in `model_renderer.py` redundant — it now imports
+ the one from `otko.services.deformation`.)
+- **Display → Show Undeformed Reference** is enabled only in a post view and is
+ auto-cleared when returning to the model (`render_controls._reset_reference_overlay`).
+
+### #3 Load magnitude scaling + per-pattern colours + hover
+
+**Where:** `trace_builder.py` `_build_loads`, `_pattern_colors`,
+`_PATTERN_PALETTE`, `_cone_trace` (now takes `customdata` + hovertemplate).
+
+- Arrow length is proportional to `|F| / max|F|`, clamped to `[0.15·scale, scale]`
+ where `scale = 0.05 · model diagonal`. Previously all arrows were the same
+ length regardless of magnitude.
+- One cone trace per load pattern, tinted from `_PATTERN_PALETTE`. With a
+ single pattern (nothing to distinguish) the per-type style tint is kept
+ (`nodal_load_color` / `element_load_color`).
+- Hover: `" ·
|F| = "` via `customdata`.
+- Cone sizing uses `sizemode: "scaled"` with a small unitless `sizeref` (~0.12).
+ `"absolute"` interprets `sizeref` against the vector norm in *normalized*
+ scene units, which rendered oversized "fins" that hid the model on large
+ models (see the `snip4.png` report). `_cone_trace` docstring records this.
+
+### #4 DOF-accurate support glyphs
+
+**Where:** `trace_builder.py` `_build_supports`, `_support_loops`.
+
+- Ported/modified from opstool `_get_bc_points_3d` / `_get_bc_points_2d`
+ (GPL-3.0). Each restrained translation axis → a plate perpendicular to it;
+ 2D roller → circle; 2D ux&uy → triangle. Rotation-only supports fall back to
+ a square marker.
+- Emits one `scatter3d` lines trace named `"supports"`.
+- **NOTICE updated** to record this GPL port (already done).
+
+### #5 In-page plotly frame animation
+
+**Where:**
+- `html.py`: `window.otkoAnimate(payloadJson, durationMs, loops, preserveView)`
+ and `window.otkoStopAnimation()`. Builds a name list, repeats it `loops`
+ times, `Plotly.react` → `addFrames` → `animate` (with `mergeView` to preserve
+ camera/ranges).
+- `plotly_canvas.py`: `animate(options, duration_ms=40, loops=100)`,
+ `stop_animation()`, `base_scene_options()`;
+ `CanvasCapabilities(in_page_animation=True)`.
+- `canvas_base.py`: `CanvasCapabilities.in_page_animation` (default False).
+- `docks/mode_shape_animator.py`: new `playToggled(bool)` signal,
+ `period_seconds()`, `set_in_page_mode(bool)`; `_on_tick` updates the scrubber
+ but does **not** emit frames while `_in_page`.
+- `dock_manager.py`: `_animate_mode_in_page()` builds 36 phase frames from
+ `modal_to_deformation` and calls `canvas.animate(...)` when the capability is
+ present; play/pause map to animate/stop.
+- `render_controls._on_show_undeformed` calls `stop_animation()` if present.
+
+---
+
+## 4. Files changed (all uncommitted)
+
+```
+ M AGENTS.md
+ M NOTICE
+ M docs/QUICK_GUIDE.md
+ M src/otko/services/deformation.py # magnitudes()
+ M src/otko/views/action_handlers.py # (earlier) Mouse Controls dialog
+ M src/otko/views/canvas3d/model_canvas.py # set_show_undeformed
+ M src/otko/views/canvas3d/model_renderer.py # ghost overlay; import DeformationSource
+ M src/otko/views/canvas_base.py # protocol + capability
+ M src/otko/views/canvas_plotly/html.py # gestures, otkoAnimate
+ M src/otko/views/canvas_plotly/plotly_canvas.py # show_undeformed, animate
+ M src/otko/views/canvas_plotly/trace_builder.py # #1–#4
+ M src/otko/views/dialogs/__init__.py # MouseControlsDialog export
+ M src/otko/views/dialogs/quick_guide.py # nav hint
+ M src/otko/views/dock_manager.py # in-page animation
+ M src/otko/views/docks/mode_shape_animator.py # playToggled / in-page
+ M src/otko/views/main_window.py # reference toggle wiring
+ M src/otko/views/menu_builder.py # _act_show_reference
+ M src/otko/views/render_controls.py # enable/reset reference
+ M tests/gui/test_main_window.py
+ M tests/gui/test_plotly_hover.py
+ M tests/gui/test_plotly_view_preservation.py # animation push + deformed push tests
+ M tests/unit/test_plotly_trace_builder.py # #1–#4 tests
+?? src/otko/views/dialogs/mouse_controls.py # earlier: Help dialog
+?? tests/gui/test_plotly_gestures.py # earlier: gestures
+?? tests/gui/test_undeformed_reference.py # PyVista ghost overlay
+?? vis_improvement.md # this brief
+```
+
+---
+
+## 5. Tests already added and passing
+
+- `tests/unit/test_plotly_trace_builder.py`
+ - `test_loads_scale_with_magnitude_and_colour_by_pattern`
+ - `test_supports_use_dof_glyphs_not_markers`
+ - `test_scalar_colouring_adds_arrays_and_colorbar`
+ - `test_deformation_auto_colours_by_magnitude`
+ - `test_undeformed_reference_overlay_is_opt_in`
+ - (`_FakeDeformation` stand-in keeps the unit test free of pyvista/Qt)
+- `tests/gui/test_plotly_view_preservation.py`
+ - `test_animation_push_carries_prebuilt_frames` — parses the emitted
+ `window.otkoAnimate(...)` payload with `json.JSONDecoder().raw_decode`.
+- `tests/gui/test_plotly_gestures.py` — asserts `window.otkoAnimate` /
+ `window.otkoStopAnimation` exist in the page.
+
+Last full gate (after all of the above, except the final two tests below):
+`pytest -m "not slow"` → **100% pass, only pre-existing skips**; `ruff check`
+→ the pre-existing 15 findings only; `mypy core/services` → the 3 pre-existing
+environment errors.
+
+Additional tests added during the follow-up verification pass:
+
+- `tests/gui/test_undeformed_reference.py` — exercises the **PyVista** ghost
+ overlay (`_refresh_undeformed_overlay`) in MODEL vs DEFORMED mode and toggles
+ it off.
+- `tests/gui/test_plotly_view_preservation.py::test_deformed_push_colours_by_scalar_and_ghosts_the_reference`
+ — canvas wiring: a DEFORMED push with `show_undeformed` carries the
+ `undeformed-reference` trace and a node colourbar titled `|u|`.
+
+---
+
+## 6. What remains / known risks (DO THIS NEXT)
+
+1. ~~Run the full gate.~~ **Done** — all green (see §5). Note: `pytest`
+ segfaults at interpreter teardown in this env (QtWebEngine "profile still
+ not deleted") **on the clean baseline too**; it is pre-existing, not caused
+ by these changes. CI (xvfb) should be fine.
+2. **Manually eyeball in-page animation on a real display (only remaining
+ item).** Offscreen QtWebEngine throttles `requestAnimationFrame`, so
+ `Plotly.animate`'s promise may not resolve in tests. A dispatch probe
+ confirmed `addFrames(n)` and `animate(sequence)` are called with the right
+ sizes, but end-to-end playback (loop, pause, camera preservation) has **not**
+ been seen on-screen. Launch `python -m otko`, open a model with a modal
+ result, **Display → Animate Mode Shape → Play** on the Plotly backend and
+ confirm looping + Pause + Back-to-model. `loops=100` × 36 frames = 3600
+ frame names; reduce if it stutters.
+3. **Animation stop path — verified from source.** `Plotly.animate(gd, [],
+ {mode:'immediate'})` calls `discardExistingFrames()` (plotly.js
+ `plot_api.js` `animate`), so `otkoStopAnimation` does interrupt. Interrupt
+ rejects the previous animate promise with no reason; the JS error handler
+ only logs truthy errors to avoid console noise.
+4. **PyVista ghost overlay — tested** (see §5). Still worth a glance that it
+ does not interfere with node picking on-screen, but the actor is
+ `pickable=False`.
+5. **Docs — done** for the new features (`docs/QUICK_GUIDE.md` §2/§3,
+ `AGENTS.md`, `NOTICE`).
+6. **Optional polish (opstool parity not yet done)**
+ - scene title with model stats + `font.family` (opstool `update_fig`);
+ - **2D auto-scene for planar models — evaluated and deliberately skipped.**
+ Turntable's `updateFx` forces `camera.up = [0,0,1]`, so a top view's
+ screen-up is arbitrary (a planar XY truss renders rotated 90°: verified
+ via screenshot). Fixing it needs per-preset up handling that fights
+ turntable; not worth the risk.
+ - Max/Min response annotations (`show_max_min`);
+ - response component selector (currently only `|u|` magnitude);
+ - smoothing/interpolated beam displacement (opstool `interpolate_beam_disp`);
+ - colourbar units (currently label only, no unit string).
+
+---
+
+## 7. Architecture / constraints to respect
+
+- Layering: `views → viewmodels → services → core`. `core` = stdlib+numpy+
+ pydantic; `services` may use h5py/openseespy; `views` = Qt/PyVista/plotly.
+ `trace_builder.py` is **pure** (no Qt, no pyvista, no plotly import) and is
+ unit-tested headless — keep it that way.
+- Both canvas backends implement the `CanvasBackend` protocol
+ (`views/canvas_base.py`). If you add a consumer-facing method, add it to
+ **both** canvases and (ideally) the protocol.
+- opstool is GPL-3.0; any ported code must be recorded in `NOTICE` (already
+ done for `_support_loops` and the colour/load recipes).
+- Never commit `.osmodel` by hand (not relevant here).
+- Do not commit changes unless the user asks. Conventional Commits style.
+
+---
+
+## 8. Useful commands / environment
+
+```bash
+# Python lives in the repo venv (system pytest lacks otko on sys.path)
+.venv/bin/python -c "import otko"
+.venv/bin/pytest tests/unit/test_plotly_trace_builder.py -q
+.venv/bin/pytest tests/gui/test_plotly_gestures.py -q # opens QtWebEngine
+```
+
+Rendering screenshots for quick visual checks (used during development):
+use in-page `Plotly.toImage('plot', {format:'png', width:900, height:640})`
+(a promise; poll `window.__img` from Python and base64-decode). Offscreen
+`qtbot` widgets do not need `show()`; WebGL works but rAF is throttled.
+
+Quick smoke to inspect trace shapes without Qt:
+
+```python
+from otko.services import load_project
+from otko.views.canvas_plotly.trace_builder import PlotlyTraceBuilder, SceneOptions
+scene = PlotlyTraceBuilder().build(load_project("examples/space_frame_3d.osmodel"), SceneOptions())
+for t in scene.data:
+ print(t.get("name"), t["type"])
+```
+
+---
+
+## 9. One-paragraph recap for a fresh LLM
+
+The Plotly canvas now frames correctly (normalized camera, turntable, model
+bounds), has VTK-parity mouse gestures, and five opstool-inspired upgrades:
+scalar response colouring with a colourbar, an undeformed reference overlay,
+magnitude-scaled per-pattern load arrows with hover, DOF-accurate support
+glyphs, and in-page plotly frame animation. Everything is implemented and
+covered by focused unit/GUI tests; the remaining work is running the full gate,
+eyeballing the animation and PyVista ghost on a real display, and finishing
+docs. Start by reading `trace_builder.py` (`SceneOptions`, `build`,
+`_build_nodes`, `_build_frames`, `_build_supports`, `_build_loads`),
+`canvas_plotly/html.py` (gestures + `otkoAnimate`), and
+`canvas_plotly/plotly_canvas.py` (`_push_scene`, `_camera_dict`, `animate`).