chore: import upstream snapshot with attribution

2026-07-13 13:05:14 +08:00
commit 2a547be7fe
7904 changed files with 1000926 additions and 0 deletions
@@ -0,0 +1,83 @@
+# 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.