hyperray 0.0.1__py3-none-any.whl

hyperdrone/_native/env/CMakeLists.txt

@@ -0,0 +1,98 @@
+cmake_minimum_required(VERSION 3.24)
+project(hyperdrone_env LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+set(RLTOOLS_ROOT "" CACHE PATH "Path to the rl-tools source root")
+set(HYPERDRONE_VARIANT "OPTIX" CACHE STRING "Raytracing backend (OPTIX|METAL|VULKAN|WEBGPU|GENERIC)")
+
+if(NOT RLTOOLS_ROOT)
+    message(FATAL_ERROR "RLTOOLS_ROOT must point to the rl-tools source root")
+endif()
+
+set(RL_TOOLS_DISABLE_TARGETS ON CACHE BOOL "" FORCE)
+set(RL_TOOLS_DISABLE_TESTS ON CACHE BOOL "" FORCE)
+set(RL_TOOLS_DISABLE_GIT_DIFF ON CACHE BOOL "" FORCE)
+set(RL_TOOLS_RL_ENVIRONMENTS_DISABLE_MUJOCO ON CACHE BOOL "" FORCE)
+set(RL_TOOLS_WARNINGS_AS_ERRORS OFF CACHE BOOL "" FORCE)
+# an explicit backend selection hard-requires raytracing inside the rl_tools subtree
+set(RL_TOOLS_RENDERING_RAYTRACING_BACKEND ${HYPERDRONE_VARIANT} CACHE STRING "" FORCE)
+if(HYPERDRONE_VARIANT STREQUAL "OPTIX")
+    # a normal variable before enable_language shadows the compiler default it caches, also in
+    # trees configured before; CUDAARCHS overrides
+    if(NOT DEFINED ENV{CUDAARCHS})
+        set(CMAKE_CUDA_ARCHITECTURES native)
+    endif()
+    enable_language(CUDA)
+    set(CMAKE_CUDA_STANDARD 17)
+    set(CMAKE_CUDA_STANDARD_REQUIRED ON)
+endif()
+if(HYPERDRONE_VARIANT STREQUAL "VULKAN")
+    find_package(Vulkan REQUIRED COMPONENTS glslangValidator)
+endif()
+
+unset(FETCHCONTENT_SOURCE_DIR_ASSIMP CACHE)
+add_subdirectory(${RLTOOLS_ROOT} rl_tools EXCLUDE_FROM_ALL)
+set(RL_TOOLS_RENDERING_RAYTRACING_BACKEND_RESOLVED ${HYPERDRONE_VARIANT})
+add_subdirectory(${RLTOOLS_ROOT}/src/rendering/raytracing/backends rl_tools_rt_backends EXCLUDE_FROM_ALL)
+
+include(FetchContent)
+FetchContent_Declare(
+    stb
+    GIT_REPOSITORY https://github.com/nothings/stb.git
+    GIT_TAG        f1c79c02822848a9bed4315b12c8c8f3761e1296
+    EXCLUDE_FROM_ALL
+)
+FetchContent_MakeAvailable(stb)
+add_library(hyperdrone_env_stb INTERFACE)
+target_include_directories(hyperdrone_env_stb SYSTEM INTERFACE ${stb_SOURCE_DIR})
+
+include(${CMAKE_CURRENT_SOURCE_DIR}/../cmake/hyperdrone_jit.cmake)
+hyperdrone_jit_find_nanobind()
+
+# the environment's drone rig instantiates the render core's RigModel (shared struct header,
+# type registered by the render core, which the Python wrapper loads first)
+nanobind_add_module(hyperdrone_env_core rotorcraft_bindings.cpp)
+target_include_directories(hyperdrone_env_core PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../common ${CMAKE_CURRENT_SOURCE_DIR}/../render)
+target_link_libraries(hyperdrone_env_core PRIVATE RLtools::RLtools hyperdrone_env_stb)
+set_target_properties(hyperdrone_env_core PROPERTIES LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+if(HYPERDRONE_VARIANT STREQUAL "OPTIX")
+    find_package(CUDAToolkit REQUIRED)
+    target_link_libraries(hyperdrone_env_core PRIVATE CUDA::cudart)
+endif()
+
+function(hyperdrone_component_libraries DEFINES OUT_LIBRARIES)
+    hyperdrone_jit_parse_defines("${DEFINES}" CONFIG)
+    if(DEFINED CONFIG_HYPERDRONE_ENV_SPEC_HEADER)
+        set(${OUT_LIBRARIES} rendering_raytracing_backend rendering_raytracing_backend_depth rendering_raytracing_backend_segmentation rendering_raytracing_backend_normals PARENT_SCOPE)
+    elseif(CONFIG_HYPERDRONE_ENV_OUTPUT_NORMALS)
+        set(${OUT_LIBRARIES} rendering_raytracing_backend_normals PARENT_SCOPE)
+    elseif(CONFIG_HYPERDRONE_ENV_OUTPUT_SEGMENTATION)
+        set(${OUT_LIBRARIES} rendering_raytracing_backend_segmentation PARENT_SCOPE)
+    elseif(CONFIG_HYPERDRONE_ENV_OUTPUT_DEPTH)
+        set(${OUT_LIBRARIES} rendering_raytracing_backend_depth PARENT_SCOPE)
+    else()
+        set(${OUT_LIBRARIES} rendering_raytracing_backend PARENT_SCOPE)
+    endif()
+endfunction()
+
+# under OptiX impl.cpp, which holds the environment behind the binding, is compiled by nvcc so
+# the World can run on the GPU (EnvConfig.device); the nanobind translation unit stays C++
+if(HYPERDRONE_VARIANT STREQUAL "OPTIX")
+    add_compile_definitions(HYPERDRONE_ENV_CUDA=1)
+    set_source_files_properties(impl.cpp PROPERTIES LANGUAGE CUDA)
+endif()
+
+set(hyperdrone_env_libraries RLtools::RLtools hyperdrone_env_stb)
+if(TARGET RLtools::HyperDroneSpy)
+    list(APPEND hyperdrone_env_libraries RLtools::HyperDroneSpy rendering_raytracing_backend)
+endif()
+
+hyperdrone_jit_add_configs(
+    COMPONENT env
+    PYTHON_MODULE
+    SOURCES environment.cpp impl.cpp
+    LINK ${hyperdrone_env_libraries}
+)

hyperdrone/_native/env/environment.cpp

@@ -0,0 +1,190 @@
+#include "environment.h"
+#include "bindings.h"
+#include <nanobind/stl/optional.h>
+#include <nanobind/stl/map.h>
+#include <nanobind/stl/string.h>
+#include <nanobind/stl/vector.h>
+
+namespace nb = nanobind;
+
+namespace HYPERDRONE_MODULE_NAME {
+    using HostMask = nb::ndarray<const bool, nb::c_contig, nb::device::cpu>;
+    using Mask = nb::ndarray<const bool, nb::c_contig>;
+    using Actions = nb::ndarray<const float, nb::c_contig>;
+    using FloatOutput = nb::ndarray<float, nb::c_contig>;
+    using FlagsOutput = nb::ndarray<bool, nb::c_contig>;
+
+    template <typename ARRAY>
+    void check_size(const ARRAY& array, size_t expected){
+        if(array.size() != expected){
+            throw std::invalid_argument("hyperdrone: buffer size does not match the environment specification");
+        }
+    }
+
+    template <typename ARRAY>
+    bool resident(const Environment& self, const ARRAY& array, size_t expected){
+        check_size(array, expected);
+        const bool cuda = array.device_type() == nb::device::cuda::value;
+        if(!cuda && array.device_type() != nb::device::cpu::value){
+            throw std::invalid_argument("hyperdrone: arrays must live in host or CUDA device memory");
+        }
+        if(cuda && !CUDA_WORLD){
+            throw std::invalid_argument("hyperdrone: this environment's World runs on the host (device='cpu'); pass host arrays");
+        }
+        if(cuda && array.device_id() != self.device_id()){
+            throw std::invalid_argument("hyperdrone: CUDA arrays must live on the environment's GPU (device_id)");
+        }
+        return cuda == CUDA_WORLD;
+    }
+
+    nb::dict layout_dict(const ObservationLayout& layout){
+        nb::list shape;
+        for(TI dimension : layout.shape){
+            shape.append(dimension);
+        }
+        nb::dict blocks;
+        for(const ObservationBlock& block : layout.blocks){
+            blocks[block.name.c_str()] = nb::make_tuple(block.offset, block.size);
+        }
+        nb::dict value;
+        value["shape"] = nb::tuple(shape);
+        value["axis"] = layout.axis;
+        value["blocks"] = blocks;
+        return value;
+    }
+
+    template <void (Environment::*VERB)(float*, bool), TI DIM>
+    void bind_output(nb::class_<Environment>& environment_class, const char* name){
+        environment_class.def(name, [](Environment& self, FloatOutput out){
+            const bool in_place = resident(self, out, TOTAL * DIM);
+            nb::gil_scoped_release release;
+            (self.*VERB)(out.data(), in_place);
+        }, nb::arg("out").noconvert());
+    }
+
+    template <typename VALUE, void (Environment::*VERB)(VALUE*, bool), TI CHANNELS>
+    void bind_image_output(nb::class_<Environment>& environment_class, const char* name){
+        environment_class.def(name, [](Environment& self, nb::ndarray<VALUE, nb::c_contig> out){
+            constexpr TI HEIGHT = WORLD::SPEC::CAM_HEIGHT;
+            constexpr TI WIDTH = WORLD::SPEC::CAM_WIDTH;
+            const bool in_place = resident(self, out, TOTAL * WORLD::N_VIEWS * HEIGHT * WIDTH * CHANNELS);
+            if(out.ndim() != (CHANNELS == 1 ? 4 : 5) || out.shape(0) != TOTAL || out.shape(1) != WORLD::N_VIEWS || out.shape(2) != HEIGHT || out.shape(3) != WIDTH || (CHANNELS > 1 && out.shape(4) != CHANNELS)){
+                throw std::invalid_argument("hyperdrone: image output must have shape (total_instances, num_views, height, width[, channels])");
+            }
+            nb::gil_scoped_release release;
+            (self.*VERB)(out.data(), in_place);
+        }, nb::arg("out").noconvert());
+    }
+
+    template <typename WORLD_TYPE>
+    void bind_imu(nb::module_& m, nb::class_<Environment>& environment_class){
+        if constexpr (ObservationIMUDim<WORLD_TYPE>::VALUE > 0){
+            m.attr("observation_layout_imu") = layout_dict(observation_layout_imu());
+            bind_output<&Environment::observe_imu, ObservationIMUDim<WORLD_TYPE>::VALUE>(environment_class, "observe_imu");
+        }
+    }
+}
+
+NB_MODULE(HYPERDRONE_MODULE_NAME, m){
+    using namespace HYPERDRONE_MODULE_NAME;
+    m.def("_set_verbosity", &hyperdrone::set_verbosity);
+
+    m.doc() = "JIT-specialized RLtools hyperdrone environment";
+    m.attr("observation_layout") = layout_dict(observation_layout());
+    m.attr("observation_layout_privileged") = layout_dict(observation_layout_privileged());
+    m.attr("CUDA_WORLD") = CUDA_WORLD;
+    m.attr("render_backend") = rlt::rendering::raytracing::backends::name<typename WORLD::RENDERER::BACKEND>();
+    m.attr("synchronized_resets") = SynchronizedResets<WORLD>::VALUE;
+    nb::dict dimensions;
+    dimensions["num_environments"] = NUM_ENVIRONMENTS;
+    dimensions["instances_per_environment"] = WORLD::INSTANCES;
+    dimensions["total_instances"] = TOTAL;
+    dimensions["num_agents"] = WORLD::N_AGENTS;
+    dimensions["num_cameras_per_agent"] = WORLD::N_CAMERAS_PER_AGENT;
+    dimensions["num_views"] = WORLD::N_VIEWS;
+    dimensions["width"] = WORLD::SPEC::CAM_WIDTH;
+    dimensions["height"] = WORLD::SPEC::CAM_HEIGHT;
+    dimensions["image_channels"] = WORLD::IMAGE_CHANNELS;
+    dimensions["observation_dim"] = WORLD::OBSERVATION_DIM;
+    dimensions["observation_dim_privileged"] = WORLD::OBSERVATION_DIM_PRIVILEGED;
+    dimensions["action_dim"] = WORLD::ACTION_DIM;
+    dimensions["episode_step_limit"] = WORLD::EPISODE_STEP_LIMIT;
+    dimensions["observation_dim_imu"] = OBSERVATION_DIM_IMU;
+    dimensions["frame_stride"] = FrameStride<WORLD>::VALUE;
+    dimensions["max_drone_types"] = WORLD::SPEC::MAX_DRONES;
+    dimensions["self_visible"] = WORLD::SPEC::SELF_VISIBLE;
+    m.attr("dimensions") = dimensions;
+    nb::list outputs;
+    if(WORLD::RENDERER_SPEC::HAS_RGB){
+        outputs.append("rgb");
+    }
+    if(WORLD::RENDERER_SPEC::HAS_DEPTH){
+        outputs.append("depth");
+    }
+    if(WORLD::RENDERER_SPEC::HAS_SEGMENTATION){
+        outputs.append("segmentation");
+    }
+    if(WORLD::RENDERER_SPEC::HAS_NORMALS){
+        outputs.append("normals");
+    }
+    if(WORLD::RENDERER_SPEC::HAS_FLOW){
+        outputs.append("flow");
+    }
+    m.attr("outputs") = nb::tuple(outputs);
+    m.attr("segmentation_mode") = WORLD::RENDERER_SPEC::SEMANTIC_SEGMENTATION ? "semantic" : "instance";
+
+    auto environment_class = nb::class_<Environment>(m, "Environment");
+    environment_class
+        .def(nb::init<>())
+        .def("init", &Environment::init, nb::arg("scenes"), nb::arg("drone_assets"), nb::arg("drone_parameters"), nb::arg("assets"), nb::arg("seed"), nb::call_guard<nb::gil_scoped_release>())
+        .def_prop_ro("segmentation_taxonomy", &Environment::segmentation_taxonomy)
+        .def_prop_ro("segmentation_classes", &Environment::segmentation_classes)
+        .def("parameters", &Environment::parameters_json, nb::call_guard<nb::gil_scoped_release>())
+        .def("drones", &Environment::drones_json, nb::call_guard<nb::gil_scoped_release>())
+        .def("instance_parameters", &Environment::instance_parameters_json, nb::call_guard<nb::gil_scoped_release>())
+        .def("spawn_points", &Environment::spawn_points_json, nb::call_guard<nb::gil_scoped_release>())
+        .def("set_instance_parameters", [](Environment& self, HostMask mask, const std::string& json){
+            check_size(mask, TOTAL);
+            nb::gil_scoped_release release;
+            self.set_instance_parameters(mask.data(), json);
+        }, nb::arg("mask").noconvert(), nb::arg("json"))
+        .def("model", &Environment::model, nb::arg("name"), nb::call_guard<nb::gil_scoped_release>())
+        .def("rotate_scene", &Environment::rotate_scene, nb::call_guard<nb::gil_scoped_release>())
+        .def("reset", [](Environment& self, std::optional<Mask> mask, const std::string& spawn_points){
+            const bool in_place = !mask || resident(self, *mask, TOTAL);
+            const bool* pointer = mask ? mask->data() : nullptr;
+            nb::gil_scoped_release release;
+            self.reset(pointer, in_place, spawn_points);
+        }, nb::arg("mask").none().noconvert(), nb::arg("spawn_points") = "")
+        .def("step", [](Environment& self, Actions actions){
+            const bool in_place = resident(self, actions, TOTAL * WORLD::ACTION_DIM);
+            nb::gil_scoped_release release;
+            self.step(actions.data(), in_place);
+        }, nb::arg("actions").noconvert())
+        .def("terminated", [](Environment& self, FlagsOutput out){
+            const bool in_place = resident(self, out, TOTAL);
+            nb::gil_scoped_release release;
+            self.terminated(out.data(), in_place);
+        }, nb::arg("out").noconvert())
+        .def_prop_rw("stream", [](const Environment& self){ return self.stream(); }, [](Environment& self, uintptr_t stream){
+            if(!CUDA_WORLD){
+                throw std::invalid_argument("hyperdrone: this environment's World runs on the host and has no stream");
+            }
+            nb::gil_scoped_release release;
+            self.set_stream(stream);
+        })
+        .def_prop_ro("device_id", &Environment::device_id)
+        .def("spy_open", &Environment::spy_open, nb::call_guard<nb::gil_scoped_release>())
+        .def("spy_update", &Environment::spy_update, nb::call_guard<nb::gil_scoped_release>())
+        .def("spy_close", &Environment::spy_close, nb::call_guard<nb::gil_scoped_release>())
+        .def("synchronize", &Environment::synchronize, nb::call_guard<nb::gil_scoped_release>());
+    bind_output<&Environment::observe, WORLD::OBSERVATION_DIM>(environment_class, "observe");
+    bind_output<&Environment::observe_privileged, WORLD::OBSERVATION_DIM_PRIVILEGED>(environment_class, "observe_privileged");
+    bind_output<&Environment::rewards, 1>(environment_class, "rewards");
+    bind_image_output<float, &Environment::depth, 1>(environment_class, "depth");
+    bind_image_output<uint32_t, &Environment::segmentation, 1>(environment_class, "segmentation");
+    bind_image_output<float, &Environment::normals, 3>(environment_class, "normals");
+    bind_image_output<float, &Environment::flow, 2>(environment_class, "flow");
+    bind_image_output<uint32_t, &Environment::flow_status, 1>(environment_class, "flow_status");
+    bind_imu<WORLD>(m, environment_class);
+}

hyperdrone/_native/env/environment.h

@@ -0,0 +1,282 @@
+#pragma once
+#include "../common/verbosity.h"
+#include <rl_tools/operations/cpu.h>
+#include <rl_tools/rl/environments/hyperdrone/operations_cpu.h>
+#if defined(HYPERDRONE_ENV_TASK) && HYPERDRONE_ENV_TASK == 1
+#include <rl_tools/rl/environments/hyperdrone/tasks/target_frame/operations_cpu.h>
+#endif
+#if defined(HYPERDRONE_ENV_TASK) && HYPERDRONE_ENV_TASK == 2
+#include <rl_tools/rl/environments/hyperdrone/tasks/moving_gate/operations_cpu.h>
+#endif
+#if defined(HYPERDRONE_ENV_TASK) && HYPERDRONE_ENV_TASK == 3
+#include <rl_tools/rl/environments/hyperdrone/tasks/visual_inertial_localization/operations_cpu.h>
+#endif
+#if defined(HYPERDRONE_ENV_PRESET) && HYPERDRONE_ENV_PRESET >= 1
+#include <rl_tools/rl/environments/hyperdrone/presets.h>
+#endif
+
+#include <rl_tools/rl/environments/l2f/operations_cpu.h>
+
+#include <cstdint>
+#include <optional>
+#include <map>
+#include <string>
+#include <vector>
+
+#if !defined(HYPERDRONE_ENV_NUM_ENVIRONMENTS) || !defined(HYPERDRONE_ENV_INSTANCES) || !defined(HYPERDRONE_ENV_CAM_WIDTH) || !defined(HYPERDRONE_ENV_CAM_HEIGHT) || !defined(HYPERDRONE_ENV_SHADING) || !defined(HYPERDRONE_ENV_MB_SAMPLES) || !defined(HYPERDRONE_ENV_PRESET) || !defined(HYPERDRONE_ENV_TASK) || !defined(HYPERDRONE_ENV_N_AGENTS) || !defined(HYPERDRONE_ENV_N_CAMERAS_PER_AGENT) || !defined(HYPERDRONE_ENV_DEVICE_CUDA)
+#error "every HYPERDRONE_ENV_* configuration define must be set (hyperdrone.env.EnvConfig.defines())"
+#endif
+#if HYPERDRONE_ENV_DEVICE_CUDA && !defined(HYPERDRONE_ENV_CUDA)
+#error "a CUDA World needs the OptiX variant"
+#endif
+
+#define HYPERDRONE_ENV_STRINGIFY_INNER(x) #x
+#define HYPERDRONE_ENV_STRINGIFY(x) HYPERDRONE_ENV_STRINGIFY_INNER(x)
+
+// the escape hatch: a user header defining hyperdrone_env_user::WORLD (a fully built
+// World or task chain); preset/task/instance defines are superseded by the user type
+#ifdef HYPERDRONE_ENV_SPEC_HEADER
+#include HYPERDRONE_ENV_STRINGIFY(HYPERDRONE_ENV_SPEC_HEADER)
+#endif
+
+namespace rlt = rl_tools;
+
+// Each configuration needs a distinct C++ type in nanobind's shared type registry.
+namespace HYPERDRONE_MODULE_NAME {
+    using HOST_DEVICE = rlt::devices::CPU<hyperdrone::CPUSpecification>;
+    using T = float;
+    using TI = HOST_DEVICE::index_t;
+    constexpr bool CUDA_WORLD = HYPERDRONE_ENV_DEVICE_CUDA == 1;
+    static_assert(HYPERDRONE_ENV_DATASET == 0 || HYPERDRONE_ENV_DATASET == 1, "unknown HYPERDRONE_ENV_DATASET");
+    using DATASET = rlt::utils::typing::conditional_t<HYPERDRONE_ENV_DATASET == 0,
+        rlt::rendering::datasets::glb::Dataset, rlt::rendering::datasets::procthor::GLB>;
+
+    namespace l2f = rlt::rl::environments::l2f;
+#ifdef HYPERDRONE_ENV_SPEC_HEADER
+    using WORLD = ::hyperdrone_env_user::WORLD;
+#else
+#if HYPERDRONE_ENV_PRESET == 0
+    using REWARD_FUNCTION = l2f::parameters::reward_functions::Squared<T>;
+    static constexpr TI EPISODE_STEP_LIMIT = 500;
+    using PARAMETERS_SPEC = l2f::ParametersBaseSpecification<T, TI, 4, EPISODE_STEP_LIMIT, REWARD_FUNCTION>;
+    using PARAMETERS_TYPE = l2f::ParametersDisturbances<l2f::ParametersSpecification<T, TI, l2f::ParametersBase<PARAMETERS_SPEC>>>;
+    struct DYNAMICS_STATIC_PARAMETERS {
+        static constexpr auto ACTION_INTERFACE = l2f::parameters::ActionInterface::DIRECT_MOTOR;
+        static constexpr TI EPISODE_STEP_LIMIT = HYPERDRONE_MODULE_NAME::EPISODE_STEP_LIMIT;
+        static constexpr TI N_SUBSTEPS = 1;
+        static constexpr TI ACTION_HISTORY_LENGTH = 1;
+        static constexpr TI CLOSED_FORM = false;
+        using STATE_BASE = l2f::StateBase<l2f::StateSpecification<T, TI>>;
+        using STATE_TYPE = l2f::StateRotorsHistory<l2f::StateRotorsHistorySpecification<T, TI, ACTION_HISTORY_LENGTH, CLOSED_FORM, l2f::StateRandomForce<l2f::StateSpecification<T, TI, l2f::StateLastAction<l2f::StateSpecification<T, TI, STATE_BASE>>>>>>;
+        using OBSERVATION_TYPE = l2f::observation::Position<l2f::observation::PositionSpecification<T, TI,
+                l2f::observation::OrientationRotationMatrix<l2f::observation::OrientationRotationMatrixSpecification<T, TI,
+                l2f::observation::LinearVelocity<l2f::observation::LinearVelocitySpecification<T, TI,
+                l2f::observation::AngularVelocity<l2f::observation::AngularVelocitySpecification<T, TI>>>>>>>>;
+        using OBSERVATION_TYPE_PRIVILEGED = l2f::observation::Position<l2f::observation::PositionSpecificationPrivileged<T, TI,
+                l2f::observation::OrientationRotationMatrix<l2f::observation::OrientationRotationMatrixSpecificationPrivileged<T, TI,
+                l2f::observation::LinearVelocity<l2f::observation::LinearVelocitySpecificationPrivileged<T, TI,
+                l2f::observation::AngularVelocity<l2f::observation::AngularVelocitySpecificationPrivileged<T, TI>>>>>>>>;
+        static constexpr bool PRIVILEGED_OBSERVATION_NOISE = false;
+        using PARAMETERS = PARAMETERS_TYPE;
+        static constexpr auto dynamics = l2f::parameters::dynamics::registry<l2f::parameters::dynamics::REGISTRY::crazyflie, PARAMETERS_SPEC>;
+        static constexpr typename PARAMETERS_TYPE::Integration integration = {(T)0.01};
+        static constexpr typename PARAMETERS_TYPE::MDP::Initialization init = l2f::parameters::init::init_90_deg<PARAMETERS_SPEC>;
+        static constexpr typename PARAMETERS_TYPE::MDP mdp = {init, REWARD_FUNCTION{}, {}, {}, {}};
+        static constexpr typename PARAMETERS_TYPE::Disturbances disturbances = {{0, 0}, {0, 0}};
+        static constexpr PARAMETERS_TYPE PARAMETER_VALUES = {{dynamics, integration, mdp}, disturbances};
+        static constexpr T STATE_LIMIT_POSITION_X = 100000;
+        static constexpr T STATE_LIMIT_POSITION_Y = 100000;
+        static constexpr T STATE_LIMIT_POSITION_Z = 100000;
+        static constexpr T STATE_LIMIT_VELOCITY_X = 100000;
+        static constexpr T STATE_LIMIT_VELOCITY_Y = 100000;
+        static constexpr T STATE_LIMIT_VELOCITY_Z = 100000;
+        static constexpr T STATE_LIMIT_ANGULAR_VELOCITY_X = 100000;
+        static constexpr T STATE_LIMIT_ANGULAR_VELOCITY_Y = 100000;
+        static constexpr T STATE_LIMIT_ANGULAR_VELOCITY_Z = 100000;
+    };
+    using PRESET_SPEC = rlt::rl::environments::hyperdrone::Specification<T, TI, DYNAMICS_STATIC_PARAMETERS>;
+#elif HYPERDRONE_ENV_PRESET == 1
+    using PRESET_SPEC = rlt::rl::environments::hyperdrone::presets::X500FPV<T, TI>;
+#elif HYPERDRONE_ENV_PRESET == 2
+    using PRESET_SPEC = rlt::rl::environments::hyperdrone::presets::X500FPVIMU<T, TI>;
+#else
+#error "unknown HYPERDRONE_ENV_PRESET"
+#endif
+    struct WORLD_SPEC: PRESET_SPEC {
+        static constexpr bool OUTPUT_RGB = HYPERDRONE_ENV_OUTPUT_RGB != 0;
+        static constexpr bool OUTPUT_DEPTH = HYPERDRONE_ENV_OUTPUT_DEPTH != 0;
+        static constexpr bool OUTPUT_SEGMENTATION = HYPERDRONE_ENV_OUTPUT_SEGMENTATION != 0;
+        static constexpr bool OUTPUT_NORMALS = HYPERDRONE_ENV_OUTPUT_NORMALS != 0;
+        static constexpr bool OUTPUT_FLOW = HYPERDRONE_ENV_OUTPUT_FLOW != 0;
+        static constexpr bool SEMANTIC_SEGMENTATION = HYPERDRONE_ENV_SEMANTIC_SEGMENTATION != 0;
+        static constexpr TI INSTANCES_PER_ENVIRONMENT = HYPERDRONE_ENV_INSTANCES;
+        static constexpr TI N_AGENTS = HYPERDRONE_ENV_N_AGENTS;
+        static constexpr TI N_CAMERAS_PER_AGENT = HYPERDRONE_ENV_N_CAMERAS_PER_AGENT;
+        static constexpr TI MAX_ENTITY_SLOTS_PER_INSTANCE =
+            (HYPERDRONE_ENV_TASK == 2 && PRESET_SPEC::MAX_ENTITY_SLOTS_PER_INSTANCE == 0 ? 8 : PRESET_SPEC::MAX_ENTITY_SLOTS_PER_INSTANCE)
+            + (N_AGENTS - 1) * rlt::rl::environments::hyperdrone::rig::Rotorcraft<TI>::SPEC::MAX_PARTS;
+        // the visual-inertial localization benchmark flies without self-occlusion, like its
+        // C++ harness (src/rl/environments/hyperdrone/tasks/visual_inertial_localization_harness.h)
+        static constexpr bool SELF_VISIBLE = HYPERDRONE_ENV_TASK != 3 && PRESET_SPEC::SELF_VISIBLE;
+        static constexpr TI CAM_WIDTH = HYPERDRONE_ENV_CAM_WIDTH;
+        static constexpr TI CAM_HEIGHT = HYPERDRONE_ENV_CAM_HEIGHT;
+        static constexpr bool ENABLE_MOTION_BLUR = HYPERDRONE_ENV_MB_SAMPLES > 1;
+        static constexpr TI MOTION_BLUR_SAMPLES = HYPERDRONE_ENV_MB_SAMPLES;
+        static constexpr TI MAX_DRONES = 8;
+        using SHADING = rlt::utils::typing::conditional_t<HYPERDRONE_ENV_SHADING == 0, rlt::rendering::raytracing::Low,
+                        rlt::utils::typing::conditional_t<HYPERDRONE_ENV_SHADING == 1, rlt::rendering::raytracing::Medium,
+                                                                                      rlt::rendering::raytracing::High>>;
+    };
+    using BASE_WORLD = rlt::rl::environments::hyperdrone::World<WORLD_SPEC>;
+#if HYPERDRONE_ENV_TASK == 0
+    using WORLD = BASE_WORLD;
+#elif HYPERDRONE_ENV_TASK == 1
+    struct TASK_SPEC: rlt::rl::environments::hyperdrone::tasks::target_frame::Specification<BASE_WORLD> {};
+    using WORLD = rlt::rl::environments::hyperdrone::tasks::target_frame::World<TASK_SPEC>;
+#elif HYPERDRONE_ENV_TASK == 2
+    struct TASK_SPEC: rlt::rl::environments::hyperdrone::tasks::moving_gate::Specification<BASE_WORLD> {};
+    using WORLD = rlt::rl::environments::hyperdrone::tasks::moving_gate::World<TASK_SPEC>;
+#elif HYPERDRONE_ENV_TASK == 3
+    struct TASK_SPEC: rlt::rl::environments::hyperdrone::tasks::visual_inertial_localization::Specification<BASE_WORLD> {};
+    using WORLD = rlt::rl::environments::hyperdrone::tasks::visual_inertial_localization::World<TASK_SPEC>;
+#else
+#error "unknown HYPERDRONE_ENV_TASK"
+#endif
+#endif
+
+    constexpr TI NUM_ENVIRONMENTS = HYPERDRONE_ENV_NUM_ENVIRONMENTS;
+    using ENV = rlt::rl::environments::hyperdrone::MultiEnvironment<WORLD, NUM_ENVIRONMENTS>;
+    constexpr TI TOTAL = NUM_ENVIRONMENTS * WORLD::INSTANCES;
+    using DYNAMICS = typename WORLD::DYNAMICS_ENV::Parameters::Dynamics;
+
+    // optional World surface beyond the base verbs, detected by type: an IMU observation
+    // stream and a camera frame stride (the visual_inertial_localization task defines both)
+    template <typename WORLD_TYPE, typename = void>
+    struct ObservationIMUDim { static constexpr TI VALUE = 0; };
+    template <typename WORLD_TYPE>
+    struct ObservationIMUDim<WORLD_TYPE, rlt::utils::typing::void_t<typename WORLD_TYPE::ObservationIMU>> { static constexpr TI VALUE = WORLD_TYPE::ObservationIMU::DIM; };
+    template <typename WORLD_TYPE, typename = void>
+    struct FrameStride { static constexpr TI VALUE = 1; };
+    template <typename WORLD_TYPE>
+    struct FrameStride<WORLD_TYPE, rlt::utils::typing::void_t<decltype(WORLD_TYPE::FRAME_STRIDE)>> { static constexpr TI VALUE = WORLD_TYPE::FRAME_STRIDE; };
+    constexpr TI OBSERVATION_DIM_IMU = ObservationIMUDim<WORLD>::VALUE;
+
+    template <typename WORLD_TYPE, typename = void>
+    struct SynchronizedResets { static constexpr bool VALUE = false; };
+    template <typename WORLD_TYPE>
+    struct SynchronizedResets<WORLD_TYPE, rlt::utils::typing::void_t<decltype(WORLD_TYPE::SYNCHRONIZED_RESETS)>> { static constexpr bool VALUE = WORLD_TYPE::SYNCHRONIZED_RESETS; };
+
+    // The environment behind the binding. The World, its RNG and every instance tensor live in the
+    // World's memory (GPU under CUDA_WORLD, impl.cpp is then compiled by nvcc) and every verb is
+    // enqueued on stream(). A `resident` array lives in the World's memory and is read or written
+    // in place on that stream; any other array is a host array, staged through the environment
+    // with a synchronization. A null reset mask selects every instance.
+    struct Environment {
+        struct Impl;
+        Impl* impl;
+        Environment();
+        ~Environment();
+        Environment(const Environment&) = delete;
+        Environment& operator=(const Environment&) = delete;
+        // drones: the shared table, one asset (SELF_VISIBLE) and one resolved parameter set per entry
+        void init(const std::vector<std::string>& scenes, const std::vector<std::optional<std::string>>& drone_assets, const std::vector<std::string>& drone_parameters, const std::map<std::string, std::string>& assets, unsigned long long seed);
+        std::string segmentation_taxonomy() const;
+        std::map<uint32_t, std::string> segmentation_classes() const;
+        std::string parameters_json();
+        std::string drones_json();
+        std::string instance_parameters_json();
+        // per instance: the active scene's content hash, the drone entry, the scene placement,
+        // the agent poses (xyz, wxyz) and the shutter fraction, which reset replays
+        std::string spawn_points_json();
+        void set_instance_parameters(const bool* mask, const std::string& json);
+        std::optional<std::string> model(const std::string& name);
+        void rotate_scene();
+
+        // spawn_points (one per selected instance, see spawn_points_json, a host mask): the
+        // entry's nominal drone at the recorded placement and poses; empty samples as usual
+        void reset(const bool* mask, bool resident, const std::string& spawn_points = "");
+        void step(const float* actions, bool resident);
+        void observe(float* out, bool resident);
+        void depth(float* out, bool resident);
+        void segmentation(uint32_t* out, bool resident);
+        void normals(float* out, bool resident);
+        void flow(float* out, bool resident);
+        void flow_status(uint32_t* out, bool resident);
+
+        void observe_privileged(float* out, bool resident);
+        void observe_imu(float* out, bool resident);
+        void rewards(float* out, bool resident);
+        void terminated(bool* out, bool resident);
+        uintptr_t stream() const;
+        void set_stream(uintptr_t stream);
+        int device_id() const;
+        void synchronize();
+        void spy_open();
+        bool spy_update();
+        void spy_close();
+    };
+
+    struct ObservationBlock {
+        std::string name;
+        TI offset;
+        TI size;
+    };
+    struct ObservationLayout {
+        std::vector<TI> shape;
+        std::string axis;
+        std::vector<ObservationBlock> blocks;
+    };
+
+    inline ObservationLayout observation_layout(){
+        constexpr TI HEIGHT = WORLD::Observation::HEIGHT;
+        constexpr TI WIDTH = WORLD::Observation::WIDTH;
+        constexpr TI CHANNELS = WORLD::Observation::CHANNELS;
+        ObservationLayout layout{{HEIGHT, WIDTH, CHANNELS}, "channel", {}};
+#if HYPERDRONE_ENV_TASK == 1
+        constexpr TI STACK_CHANNELS = TASK_SPEC::IMAGE_STACK_N * BASE_WORLD::IMAGE_CHANNELS;
+        layout.blocks.push_back({"image_stack", 0, STACK_CHANNELS});
+        layout.blocks.push_back({"target_image", STACK_CHANNELS, BASE_WORLD::IMAGE_CHANNELS});
+        if constexpr (CHANNELS > STACK_CHANNELS + BASE_WORLD::IMAGE_CHANNELS){
+            constexpr TI USED = STACK_CHANNELS + BASE_WORLD::IMAGE_CHANNELS;
+            layout.blocks.push_back({"pad", USED, CHANNELS - USED});
+        }
+#else
+        layout.blocks.push_back({"image", 0, CHANNELS});
+#endif
+        return layout;
+    }
+
+    inline ObservationLayout observation_layout_privileged(){
+        ObservationLayout layout{{WORLD::OBSERVATION_DIM_PRIVILEGED}, "flat", {}};
+#ifdef HYPERDRONE_ENV_SPEC_HEADER
+        layout.blocks.push_back({"observation", 0, WORLD::OBSERVATION_DIM_PRIVILEGED});
+#else
+        // the dynamics observation chain: Position(3), OrientationRotationMatrix(9),
+        // LinearVelocity(3), AngularVelocity(3) — per agent, agents contiguous
+        constexpr TI PER_AGENT = 18;
+        for(TI agent_i = 0; agent_i < WORLD::N_AGENTS; agent_i++){
+            std::string prefix = WORLD::N_AGENTS > 1 ? ("agent" + std::to_string(agent_i) + "/") : "";
+            TI base = agent_i * PER_AGENT;
+            layout.blocks.push_back({prefix + "position", base, 3});
+            layout.blocks.push_back({prefix + "orientation_rotation_matrix", base + 3, 9});
+            layout.blocks.push_back({prefix + "linear_velocity", base + 12, 3});
+            layout.blocks.push_back({prefix + "angular_velocity", base + 15, 3});
+        }
+#if HYPERDRONE_ENV_TASK == 2
+        layout.blocks.push_back({"gate_state", WORLD::N_AGENTS * PER_AGENT, 8});
+#endif
+#if HYPERDRONE_ENV_TASK == 3
+        layout.blocks.push_back({"waypoint", WORLD::N_AGENTS * PER_AGENT, 3});
+#endif
+#endif
+        return layout;
+    }
+
+    inline ObservationLayout observation_layout_imu(){
+#if HYPERDRONE_ENV_TASK == 3
+        return {{OBSERVATION_DIM_IMU}, "flat", {{"accelerometer", 0, 3}, {"gyroscope", 3, 3}, {"frame_age", 6, 1}, {"new_frame", 7, 1}}};
+#else
+        return {{OBSERVATION_DIM_IMU}, "flat", {{"imu", 0, OBSERVATION_DIM_IMU}}};
+#endif
+    }
+}