Skip to content

Usage

This page covers practical use of ssl_vista: listing available resources, launching the app, and controlling playback.

Prerequisites

  • Python 3.12+
  • GUI environment compatible with Qt (X11/xcb on Linux)
  • Simulation CSV files generated by ssl_simulator

For local development:

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

CLI entrypoint

The project exposes sslvista:

uv run sslvista --help

Primary options:

  • --layout / -l: layout name (2d_canvas) or path to a layout JSON file
  • --data-path / -data: sample name (data_uny_test) or CSV path
  • --list-layouts / -ll: print built-in layout names and exit
  • --list-data / -ld: print bundled sample data names and exit
  • --auto-play / -ap: start playback automatically after data load

Typical workflows

1) Discover bundled resources

uv run sslvista --list-layouts
uv run sslvista --list-data

2) Run with bundled layout and sample data

uv run sslvista --layout 2d_canvas --data-path data_uny_test
uv run sslvista --layout 3d_canvas --data-path data_3d_test

3) Run with custom files

uv run sslvista --layout ./my_layout.json --data-path ./my_run.csv

4) Start immediately playing

uv run sslvista --layout 3d_canvas --data-path data_3d_test --auto-play

In-app controls

Toolbar actions

  • Load Grid Layout: open a JSON layout file
  • Load CSV: open a simulation CSV file
  • Reload CSV: reprocess currently loaded file
  • Play / Stop / Reset: playback controls
  • Time slider: manual frame selection

Keyboard shortcuts (main window)

  • Space: play/pause
  • R: reset simulation
  • Left / Right: coarse step backward/forward
  • , / .: single-step backward/forward
  • Q: quit application

Keyboard shortcuts (3D attitude plotter)

  • PageUp / PageDown: cycle focused robot index
  • R: reset camera in the attitude panel

Layout and data inputs

  • Layout files are JSON configurations loaded by SimulationGrid.
  • Each plotter declares required simulation keys and shapes.
  • Bundled examples are in src/ssl_vista/data/grid_layouts and src/ssl_vista/data/samples.

See Layout schema and Data schema for exact contracts.

Common dev commands

just test        # run the test suite
just test-fast   # parallel, skips slow tests
just test-one X  # run a single test by name
just lint        # ruff format + check
just typecheck   # ty
just docs        # serve the docs locally
just docs-build  # build the static site
just clean       # remove build artifacts

Run just --list for the full command reference.