hyperray 0.0.1__py3-none-any.whl

hyperdrone/examples/HyperDrone.ipynb

@@ -0,0 +1,589 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/rl-tools/rl-tools/blob/master/interface/python/hyperdrone/hyperdrone/examples/HyperDrone.ipynb)\n",
+    "\n",
+    "# HyperDrone\n",
+    "\n",
+    "Fly the C++ RLtools training environment from Python: **use it, configure it, drive it,\n",
+    "or extend it**. Each section produces a short video; the last cell combines them into\n",
+    "`hyperdrone.mp4`.\n",
+    "\n",
+    "1. **Fly the preset** — an X500 with tiled sensor outputs, then six different drone models flying together.\n",
+    "2. **A task is one knob** — current and target images, side by side.\n",
+    "3. **Your own task is a Python loop** — rewards, goals, and independent episode resets.\n",
+    "4. **Your own world is a small C++ header** — shutter sampling and anti-aliasing.\n",
+    "\n",
+    "RAPTOR supplies the motor commands using **privileged state**, not pixels. The images\n",
+    "are the environment's visual observations; this is an API demonstration, not a trained\n",
+    "visual-navigation policy. First construction JIT-compiles each configuration and caches it."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "import importlib.util\n",
+    "import site\n",
+    "import sysconfig\n",
+    "from pathlib import Path\n",
+    "\n",
+    "checkout = next((path for path in [Path.cwd(), *Path.cwd().parents] if (path / \"interface/python/hyperdrone/pyproject.toml\").is_file()), None)\n",
+    "if checkout is not None:\n",
+    "    %pip install -q -e \"{checkout}/interface/python/hyperdrone[examples]\"\n",
+    "    site.addsitedir(sysconfig.get_paths()[\"purelib\"])  # activates the editable install's .pth without a kernel restart\n",
+    "elif importlib.util.find_spec(\"hyperdrone\") is None:  # fresh runtime (e.g. Colab)\n",
+    "    %pip install -q \"hyperdrone[examples]\"\n",
+    "%pip install -q foundation-policy==1.0.1"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Setup\n",
+    "\n",
+    "The two content hashes pin the scene corpus; `conta` downloads it once into the shared\n",
+    "cache. Every listed scene stays resident, so keep this working set small. Recorded\n",
+    "[shot coordinates](shots.py) pin each episode independently of the RNG; camera mounts\n",
+    "remain explicit below. To compose new shots, capture `env.spawn_points()` after a reset.\n",
+    "\n",
+    "We film at 25 FPS, capturing every fourth 10 ms dynamics step: playback is real time.\n",
+    "The preset examples use eight shutter samples for motion blur; set `motion_blur_samples=1`\n",
+    "for faster previews. Small initial displacements and nearby goals keep the flights compact.\n",
+    "\n",
+    "The folded cell below contains only video-formatting helpers."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "from itertools import cycle\n",
+    "from contextlib import closing\n",
+    "from dataclasses import replace\n",
+    "from pathlib import Path\n",
+    "\n",
+    "import numpy as np\n",
+    "from foundation_policy import Raptor\n",
+    "from IPython.display import Video, display\n",
+    "from scipy.spatial.transform import Rotation\n",
+    "\n",
+    "import hyperdrone\n",
+    "from hyperdrone import render\n",
+    "from hyperdrone.env import EnvConfig, MultiEnvironment\n",
+    "from hyperdrone.examples.data import PROCTHOR_SCENE, rigged_model_path, x500_model_path\n",
+    "from hyperdrone.examples.shots import HYPERDRONE_SHOTS as shots\n",
+    "\n",
+    "hyperdrone.set_verbosity(\"warning\")\n",
+    "\n",
+    "scenes = [PROCTHOR_SCENE, {\n",
+    "    \"description\": \"ai2thor-hab/glb/ProcTHOR-Train-0.glb\",\n",
+    "    \"hash\": \"28d17959b463626d64257f0d9ea8e47daae68409\",\n",
+    "}]\n",
+    "WIDTH, HEIGHT = 640, 360\n",
+    "STEPS, STRIDE, FPS = 500, 4, 25\n",
+    "output = Path(\"hyperdrone_videos\")\n",
+    "output.mkdir(exist_ok=True)\n",
+    "drone_asset = x500_model_path()\n",
+    "config = EnvConfig(instances_per_environment=1, width=WIDTH, height=HEIGHT, preset=\"x500_fpv\", motion_blur_samples=8)\n",
+    "initial = {\"mdp\": {\"init\": {\n",
+    "    \"guidance\": 0.0, \"max_position\": 0.25, \"max_angle\": 0.1,\n",
+    "    \"max_linear_velocity\": 0.0, \"max_angular_velocity\": 0.0,\n",
+    "    \"min_rpm\": 0.0, \"max_rpm\": 0.0,\n",
+    "}}}\n",
+    "\n",
+    "def camera(position, pitch, yaw, fov):\n",
+    "    orientation = Rotation.from_euler(\"ZY\", [yaw, pitch]).as_quat()[[3, 0, 1, 2]].tolist()\n",
+    "    return {\"fov\": fov, \"mount\": {\"pose\": {\"position\": position, \"orientation\": orientation}}}\n",
+    "\n",
+    "fpv = camera([0.1, 0, 0.32], 0.3, 0, 100)\n",
+    "chase = camera([-0.8, -0.8, 0.6], 0.45, np.pi / 4, 65)"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {
+    "jupyter": {
+     "source_hidden": true
+    }
+   },
+   "source": [
+    "from itertools import zip_longest\n",
+    "\n",
+    "import imageio.v2 as imageio\n",
+    "import matplotlib\n",
+    "from PIL import Image, ImageDraw, ImageFont, ImageOps\n",
+    "\n",
+    "\n",
+    "FONT = ImageFont.truetype(str(Path(matplotlib.get_data_path()) / \"fonts/ttf/DejaVuSans.ttf\"), 16)\n",
+    "\n",
+    "\n",
+    "def rgb(image):\n",
+    "    return image if image.dtype == np.uint8 else (np.clip(image, 0, 1) * 255).astype(np.uint8)\n",
+    "\n",
+    "\n",
+    "def writer(path, fps):\n",
+    "    return imageio.get_writer(str(path), fps=fps, codec=\"libx264\", quality=8, macro_block_size=1)\n",
+    "\n",
+    "\n",
+    "def panel(images, titles):\n",
+    "    images = [rgb(image) for image in images]\n",
+    "    height, width = images[0].shape[:2]\n",
+    "    canvas = Image.new(\"RGB\", (width * len(images), height + 32), \"#111827\")\n",
+    "    draw = ImageDraw.Draw(canvas)\n",
+    "    for i, (image, title) in enumerate(zip(images, titles)):\n",
+    "        canvas.paste(Image.fromarray(image), (i * width, 32))\n",
+    "        draw.text((i * width + 12, 6), title, font=FONT, fill=\"#e5e7eb\")\n",
+    "    return np.asarray(canvas)\n",
+    "\n",
+    "\n",
+    "def sensor_panel(depth, labels, normals, flow, status):\n",
+    "    depth_image = matplotlib.colormaps[\"viridis\"](np.clip(depth / 10, 0, 1))[..., :3]\n",
+    "    depth_image[labels == 0xFFFFFFFF] = 0\n",
+    "    label_image = matplotlib.colormaps[\"tab20\"](labels % 20)[..., :3]\n",
+    "    label_image[labels == 0xFFFFFFFF] = 0\n",
+    "    normal_image = np.clip(normals * 0.5 + 0.5, 0, 1)\n",
+    "    normal_image[np.all(normals == 0, axis=-1)] = 0\n",
+    "    flow_image = matplotlib.colormaps[\"magma\"](np.clip(np.linalg.norm(flow, axis=-1) / 50, 0, 1))[..., :3]\n",
+    "    flow_image[status != render.FlowStatus.VALID] = 0\n",
+    "    images = [np.asarray(Image.fromarray(rgb(image)).resize((WIDTH // 2, HEIGHT // 2), Image.Resampling.NEAREST))\n",
+    "              for image in (depth_image, label_image, normal_image, flow_image)]\n",
+    "    return panel(images, [\"FPV depth | 0-10 m\", \"FPV semantic IDs\",\n",
+    "                          \"FPV world normals\", \"FPV flow | 0-50 px\"])\n",
+    "\n",
+    "\n",
+    "def pair(left, right, output, titles, fps):\n",
+    "    with imageio.get_reader(str(left)) as a, imageio.get_reader(str(right)) as b, writer(output, fps) as out:\n",
+    "        for images in zip_longest(a, b):\n",
+    "            if any(image is None for image in images):\n",
+    "                raise ValueError(\"The two camera takes have different frame counts\")\n",
+    "            out.append_data(panel(images, titles))\n",
+    "\n",
+    "\n",
+    "def join(paths, output, fps):\n",
+    "    with imageio.get_reader(str(paths[0])) as first:\n",
+    "        size = first.get_meta_data()[\"size\"]\n",
+    "    with writer(output, fps) as out:\n",
+    "        for path in paths:\n",
+    "            with imageio.get_reader(str(path)) as source:\n",
+    "                for frame in source:\n",
+    "                    out.append_data(np.asarray(ImageOps.pad(Image.fromarray(frame), size, color=\"#111827\")))"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "def block(state, layout, name):\n",
+    "    offset, size = layout.blocks[name]\n",
+    "    return state[:, offset:offset + size]\n",
+    "\n",
+    "def pilots(env):\n",
+    "    policies = [Raptor() for _ in range(env.total_instances * env.num_agents)]\n",
+    "    for policy in policies:\n",
+    "        policy.reset()\n",
+    "    return policies, np.zeros((env.total_instances, env.action_dim), dtype=np.float32)\n",
+    "\n",
+    "def act(env, policies, previous, target=0, layout=None):\n",
+    "    layout = env.observation_layout_privileged if layout is None else layout\n",
+    "    state = env.observe_privileged().reshape(env.total_instances * env.num_agents, -1)\n",
+    "    prefix = \"agent0/\" if env.num_agents > 1 else \"\"\n",
+    "    observation = np.concatenate([\n",
+    "        block(state, layout, prefix + \"position\") - target,\n",
+    "        *[block(state, layout, prefix + name) for name in\n",
+    "          (\"orientation_rotation_matrix\", \"linear_velocity\", \"angular_velocity\")],\n",
+    "        previous.reshape(len(policies), -1),\n",
+    "    ], axis=1)\n",
+    "    return np.concatenate([policy.evaluate_step(row[None]) for policy, row in zip(policies, observation)]).astype(np.float32).reshape(env.total_instances, env.action_dim)\n",
+    "\n",
+    "def replay(configuration, tape, mount, path):\n",
+    "    with closing(MultiEnvironment(scenes, config=configuration, drone_asset=drone_asset,\n",
+    "                                  parameters={\"dynamics\": x500_dynamics, \"cameras\": [mount]})) as take:\n",
+    "        take.reset(spawn_points=shots[\"flight\"])\n",
+    "        fps = 1 / (STRIDE * take.dt)\n",
+    "        with writer(path, fps) as video:\n",
+    "            for step, (action, state) in enumerate(tape):\n",
+    "                take.step(action)\n",
+    "                np.testing.assert_array_equal(take.observe_privileged(), state)\n",
+    "                if (step + 1) % STRIDE == 0:\n",
+    "                    image = take.observe().reshape(-1, HEIGHT, WIDTH, 3)[0]\n",
+    "                    video.append_data(rgb(image))"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. Fly the preset\n",
+    "\n",
+    "`preset=\"x500_fpv\"` selects the platform, including its visible body and dynamics-driven\n",
+    "propellers. Fly back to the origin, then shift the goal by 25 cm. These coordinates are\n",
+    "relative to the episode's scene placement, not absolute room coordinates.\n",
+    "\n",
+    "One environment carries two camera mounts on the same drone, so FPV and chase views\n",
+    "share the same flight and capture time. Below them, tile the FPV depth,\n",
+    "semantic segmentation, world normals, and optical flow from the same capture.\n",
+    "\n",
+    "`output=` enables auxiliary arrays shaped `(total_instances, num_views, H, W[, channels])`;\n",
+    "where `num_views = num_agents * num_cameras_per_agent`, ordered by agent then camera.\n",
+    "Policy observations remain RGB. The environment handles capture history and masked resets.\n",
+    "Flow measures current-to-previous capture displacement in pixels; invalid flow and missed\n",
+    "surfaces are black. Depth (0–10 m) and flow (0–50 px) use fixed scales, and each semantic\n",
+    "ID keeps its palette color across frames.\n",
+    "\n",
+    "`dataset=\"procthor\"` validates the scenes' `ai2thor-hab` taxonomy. With\n",
+    "`semantic_segmentation=True`, `env.segmentation()` returns class IDs and\n",
+    "`env.segmentation_classes` gives the shared `{id: name}` dictionary for all loaded scenes.\n",
+    "Below we print the classes visible in the first frame. ID `0` is Undefined;\n",
+    "`0xFFFFFFFF` is background and is absent from the dictionary. Set\n",
+    "`semantic_segmentation=False` to obtain instance IDs instead.\n",
+    "\n",
+    "The model fits use normalized motor speed. Use the same illustrative 10,000 RPM full\n",
+    "scale as Renderer.ipynb, rescaling each thrust polynomial to preserve its force curve.\n",
+    "These parameters drive propeller animation in every section, including after resets.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "with closing(MultiEnvironment(scenes, config=config, drone_asset=drone_asset)) as preset:\n",
+    "    print(f\"Rendering backend: {preset.render_backend}\")\n",
+    "    nominal_dynamics = preset.parameters[\"dynamics\"][\"dynamics\"]\n",
+    "\n",
+    "def rpm_parameters(nominal, scale=10_000.0):\n",
+    "    return {\n",
+    "        \"action_limit\": {key: value * scale for key, value in nominal[\"action_limit\"].items()},\n",
+    "        \"rotor_thrust_coefficients\": (np.array(nominal[\"rotor_thrust_coefficients\"]) /\n",
+    "                                      [1, scale, scale ** 2]).tolist(),\n",
+    "    }\n",
+    "\n",
+    "x500_motors = rpm_parameters(nominal_dynamics)\n",
+    "x500_dynamics = {**initial, \"dynamics\": x500_motors}\n",
+    "\n",
+    "sensor_config = replace(config, num_cameras_per_agent=2, dataset=\"procthor\", semantic_segmentation=True,\n",
+    "                        output=(\"rgb\", \"depth\", \"segmentation\", \"normals\", \"flow\"))\n",
+    "with closing(MultiEnvironment(scenes, config=sensor_config, drone_asset=drone_asset,\n",
+    "                              parameters={\"dynamics\": x500_dynamics, \"cameras\": [fpv, chase]})) as env:\n",
+    "    env.reset(spawn_points=shots[\"flight\"])\n",
+    "    env.observe()\n",
+    "    semantic_classes = env.segmentation_classes\n",
+    "    semantic_ids = env.segmentation()[0, 0]\n",
+    "    print(\"Visible semantic IDs:\", {int(id): semantic_classes[int(id)]\n",
+    "                                    for id in np.unique(semantic_ids) if id != 0xFFFFFFFF})\n",
+    "    base_layout = env.observation_layout_privileged\n",
+    "    image_layout = env.observation_layout\n",
+    "    policies, previous = pilots(env)\n",
+    "    assert np.isclose(STRIDE * env.dt, 1 / FPS)\n",
+    "    with writer(output / \"01-preset.mp4\", FPS) as video:\n",
+    "        for step in range(STEPS):\n",
+    "            target = np.array([0.25 if step >= 200 else 0, 0, 0], dtype=np.float32)\n",
+    "            previous = act(env, policies, previous, target)\n",
+    "            env.step(previous)\n",
+    "            if (step + 1) % STRIDE == 0:\n",
+    "                frames = env.frames().reshape(env.num_views, HEIGHT, WIDTH, 3)\n",
+    "                views = panel(frames,\n",
+    "                              [\"1 / Fly the preset - FPV\", \"Same flight - chase camera\"])\n",
+    "                sensors = sensor_panel(env.depth()[0, 0], env.segmentation()[0, 0],\n",
+    "                                       env.normals()[0, 0], env.flow()[0, 0], env.flow_status()[0, 0])\n",
+    "                video.append_data(np.concatenate([views, sensors], axis=0))\n",
+    "\n",
+    "display(Video(str(output / \"01-preset.mp4\"), embed=True))"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Multiple drone models\n",
+    "\n",
+    "An instance is a group of mutually visible agents: `instances_per_environment=1, num_agents=7` puts six\n",
+    "models and a filming drone in one episode. Each agent has its own dynamics, camera,\n",
+    "and RAPTOR pilot; all share the scene placement and reset together. The filming drone\n",
+    "hovers behind the formation while the others move between nearby goals.\n",
+    "\n",
+    "`drones=` is the model catalog. Reset normally samples each agent's entry independently;\n",
+    "our recorded spawn pins one of each model. `instance_parameters()[0][\"agents\"]` reports\n",
+    "the selected entries and their sampled parameters. The brushless Crazyflie and SavageBee\n",
+    "meshes reuse the Crazyflie dynamics preset here; the asset-to-dynamics pairing is explicit.\n",
+    "RAPTOR uses the X500/Crazyflie motor order, so we map its actions to each model's rotor order.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "models = {\"x500\": \"x500\", \"arpl\": \"arpl\", \"soft\": \"soft\",\n",
+    "          \"crazyflie_brushless\": \"crazyflie\", \"crazyflie\": \"crazyflie\",\n",
+    "          \"savagebee_pusher\": \"crazyflie\"}\n",
+    "names = list(models)\n",
+    "drones = [{\"asset\": rigged_model_path(name), \"parameters\": {\n",
+    "    \"dynamics\": {\"dynamics\": {\"model\": model}}, \"cameras\": [fpv],\n",
+    "}} for name, model in models.items()]\n",
+    "with closing(MultiEnvironment(scenes, config=config, drones=drones)) as preset:\n",
+    "    nominal_drones = preset.drones\n",
+    "for entry, nominal in zip(drones, nominal_drones):\n",
+    "    entry[\"parameters\"][\"dynamics\"][\"dynamics\"].update(rpm_parameters(nominal[\"parameters\"][\"dynamics\"][\"dynamics\"]))\n",
+    "\n",
+    "group_config = replace(config, num_agents=len(names) + 1)\n",
+    "with closing(MultiEnvironment(scenes, config=group_config, drones=drones,\n",
+    "                              parameters={\"dynamics\": initial})) as mixed:\n",
+    "    mixed.reset(spawn_points=shots[\"models\"])\n",
+    "    mixed.set_instance_parameters({\"agents\": [\n",
+    "        {\"cameras\": [camera([0.4, 0, 0.12], 0.35, 0, 90)]}, *[{} for _ in names],\n",
+    "    ]})\n",
+    "    anchors = np.array(shots[\"models\"][0][\"poses\"], dtype=np.float32)[:, :3]\n",
+    "    policies, previous = pilots(mixed)\n",
+    "    policy_rotors = [tuple(np.sign(p[:2])) for p in nominal_dynamics[\"rotor_positions\"]]\n",
+    "    motor_order = np.array([\n",
+    "        [policy_rotors.index(tuple(np.sign(p[:2]))) for p in agent[\"dynamics\"][\"dynamics\"][\"rotor_positions\"]]\n",
+    "        for agent in mixed.instance_parameters()[0][\"agents\"]\n",
+    "    ])\n",
+    "    with writer(output / \"02-models.mp4\", FPS) as video:\n",
+    "        for step in range(STEPS):\n",
+    "            targets = anchors.copy()\n",
+    "            targets[1:, 2] += 0.12 * np.sin(2 * np.pi * step * mixed.dt / 4 + np.arange(len(names)))\n",
+    "            previous = act(mixed, policies, previous, targets)\n",
+    "            mixed.step(np.take_along_axis(previous.reshape(-1, 4), motor_order, axis=1).reshape(1, -1))\n",
+    "            if (step + 1) % STRIDE == 0:\n",
+    "                filming_view = mixed.frames().reshape(1, mixed.num_views, HEIGHT, WIDTH, 3)[0, 0]\n",
+    "                video.append_data(panel([filming_view], [\"Six drone models | filmed by a seventh drone\"]))\n",
+    "display(Video(str(output / \"02-models.mp4\"), embed=True))\n"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. A task is one knob\n",
+    "\n",
+    "`task=\"target_frame\"` adds the desired image to the observation. The named layout locates\n",
+    "both channel blocks. RAPTOR returns toward the origin while the reference image stays\n",
+    "fixed for the episode; small propeller and pose differences remain at the goal."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "with closing(MultiEnvironment(scenes, config=replace(config, task=\"target_frame\"),\n",
+    "                              drone_asset=drone_asset, parameters={\"dynamics\": x500_dynamics, \"cameras\": [fpv]})) as task:\n",
+    "    print(\"preset:\", image_layout.blocks, \"target_frame:\", task.observation_layout.blocks)\n",
+    "    task.reset(spawn_points=shots[\"flight\"])\n",
+    "    task.observe()\n",
+    "    target_offset, target_size = task.observation_layout.blocks[\"target_image\"]\n",
+    "    target_image = task.frames()[0, ..., target_offset:target_offset + target_size].copy()\n",
+    "    policies, previous = pilots(task)\n",
+    "    with writer(output / \"03-target.mp4\", FPS) as video:\n",
+    "        for step in range(STEPS):\n",
+    "            previous = act(task, policies, previous)\n",
+    "            task.step(previous)\n",
+    "            if (step + 1) % STRIDE == 0:\n",
+    "                frame = task.frames()[0]\n",
+    "                images = [frame[..., offset:offset + size] for offset, size in task.observation_layout.blocks.values()]\n",
+    "                np.testing.assert_array_equal(images[1], target_image)\n",
+    "                video.append_data(panel(images, [\"2 / Current image - returning to the goal\", \"Target image - fixed this episode\"]))\n",
+    "display(Video(str(output / \"03-target.mp4\"), embed=True))"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. Your own task is a Python loop\n",
+    "\n",
+    "The preset's reward is zero. Here Python defines distance/velocity shaping, success,\n",
+    "failure, and independent time limits, then resets only the finished instances and their\n",
+    "recurrent pilots. Each new episode reverses that instance's goal. Halfway through, rotate\n",
+    "the scene and reset everyone: the same task now runs in another room. Each instance\n",
+    "cycles through its recorded starts in that room."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "with closing(MultiEnvironment(scenes, config=replace(config, instances_per_environment=2), drone_asset=drone_asset,\n",
+    "                              parameters={\"dynamics\": x500_dynamics, \"cameras\": [fpv]})) as env:\n",
+    "    spawn_cycles = [[cycle(starts) for starts in room] for room in shots[\"python_task\"]]\n",
+    "    room = 0\n",
+    "    env.reset(spawn_points=[next(starts) for starts in spawn_cycles[room]])\n",
+    "    policies, previous = pilots(env)\n",
+    "    targets = np.array([[0.2, 0, 0], [-0.2, 0, 0]], dtype=np.float32)\n",
+    "    age, episodes = np.zeros(2, dtype=int), np.zeros(2, dtype=int)\n",
+    "    last_reset = np.full(2, -100)\n",
+    "    with writer(output / \"04-python-task.mp4\", FPS) as video:\n",
+    "        for step in range(800):\n",
+    "            previous = act(env, policies, previous, targets)\n",
+    "            env.step(previous)\n",
+    "            state = env.observe_privileged()\n",
+    "            distance = np.linalg.norm(block(state, base_layout, \"position\") - targets, axis=1)\n",
+    "            speed = np.linalg.norm(block(state, base_layout, \"linear_velocity\"), axis=1)\n",
+    "            reward = -distance - 0.1 * speed\n",
+    "            age += 1\n",
+    "            terminated = ((distance < 0.04) & (speed < 0.15) & (age >= 100)) | (distance > 1.0)\n",
+    "            reset = terminated | (age >= [250, 350])\n",
+    "            if step == 399:\n",
+    "                env.rotate_scene()\n",
+    "                room = 1\n",
+    "                reset[:] = True\n",
+    "            env.reset(reset, spawn_points=[next(spawn_cycles[room][i]) for i in np.flatnonzero(reset)])\n",
+    "            for i in np.flatnonzero(reset):\n",
+    "                policies[i].reset()\n",
+    "                previous[i] = 0\n",
+    "                age[i] = 0\n",
+    "                episodes[i] += 1\n",
+    "                targets[i] *= -1\n",
+    "                last_reset[i] = step\n",
+    "            if (step + 1) % STRIDE == 0:\n",
+    "                env.observe()\n",
+    "                titles = [f\"3 / Instance {i} | episode {episodes[i]} | \" +\n",
+    "                          (\"RESET\" if step - last_reset[i] < 20 else f\"reward {reward[i]:.2f} | error {distance[i]:.2f} m\")\n",
+    "                          for i in range(2)]\n",
+    "                video.append_data(panel(env.frames(), titles))\n",
+    "    print(\"completed episodes:\", episodes.tolist())\n",
+    "display(Video(str(output / \"04-python-task.mp4\"), embed=True))"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. Your own world is a small C++ header\n",
+    "\n",
+    "Derive from the shipped specification to change rendering and observation features;\n",
+    "`spec_header=` lets the JIT compile that World directly. Its content hash is part of the\n",
+    "cache key. Leave `preset` / `task` / `num_agents` / `num_cameras_per_agent` at their defaults when supplying a header.\n",
+    "\n",
+    "Compare two shutter samples with eight plus 2×2 anti-aliasing. Both configurations enable\n",
+    "motion blur and use the same recorded spawn; the replay verifies equal\n",
+    "states. Custom Worlds export flat observations: reshape their images explicitly, and use\n",
+    "the X500 privileged layout because this header preserves its dynamics observation chain."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "%%writefile my_world.h\n",
+    "#pragma once\n",
+    "#include <rl_tools/rl/environments/hyperdrone/presets.h>\n",
+    "#include <cstddef>\n",
+    "\n",
+    "namespace hyperdrone_env_user {\n",
+    "    struct SPEC: rl_tools::rl::environments::hyperdrone::presets::X500FPV<float, std::size_t> {\n",
+    "        static constexpr std::size_t INSTANCES_PER_ENVIRONMENT = 1;\n",
+    "        static constexpr std::size_t CAM_WIDTH = 640;\n",
+    "        static constexpr std::size_t CAM_HEIGHT = 360;\n",
+    "        using SHADING = rl_tools::rendering::raytracing::High;\n",
+    "        static constexpr bool ENABLE_MOTION_BLUR = true;\n",
+    "        static constexpr std::size_t MOTION_BLUR_SAMPLES = 8;\n",
+    "        static constexpr bool ENABLE_ANTI_ALIASING = true;\n",
+    "        static constexpr std::size_t ANTI_ALIASING_GRID_SIZE = 2;\n",
+    "    };\n",
+    "    using WORLD = rl_tools::rl::environments::hyperdrone::World<SPEC>;\n",
+    "}"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "header = Path(\"my_world.h\").read_text()\n",
+    "preview_header = output / \"my_world_preview.h\"\n",
+    "preview_header.write_text(header.replace(\"MOTION_BLUR_SAMPLES = 8\", \"MOTION_BLUR_SAMPLES = 2\")\n",
+    "                               .replace(\"ANTI_ALIASING_GRID_SIZE = 2\", \"ANTI_ALIASING_GRID_SIZE = 1\"))\n",
+    "custom_tape = []\n",
+    "with closing(MultiEnvironment(scenes, config=EnvConfig(spec_header=str(preview_header)),\n",
+    "                              drone_asset=drone_asset, parameters={\"dynamics\": x500_dynamics, \"cameras\": [chase]})) as custom:\n",
+    "    custom.reset(spawn_points=shots[\"flight\"])\n",
+    "    policies, previous = pilots(custom)\n",
+    "    with writer(output / \"two-samples.mp4\", FPS) as video:\n",
+    "        for step in range(STEPS):\n",
+    "            target = np.array([0.25 if step >= 200 else 0, 0, 0], dtype=np.float32)\n",
+    "            previous = act(custom, policies, previous, target, layout=base_layout)\n",
+    "            custom.step(previous)\n",
+    "            custom_tape.append((previous.copy(), custom.observe_privileged()))\n",
+    "            if (step + 1) % STRIDE == 0:\n",
+    "                views = custom.observe().reshape(custom.total_instances, HEIGHT, WIDTH, custom.image_channels)\n",
+    "                video.append_data(rgb(views[0]))\n",
+    "\n",
+    "replay(EnvConfig(spec_header=\"my_world.h\"), custom_tape, chase, output / \"motion-blur.mp4\")\n",
+    "pair(output / \"two-samples.mp4\", output / \"motion-blur.mp4\", output / \"05-custom-world.mp4\",\n",
+    "     [\"4 / Two shutter samples\", \"Your header - 8 shutter samples + 2x2 AA\"], FPS)\n",
+    "display(Video(str(output / \"05-custom-world.mp4\"), embed=True))"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## The whole flight demo\n",
+    "\n",
+    "The combined MP4 contains all five clips at real-time speed. For a compiled task with a\n",
+    "moving object, reward, and collision termination, continue with [Orbiter.ipynb](Orbiter.ipynb).\n",
+    "For manual renderer/dynamics composition see [Renderer.ipynb](Renderer.ipynb);\n",
+    "for throughput see [Benchmark.ipynb](Benchmark.ipynb)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "clips = [output / name for name in (\"01-preset.mp4\", \"02-models.mp4\", \"03-target.mp4\",\n",
+    "                                   \"04-python-task.mp4\", \"05-custom-world.mp4\")]\n",
+    "join(clips, \"hyperdrone.mp4\", FPS)\n",
+    "display(Video(\"hyperdrone.mp4\", embed=True))\n",
+    "print(\"Saved\", Path(\"hyperdrone.mp4\").resolve())"
+   ],
+   "execution_count": null,
+   "outputs": []
+  }
+ ],
+ "metadata": {
+  "accelerator": "GPU",
+  "kernelspec": {
+   "display_name": ".venv (3.12.3)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}