# Installation

## Prerequisites

We recommend installing [uv](https://docs.astral.sh/uv/) before working with
TopoVec.

## User installation

If you only need the packaged tools or notebooks, create a fresh environment
and add TopoVec from PyPI:

```sh
uv init my_topovec_project
cd my_topovec_project
uv add topovec
```

Most functionality is provided by optional plugins. To install all extras:

```sh
uv add topovec --all-extras
```

## Development installation

To work on the repository itself:

```sh
git clone https://gitlab.com/alepoydes/topovec.git
cd topovec
uv sync --all-extras
```

If you only need a subset of plugins, choose the relevant extras explicitly:

```sh
uv sync --extra mgl
```

For the desktop viewer only, install the packaged tool with the dedicated
viewer extra:

```sh
uv tool install 'topovec[view]'
```

This exposes the `topovec` command for browsing `.npz` and `.sad` files in the
PySide6 desktop application through the `view` subcommand.

If you are developing inside the repository, use:

```sh
uv sync --extra view
```

`topovec view` is the native TopoVec desktop frontend. It is intended for interactive
inspection of saved states and trajectories with:

- dockable source, property, snippet, and log panels
- built-in `topovec.mgl` scene switching
- auto-generated render controls
- recent-files history and high-resolution image export

Typical usage:

```sh
topovec view path/to/state.npz
topovec view path/to/trajectory.sad path/to/other_state.npz
```

On Linux, `topovec view` may exhibit OpenGL compositing artifacts under Qt Wayland on
some systems. If the viewport looks overbright or unstable, run it through the
X11 Qt backend instead:

```sh
QT_QPA_PLATFORM=xcb topovec view --debug
```
