# The Viewer: Viz

`Viz`, from `plesty.lib.monitor`, is an experiment's viewer: a window that shows a
run's data as plots, and redraws them as the run goes on. An experiment module
usually ships one, in a file of its own such as `plesty/pol_pl/viz.py`, so that
anyone can watch its runs. [The layers of a viewer](index.md#the-layers-of-a-viewer)
shows where it sits.

## A viewer

```python
# power_viz.py
import sys

from plesty.lib.monitor import Line, Viz

viz = Viz("Power scan", experiment="powerscan")


@viz.plot("Power")
def power(data):
    return [Line(x=data.column("wavelength_nm"), y=data.column("power_w"),
                 x_label="Wavelength (nm)", y_label="Power (W)")]


if __name__ == "__main__":
    sys.exit(viz.main())
```

`Viz` takes:

| Argument | Meaning |
|---|---|
| title | the window's title |
| `experiment=` | the experiment name whose runs to show, as in the run ids (`powerscan_…`). Several names are allowed, for an experiment that was renamed. `None` shows the newest run of any experiment. |
| `run_root=` | where to look for runs. A relative path is taken inside the shared disk when `PLESTY_DATA` is set (see [Data on a Shared Disk](../experiment/shared_disk.md)); by default the shared disk itself, or `runs` without one. |
| `reads=` | a function that turns a row naming a file into the numbers inside it; see [`reads`: rows that name a file](run_data.md#reads-rows-that-name-a-file) |

Add plots with `@viz.plot("Title")` over a function, or `viz.add_plot(plot)` for a
plot object; [Plots and Drawables](plots.md) explains both. `@viz.plot` also takes
`weight=`, the plot's share of the window when the panels are first laid out, and
`name=`, the key the window's layout is remembered under (the title by default).

## Starting it

`viz.main()` gives the viewer a command line with two subcommands. `monitor` needs the
`gui` extra; `render` needs the `gui` and `record` extras (see
[Install](../install.md#extras)).

```bash
python power_viz.py monitor                      # a window following the newest run
python power_viz.py monitor --replay 2           # play a finished run back, 2 rows per refresh
python power_viz.py monitor --record demo.mp4    # also record the window to a video
python power_viz.py render --run powerscan_20260925-101534   # the run as a video, no window
```

`render` draws without a screen, so it also works on a computer without one, and
stops by itself when the run's data is used up.

A replayed run can be held: **Replay ▸ Pause**, or the space bar, stops the plots
where they are, and the same again resumes them. Panels can still be moved and
closed while it is paused. A live run has no such menu. Code that builds its own
window calls the window's `pause()` and `resume()`, and `offer_pause()` adds the
menu.

| Option | For | Meaning |
|---|---|---|
| `--run RUN_ID` | both | the run to show; the newest by default |
| `--run-root FOLDER` | both | where to look for runs, instead of the viewer's `run_root` |
| `--data-root FOLDER` | both | where this computer sees the shared disk, instead of `PLESTY_DATA` |
| `--interval-ms MS` | both | how often the plots are redrawn; 500 by default |
| `--record-fps FPS` | both | the frame rate of a recorded video; 10 by default |
| `--replay [ROWS]` | `monitor` | play a finished run back instead of following it live, `ROWS` rows per refresh (1 if no number is given) |
| `--record PATH` | `monitor` | record the window to a video, saved when the window closes |
| `--rows ROWS` | `render` | rows added per video frame; 1 by default |
| `--out PATH` | `render` | where to save the video; `<run id>.mp4` next to the run folder by default |

`--help` works without the `gui` extra, so the options can be read on any computer.

## Showing it inside another window

`viz.view(run)` builds the viewer's window content for `run` without showing it, and
returns it for another program to place in its own window, such as a console that
shows the runs it started. It is not refreshing yet: call its `start()` once it is in
place. Pass `remember_layout=False` there: the arrangement inside another window is
not the viewer's own.
[Shell Framework](ui.md) explains the window it returns.