Metadata-Version: 2.3
Name: nova-rerun-bridge
Version: 0.17.0
Summary: Visualizes the state of your nova instance inside of [rerun.io](https://rerun.io). This is intended to be used alongside the [nova python lib](https://github.com/wandelbotsgmbh/wandelbots-nova).
Author: Wandelbots GmbH
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: APScheduler (>=3.11.0,<4.0.0)
Requires-Dist: python-decouple (>=3.8,<4.0)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Requires-Dist: rerun-sdk (>=0.21.0,<0.22.0)
Requires-Dist: scipy (>=1.14.1,<2.0.0)
Requires-Dist: trimesh (>=4.5.3,<5.0.0)
Requires-Dist: wandelbots-nova (>=0.16)
Description-Content-Type: text/markdown

# Nova Rerun Bridge

[![PyPI version](https://badge.fury.io/py/nova-rerun-bridge.svg)](https://badge.fury.io/py/nova-rerun-bridge)
[![License](https://img.shields.io/github/license/wandelbotsgmbh/nova-rerun-bridge.svg)](https://github.com/wandelbotsgmbh/nova-rerun-bridge/blob/main/LICENSE)
[![Build Status](https://github.com/wandelbotsgmbh/nova-rerun-bridge/actions/workflows/release.yml/badge.svg)](https://github.com/wandelbotsgmbh/nova-rerun-bridge/actions/workflows/release.yml)

A visualization extension for [wandelbots-nova](https://github.com/wandelbotsgmbh/wandelbots-nova) that enables real-time 3D visualization of robot trajectories using [rerun.io](https://rerun.io).

https://github.com/user-attachments/assets/ab527bc4-720a-41f2-9499-54d6ed027163

## Prerequisites

- A running Nova instance (get access at [wandelbots.com](https://www.wandelbots.com/))
- [wandelbots-nova](https://pypi.org/project/wandelbots-nova/) Python package
- Valid Nova API credentials

## 🚀 Quick Start

```bash
# Install the package
poetry install nova-rerun-bridge

# Download required robot models
poetry run download-models
```

```python
from nova_rerun_bridge import NovaRerunBridge
from nova import Nova

# Connect to your Nova instance (or use .env file)
nova = Nova(
    host="https://your-instance.wandelbots.io",
    access_token="your-token"
)
bridge = NovaRerunBridge(nova)

# Setup visualization
await bridge.setup_blueprint()

# Log a trajectory
await bridge.log_trajectory(joint_trajectory, tcp, motion_group)
```

# ✨ Features

- 🤖 Real-time 3D robot visualization (see a [list](https://wandelbotsgmbh.github.io/wandelbots-js-react-components/?path=/story/3d-view-robot-supported-models) of supported robots)
- 🎯 Trajectory playback and analysis
- 💥 Collision scene visualization
- ⏱️ Motion timing analysis
- 🔄 Continuous monitoring mode

## 💻 Usage Examples

The python library can be used to feed data to the rerun desktop app. The library is built on top of the nova python library and provides a simple interface to feed data to the rerun desktop app. See the [minimal example](https://github.com/wandelbotsgmbh/nova-rerun-bridge/tree/main/minimal_example) on how to use the library.

### Basic Motion Logging

```python
# Log simple motion
await bridge.log_trajectory(joint_trajectory, tcp, motion_group)
```

### Collision Scene Visualization

```python
# Log collision scenes
await bridge.log_collision_scenes()
```

### Stream current robot state

```python
# Start streaming robot state
await bridge.start_streaming(motion_group)

# Stop streaming all robot states
await bridge.stop_streaming()
```

### Log Actions

```python
# Log planned actions
await bridge.log_actions(actions)
```

## Setup

Adjust the `NOVA_API` and `NOVA_ACCESS_TOKEN` in the `.env` file to your instance URL (e.g. `https://unzhoume.instance.wandelbots.io`) and access token. You can find the access token in the developer portal.

## 📚 More Examples

Check out our [example repository](https://github.com/wandelbotsgmbh/nova-rerun-bridge/tree/main/nova_rerun_bridge/examples) for more detailed examples.

## ⚙️ Configuration

The bridge can be configured through environment variables:

- RECORDING_INTERVAL: Set visualization update interval (default: 0.1s)

## Download Robot Models

After installing the library, you need to download the robot models:

```bash
# If installed via poetry
poetry run download-models

# If installed via pip
python -m nova_rerun_bridge.models.download_models
```

This will download the robot models into your project folder. You can use the library without downloading the models, but you will not be able to visualize the robot models in the rerun viewer.

### Tools

Code formatting and linting is done with [ruff]

```bash
poetry run ruff check scripts/. --fix
poetry run ruff format
```

### Build

To build the package locally, run the following command

```bash
poetry build
```

This will create a dist/ directory with the built package (.tar.gz and .whl files).

#### Install a development branch in Poetry

```
nova-rerun-bridge = { git = "https://github.com/wandelbotsgmbh/nova-rerun-bridge.git", branch = "feature/branchname" }
```

# Run as Nova App

The easiest way to try it out is to install the app on your nova instance. Use the nova cli tool and run:

```bash
nova catalog install rerun
```

The app uses the populate script to feed the data to the rerun desktop app. The app automatically runs this script in the background. You can also run the script manually on your local machine.

- run `python nova_rerun_bridge/polling/populate.py` to start a service which periodically polls the nova instance for new planned trajectories

## Development

### Deploy on local instance

- use the kubeconfig from your nova instance and run `export KUBECONFIG=kubeconfig`

- you can use [skaffold](https://skaffold.dev/) to build the image and change the deployment

```bash
skaffold dev --cleanup=false --status-check=false
```

## Issues

- rerun is able to run behind reverse proxy and the viewer can connect via web
- rerun sdk is _not_ able to connect to rerun which is hosted behind reverse proxy
  - [client](https://github.com/rerun-io/rerun/blob/cf9299d9205134713687e54fdf13551ed1f44bce/crates/store/re_sdk_comms/src/buffered_client.rs#L2) communicates just via sockets
  - intermediate solution is [socat](https://linux.die.net/man/1/socat)

```bash
brew install socat
socat TCP4-LISTEN:6666,fork SYSTEM:"curl -X POST -d @- http://172.30.2.224/some/rerun/sdk/"

{ echo "load_module /usr/lib/nginx/modules/ngx_stream_module.so;"; cat /etc/nginx/nginx.conf; } > temp_file && mv temp_file /etc/nginx/nginx.conf
```

# 📝 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

