Skip to content

Development

Warning

Under development. This page may not reflect the current state of the source. We're working on it.

Building the Python extension

No need to install maturin yourself — uv fetches it automatically as a PEP 517 build backend.

The repo is a uv workspace of three packages. python/misina-lab is plain Python: the USD builder and the Isaac Lab spawner every generator shares. crates/vinery-lab is a maturin project in its mixed layout: hand-written Python lives in crates/vinery-lab/python/vinery_lab/, and the compiled Rust extension is built into it as the _core submodule, which __init__.py re-exports. Only the isaaclab subpackages import Isaac Lab, so plain import vinery_lab stays usable without it. crates/greenhouse-lab is laid out the same way, as greenhouse_lab; --reinstall-package greenhouse-lab rebuilds it.

How the binding surface is shaped — why fragments are Py<T>, what write_usd releases the GIL around — is in the framework's generators.md.

Iterating on the wrapper itself

uv sync                                  # at the repo root; builds the extension
uv sync --reinstall-package vinery-lab    # after a Rust change

Consuming it as a dependency (e.g. examples/isaaclab_demo)

cd examples/isaaclab_demo
uv sync
uv run python main.py

If you only changed Rust source (not pyproject.toml), force a rebuild:

uv sync --reinstall-package vinery-lab

Build the distributions

CARGO_TARGET_DIR=$PWD/target uv build --all-packages

An sdist and a wheel for each package, into dist/, as the release workflow builds them. Each wheel is built from its sdist in a scratch directory; the target directory lets them reuse this checkout's compiled dependencies instead of building Bevy once per generator.

Checks

.github/workflows/ci.yml runs all of these on every push and pull request:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --features vinery-lab/python,greenhouse-lab/python -- -D warnings
cargo test --workspace
ruff check . && ruff format --check .
mypy
pytest tests

Each generator's python feature is what puts the PyO3 side — crates/misina-lab/src/python.rs and what the generator! macro emits — in front of clippy. It is out of the default feature set, so a plain cargo clippy never sees it.

cargo test also fails while a generator's Python stub, its Isaac Lab cfg classes or its docs/parameters.md are stale against the Rust params structs they are generated from. cargo test regen_params -- --ignored rewrites them — see editing-parameters.md.

Isaac Lab is not installed on the runner, so tests/test_isaaclab_cfg.py skips itself there. It runs locally, from the demo venv:

examples/isaaclab_demo/.venv/bin/python -m pytest tests/ -q -s < /dev/null

Capture has to be off: pytest's stdin capture breaks Kit's kernel bootstrap. The demo's own tests live beside its code and run the same way:

examples/isaaclab_demo/.venv/bin/python -m pytest examples/isaaclab_demo -q -s < /dev/null

Formatting and the fast lints are also available as commit hooks:

uvx pre-commit install

Clippy and the test suites stay out of them — a Bevy rebuild is too slow to sit in front of a commit.

Releasing

misina-lab, vinery-lab and greenhouse-lab release to PyPI together, under the workspace version, [workspace.package] in the root Cargo.toml. The generators' wheels take it from their crates. Two other places spell it out: version in python/misina-lab/pyproject.toml, and the misina-lab== pin in each generator's pyproject.toml. tests/test_versions.py fails until all four agree.

  1. Bump the version in all four places and merge.
  2. Tag the merge commit v<version> and push the tag.

.github/workflows/release.yml then builds an sdist and a Linux x86_64 wheel for each package and publishes them. A manual run of it from a branch builds them without publishing.

Publishing goes through PyPI's trusted publishing, so no token is stored. Each project's publisher on PyPI names the azazdeaz/misina-lab repository, the release.yml workflow and the pypi environment. A project not on PyPI yet takes a pending publisher, which its first upload turns into the project. Renaming the repository means updating all three publishers.

Viewer (interactive)

cargo run --release                         # the vineyard
cargo run --release -p greenhouse-lab       # the greenhouse

The panel is built from the params structs: one section per fragment of VineyardParams, one control per field, with the caption, range and tooltip read off the field's declaration — see crates/misina-lab/src/ui.rs and editing-parameters.md. Sliders write a staged copy of the params; a value reaches the live resources once it has held still for 150 ms, and re-runs the layers below it. Dragging one is a single rebuild rather than one per frame.

Clicking a slider without dragging it turns it into a text field, as Blender's sliders do: the number starts selected, Enter or clicking away applies it, Escape drops it. A typed value is clamped to the slider's range.

The footer's Colliders box draws what a physics engine collides with over the scene: in magenta the capsules nothing moves, the posts' and the wood's proxies and each rod's held first segment; in yellow every other rod segment, as thick as the mean of the widths at its two ends, which is how Newton sizes it; in cyan the meshes that collide as themselves, the ground among them. See crates/misina-lab/src/colliders.rs.

Press S to write the scene out as scene.json, and build it with:

python -m misina_lab.usd scene.json scene.usd

Press P to log the camera as a storyboard's camera, ready to paste into a storyboard or a docs picture: that is how a view framed by hand goes into either.

