hyperray 0.0.1__py3-none-any.whl

hyperdrone/_vendor/rl-tools/src/rl/environments/hyperdrone/spy/ui.cpp

@@ -0,0 +1,380 @@
+#include <rl_tools/rl/environments/hyperdrone/spy/ui.h>
+
+#define GLFW_INCLUDE_NONE
+#include <GLFW/glfw3.h>
+#ifdef __APPLE__
+#define GL_SILENCE_DEPRECATION
+#include <OpenGL/gl3.h>
+#include <pthread.h>
+#else
+#include <GL/gl.h>
+#endif
+#ifdef __linux__
+#include <sys/syscall.h>
+#include <unistd.h>
+#endif
+#include <imgui.h>
+#include <imgui_impl_glfw.h>
+#include <imgui_impl_opengl3.h>
+
+#include <algorithm>
+#include <cmath>
+#include <limits>
+#include <memory>
+#include <stdexcept>
+#include <thread>
+#include <vector>
+
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools::rl::environments::hyperdrone::spy::ui {
+    struct Window {
+        GLFWwindow* handle = nullptr;
+        ImGuiContext* imgui = nullptr;
+        std::thread::id owner = std::this_thread::get_id();
+        GLuint atlas = 0;
+        GLuint spectator = 0;
+        std::size_t members = 0;
+        std::size_t instances = 0;
+        std::size_t agents = 0;
+        std::size_t cameras_per_agent = 0;
+        std::size_t selected = 0;
+        int atlas_width = 0;
+        int atlas_height = 0;
+        int columns = 0;
+        int rows = 0;
+        int spectator_width = 0;
+        int spectator_height = 0;
+        bool glfw_backend = false;
+        bool opengl_backend = false;
+        bool mouse_captured = false;
+        double mouse_x = 0;
+        double mouse_y = 0;
+    };
+
+    namespace {
+        Window* active_window = nullptr;
+
+        void require_main_thread() {
+#ifdef __APPLE__
+            if(!pthread_main_np()) {
+                throw std::runtime_error("HyperDrone spy must run on the main thread");
+            }
+#elif defined(__linux__)
+            if(syscall(SYS_gettid) != getpid()) {
+                throw std::runtime_error("HyperDrone spy must run on the main thread");
+            }
+#endif
+        }
+
+        void require_owner(Window* window) {
+            if(window == nullptr || window->owner != std::this_thread::get_id()) {
+                throw std::runtime_error("HyperDrone spy must be updated and closed on its creating thread");
+            }
+        }
+
+        struct ContextScope {
+            GLFWwindow* glfw = glfwGetCurrentContext();
+            ImGuiContext* imgui = ImGui::GetCurrentContext();
+            bool graphics;
+
+            explicit ContextScope(Window* window, bool use_graphics = true): graphics(use_graphics) {
+                if(graphics) {
+                    glfwMakeContextCurrent(window->handle);
+                }
+                ImGui::SetCurrentContext(window->imgui);
+            }
+
+            ~ContextScope() {
+                ImGui::SetCurrentContext(imgui);
+                if(graphics) {
+                    glfwMakeContextCurrent(glfw);
+                }
+            }
+        };
+
+        template <auto CALLBACK, typename... ARGS>
+        void forward_event(GLFWwindow* handle, ARGS... args) {
+            auto* window = static_cast<Window*>(glfwGetWindowUserPointer(handle));
+            ContextScope context(window, false);
+            CALLBACK(handle, args...);
+        }
+
+        void release_mouse(Window* window) {
+            if(window->mouse_captured) {
+                glfwSetInputMode(window->handle, GLFW_CURSOR, GLFW_CURSOR_NORMAL);
+                window->mouse_captured = false;
+            }
+        }
+
+        void release_graphics(Window* window) {
+            glfwSetWindowFocusCallback(window->handle, nullptr);
+            glfwSetCursorEnterCallback(window->handle, nullptr);
+            glfwSetCursorPosCallback(window->handle, nullptr);
+            glfwSetMouseButtonCallback(window->handle, nullptr);
+            glfwSetScrollCallback(window->handle, nullptr);
+            glfwSetKeyCallback(window->handle, nullptr);
+            glfwSetCharCallback(window->handle, nullptr);
+            release_mouse(window);
+            if(window->opengl_backend) {
+                ImGui_ImplOpenGL3_Shutdown();
+            }
+            if(window->glfw_backend) {
+                ImGui_ImplGlfw_Shutdown();
+            }
+            if(window->imgui != nullptr) {
+                ImGui::DestroyContext(window->imgui);
+                window->imgui = nullptr;
+            }
+            glDeleteTextures(1, &window->atlas);
+            glDeleteTextures(1, &window->spectator);
+        }
+
+        GLuint create_texture(int width, int height) {
+            std::vector<std::uint32_t> pixels(static_cast<std::size_t>(width) * height, 0xff171717u);
+            GLuint texture = 0;
+            glGenTextures(1, &texture);
+            glBindTexture(GL_TEXTURE_2D, texture);
+            glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
+            glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
+            glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
+            glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
+            glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA8, width, height, 0, GL_RGBA, GL_UNSIGNED_BYTE, pixels.data());
+            glBindTexture(GL_TEXTURE_2D, 0);
+            if(glGetError() != GL_NO_ERROR) {
+                glDeleteTextures(1, &texture);
+                throw std::runtime_error("HyperDrone spy could not allocate its display textures");
+            }
+            return texture;
+        }
+
+        void upload(Window* window, GLuint texture, int width, int height, const std::uint32_t* pixels) {
+            require_owner(window);
+            ContextScope context(window);
+            glBindTexture(GL_TEXTURE_2D, texture);
+            glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, width, height, GL_RGBA, GL_UNSIGNED_BYTE, pixels);
+            glBindTexture(GL_TEXTURE_2D, 0);
+        }
+
+        ImVec2 image_size(int width, int height) {
+            const auto available = ImGui::GetContentRegionAvail();
+            const float scale = std::max(0.01f, std::min(available.x / width, available.y / height));
+            return ImVec2(width * scale, height * scale);
+        }
+
+        void frame_age(const char* label, double age) {
+            if(std::isfinite(age) && age >= 0) {
+                ImGui::Text("%s: %.0f ms old", label, age * 1000);
+            }
+            else {
+                ImGui::Text("%s: waiting for a frame", label);
+            }
+        }
+
+        void camera_identity(Window* window, std::size_t camera) {
+            const auto views = window->agents * window->cameras_per_agent;
+            ImGui::Text("Member %zu / instance %zu / agent %zu / camera %zu", camera / (window->instances * views), (camera / views) % window->instances, (camera / window->cameras_per_agent) % window->agents, camera % window->cameras_per_agent);
+        }
+
+        void draw(Window* window, Input& input, double atlas_age, double spectator_age, const char* status) {
+            const auto previous_selection = window->selected;
+            ImGui_ImplOpenGL3_NewFrame();
+            ImGui_ImplGlfw_NewFrame();
+            ImGui::NewFrame();
+            ImGui::SetNextWindowPos(ImVec2(0, 0));
+            ImGui::SetNextWindowSize(ImGui::GetIO().DisplaySize);
+            ImGui::Begin("HyperDrone spy", nullptr, ImGuiWindowFlags_NoDecoration | ImGuiWindowFlags_NoMove | ImGuiWindowFlags_NoSavedSettings);
+            const float left_width = ImGui::GetContentRegionAvail().x * 0.45f;
+            ImGui::BeginChild("Cameras", ImVec2(left_width, 0));
+            frame_age("Cameras", atlas_age);
+            camera_identity(window, window->selected);
+            const auto atlas_size = image_size(window->atlas_width, window->atlas_height);
+            const auto atlas_origin = ImGui::GetCursorScreenPos();
+            ImGui::Image((ImTextureID)(std::intptr_t)window->atlas, atlas_size);
+            if(!window->mouse_captured && ImGui::IsItemHovered()) {
+                const auto cursor = ImGui::GetIO().MousePos;
+                const auto column = std::min(window->columns - 1, static_cast<int>((cursor.x - atlas_origin.x) * window->columns / atlas_size.x));
+                const auto row = std::min(window->rows - 1, static_cast<int>((cursor.y - atlas_origin.y) * window->rows / atlas_size.y));
+                const auto camera = static_cast<std::size_t>(row) * window->columns + column;
+                if(camera < window->members * window->instances * window->agents * window->cameras_per_agent) {
+                    ImGui::BeginTooltip();
+                    camera_identity(window, camera);
+                    ImGui::EndTooltip();
+                    if(ImGui::IsMouseClicked(ImGuiMouseButton_Left)) {
+                        window->selected = camera;
+                    }
+                }
+            }
+            const float tile_width = atlas_size.x / window->columns;
+            const float tile_height = atlas_size.y / window->rows;
+            const ImVec2 tile_origin(atlas_origin.x + (window->selected % window->columns) * tile_width, atlas_origin.y + (window->selected / window->columns) * tile_height);
+            ImGui::GetWindowDrawList()->AddRect(tile_origin, ImVec2(tile_origin.x + tile_width, tile_origin.y + tile_height), IM_COL32(255, 194, 62, 255), 0, 0, 2);
+            ImGui::EndChild();
+            ImGui::SameLine();
+            ImGui::BeginChild("Spectator", ImVec2(0, 0));
+            if(window->selected != previous_selection) {
+                spectator_age = -1;
+            }
+            frame_age("Spectator", spectator_age);
+            input.reset_camera = ImGui::Button("Start from selected camera") && !window->mouse_captured;
+            ImGui::TextUnformatted("Click view: mouse look | WASD: move | Q/E: down/up | Shift: faster | Esc: release");
+            if(status != nullptr && status[0] != '\0') {
+                ImGui::TextWrapped("%s", status);
+            }
+            const auto spectator_size = image_size(window->spectator_width, window->spectator_height);
+            if(spectator_age >= 0) {
+                ImGui::Image((ImTextureID)(std::intptr_t)window->spectator, spectator_size);
+            }
+            else {
+                ImGui::Dummy(spectator_size);
+            }
+            if(!window->mouse_captured && ImGui::IsItemHovered() && ImGui::IsMouseClicked(ImGuiMouseButton_Left)) {
+                glfwSetInputMode(window->handle, GLFW_CURSOR, GLFW_CURSOR_DISABLED);
+                glfwGetCursorPos(window->handle, &window->mouse_x, &window->mouse_y);
+                window->mouse_captured = true;
+            }
+            ImGui::EndChild();
+            ImGui::End();
+            ImGui::Render();
+            int width = 0;
+            int height = 0;
+            glfwGetFramebufferSize(window->handle, &width, &height);
+            glViewport(0, 0, width, height);
+            glClearColor(0.06f, 0.06f, 0.06f, 1.0f);
+            glClear(GL_COLOR_BUFFER_BIT);
+            ImGui_ImplOpenGL3_RenderDrawData(ImGui::GetDrawData());
+            glfwSwapBuffers(window->handle);
+        }
+    }
+
+    Window* create(std::size_t members, std::size_t instances, std::size_t agents, std::size_t cameras_per_agent, int atlas_width, int atlas_height, int columns, int rows, int spectator_width, int spectator_height) {
+        require_main_thread();
+        if(active_window != nullptr) {
+            throw std::runtime_error("Only one HyperDrone spy window can be open per process");
+        }
+        if(members == 0 || instances == 0 || agents == 0 || cameras_per_agent == 0 || members > std::numeric_limits<std::size_t>::max() / instances || members * instances > std::numeric_limits<std::size_t>::max() / agents || members * instances * agents > std::numeric_limits<std::size_t>::max() / cameras_per_agent || columns <= 0 || rows <= 0 || atlas_width < columns || atlas_height < rows || spectator_width <= 0 || spectator_height <= 0 || members * instances * agents * cameras_per_agent > static_cast<std::size_t>(columns) * rows) {
+            throw std::invalid_argument("HyperDrone spy received invalid camera or image dimensions");
+        }
+        if(!glfwInit()) {
+            throw std::runtime_error("HyperDrone spy could not initialize GLFW; a desktop display is required");
+        }
+        auto window = std::make_unique<Window>();
+        window->members = members;
+        window->instances = instances;
+        window->agents = agents;
+        window->cameras_per_agent = cameras_per_agent;
+        window->atlas_width = atlas_width;
+        window->atlas_height = atlas_height;
+        window->columns = columns;
+        window->rows = rows;
+        window->spectator_width = spectator_width;
+        window->spectator_height = spectator_height;
+        glfwDefaultWindowHints();
+        glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
+        glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 2);
+        glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE);
+        glfwWindowHint(GLFW_OPENGL_FORWARD_COMPAT, GLFW_TRUE);
+        window->handle = glfwCreateWindow(1440, 800, "HyperDrone spy", nullptr, nullptr);
+        glfwDefaultWindowHints();
+        if(window->handle == nullptr) {
+            throw std::runtime_error("HyperDrone spy could not create an OpenGL 3.2 window");
+        }
+        try {
+            ContextScope context(window.get());
+            IMGUI_CHECKVERSION();
+            window->imgui = ImGui::CreateContext();
+            ImGui::GetIO().IniFilename = nullptr;
+            ImGui::GetIO().LogFilename = nullptr;
+            ImGui::StyleColorsDark();
+            glfwSwapInterval(0);
+            if(!ImGui_ImplGlfw_InitForOpenGL(window->handle, false)) {
+                throw std::runtime_error("HyperDrone spy could not initialize its GLFW GUI backend");
+            }
+            window->glfw_backend = true;
+            glfwSetWindowUserPointer(window->handle, window.get());
+            glfwSetWindowFocusCallback(window->handle, forward_event<ImGui_ImplGlfw_WindowFocusCallback>);
+            glfwSetCursorEnterCallback(window->handle, forward_event<ImGui_ImplGlfw_CursorEnterCallback>);
+#if IMGUI_VERSION_NUM >= 18700
+            glfwSetCursorPosCallback(window->handle, forward_event<ImGui_ImplGlfw_CursorPosCallback>);
+#endif
+            glfwSetMouseButtonCallback(window->handle, forward_event<ImGui_ImplGlfw_MouseButtonCallback>);
+            glfwSetScrollCallback(window->handle, forward_event<ImGui_ImplGlfw_ScrollCallback>);
+            glfwSetKeyCallback(window->handle, forward_event<ImGui_ImplGlfw_KeyCallback>);
+            glfwSetCharCallback(window->handle, forward_event<ImGui_ImplGlfw_CharCallback>);
+            if(!ImGui_ImplOpenGL3_Init("#version 150")) {
+                throw std::runtime_error("HyperDrone spy could not initialize its OpenGL GUI backend");
+            }
+            window->opengl_backend = true;
+            window->atlas = create_texture(atlas_width, atlas_height);
+            window->spectator = create_texture(spectator_width, spectator_height);
+        }
+        catch(...) {
+            {
+                ContextScope context(window.get());
+                release_graphics(window.get());
+            }
+            glfwDestroyWindow(window->handle);
+            throw;
+        }
+        active_window = window.get();
+        return window.release();
+    }
+
+    Input update(Window* window, double atlas_age, double spectator_age, const char* status) {
+        require_owner(window);
+        glfwPollEvents();
+        ContextScope context(window, false);
+        Input input;
+        input.camera = window->selected;
+        input.closed = glfwWindowShouldClose(window->handle);
+        if(input.closed) {
+            release_mouse(window);
+            return input;
+        }
+        if(glfwGetKey(window->handle, GLFW_KEY_ESCAPE) == GLFW_PRESS || !glfwGetWindowAttrib(window->handle, GLFW_FOCUSED)) {
+            release_mouse(window);
+        }
+        if(window->mouse_captured) {
+            double x = 0;
+            double y = 0;
+            glfwGetCursorPos(window->handle, &x, &y);
+            input.yaw_delta = static_cast<float>(window->mouse_x - x) * 0.002f;
+            input.pitch_delta = static_cast<float>(window->mouse_y - y) * 0.002f;
+            window->mouse_x = x;
+            window->mouse_y = y;
+            const float speed = glfwGetKey(window->handle, GLFW_KEY_LEFT_SHIFT) == GLFW_PRESS ? 3.0f : 1.0f;
+            input.forward = speed * ((glfwGetKey(window->handle, GLFW_KEY_W) == GLFW_PRESS) - (glfwGetKey(window->handle, GLFW_KEY_S) == GLFW_PRESS));
+            input.right = speed * ((glfwGetKey(window->handle, GLFW_KEY_D) == GLFW_PRESS) - (glfwGetKey(window->handle, GLFW_KEY_A) == GLFW_PRESS));
+            input.up = speed * ((glfwGetKey(window->handle, GLFW_KEY_E) == GLFW_PRESS) - (glfwGetKey(window->handle, GLFW_KEY_Q) == GLFW_PRESS));
+        }
+        ContextScope graphics(window);
+        draw(window, input, atlas_age, spectator_age, status);
+        input.camera = window->selected;
+        return input;
+    }
+
+    void upload_atlas(Window* window, const std::uint32_t* pixels) {
+        require_owner(window);
+        upload(window, window->atlas, window->atlas_width, window->atlas_height, pixels);
+    }
+
+    void upload_spectator(Window* window, const std::uint32_t* pixels) {
+        require_owner(window);
+        upload(window, window->spectator, window->spectator_width, window->spectator_height, pixels);
+    }
+
+    void destroy(Window* window) {
+        if(window == nullptr) {
+            return;
+        }
+        require_owner(window);
+        {
+            ContextScope context(window);
+            release_graphics(window);
+        }
+        glfwDestroyWindow(window->handle);
+        active_window = nullptr;
+        delete window;
+        // GLFW has no initialization ownership query; terminating it would also destroy the host application's windows.
+    }
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END

