ssl_vista

ssl_vista is a Qt desktop visualization tool for simulation logs generated by ssl-simulator. It combines PyVista plotters (2D/3D robot views) and optional Matplotlib plotters in a configurable grid layout.

What this project does

• Launches an interactive viewer from CLI (sslvista)
• Loads simulation CSV data with ssl_simulator.load_sim
• Builds the UI from a JSON grid layout (data/grid_layouts/*.json)
• Supports built-in plotters and file-based custom Matplotlib plotters

Install

pip install ssl_vista

Optional extras: mpl (Matplotlib plotters and the ssl_vista.mpl helpers - Matplotlib and SciPy are not hard dependencies), video (movie export).

Quick start

# Clone and enter the repository
git clone https://github.com/Swarm-Systems-Lab/ssl_simulator_vista
cd ssl_simulator_vista

# Setup development environment
just setup

# See available bundled layouts and sample datasets
uv run sslvista --list-layouts
uv run sslvista --list-data

# Run with a bundled layout and sample data
uv run sslvista --layout 2d_canvas --data-path data_uny_test

Main concepts

• Layout file: declares grid shape and plotter instances
• Plotter: widget responsible for rendering and frame updates
• SimulationGrid: container that owns plotters and frame timer
• MainWindow: orchestrates file loading, playback, and keyboard controls

See Usage for end-to-end workflows and Architecture for internals.

Documentation map

• Usage: CLI options, loading data/layouts, keyboard controls
• Architecture: runtime flow and component responsibilities
• Layout schema: JSON layout format with examples
• Data schema: expected simulation keys/shapes by plotter
• Plotter development: extending with custom plotters
• API reference: module-level API docs
• Troubleshooting: common runtime issues

Development commands

just test
just lint
just typecheck
just docs
just docs-build