VINERY_LAB_PERF=1 cargo run logs a per-layer breakdown on any frame that rebuilt something — the marks are crates/vinery-lab/src/perf.rs, the report crates/misina-lab/src/perf.rs.

VINERY_LAB_RECORD=demo.mp4 cargo run --release records the window for the whole run, for demo videos. One captured frame becomes one video frame, so the stall a rebuild causes costs a frame rather than the freeze a screen recorder would keep. Frames are piped to ffmpeg, which has to be on PATH; the extension picks the container. VINERY_LAB_RECORD_FPS sets the rate, 30 by default, and is also how often a frame is captured. See crates/misina-lab/src/record.rs.

VINERY_LAB_TOUR=docs/video/vinery-lab.json cargo run --release plays a storyboard of camera moves and panel edits, then hands the window back to the pointer. A slider it slides rebuilds the scene at every frame of the slide, not once it settles as a drag does. With VINERY_LAB_RECORD set too its clock advances one video frame per rendered frame, so the recording is smooth however long the rebuilds take, and the app quits at the end; docs/video/record.sh [crate] records a README video that way, the vineyard's or, with greenhouse-lab, the greenhouse's. VINERY_LAB_SHOT=still.png instead saves the last frame as the storyboard ends, and quits. With either set the viewer opens no window: the camera draws the scene and the panel into an image of the storyboard's size, so a still or a video needs no display. See crates/misina-lab/src/tour.rs, and the skill for changing the videos.

The pruning, greenhouse and straddler demos' videos are filmed in Isaac Sim instead, headless: each demo's record.sh runs its video.py, which samples an RTX camera on the simulation's clock through misina_lab.isaaclab.film. All four scripts encode what they record with docs/video/encode.sh. See the pruning video's skill for changing that one. docs/video/publish.sh uploads any of the videos to the branch's pull request and puts the link GitHub gives it in its README. github.com plays only video that GitHub hosts, so the videos stay uploads; the pictures are published separately, see Docs pictures.

Web build

Each generator's viewer, compiled to wasm, is a playground: vinery and greenhouse. The manually triggered .github/workflows/playground.yml builds both and attaches a bundle per playground to the playground release, which the site is deployed from; see Docs site. To reproduce one locally, here the greenhouse:

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.127   # must match Cargo.lock
cargo build --profile wasm-release --target wasm32-unknown-unknown -p greenhouse-lab --bins
mkdir -p site/playground/greenhouse
sed 's/{title}/Greenhouse Lab/' web/index.html > site/playground/greenhouse/index.html
wasm-bindgen --target web --no-typescript --out-name viewer --out-dir site/playground/greenhouse \
  target/wasm32-unknown-unknown/wasm-release/greenhouse-lab.wasm
python3 -m http.server -d site 8000      # localhost:8000/playground/greenhouse/

A docs build empties site/ first, so build the playground after it. Serve it rather than opening the file: the module is fetched, and localhost is a secure context, which both WebGPU and the clipboard require.

Two things differ from the native build. The renderer is WebGPU — the webgpu feature in crates/misina-lab/Cargo.toml is target-gated, and WebGL2 would lose compute shaders, which this many meshes need. And the S key is compiled out, since there is no filesystem to write scene.json to; Copy Isaac Lab cfg is the whole export path on the web.

Docs pictures

The pictures in the docs are rendered from shots, JSON files under docs/shots/ that hold the scene's parameters, the camera, the size, and for Isaac Lab how long the robot walks first:

docs/shots/render.sh     # every shot, into target/docs-assets
docs/shots/publish.sh    # force-pushes that folder to the assets repository

docs/shots/A/B.json becomes A/B.webp in azazdeaz/misina-lab-docs-assets, which holds only the current set, and a page links it as https://raw.githubusercontent.com/azazdeaz/misina-lab-docs-assets/main/A/B.webp. A viewer shot is a storyboard with no steps; an Isaac Lab shot is read by the example's shot.py. Both take the camera in a storyboard's terms, and both apps print their camera on P, so a view placed by hand goes straight into a shot. The skill is the how-to.

Docs site

azazdeaz.github.io/misina-lab is built with Zensical from the pages where they live in the repository. The nav in zensical.toml lists every page on the site by its path, and web/stage_docs.py copies those pages to target/docs under the same paths: a link between two pages works as written, and every other link, to source or to a page left off the site, is pointed at GitHub at the commit being built. A line holding only a github.com/user-attachments URL, which GitHub plays as a video, becomes a <video> tag in the staged copy. tests/test_docs.py fails while a page of a docs folder is missing from the nav.

python3 web/stage_docs.py
uv run --only-group docs zensical serve    # localhost:8000

The server rebuilds when the staged copy changes, so re-run the script after editing a page. zensical build writes the site to site/ instead.

.github/workflows/pages.yml builds the site on every push to main and after every successful playground build, unpacks each bundle of the playground release under /playground/, and deploys the lot. A Pages deploy replaces the whole site, so it is the only workflow that deploys. It fails while that release does not exist, so the Playground workflow has to have run once.