hyperdrone/dynamics/__init__.py

@@ -0,0 +1,5 @@
+"""Vectorized L2F dynamics, independent of rendering; Sim defaults to CPU and exports device camera bases through camera_bases_dlpack()."""
+from ._config import MODELS
+from ._sim import IDENTITY_MOUNT, Sim
+
+__all__ = ["IDENTITY_MOUNT", "MODELS", "Sim"]

hyperdrone/dynamics/_component.py

@@ -0,0 +1,31 @@
+from .. import _jit as jit
+from .._jit._toolchain import cuda_available
+
+DEVICES = ("cpu", "cuda")
+
+
+def _resolve_device(device):
+    value = str(device).lower()
+    if value == "auto":
+        value = "cuda" if cuda_available() else "cpu"
+    if value not in DEVICES:
+        raise ValueError(f"hyperdrone: invalid dynamics device {value} (CPU|CUDA|AUTO)")
+    return value
+
+
+def component(device):
+    resolved = _resolve_device(device)
+    return jit.Component(
+        name="dynamics",
+        variant=resolved.lower(),
+        core_target="hyperdrone_dynamics_core",
+        needs_cuda=resolved == "cuda",
+    )
+
+
+def load_core(device):
+    return jit.core(component(device))
+
+
+def ensure_sim_library(config, device):
+    return jit.ensure(component(device), config)

