Metadata-Version: 2.4
Name: simview
Version: 3.5
Summary: THREE.js-based simulation visualization tool
Author-email: Jan Vlk <vlkjan6@fel.cvut.cz>, Ales Kucera <kuceral4@fel.cvut.cz>, David Korcak <david.korcak@gmail.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://vlk-jan.github.io/simview/
Project-URL: Repository, https://github.com/vlk-jan/simview
Project-URL: Issues, https://github.com/vlk-jan/simview/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.135.3
Requires-Dist: httptools>=0.7.1; sys_platform != "win32"
Requires-Dist: jinja2>=3.1.6
Requires-Dist: orjson>=3.11.8
Requires-Dist: uvicorn>=0.44.0
Requires-Dist: uvloop>=0.22.1; sys_platform != "win32"
Provides-Extra: authoring
Requires-Dist: torch; extra == "authoring"
Requires-Dist: einops; extra == "authoring"
Requires-Dist: numpy; extra == "authoring"
Provides-Extra: render
Requires-Dist: playwright>=1.40; extra == "render"
Dynamic: license-file

# SimView Visualizer

[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://vlk-jan.github.io/simview/)
[![Live Demo](https://img.shields.io/badge/demo-live-brightgreen.svg)](https://vlk-jan.github.io/assets/demos/simview/)

**SimView** is a powerful and interactive tool for visualizing 3D models and terrain data in simulations. It enables you to explore and analyze multiple simulation scenarios (batches) within a shared environment, all defined through an intuitive JSON format or a Python API.

Whether you're simulating physical objects or comparing different runs, SimView provides a flexible and efficient way to bring your data to life using a web-based interface powered by Three.js.

---

## Documentation

Full documentation — usage guides, CLI reference, the JSON format specification,
the API reference, and developer/architecture docs — is available at:

**[https://vlk-jan.github.io/simview/](https://vlk-jan.github.io/simview/)**

Want to try it without installing anything? There's a
[live browser demo](https://vlk-jan.github.io/assets/demos/simview/)
(static snapshot, no backend needed).

---

## Features

- **Batched Simulations**: Visualize multiple simulation instances side-by-side.
- **Shared Terrain**: Efficient rendering with shared terrain across all batches.
- **Interactive UI**: Web-based controls for playback, camera, and data inspection.
- **Python API**: Easy-to-use API for generating scenes and launching the visualizer directly from your code.
- **JSON Support**: Load and save simulation data using a portable JSON format.

---

## Quick Start

The easiest way to get started is to run the provided example script:

```bash
python example.py
```

This script demonstrates how to use the Python API to create a simulation with wavy terrain, dynamic bodies, and time-series data.

The Python authoring API (`simview.scene`, `simview.state`, `simview.model`) depends on
`torch` and `einops`. Install them with the optional `authoring` extra shown below.
Only these are needed to *build* simulations; *viewing* an existing JSON file does not
require `torch`.

---

## Installation

Requires **Python 3.12+**.

### From PyPI

To only view existing simulation JSON files:

```bash
pip install simview
```

To also author simulations from Python (installs `torch` and `einops`):

```bash
pip install "simview[authoring]"
```

### From source

For working on SimView itself (or to track an unreleased commit), install an
editable checkout instead:

```bash
pip install -e .              # viewing only
pip install -e ".[authoring]" # viewing + authoring
```

For independent use of this repository, use `venv` or `uv`:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[authoring]"
```

```bash
uv sync --extra authoring
source .venv/bin/activate
```

---

## License

SimView is distributed under the [BSD 3-Clause License](LICENSE). The web interface
vendors [uPlot](https://github.com/leeoniya/uPlot), [three.js](https://github.com/mrdoob/three.js),
and [chroma-js](https://github.com/gka/chroma.js) (all MIT licensed) under
`simview/static/lib/` so the viewer works fully offline — see the
[documentation](https://vlk-jan.github.io/simview/dev/architecture/#vendored-third-party-libraries)
for details. All third-party libraries used by SimView are permissively licensed
(MIT/BSD), so there are no licensing restrictions on commercial use.
