# Workspace and interaction reference

The starting point for this interface was the original project's `ecg_sim.html`: a full-window heart viewer, compact dockable controls, and an independently scrolling ECG pane. The new application's atlas and volume-weighted electrical model remain separate from its display geometry.

## Original behaviours retained

| Area                | Controls                                                                                                                                                                   |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workspace           | Heart / controls / ECG by default; left, centre and right control docking; Stack ECG; Swap sides; resizable viewer divider and control edge; collapsible control sections. |
| Main camera         | Left- or right-drag empty space to orbit; wheel or pinch zoom; Front / Back / Left / Right / Top / Bot snaps.                                                              |
| Saved cameras       | Shift-click one of three numbered slots to save, click to restore. Slots also store inset layout, directions and zoom.                                                     |
| Orthographic views  | Front / side / top panes; independent wheel zoom; click a pane label to flip direction; drag inset dividers to resize.                                                     |
| Interactive markers | Left-drag SA or RA / LA / LL; V electrodes exposes V1–V6. Electrodes update new samples during dragging; SA recalculates on release. Reset SA and Reset leads restore defaults.                                               |
| Tissue painting     | Left-drag scar, ischaemia or erase; radius and wall-depth choices; right-drag to orbit while painting; Undo stroke and Clear tissue.                                       |
| Display             | Chamber visibility, three colour modes, opacity, wireframe, 10 ms isochrones and three-axis slicing.                                                                       |
| ECG                 | Fixed paper scale, grid or lead-column layout, lead checklist with All / None, 500 Hz append-only recording, playback speed, pause and scrubbing.                             |
| Models              | Model gallery and local JSON import; Methods and controls guide.                                                                                                           |

## Detailed behaviour

Divider drags use pointer capture, so leaving the handle does not interrupt a resize. Escape, pointer cancellation and window blur cancel unfinished divider drags. Double-click a handle to reset its size. Focus a handle and use the appropriate arrow keys to resize; Home resets the viewer split. The centre dock's width is excluded from the split calculation.

Layout and camera slots are stored locally in the browser. Reset layout restores a 244 px centre control dock and a 60/40 split of the remaining viewer width. On windows narrower than 720 px, the viewers stack above a separately scrolling controls area. Orthographic panes require at least 220 × 180 px of viewer space. Resizing preserves camera orientation; Reset view refits the heart and visible markers.

Dragging SA snaps it to the nearest simulation node. Its default is in the RA; moving it elsewhere creates an experimental periodic stimulus site. Electrode drags move in the active camera plane and rebuild the shared forward calculation. They do not modify tissue conduction. Marker movement and unfinished painting can be cancelled with Escape.

The spherical brush operates in millimetres and changes simulation tissue, including tissue beneath the visible surface within its radius. Full wall can affect all chambers. Subendocardial, mid-wall and epicardial choices restrict ventricular depth; use Full wall on atria. Stroke undo retains up to twelve previous tissue/configuration states. Save model + setup stores painting and physiology; CSV exports recorded voltages separately.

ECG paper uses 4 CSS pixels per schematic millimetre, 25 mm/s and a default gain of 10 mm/mV. A wider pane shows more time. The rhythm strip spans the full width; each cell in the grid shows the duration that fits its width, so it may show less than a full beat in narrow panes. All selected leads can instead be viewed at full width in Column view. The paper scroll area holds overflow without scrolling the entire workspace. Physical screen millimetres depend on browser zoom and display density.

Click or drag a waveform to pause and seek. Left/right arrows on the focused ECG move 10 ms. The bottom slider seeks within the retained 120 s history; the adjacent arrow returns to its start. Space toggles playback outside form controls and dialogs. The live display records new samples using current electrodes and a periodic activation history. Previous values never change. Live edge returns to the latest time; Play resumes recording there, and Clear recording empties both main and reference buffers. Switching models starts a new recording. Marker and tissue edits return to the live edge; historical review restores activation and electrode positions.

Compare with normal uses the same rate and electrode positions as the current result. Paper gain applies equally to all leads and to the overlay. CSV export contains the computed sample values, independent of paper gain.

## Deliberate differences and current limits

- The old strip-teaching lesson is replaced by a controls guide; its lesson content has not been migrated.
- Contraction 0–12% illustrates delayed shortening and relaxation. It is display-only; painting uses rest geometry. No force, pressure or electromechanical coupling is implemented.
- Per-lead automatic amplitude recalibration is not carried over. Display gain changes the common paper scale while retaining the shared forward model's relative amplitudes.
- The new model gallery accepts the volume-weighted [asset contract](ANATOMY.md). Original Blender shell/vertex-group JSON files and old saved presets require conversion; they are not directly compatible.
- The original mesh-dependent speed controls are expressed as myocardial and fast-path velocity, AV delay and RV gateway delay in the new solver. Their numbers do not map directly to old presets. The current model supports one selected bundle block at a time.
- This remains an educational electrical model with the limitations described in [MODEL.md](MODEL.md), including simplified atrial/RV anatomy and no validated clinical waveform accuracy.

The gallery includes Rodero adult average, Tissue sphere and Muscle strip. Heart-only controls and interval measurements are disabled for tissue. Save model + setup and re-import preserve model geometry, explicit landmarks, physiological settings, electrodes, stimulus, painted mask and contraction. Contraction, camera and display mode remain current while reviewing earlier recorded activation. See [Blender workflow](BLENDER_PL.md).