Metadata-Version: 2.4
Name: sstcam-tio-view
Version: 1.0.0
Summary: Interactive R0/R1 waveform viewer for SST-camera data (GUI + TUI)
Author-email: Richard White <richard.white@mpi-hd.mpg.de>, Jason Watson <jason.watson@desy.de>
License-Expression: BSD-3-Clause
Project-URL: repository, https://gitlab.cta-observatory.org/cta-array-elements/sst/camera/analysis/tio-view
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy~=1.24
Requires-Dist: scipy~=1.11
Requires-Dist: nicegui~=3.0
Requires-Dist: matplotlib~=3.7
Requires-Dist: textual~=8.2
Provides-Extra: dev
Requires-Dist: ipython; extra == "dev"
Requires-Dist: pre-commit~=4.1; extra == "dev"
Requires-Dist: mypy~=1.15; extra == "dev"
Requires-Dist: pytest~=8.3; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: coverage>=7.4.0; extra == "dev"
Provides-Extra: tio
Requires-Dist: sstcam-tio~=2.0; extra == "tio"
Dynamic: license-file

# <img align="right" src="https://gitlab.cta-observatory.org/cta-array-elements/sst/camera/analysis/tio-view/-/raw/main/misc/tio-view-logo.png?ref_type=heads" height="200">

# tio-view

[![pipeline status](https://gitlab.cta-observatory.org/cta-array-elements/sst/camera/analysis/tio-view/badges/main/pipeline.svg)](https://gitlab.cta-observatory.org/cta-array-elements/sst/camera/analysis/tio-view) [![coverage report](https://gitlab.cta-observatory.org/cta-array-elements/sst/camera/analysis/tio-view/badges/main/coverage.svg)](https://gitlab.cta-observatory.org/cta-array-elements/sst/camera/analysis/tio-view)

Interactive viewer for `.tio` waveform files from the SST (Small-Sized
Telescope) camera of CTAO (Cherenkov Telescope Array Observatory) —
both raw R0 and calibrated R1 waveform files, the same ones read by the
[tio](https://gitlab.cta-observatory.org/cta-array-elements/sst/camera/analysis/tio)
package (`sstcam-tio` on PyPI), generated by the SST-camera server / TargetIO.

- `tio-view` — full web GUI (NiceGUI + matplotlib): editable data-path
  and run selection, event scrolling/playback, a full camera image
  (fixed-window integral) with click-to-select pixels, and a per-pixel
  waveform view.
- `tio-view-tui` — fast terminal viewer (Textual): deliberately
  minimal next to the GUI, for low-bandwidth / no-X11 sessions. Camera
  grid with single-pixel cursor selection, a second independently-set
  "fixed" pixel, and both traces overlaid on one Braille-canvas waveform
  plot (no matplotlib/plotting dependency).

* Supported Python versions: 3.10+
* Developed on: macOS (not yet tested on Linux/Windows)
* Source: <https://gitlab.cta-observatory.org/cta-array-elements/sst/camera/analysis/tio-view>
* Pypi: <https://pypi.org/project/sstcam-tio-view>
* License: [BSD-3-Clause](LICENSE)

## Installation

This package is installable via pip from PyPI:
```
pip install sstcam-tio-view
```

Camera geometry comes from `sstcam_configuration` (part of the SST-camera
server stack), which is **not on PyPI** — install it manually into the same
environment before running either tool.

Reading `.tio` files needs one of:
- `sstcam_waveform` (also not on PyPI — already present on the camera
  server / any environment that already has it), or
- `sstcam-tio`, installable via the `tio` extra: `pip install "sstcam-tio-view[tio]"`.

`tio_view/core/tio_reader.py` prefers `sstcam_waveform` when both are
installed.

## Usage

Both tools scan a run directory for `*_r1.tio`/`*_r0.tio` files, present
them for selection, and rescan it once a second so new runs show up
without a restart. An R0 run's Run info/Stage field shows "R0 (raw, ADC
counts)"; axis and colorbar units switch from mV to ADC counts to match.

To try either tool immediately without a real run of your own, point it
at [`tests/data`](tests/data) — a small (3.3 MB each) bundled example
run with matching R0 and R1 files, 25 events.

### `tio-view`

```bash
tio-view [--port PORT] [--dark]
```

Takes no directory argument — set the run directory from the "Data
Path" field in the UI, which is remembered (`~/.config/tio-view`) and
reused on the next launch.

- `--port PORT` — web server port (default: 8080).
- `--dark` — use a dark theme.

### `tio-view-tui`

```bash
tio-view-tui /path/to/run/directory [--window START END] [--pixel N]
tio-view-tui tests/data  # try it against the bundled example run
```

Takes the run directory as a required argument (no in-app path input,
no persistence between runs).

- `--window START END` — fixed integral window in samples (default: the
  full waveform). Set once at launch, not editable in the UI.
- `--pixel N` — initial "fixed" pixel shown in the waveform overlay
  (default: 1633). Editable at runtime via the Pixel input.

Key bindings: arrow keys move the camera cursor (the second overlaid
pixel); `n`/`p` step one event forward/back, `pageup`/`pagedown` step by
10; `space`/`f` toggle autoplay at 2 Hz / 20 Hz; `q` quits.