hyperdrone/dynamics/_config.py

@@ -0,0 +1,46 @@
+from dataclasses import dataclass
+
+from .. import _jit as jit
+
+MODELS = (
+    "crazyflie",
+    "crazyflie_openmv",
+    "mrs",
+    "x500",
+    "x500_real",
+    "x500_sim",
+    "arpl",
+    "fs_base",
+    "flightmare",
+    "soft",
+    "soft_rigid",
+)
+
+STATE_COMPONENTS = {
+    "position": (0, 3),
+    "orientation": (1, 4),
+    "linear_velocity": (2, 3),
+    "angular_velocity": (3, 3),
+    "motor_command": (4, 4),
+}
+
+
+@dataclass(frozen=True, kw_only=True)
+class SimConfig:
+    num_drones: int
+
+    def __post_init__(self):
+        if type(self.num_drones) is not int or self.num_drones < 1:
+            raise ValueError("num_drones must be a positive integer")
+
+    def canonical(self):
+        # must match build_config_string() in _native/dynamics/impl.cpp exactly
+        return f"n={self.num_drones}"
+
+    def key(self):
+        return jit.canonical_key(self.canonical())
+
+    def defines(self):
+        return {
+            "HYPERDRONE_DYNAMICS_NUM_DRONES": self.num_drones,
+        }

