Metadata-Version: 2.4
Name: ssl_vista
Version: 0.3.0
Summary: A Qt-based visualization app
Author-email: Jesus Bautista Villar <jesbauti20@gmail.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: imageio>=2.34
Requires-Dist: ipyvtklink>=0.2.2
Requires-Dist: ipywidgets>=8.0
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic>=2.8
Requires-Dist: pyqt5>=5.15.0
Requires-Dist: pyvista>=0.46.3
Requires-Dist: pyvistaqt>=0.11.3
Requires-Dist: ssl-simulator>=1.0.0
Requires-Dist: typer
Requires-Dist: vtk>=9.6
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: tox-uv>=1.9; extra == 'dev'
Requires-Dist: tox>=4.18; extra == 'dev'
Requires-Dist: twine>=5.1.1; extra == 'dev'
Requires-Dist: ty>=0.0.14; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
Provides-Extra: examples
Requires-Dist: ipykernel; extra == 'examples'
Requires-Dist: ipython>=8.0; extra == 'examples'
Requires-Dist: matplotlib-inline<0.3,>=0.1.6; extra == 'examples'
Requires-Dist: matplotlib>=3.7; extra == 'examples'
Provides-Extra: lint
Requires-Dist: ruff>=0.9.0; extra == 'lint'
Provides-Extra: mpl
Requires-Dist: matplotlib-inline>=0.1.6; extra == 'mpl'
Requires-Dist: matplotlib>=3.7; extra == 'mpl'
Requires-Dist: scipy>=1.5; extra == 'mpl'
Provides-Extra: pre-commit
Requires-Dist: pre-commit>=3.0; extra == 'pre-commit'
Provides-Extra: release
Requires-Dist: build>=1.2.2; extra == 'release'
Requires-Dist: twine>=5.1.1; extra == 'release'
Provides-Extra: tests
Requires-Dist: pytest-cov>=4.0; extra == 'tests'
Requires-Dist: pytest-xdist>=3.5; extra == 'tests'
Requires-Dist: pytest>=7.0; extra == 'tests'
Provides-Extra: type-checking
Requires-Dist: ty>=0.0.14; extra == 'type-checking'
Provides-Extra: video
Requires-Dist: imageio-ffmpeg>=0.4; extra == 'video'
Description-Content-Type: text/markdown

# ssl_vista

Qt-based visualization app for simulation logs generated by
[ssl_simulator](https://github.com/Swarm-Systems-Lab/ssl_simulator).

It loads a run with `ssl_simulator.load_sim`, builds a multi-panel window from a JSON layout, and
plays the simulation back with PyVista (2D/3D scenes) and optional Matplotlib panels.

```bash
pip install ssl_vista

sslvista --list-layouts
sslvista --list-data
sslvista --layout 2d_canvas --data-path data_uny_test
```

Full documentation is in [docs/](docs/) - see [usage](docs/usage.md) and
[data schema](docs/data-schema.md).

## What it provides

- CLI app: `sslvista`
- Configurable multi-panel layout system (`JSON`)
- Built-in PyVista plotters for 2D/3D scenes
- Optional Matplotlib plotters loaded from Python files

## Installation

Requires Python >= 3.12.

```bash
pip install ssl_vista
```

Optional extras:

| Extra | What it adds |
|---|---|
| `mpl` | Matplotlib plotters and the `ssl_vista.mpl` helpers (Matplotlib + SciPy) |
| `video` | Movie/animation export |

Matplotlib is deliberately **not** a hard dependency - 2D plotting is expected to move to a
GPU-backed stack. Importing `ssl_vista.mpl` without the extra raises a message telling you to
install it.

## Data it expects

Plotters look up simulation arrays by **exact key**, matching the flat names `ssl_simulator` logs:

| Plotter | Keys | Shapes |
|---|---|---|
| `Plotter2DCanvas` | `p`, `theta` | `(T, N, 2)`, `(T, N)` |
| `Plotter3DCanvas` | `p`, `R` | `(T, N, 3)`, `(T, N, 3, 3)` |
| `Plotter3DAttitude` | `R` | `(T, N, 3, 3)` |

Any label can be overridden per plotter in the layout's `args`. See
[docs/data-schema.md](docs/data-schema.md).

## Quick start (development)

```bash
git clone https://github.com/Swarm-Systems-Lab/ssl_simulator_vista
cd ssl_simulator_vista
just setup

uv run sslvista --list-layouts
uv run sslvista --list-data
uv run sslvista --layout 2d_canvas --data-path data_uny_test
```

Common tasks - run `just --list` for the rest:

```bash
just test         # run the test suite
just lint         # ruff format + check
just docs         # serve the docs at http://localhost:8000
```

CLI usage in dev mode using `uv`:

```bash
uv run sslvista --help
```

## License

MIT
