# TopoVec

TopoVec is a Python toolkit for constructing, analyzing, and visualizing 3D
vector and director fields, with a focus on topological solitons and
liquid-crystal workflows.

## Quick Start

Install TopoVec into a fresh project environment:

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

For all optional backends:

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

See [docs/guides/installation.md](docs/guides/installation.md) for full
installation options.

## Highlights

- 3D vector-field and director-field workflows on structured grids.
- Ansatz, coordinate-system, section, and I/O helpers for field construction.
- Multiple rendering backends and notebook-oriented exploration workflows.
- A dockable PySide6 desktop viewer for browsing NPZ/SAD states via `topovec view`.

## Project Layout

- `src/topovec` contains the main package, including the core abstractions,
  ansatz helpers, and optional backend integrations.
- `notebooks` contains demo and workflow notebooks.
- `docs` contains the Sphinx/MyST documentation sources and API reference.
- `tests` contains regression and API-level tests.

## Getting Started

- Installation: [docs/guides/installation.md](docs/guides/installation.md)
- Notebooks and interactive workflows: [docs/guides/notebooks.md](docs/guides/notebooks.md)

## Desktop Viewer

`topovec view` is the native desktop frontend for TopoVec. It opens `.npz` and `.sad`
state files in a dockable PySide6 window with built-in `topovec.mgl` scenes,
auto-generated property controls, Python reproduction snippets, recent-files
history, and high-resolution image export.

Install the GUI stack together with the ModernGL backend:

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

Then launch the desktop viewer:

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

On Linux, `topovec view` may show OpenGL compositing artifacts under Qt Wayland on
some systems. If you see overbright or unstable rendering, prefer the X11 Qt
backend:

```sh
QT_QPA_PLATFORM=xcb topovec view path/to/state.npz
```

Current `topovec view` scope:

- One active central viewport with dockable source, property, and snippet panels.
- Read-only browsing of NPZ and SAD states.
- Built-in `topovec.mgl` scenes with auto-generated property controls.
- High-resolution image export from the current render state.

## Documentation

The documentation sources live in `docs/` and the canonical hosted target is
Read the Docs.

To build the documentation locally:

```sh
uv run --extra docs --extra mgl --extra marimo --extra matplotlib --extra ti --extra sad sphinx-build -b html docs docs/_build/html
```

## Development

Developer-oriented repository notes and common operations are documented in
[DEVELOPMENT.md](DEVELOPMENT.md).