hyperdrone/dynamics/_sim.py

@@ -0,0 +1,166 @@
+import json
+
+import numpy as np
+
+from .. import _cuda
+from .._dlpack import DLPackBuffer as _DLPackBuffer, is_cuda
+from .._parameters import resolve
+from ._component import ensure_sim_library, load_core, _resolve_device
+from ._config import STATE_COMPONENTS, SimConfig
+
+IDENTITY_MOUNT = np.array([[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0]], dtype=np.float32)
+
+
+def _load_cuda_core():
+    return load_core("cuda")
+
+
+class SimState:
+    """Owned state snapshots; assignment updates the authoritative simulation state."""
+
+    def __init__(self, sim):
+        self._sim = sim
+
+    def __getitem__(self, name):
+        component, dim = STATE_COMPONENTS[name]
+        out = np.empty((self._sim.num_drones, dim), dtype=np.float32)
+        self._sim._sim.read_state(component, out)
+        self._sim._pending_inputs.clear()
+        return out
+
+    def __setitem__(self, name, values):
+        component, dim = STATE_COMPONENTS[name]
+        array = np.ascontiguousarray(values, dtype=np.float32)
+        if array.shape != (self._sim.num_drones, dim):
+            raise ValueError(f"hyperdrone: state {name!r} must have shape ({self._sim.num_drones}, {dim})")
+        self._sim._sim.set_state(component, array)
+        self._sim._pending_inputs.clear()
+
+    def keys(self):
+        return STATE_COMPONENTS.keys()
+
+
+class Sim:
+    """Vectorized L2F dynamics with a fixed shared parameter set and explicit state updates.
+
+    A seed initializes independent dynamics and observation streams once. Reset restores selected drones' nominal parameters and state; sample_states=True samples their initial states from a continuing host stream. Host accessors return owned arrays; *_dlpack accessors borrow publication buffers until the next producer update. Consumers must finish reading borrowed buffers before that update.
+    """
+
+    def __init__(self, num_drones, *, parameters=None, seed=0, device="cpu"):
+        self._config = SimConfig(num_drones=num_drones)
+        if type(seed) is not int or not 0 <= seed <= 0xFFFFFFFF:
+            raise ValueError("hyperdrone: seed must be an integer in [0, 2**32 - 1]")
+        self.device = _resolve_device(device)
+        library = ensure_sim_library(self._config, self.device)
+        self._core = load_core(self.device)
+        self._sim = self._core.JitSim(str(library), self._config.canonical())
+        nominal = resolve(json.loads(self._sim.parameters()), {} if parameters is None else parameters, self._core.model_json)
+        self._sim.init(seed, json.dumps(nominal))
+        self._pending_inputs = []
+        self.state = SimState(self)
+        if self.device == "cuda":
+            _cuda.register_provider(_load_cuda_core)
+
+    @property
+    def num_drones(self):
+        return self._sim.num_drones
+
+    @property
+    def action_dim(self):
+        return self._sim.action_dim
+
+    @property
+    def observation_dim(self):
+        return self._sim.observation_dim
+
+    @property
+    def parameters(self):
+        return json.loads(self._sim.parameters())
+
+    @property
+    def dt(self):
+        return self.parameters["dynamics"]["integration"]["dt"]
+
+    @property
+    def stream(self):
+        """The CUDA stream handle (0 on CPU), for ordering device handoffs."""
+        return self._sim.stream
+
+    def _mask(self, mask):
+        if mask is None:
+            return np.ones(self.num_drones, dtype=np.bool_)
+        array = np.ascontiguousarray(mask, dtype=np.bool_)
+        if array.shape != (self.num_drones,):
+            raise ValueError(f"hyperdrone: mask must have shape ({self.num_drones},)")
+        return array
+
+    def reset(self, mask=None, *, sample_states=False):
+        self._sim.reset(self._mask(mask), bool(sample_states))
+        self._pending_inputs.clear()
+
+    def instance_parameters(self):
+        return json.loads(self._sim.instance_parameters())
+
+    def set_instance_parameters(self, overrides, mask=None):
+        mask = self._mask(mask)
+        selected = np.flatnonzero(mask)
+        if isinstance(overrides, dict):
+            overrides = [overrides] * len(selected)
+        if len(overrides) != len(selected):
+            raise ValueError(f"hyperdrone: {len(overrides)} overrides for {len(selected)} selected drones")
+        current = self.instance_parameters()
+        merged = [resolve(current[index], values, self._core.model_json) for index, values in zip(selected, overrides)]
+        self._sim.set_instance_parameters(mask, json.dumps(merged))
+        self._pending_inputs.clear()
+
+    def step(self, actions, *, stream=0):
+        """Advance one dt with normalized rotor commands of shape (num_drones, action_dim)."""
+        if is_cuda(actions):
+            if self.device != "cuda":
+                raise RuntimeError("hyperdrone: device-resident actions require the cuda dynamics variant")
+            self._sim.step_device(actions, int(stream))
+            self._pending_inputs.append(actions)
+            return
+        array = np.ascontiguousarray(np.asarray(actions), dtype=np.float32)
+        if array.shape != (self.num_drones, self.action_dim):
+            raise ValueError(f"actions must have shape ({self.num_drones}, {self.action_dim})")
+        self._sim.step(array)
+
+    def synchronize(self):
+        self._sim.synchronize()
+        self._pending_inputs.clear()
+
+    def _buffer(self, producer):
+        return _DLPackBuffer(self, producer, self._sim.buffer_device_type, self._sim.buffer_device_id, self._sim.order_consumer)
+
+    def state_dlpack(self, name):
+        component, _ = STATE_COMPONENTS[name]
+        return self._buffer(lambda: self._sim.state_dlpack(component))
+
+    def observe_dlpack(self):
+        self._sim.update_observations()
+        return self._buffer(self._sim.observations_dlpack)
+
+    def observe(self):
+        self._sim.update_observations()
+        out = np.empty((self.num_drones, self.observation_dim), dtype=np.float32)
+        self._sim.read_observations(out)
+        self._pending_inputs.clear()
+        return out
+
+    def camera_bases_dlpack(self, *, mount=None, fov=80.0, aspect):
+        """Borrow packed camera bases derived from authoritative drone poses; fov is in degrees."""
+        mount_array = IDENTITY_MOUNT if mount is None else np.ascontiguousarray(mount, dtype=np.float32)
+        if mount_array.shape != (3, 4):
+            raise ValueError("hyperdrone: mount must have shape (3, 4)")
+        if not np.isfinite(fov) or not 0 < fov < 180 or not np.isfinite(aspect) or aspect <= 0:
+            raise ValueError("hyperdrone: fov must be in (0, 180) and aspect must be positive")
+        self._sim.update_camera_bases(mount_array, float(fov), float(aspect))
+        return self._buffer(self._sim.camera_bases_dlpack)
+
+    def camera_bases(self, *, mount=None, fov=80.0, aspect):
+        self.camera_bases_dlpack(mount=mount, fov=fov, aspect=aspect)
+        out = np.empty((self.num_drones, 12), dtype=np.float32)
+        self._sim.read_camera_bases(out)
+        self._pending_inputs.clear()
+        return out

hyperdrone/env/__init__.py

@@ -0,0 +1,23 @@
+"""hyperdrone.env — the RL environment: the C++ rl_tools hyperdrone::MultiEnvironment<World>
+driven through the exact batch verbs the C++ training targets use.
+
+All environment semantics (reset, reward, termination, scene rotation, observation
+composition) live on the C++ side; this package marshals tensors and nothing else. For
+manual composition of the render and dynamics packages (no MDP), see
+examples/drone_flythrough.py.
+"""
+from ._multi_environment import EnvConfig, MultiEnvironment, ObservationLayout
+
+__all__ = [
+    "EnvConfig",
+    "MultiEnvironment",
+    "ObservationLayout",
+    "Rotorcraft",
+]
+
+
+def __getattr__(name):
+    if name == "Rotorcraft":
+        from ._rotorcraft import Rotorcraft
+        return Rotorcraft
+    raise AttributeError(f"module 'hyperdrone.env' has no attribute {name}")