Restructure example docs by ratheron · Pull Request #138 · learnsyslab/crazyflow

ratheron · 2026-10-13T21:19:26Z

With this PR, the docs contain all examples (tested with new test). To make it less crowded (#131), the docs are strucuted as the example folders. Also, instead of having the information per example twice, we only have the docstring, which is also written into the docs during building (new script for that). Since the code of some examples is long, the code is now collapsible.

Additionally, I added some quality of life fixes, such as a --plot flag with no plotting when running regularly (would crash in the base env) and unifying the naming inside the examples (all now use trajectory() for the reference and similar changes).

This PR turned out longer than intended. Most of it is just shifting things around though. If I should split this into multiple PRs, lmk.

amacati · 2026-10-14T21:12:28Z

As we discussed before, the videos should not be included in this PR. We can add the CI job to generate them on the fly in a follow-up

ratheron · 2026-10-16T14:15:01Z

Done

amacati · 2026-10-18T18:10:03Z

-```{ .python notest }
--8<-- "examples/environments/figure8.py"
-```
+The runnable examples are grouped by topic, following the folders in `examples/`. Start with [hover](control.md#hover) if you're new, or jump to the group that matches your use case. Run an example from the repository root with `python examples/<group>/<script>.py`.


Suggested change

The runnable examples are grouped by topic, following the folders in `examples/`. Start with [hover](control.md#hover) if you're new, or jump to the group that matches your use case. Run an example from the repository root with `python examples/<group>/<script>.py`.

The runnable examples are grouped by topic, following the folders in `examples/`. Start with [hover](control.md#hover) if you're new, or jump to the group that matches your use case. Run an example from the repository root with `pixi run python examples/<group>/<script>.py`.

amacati · 2026-10-18T18:23:00Z

+
+The body rate controller keeps the attitude terms of the Mellinger controller, which level the
+drone at its current yaw and counteract the commanded rates. The example sets their `kR` and `ki_m`
+gains to zero to track the body rates.


Suggested change

gains to zero to track the body rates.

gains to zero to freely track the body rates.

amacati · 2026-10-18T18:26:09Z

+        commands = np.stack([trajectory(t) for t in times])
        reference = commands[:, 0, 0, 0:3]
-        trajectory = [np.asarray(sim.data.states.pos[0, 0])]
+        positions = [np.asarray(sim.data.states.pos[0, 0])]


Can we fix unnecessary asarray uses while we are reworking the docs?

amacati · 2026-10-18T18:31:29Z

+The goal position is set through the reset options, and the `JaxToNumpy` wrapper converts between
+NumPy actions and JAX observations.


Suggested change

The goal position is set through the reset options, and the `JaxToNumpy` wrapper converts between

NumPy actions and JAX observations.

The `JaxToNumpy` wrapper converts between NumPy actions and JAX observations.

amacati · 2026-10-18T18:32:54Z

+
+Because the simulator is built entirely from JAX operations, `jax.grad` can differentiate through
+it. Starting the drone in the air keeps it away from the floor, so the floor-clipping stage never
+fires and gradients flow freely through the entire trajectory.


Suggested change

fires and gradients flow freely through the entire trajectory.

applies and gradients flow freely through the entire trajectory.

amacati · 2026-10-18T22:30:41Z

+Two drones circle the hall center while facing each other. Requires splax
+(`pip install "crazyflow[splats]"`) and a CUDA GPU.


Suggested change

Two drones circle the hall center while facing each other. Requires splax

(`pip install "crazyflow[splats]"`) and a CUDA GPU.

Requires splax (`pip install "crazyflow[splats]"`) and a CUDA GPU.

amacati · 2026-10-18T22:33:03Z

@@ -1,17 +1,22 @@
-"""Animate the splat depth camera of a drone flying an elliptical lap through the flight hall.
+"""Example where a drone flies a lap through a hall and renders gaussian splat depth images.


Suggested change

"""Example where a drone flies a lap through a hall and renders gaussian splat depth images.

"""Fly a lap through a hall and renders gaussian splat depth images.

amacati · 2026-10-18T22:33:49Z

+`build_render_splat_rgbd_fn` compiles an RGB-D renderer that is a pure function of `sim.data`. The
+depth is measured along the optical axis and clipped to `max_range`. Requires splax
+(`pip install "crazyflow[splats]"`) and a CUDA GPU.


Suggested change

`build_render_splat_rgbd_fn` compiles an RGB-D renderer that is a pure function of `sim.data`. The

depth is measured along the optical axis and clipped to `max_range`. Requires splax

(`pip install "crazyflow[splats]"`) and a CUDA GPU.

`build_render_splat_rgbd_fn` compiles an RGB-D renderer that is a pure function of `sim.data`.

Requires splax (`pip install "crazyflow[splats]"`) and a CUDA GPU.

amacati · 2026-10-18T22:37:09Z

+baseline pose, and its photometric error is differentiated over small z and yaw offsets. The
+resulting gradients match the gradient of the squared pose error in sign and shape. Requires splax
+(`pip install "crazyflow[splats]"`) and a CUDA GPU.


Suggested change

baseline pose, and its photometric error is differentiated over small z and yaw offsets. The

resulting gradients match the gradient of the squared pose error in sign and shape. Requires splax

(`pip install "crazyflow[splats]"`) and a CUDA GPU.

baseline pose, and its photometric error is differentiated over small z and yaw offsets.

Requires splax (`pip install "crazyflow[splats]"`) and a CUDA GPU.

amacati · 2026-10-18T22:38:25Z

+def test_examples_in_docs():
+    """Every example script has a section in the example docs, and every section has a script."""
+    directive = re.compile(r'^--8<-- example "examples/(.+)"$', re.MULTILINE)
+    pages = DOCS_EXAMPLES_DIR.glob("*.md")
+    documented = {path for page in pages for path in directive.findall(page.read_text())}
+    scripts = {path.relative_to(EXAMPLES_DIR).as_posix() for path in EXAMPLES_DIR.rglob("*.py")}
+    assert not scripts - documented, f"Missing from docs/examples: {sorted(scripts - documented)}"
+    assert not documented - scripts, f"Stale in docs/examples: {sorted(documented - scripts)}"


Why is this here? We are already testing the examples outside the docs, aren't we?

ratheron added 2 commits October 13, 2026 13:53

Split examples into topic pages and add splat rendering docs

a6e7528

Update example docs and fix examples

2f283a0

ratheron requested a review from amacati October 13, 2026 21:19

Remove splat media from the example docs

c3f8f24

amacati reviewed Oct 18, 2026

View reviewed changes

Navigation Menu

Repository navigation

Restructure example docs - #138

Restructure example docs#138
ratheron wants to merge 3 commits into
mainfrom
fix.docs

ratheron commented Oct 13, 2026

Uh oh!

amacati commented Oct 14, 2026

Uh oh!

ratheron commented Oct 16, 2026

Uh oh!

amacati Oct 18, 2026

Uh oh!

amacati Oct 18, 2026

Uh oh!

amacati Oct 18, 2026

Uh oh!

amacati Oct 18, 2026

Uh oh!

amacati Oct 18, 2026

Uh oh!

amacati Oct 18, 2026

Uh oh!

amacati Oct 18, 2026

Uh oh!

amacati Oct 18, 2026

Uh oh!

amacati Oct 18, 2026

Uh oh!

amacati Oct 18, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	The runnable examples are grouped by topic, following the folders in `examples/`. Start with [hover](control.md#hover) if you're new, or jump to the group that matches your use case. Run an example from the repository root with `python examples/<group>/<script>.py`.
	The runnable examples are grouped by topic, following the folders in `examples/`. Start with [hover](control.md#hover) if you're new, or jump to the group that matches your use case. Run an example from the repository root with `pixi run python examples/<group>/<script>.py`.

	gains to zero to track the body rates.
	gains to zero to freely track the body rates.

		The goal position is set through the reset options, and the `JaxToNumpy` wrapper converts between
		NumPy actions and JAX observations.

	The goal position is set through the reset options, and the `JaxToNumpy` wrapper converts between
	NumPy actions and JAX observations.
	The `JaxToNumpy` wrapper converts between NumPy actions and JAX observations.

	fires and gradients flow freely through the entire trajectory.
	applies and gradients flow freely through the entire trajectory.

		Two drones circle the hall center while facing each other. Requires splax
		(`pip install "crazyflow[splats]"`) and a CUDA GPU.

	Two drones circle the hall center while facing each other. Requires splax
	(`pip install "crazyflow[splats]"`) and a CUDA GPU.
	Requires splax (`pip install "crazyflow[splats]"`) and a CUDA GPU.

		@@ -1,17 +1,22 @@
		"""Animate the splat depth camera of a drone flying an elliptical lap through the flight hall.
		"""Example where a drone flies a lap through a hall and renders gaussian splat depth images.

	"""Example where a drone flies a lap through a hall and renders gaussian splat depth images.
	"""Fly a lap through a hall and renders gaussian splat depth images.

Conversation

ratheron commented Oct 13, 2026

Uh oh!

amacati commented Oct 14, 2026

Uh oh!

ratheron commented Oct 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants