hyperray 0.0.1__py3-none-any.whl

hyperdrone/examples/Orbiter.ipynb

@@ -0,0 +1,496 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "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/Orbiter.ipynb)\n",
+    "\n",
+    "# Orbiter\n",
+    "\n",
+    "HyperDrone.ipynb ends at \"your own world is a small C++ header\". This notebook is that\n",
+    "rung done seriously: a user-authored **task wrapper** with a moving object — an entity\n",
+    "registered into the world, moved every step with correct motion blur, scored by a\n",
+    "compiled chase reward, and terminated on collision — written entirely inside the\n",
+    "JIT-compiled header. No repo C++, no new bindings.\n",
+    "\n",
+    "Compared to driving everything from a Python loop (HyperDrone.ipynb rung 3), a compiled\n",
+    "task runs at full rollout speed with zero per-step Python, and the same header works for\n",
+    "C++ training targets. The shipped `tasks/moving_gate` is the fork template this follows."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1",
+   "metadata": {},
+   "outputs": [],
+   "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]\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "from pathlib import Path\n",
+    "\n",
+    "import numpy as np\n",
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "from hyperdrone.env import EnvConfig, MultiEnvironment\n",
+    "from hyperdrone.examples.data import x500_model_path\n",
+    "\n",
+    "# the scene corpus, by content hash (entries from the conta store manifest:\n",
+    "# https://huggingface.co/datasets/rl-tools/conta) — resolved through conta\n",
+    "# into a cache shared with the C++ tools; set HYPERDRONE_SCENES to a directory of .glb\n",
+    "# scenes (e.g. a full ProcTHOR corpus) to use the first NUM_SCENES local scenes instead\n",
+    "scenes = [\n",
+    "    {\"description\": \"ai2thor-hab/glb/ProcTHOR-Train-0.glb\", \"hash\": \"28d17959b463626d64257f0d9ea8e47daae68409\"},\n",
+    "    {\"description\": \"ai2thor-hab/glb/ProcTHOR-Train-1.glb\", \"hash\": \"75d1d67a17ecd16bc3a214baa895240da8060df7\"},\n",
+    "]\n",
+    "NUM_SCENES = 2\n",
+    "if os.environ.get(\"HYPERDRONE_SCENES\"):\n",
+    "    scenes = sorted(Path(os.environ[\"HYPERDRONE_SCENES\"]).glob(\"*.glb\"))[:NUM_SCENES]\n",
+    "drone_asset = x500_model_path()\n",
+    "\n",
+    "def show(images, titles, size=3):\n",
+    "    figure, axes = plt.subplots(1, len(images), figsize=(size * len(images), size))\n",
+    "    for axis, image, title in zip(np.atleast_1d(axes), images, titles):\n",
+    "        axis.imshow(np.clip(image, 0, 1), interpolation=\"nearest\")\n",
+    "        axis.set_title(title, fontsize=9)\n",
+    "        axis.axis(\"off\")\n",
+    "    plt.tight_layout()\n",
+    "    plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3",
+   "metadata": {},
+   "source": [
+    "## The task, in one header\n",
+    "\n",
+    "The header defines the world (`X500FPV` derived, motion blur on) and wraps it in a task:\n",
+    "a `Parameters` component (the orbit center), a `State` component (the orbit phase), and\n",
+    "overloads for exactly the verbs the task extends — everything else binds to the base World\n",
+    "by deduction-from-derived, the same contract the shipped tasks use:\n",
+    "\n",
+    "- `init` — register the object's asset as an entity kind, then delegate (registration\n",
+    "  order pins segmentation ids). The asset arrives through `assets={\"orbiter\": reference}`; the task's `set_asset` overload consumes that name and records its path.\n",
+    "- `sample_initial_state` — after the base samples the spawn, center the orbit on it and\n",
+    "  align the phase with the sampled facing, so the object starts in front of the camera\n",
+    "  (a wall or the sampled attitude can still hide it, as some instances below show); the\n",
+    "  batched overload requests the render that shows the fresh episodes.\n",
+    "- `prepare_entity_poses` — stage only this wrapper's object poses, including the shutter-open/close pair for motion blur; it does not render or update acceleration structures.\n",
+    "- `step` — stage pending entity poses when history or flow needs the current state, then forward to the base step and advance the orbit phase.\n",
+    "- `render` — stage the same poses before forwarding image acquisition. `observe` routes a requested frame through this `render`.\n",
+    "- `reward` / `terminated` — negative distance to the object (chase), episode over on\n",
+    "  collision.\n",
+    "\n",
+    "The trailing `namespace hyperdrone_env_user::orbiter` block mirrors the shipped tasks:\n",
+    "member-lifecycle verbs (`init`) carry no tensor argument, so composite code only finds a\n",
+    "task's overload through the task type's own namespace."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%writefile my_task.h\n",
+    "#pragma once\n",
+    "#include <rl_tools/rl/environments/hyperdrone/presets.h>\n",
+    "#include <rl_tools/rl/environments/hyperdrone/operations_cpu.h>\n",
+    "#include <cstddef>\n",
+    "#include <string>\n",
+    "\n",
+    "namespace hyperdrone_env_user {\n",
+    "    namespace orbiter {\n",
+    "        using T = float;\n",
+    "        using TI = std::size_t;\n",
+    "\n",
+    "        struct BaseSpecification: rl_tools::rl::environments::hyperdrone::presets::X500FPV<T, TI> {\n",
+    "            static constexpr TI INSTANCES_PER_ENVIRONMENT = 4;\n",
+    "            static constexpr TI CAM_WIDTH = 64;\n",
+    "            static constexpr TI CAM_HEIGHT = 64;\n",
+    "            using SHADING = rl_tools::rendering::raytracing::Low;\n",
+    "            static constexpr TI MAX_ENTITY_SLOTS_PER_INSTANCE = 16;  // drone rig parts + the orbiter\n",
+    "            static constexpr bool ENABLE_MOTION_BLUR = true;\n",
+    "            static constexpr TI MOTION_BLUR_SAMPLES = 8;\n",
+    "        };\n",
+    "\n",
+    "        template <typename T_NEXT_WORLD>\n",
+    "        struct Specification {\n",
+    "            using NEXT_WORLD = T_NEXT_WORLD;\n",
+    "            using T = typename NEXT_WORLD::T;\n",
+    "            using TI = typename NEXT_WORLD::TI;\n",
+    "            static constexpr T ORBIT_RADIUS = 1.5;\n",
+    "            static constexpr T ORBIT_RATE = 1.0;  // revolutions per second\n",
+    "            static constexpr T REWARD_DISTANCE_SCALE = 1.0;\n",
+    "            static constexpr T COLLISION_RADIUS = 0.15;\n",
+    "        };\n",
+    "\n",
+    "        template <typename T_T, typename T_TI, typename T_NEXT_COMPONENT>\n",
+    "        struct ComponentSpecification {\n",
+    "            using T = T_T;\n",
+    "            using TI = T_TI;\n",
+    "            using NEXT_COMPONENT = T_NEXT_COMPONENT;\n",
+    "        };\n",
+    "        template <typename T_SPEC>\n",
+    "        struct ParametersOrbiter: T_SPEC::NEXT_COMPONENT {\n",
+    "            using SPEC = T_SPEC;\n",
+    "            using T = typename SPEC::T;\n",
+    "            using NEXT_COMPONENT = typename SPEC::NEXT_COMPONENT;\n",
+    "            T orbit_center[3] = {0, 0, 0};  // scene frame, set to the drone's spawn position at reset\n",
+    "        };\n",
+    "        template <typename T_SPEC>\n",
+    "        struct StateOrbiter: T_SPEC::NEXT_COMPONENT {\n",
+    "            using SPEC = T_SPEC;\n",
+    "            using T = typename SPEC::T;\n",
+    "            using NEXT_COMPONENT = typename SPEC::NEXT_COMPONENT;\n",
+    "            static constexpr bool REQUIRES_INTEGRATION = false;\n",
+    "            static constexpr typename SPEC::TI DIM = 1 + NEXT_COMPONENT::DIM;\n",
+    "            T orbit_phase = 0;\n",
+    "        };\n",
+    "\n",
+    "        template <typename T_TASK_SPEC>\n",
+    "        struct World: T_TASK_SPEC::NEXT_WORLD {\n",
+    "            using TASK_SPEC = T_TASK_SPEC;\n",
+    "            using NEXT_WORLD = typename TASK_SPEC::NEXT_WORLD;\n",
+    "            using T = typename NEXT_WORLD::T;\n",
+    "            using TI = typename NEXT_WORLD::TI;\n",
+    "            static_assert(NEXT_WORLD::RENDERER_CONFIG::NUM_OVERLAYS > 0, \"the orbiter task needs entity slots: set MAX_ENTITY_SLOTS_PER_INSTANCE in the base Specification\");\n",
+    "            using Parameters = ParametersOrbiter<ComponentSpecification<T, TI, typename NEXT_WORLD::Parameters>>;\n",
+    "            using State = StateOrbiter<ComponentSpecification<T, TI, typename NEXT_WORLD::State>>;\n",
+    "            std::string orbiter_asset_path;\n",
+    "            TI entity_kind_index = 0;\n",
+    "        };\n",
+    "\n",
+    "        template <typename DEVICE, typename TASK_SPEC>\n",
+    "        void drone_scene_position(DEVICE&, const typename World<TASK_SPEC>::Parameters& parameters, const typename World<TASK_SPEC>::State& state, typename TASK_SPEC::T out[3]){\n",
+    "            out[0] = parameters.scene_yaw_cos * state.position[0] - parameters.scene_yaw_sin * state.position[1] + parameters.scene_translation[0];\n",
+    "            out[1] = parameters.scene_yaw_sin * state.position[0] + parameters.scene_yaw_cos * state.position[1] + parameters.scene_translation[1];\n",
+    "            out[2] = state.position[2] + parameters.scene_translation[2];\n",
+    "        }\n",
+    "        template <typename DEVICE, typename TASK_SPEC>\n",
+    "        void orbiter_position(DEVICE& device, const typename World<TASK_SPEC>::Parameters& parameters, typename TASK_SPEC::T phase, typename TASK_SPEC::T out[3]){\n",
+    "            using T = typename TASK_SPEC::T;\n",
+    "            out[0] = parameters.orbit_center[0] + TASK_SPEC::ORBIT_RADIUS * rl_tools::math::cos(device.math, phase);\n",
+    "            out[1] = parameters.orbit_center[1] + TASK_SPEC::ORBIT_RADIUS * rl_tools::math::sin(device.math, phase);\n",
+    "            out[2] = parameters.orbit_center[2];\n",
+    "        }\n",
+    "        template <typename DEVICE, typename TASK_SPEC>\n",
+    "        void orbiter_pose(DEVICE& device, const typename World<TASK_SPEC>::Parameters& parameters, typename TASK_SPEC::T phase, float out[12]){\n",
+    "            using T = typename TASK_SPEC::T;\n",
+    "            T position[3];\n",
+    "            orbiter_position<DEVICE, TASK_SPEC>(device, parameters, phase, position);\n",
+    "            for(unsigned row = 0; row < 3; row++){\n",
+    "                for(unsigned column = 0; column < 3; column++){\n",
+    "                    out[row * 4 + column] = row == column ? 1.0f : 0.0f;\n",
+    "                }\n",
+    "                out[row * 4 + 3] = (float)position[row];\n",
+    "            }\n",
+    "        }\n",
+    "        template <typename DEVICE, typename TASK_SPEC>\n",
+    "        typename TASK_SPEC::T orbiter_distance(DEVICE& device, const typename World<TASK_SPEC>::Parameters& parameters, const typename World<TASK_SPEC>::State& state, typename TASK_SPEC::T phase){\n",
+    "            using T = typename TASK_SPEC::T;\n",
+    "            T drone[3], object[3];\n",
+    "            drone_scene_position<DEVICE, TASK_SPEC>(device, parameters, state, drone);\n",
+    "            orbiter_position<DEVICE, TASK_SPEC>(device, parameters, phase, object);\n",
+    "            T sum = 0;\n",
+    "            for(unsigned dim = 0; dim < 3; dim++){\n",
+    "                T difference = drone[dim] - object[dim];\n",
+    "                sum += difference * difference;\n",
+    "            }\n",
+    "            return rl_tools::math::sqrt(device.math, sum);\n",
+    "        }\n",
+    "    }\n",
+    "    using WORLD = orbiter::World<orbiter::Specification<rl_tools::rl::environments::hyperdrone::World<orbiter::BaseSpecification>>>;\n",
+    "}\n",
+    "\n",
+    "namespace rl_tools {\n",
+    "    template <typename DEVICE, typename TASK_SPEC>\n",
+    "    bool set_asset(DEVICE& device, hyperdrone_env_user::orbiter::World<TASK_SPEC>& world, const std::string& name, const std::string& path){\n",
+    "        if(name == \"orbiter\"){\n",
+    "            world.orbiter_asset_path = path;\n",
+    "            return true;\n",
+    "        }\n",
+    "        return set_asset(device, static_cast<typename TASK_SPEC::NEXT_WORLD&>(world), name, path);\n",
+    "    }\n",
+    "    template <typename DEVICE, typename TASK_SPEC, typename DATASET>\n",
+    "    void init(DEVICE& device, hyperdrone_env_user::orbiter::World<TASK_SPEC>& world, typename TASK_SPEC::NEXT_WORLD::SharedContext& shared, const DATASET& dataset, const typename DATASET::Corpus& corpus, typename TASK_SPEC::TI first_scene, typename TASK_SPEC::TI num_scenes, typename TASK_SPEC::TI member_index){\n",
+    "        using NEXT_WORLD = typename TASK_SPEC::NEXT_WORLD;\n",
+    "        utils::assert_exit(device, !world.orbiter_asset_path.empty(), \"orbiter: the object asset must be set before init (pass assets={'orbiter': ...})\");\n",
+    "        world.entity_kind_index = register_entity_kind(device, world, shared, world.orbiter_asset_path);\n",
+    "        init(device, static_cast<NEXT_WORLD&>(world), shared, dataset, corpus, first_scene, num_scenes, member_index);\n",
+    "    }\n",
+    "\n",
+    "    template <typename DEVICE, typename TASK_SPEC, typename RNG>\n",
+    "    void sample_initial_state(DEVICE& device, hyperdrone_env_user::orbiter::World<TASK_SPEC>& world, typename hyperdrone_env_user::orbiter::World<TASK_SPEC>::Parameters& parameters, typename hyperdrone_env_user::orbiter::World<TASK_SPEC>::State& state, RNG& rng){\n",
+    "        using T = typename TASK_SPEC::T;\n",
+    "        using NEXT_WORLD = typename TASK_SPEC::NEXT_WORLD;\n",
+    "        sample_initial_state(device, static_cast<NEXT_WORLD&>(world), static_cast<typename NEXT_WORLD::Parameters&>(parameters), static_cast<typename NEXT_WORLD::State&>(state), rng);\n",
+    "        // the orbit is centered on the freshly sampled spawn and its phase aligned with the\n",
+    "        // sampled facing, so the object starts in front of the camera (a wall or the sampled\n",
+    "        // attitude can still hide it) and crosses the view once per revolution\n",
+    "        hyperdrone_env_user::orbiter::drone_scene_position<DEVICE, TASK_SPEC>(device, parameters, state, parameters.orbit_center);\n",
+    "        const T qw = state.orientation[0], qx = state.orientation[1], qy = state.orientation[2], qz = state.orientation[3];\n",
+    "        const T forward_x = 1 - 2 * (qy * qy + qz * qz);\n",
+    "        const T forward_y = 2 * (qx * qy + qw * qz);\n",
+    "        const T scene_forward_x = parameters.scene_yaw_cos * forward_x - parameters.scene_yaw_sin * forward_y;\n",
+    "        const T scene_forward_y = parameters.scene_yaw_sin * forward_x + parameters.scene_yaw_cos * forward_y;\n",
+    "        state.orbit_phase = math::atan2(device.math, scene_forward_y, scene_forward_x);\n",
+    "    }\n",
+    "    template <typename DEVICE, typename TASK_SPEC, typename PARAMETER_SPEC, typename STATE_SPEC, typename RESET_SPEC, typename RNG>\n",
+    "    void sample_initial_state(DEVICE& device, hyperdrone_env_user::orbiter::World<TASK_SPEC>& world, Tensor<PARAMETER_SPEC>& parameters, Tensor<STATE_SPEC>& states, const Tensor<RESET_SPEC>& reset_mask, RNG& rng){\n",
+    "        using TI = typename TASK_SPEC::TI;\n",
+    "        using WORLD = hyperdrone_env_user::orbiter::World<TASK_SPEC>;\n",
+    "        static_assert(utils::typing::is_same_v<typename STATE_SPEC::T, typename WORLD::State>);\n",
+    "        for (TI instance_i = 0; instance_i < WORLD::INSTANCES; instance_i++) {\n",
+    "            if (get(device, reset_mask, instance_i)) {\n",
+    "                sample_initial_state(device, world, get_ref(device, parameters, instance_i), get_ref(device, states, instance_i), rng);\n",
+    "            }\n",
+    "        }\n",
+    "        request_render(device, world, reset_mask);\n",
+    "    }\n",
+    "\n",
+    "    template <typename DEVICE, typename TASK_SPEC, typename PARAMETER_SPEC, typename STATE_SPEC>\n",
+    "    void prepare_entity_poses(DEVICE& device, hyperdrone_env_user::orbiter::World<TASK_SPEC>& world, Tensor<PARAMETER_SPEC>& parameters, Tensor<STATE_SPEC>& states){\n",
+    "        using T = typename TASK_SPEC::T;\n",
+    "        using TI = typename TASK_SPEC::TI;\n",
+    "        using WORLD = hyperdrone_env_user::orbiter::World<TASK_SPEC>;\n",
+    "        using NEXT_WORLD = typename TASK_SPEC::NEXT_WORLD;\n",
+    "        const auto& kind = world.entity_kinds[world.entity_kind_index];\n",
+    "        const auto placement = rl::environments::hyperdrone::_entity_placement(world, kind);\n",
+    "        const float* no_coordinates = nullptr;  // a rigid entity: its rig has no coordinates\n",
+    "        auto& renderer = get_renderer(device, world);\n",
+    "        for (TI instance_i = 0; instance_i < WORLD::INSTANCES; instance_i++) {\n",
+    "            const auto& instance_parameters = get_ref(device, parameters, instance_i);\n",
+    "            const auto& state = get_ref(device, states, instance_i);\n",
+    "            float pose[12];\n",
+    "            hyperdrone_env_user::orbiter::orbiter_pose<DEVICE, TASK_SPEC>(device, instance_parameters, state.orbit_phase, pose);\n",
+    "            if constexpr (NEXT_WORLD::RENDERER_CONFIG::ENABLE_DYNAMIC_MOTION_BLUR) {\n",
+    "                constexpr T TWO_PI = (T)2 * math::PI<T>;\n",
+    "                const T dt = instance_parameters.agents[0].dynamics.integration.dt;\n",
+    "                float pose_open[12];\n",
+    "                T phase_open = state.orbit_phase - TWO_PI * TASK_SPEC::ORBIT_RATE * dt * instance_parameters.shutter_fraction;\n",
+    "                hyperdrone_env_user::orbiter::orbiter_pose<DEVICE, TASK_SPEC>(device, instance_parameters, phase_open, pose_open);\n",
+    "                set_transform_pair(device, renderer, rendering::raytracing::OverlayIndex{instance_i}, placement, kind.rig, pose_open, pose, no_coordinates, no_coordinates);\n",
+    "            } else {\n",
+    "                set_transform(device, renderer, rendering::raytracing::OverlayIndex{instance_i}, placement, kind.rig, pose, no_coordinates);\n",
+    "            }\n",
+    "        }\n",
+    "    }\n",
+    "\n",
+    "    template <typename DEVICE, typename TASK_SPEC, typename PARAMETER_SPEC, typename STATE_SPEC, typename ACTION_SPEC, typename NEXT_STATE_SPEC, typename RNG>\n",
+    "    void step(DEVICE& device, hyperdrone_env_user::orbiter::World<TASK_SPEC>& world, Tensor<PARAMETER_SPEC>& parameters, Tensor<STATE_SPEC>& states, const Tensor<ACTION_SPEC>& actions, Tensor<NEXT_STATE_SPEC>& next_states, RNG& rng){\n",
+    "        using T = typename TASK_SPEC::T;\n",
+    "        using TI = typename TASK_SPEC::TI;\n",
+    "        using WORLD = hyperdrone_env_user::orbiter::World<TASK_SPEC>;\n",
+    "        using NEXT_WORLD = typename TASK_SPEC::NEXT_WORLD;\n",
+    "        constexpr T TWO_PI = (T)2 * math::PI<T>;\n",
+    "        if constexpr (NEXT_WORLD::SPEC::HISTORY_LENGTH > 1 || NEXT_WORLD::SPEC::OUTPUT_FLOW){\n",
+    "            if(world.render_pending){\n",
+    "                prepare_entity_poses(device, world, parameters, states);\n",
+    "            }\n",
+    "        }\n",
+    "        step(device, static_cast<NEXT_WORLD&>(world), parameters, states, actions, next_states, rng);\n",
+    "        for (TI instance_i = 0; instance_i < WORLD::INSTANCES; instance_i++) {\n",
+    "            const auto& instance_parameters = get_ref(device, parameters, instance_i);\n",
+    "            const T dt = instance_parameters.agents[0].dynamics.integration.dt;\n",
+    "            T phase = get_ref(device, states, instance_i).orbit_phase + TWO_PI * TASK_SPEC::ORBIT_RATE * dt;\n",
+    "            phase = phase - math::floor(device.math, phase / TWO_PI) * TWO_PI;\n",
+    "            get_ref(device, next_states, instance_i).orbit_phase = phase;\n",
+    "        }\n",
+    "    }\n",
+    "\n",
+    "    template <typename DEVICE, typename TASK_SPEC, typename PARAMETER_SPEC, typename STATE_SPEC, typename RESET_SPEC>\n",
+    "    void render(DEVICE& device, hyperdrone_env_user::orbiter::World<TASK_SPEC>& world, Tensor<PARAMETER_SPEC>& parameters, Tensor<STATE_SPEC>& states, const Tensor<RESET_SPEC>& reset_mask){\n",
+    "        if(!world.render_pending){\n",
+    "            return;\n",
+    "        }\n",
+    "        using NEXT_WORLD = typename TASK_SPEC::NEXT_WORLD;\n",
+    "        request_render(device, world, reset_mask);\n",
+    "        prepare_entity_poses(device, world, parameters, states);\n",
+    "        render(device, static_cast<NEXT_WORLD&>(world), parameters, states, world.render_reset);\n",
+    "    }\n",
+    "    // a frame requested by reset or step and observed without an explicit render goes through\n",
+    "    // the task's render, so the object moves with it\n",
+    "    template <typename DEVICE, typename TASK_SPEC, typename PARAMETER_SPEC, typename STATE_SPEC, typename OBSERVATION_SPEC, typename RNG>\n",
+    "    void observe(DEVICE& device, hyperdrone_env_user::orbiter::World<TASK_SPEC>& world, Tensor<PARAMETER_SPEC>& parameters, Tensor<STATE_SPEC>& states, typename TASK_SPEC::NEXT_WORLD::Observation observation_type, Tensor<OBSERVATION_SPEC>& observations, RNG& rng){\n",
+    "        using NEXT_WORLD = typename TASK_SPEC::NEXT_WORLD;\n",
+    "        if(world.render_pending){\n",
+    "            render(device, world, parameters, states, world.render_reset);\n",
+    "        }\n",
+    "        observe(device, static_cast<NEXT_WORLD&>(world), parameters, states, observation_type, observations, rng);\n",
+    "    }\n",
+    "\n",
+    "    template <typename DEVICE, typename TASK_SPEC, typename PARAMETER_SPEC, typename STATE_SPEC, typename ACTION_SPEC, typename NEXT_STATE_SPEC, typename REWARD_SPEC, typename RNG>\n",
+    "    void reward(DEVICE& device, hyperdrone_env_user::orbiter::World<TASK_SPEC>& world, Tensor<PARAMETER_SPEC>& parameters, Tensor<STATE_SPEC>& states, const Tensor<ACTION_SPEC>& actions, Tensor<NEXT_STATE_SPEC>& next_states, Tensor<REWARD_SPEC>& rewards, RNG& rng){\n",
+    "        using T = typename TASK_SPEC::T;\n",
+    "        using TI = typename TASK_SPEC::TI;\n",
+    "        using WORLD = hyperdrone_env_user::orbiter::World<TASK_SPEC>;\n",
+    "        using NEXT_WORLD = typename TASK_SPEC::NEXT_WORLD;\n",
+    "        reward(device, static_cast<NEXT_WORLD&>(world), parameters, states, actions, next_states, rewards, rng);\n",
+    "        for (TI instance_i = 0; instance_i < WORLD::INSTANCES; instance_i++) {\n",
+    "            const auto& instance_parameters = get_ref(device, parameters, instance_i);\n",
+    "            const auto& next_state = get_ref(device, next_states, instance_i);\n",
+    "            T distance = hyperdrone_env_user::orbiter::orbiter_distance<DEVICE, TASK_SPEC>(device, instance_parameters, next_state, next_state.orbit_phase);\n",
+    "            set(device, rewards, get(device, rewards, instance_i) - TASK_SPEC::REWARD_DISTANCE_SCALE * distance, instance_i);\n",
+    "        }\n",
+    "    }\n",
+    "\n",
+    "    template <typename DEVICE, typename TASK_SPEC, typename PARAMETER_SPEC, typename STATE_SPEC, typename TERMINATED_SPEC, typename RNG>\n",
+    "    void terminated(DEVICE& device, hyperdrone_env_user::orbiter::World<TASK_SPEC>& world, Tensor<PARAMETER_SPEC>& parameters, Tensor<STATE_SPEC>& states, Tensor<TERMINATED_SPEC>& terminated_flags, RNG& rng){\n",
+    "        using T = typename TASK_SPEC::T;\n",
+    "        using TI = typename TASK_SPEC::TI;\n",
+    "        using WORLD = hyperdrone_env_user::orbiter::World<TASK_SPEC>;\n",
+    "        using NEXT_WORLD = typename TASK_SPEC::NEXT_WORLD;\n",
+    "        terminated(device, static_cast<NEXT_WORLD&>(world), parameters, states, terminated_flags, rng);\n",
+    "        for (TI instance_i = 0; instance_i < WORLD::INSTANCES; instance_i++) {\n",
+    "            const auto& instance_parameters = get_ref(device, parameters, instance_i);\n",
+    "            const auto& state = get_ref(device, states, instance_i);\n",
+    "            T distance = hyperdrone_env_user::orbiter::orbiter_distance<DEVICE, TASK_SPEC>(device, instance_parameters, state, state.orbit_phase);\n",
+    "            if (distance < TASK_SPEC::COLLISION_RADIUS) {\n",
+    "                set(device, terminated_flags, true, instance_i);\n",
+    "            }\n",
+    "        }\n",
+    "    }\n",
+    "}\n",
+    "\n",
+    "// ADL entry points, mirroring the shipped tasks: member-lifecycle verbs carry no Tensor\n",
+    "// argument, so composite code only finds a task's overloads through the task type's own\n",
+    "// namespace at instantiation\n",
+    "namespace hyperdrone_env_user::orbiter {\n",
+    "    template <typename DEVICE, typename TASK_SPEC>\n",
+    "    bool set_asset(DEVICE& device, World<TASK_SPEC>& world, const std::string& name, const std::string& path){\n",
+    "        return ::rl_tools::set_asset(device, world, name, path);\n",
+    "    }\n",
+    "    template <typename DEVICE, typename TASK_SPEC, typename DATASET>\n",
+    "    void init(DEVICE& device, World<TASK_SPEC>& world, typename TASK_SPEC::NEXT_WORLD::SharedContext& shared, const DATASET& dataset, const typename DATASET::Corpus& corpus, typename TASK_SPEC::TI first_scene, typename TASK_SPEC::TI num_scenes, typename TASK_SPEC::TI member_index){\n",
+    "        ::rl_tools::init(device, world, shared, dataset, corpus, first_scene, num_scenes, member_index);\n",
+    "    }\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5",
+   "metadata": {},
+   "source": [
+    "## Fly against it\n",
+    "\n",
+    "The object's asset is any GLB — here the x500 model doubles as the orbiter body. The\n",
+    "first construction JIT-compiles the header (its content hash is the cache key, so\n",
+    "editing the header recompiles). A user World reports its image layout through `observation_layout`; `observe()` returns a flat batch and acquires the image lazily. Call `reset → observe → step → rewards/terminated`, with repeated image reads reusing the step's capture."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "env = MultiEnvironment(\n",
+    "    scenes,\n",
+    "    config=EnvConfig(spec_header=\"my_task.h\"),\n",
+    "    seed=0,\n",
+    "    drone_asset=drone_asset,\n",
+    "    assets={\"orbiter\": drone_asset},  # consumed by the task's set_asset(\"orbiter\", ...)\n",
+    ")\n",
+    "print(env.config)\n",
+    "\n",
+    "reset_all = np.ones(env.total_instances, dtype=bool)\n",
+    "reset_none = np.zeros(env.total_instances, dtype=bool)\n",
+    "env.reset(reset_all)\n",
+    "env.observe()\n",
+    "views = env.observe().reshape(env.total_instances, env.height, env.width, env.image_channels)\n",
+    "show(list(views), [f\"instance {i}\" for i in range(env.total_instances)])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7",
+   "metadata": {},
+   "source": [
+    "## The orbit, the reward, the collision\n",
+    "\n",
+    "Holding the motors keeps the drone near its spawn while the object circles it\n",
+    "(one revolution per second, 3.6° per step — motion-blurred by the shutter). The\n",
+    "compiled reward is the negative distance to the object, so it hovers around −1.5 (the\n",
+    "orbit radius) and responds as the drone drifts. The collision termination stays quiet\n",
+    "at this distance."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hold = np.zeros((env.total_instances, env.action_dim), dtype=np.float32)\n",
+    "strip = []\n",
+    "rewards_trace = []\n",
+    "for step in range(13):\n",
+    "    env.step(hold)\n",
+    "    env.observe()\n",
+    "    rewards_trace.append(env.rewards().copy())\n",
+    "    if step % 4 == 0:\n",
+    "        frame = env.observe().reshape(env.total_instances, env.height, env.width, env.image_channels)[0]\n",
+    "        strip.append((step, frame))\n",
+    "\n",
+    "show([frame for _, frame in strip], [f\"step {step}\" for step, _ in strip])\n",
+    "rewards_trace = np.stack(rewards_trace)\n",
+    "print(\"chase reward per instance (first/last step):\")\n",
+    "print(np.round(rewards_trace[0], 3), np.round(rewards_trace[-1], 3))\n",
+    "print(\"terminated:\", env.terminated())\n",
+    "env.close()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9",
+   "metadata": {},
+   "source": [
+    "The header is the whole task — `include/rl_tools/rl/environments/hyperdrone/presets.h`\n",
+    "and `tasks/` are the fork templates for more (the moving gate adds reward events, a\n",
+    "privileged observation block, and free-space trajectory sampling). `tests/env/test_orbiter.py`\n",
+    "in the rl-tools repository compiles and flies this notebook's header, so it tracks the\n",
+    "task contract."
+   ]
+  }
+ ],
+ "metadata": {
+  "accelerator": "GPU",
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}