wehub-resource-sync
84 lines
3.1 KiB
Markdown
84 lines
3.1 KiB
Markdown
# Rerun Python examples
|
|
The simplest example is [`minimal`](minimal/minimal.py). You may want to start there!
|
|
|
|
Read more about our examples at <https://www.rerun.io/examples>.
|
|
|
|
## Setup
|
|
First install the Rerun Python SDK with `pip install rerun-sdk` or via [`conda`](https://github.com/conda-forge/rerun-sdk-feedstock).
|
|
|
|
> Note: Make sure your SDK version matches the code in the examples.
|
|
For example, if your SDK version is `0.15.1`, check out the matching tag
|
|
for this repository by running `git checkout v0.15.1`.
|
|
|
|
## Installing the example
|
|
Each example is packaged as a regular Python package, with a `pyproject.toml` file specifying its required dependencies. To run an example, it must first be installed.
|
|
|
|
For example, to install dependencies and run the toy `minimal` example (which doesn't need to download any data) run:
|
|
|
|
```sh
|
|
pip install -e examples/python/minimal
|
|
```
|
|
|
|
**Note**: it is import to install example in editable mode, which is done using the `-e` flag (short for `--editable`).
|
|
|
|
Once installed, the example can be run as a regular Python module:
|
|
|
|
```shell
|
|
python -m minimal
|
|
```
|
|
|
|
Examples also declare console script, so they can also be run directly:
|
|
|
|
```shell
|
|
minimal
|
|
```
|
|
|
|
|
|
## Running the examples
|
|
By default, the examples spawn a Rerun Viewer and stream log data to it.
|
|
|
|
For most examples you can instead save the log data to an `.rrd` file using `plots --save data.rrd`. You can then view that `.rrd` file with `rerun data.rrd`.
|
|
|
|
(`rerun` is an alias for `python -m rerun`).
|
|
|
|
NOTE: `.rrd` files do not yet guarantee any backwards or forwards compatibility. One version of Rerun will likely not be able to open an `.rrd` file generated by another Rerun version.
|
|
|
|
## Running examples with Pixi
|
|
|
|
The Rerun project makes extensive use of [Pixi](https://pixi.sh/latest/) for various developer tasks, and Pixi can be used to run examples as well. For this, you need to install Pixi as per the installation instructions on their website.
|
|
|
|
### Running examples with Pixi from source
|
|
|
|
You can build Rerun from source, and install it in the uv environment managed by Pixi. Note that this requires a Rust toolchain to be installed on your system.
|
|
|
|
Before running examples, build the SDK:
|
|
```shell
|
|
pixi run py-build
|
|
```
|
|
|
|
Now you can run examples via uv:
|
|
```shell
|
|
pixi run uv run examples/python/minimal/minimal.py
|
|
```
|
|
|
|
### Installing and running examples
|
|
You can install all of the rerun python examples into the uv managed environment with:
|
|
```shell
|
|
pixi run py-build-examples
|
|
```
|
|
|
|
Then you can just examples based on their installed name, for example:
|
|
```shell
|
|
pixi run uv run plots
|
|
```
|
|
|
|
## Datasets
|
|
Some examples will download a small datasets before they run. They will do so the first time you run the example. The datasets will be added to a subdir called `dataset`, which is in the repo-wide `.gitignore`.
|
|
|
|
## Contributions welcome
|
|
Feel free to open a PR to add a new example!
|
|
|
|
If you add an example, please make sure to add the corresponding entry to the top-level `pixi.toml` file as well, otherwise it will not be picked up.
|
|
|
|
See [`CONTRIBUTING.md`](../../CONTRIBUTING.md) for details on how to contribute.
|