hyperverse 0.0.1__py3-none-any.whl

hyperdrone/_vendor/rl-tools/include/rl_tools/random/operations_generic.h

@@ -0,0 +1,133 @@
+#include "../version.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_UTILS_RANDOM_OPERATIONS_GENERIC_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_UTILS_RANDOM_OPERATIONS_GENERIC_H
+
+
+#include "../utils/generic/typing.h"
+
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools{
+    template <typename DEVICE, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT void malloc(const DEVICE& dev, devices::generic::random::ENGINE<SPEC>& rng){}
+    template <typename DEVICE, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT void free(const DEVICE& dev, devices::generic::random::ENGINE<SPEC>& rng){}
+    template <template <typename DEV_SPEC> typename DEVICE, typename DEV_SPEC, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT void init(const DEVICE<DEV_SPEC>& dev, devices::generic::random::ENGINE<SPEC>& rng, typename DEV_SPEC::MATH::index_t seed = 1){
+        rng.state = 0b10101010101010101010101010101010 + seed;
+    }
+    namespace random{
+        namespace generic{
+            template <typename MATH_DEV>
+            RL_TOOLS_FUNCTION_PLACEMENT constexpr typename MATH_DEV::index_t next_max(const devices::random::Generic<MATH_DEV>& dev){
+                return MATH_DEV::MAX_INDEX;
+            }
+            template<typename MATH_DEV, typename RNG>
+            RL_TOOLS_FUNCTION_PLACEMENT void next(const devices::random::Generic<MATH_DEV>& dev, RNG& rng){
+                // static_assert(utils::typing::is_same_v<typename RNG::STATE_TYPE, typename MATH_DEV::index_t>);
+                rng.state ^= (rng.state << 13);
+                rng.state ^= (rng.state >> 17);
+                rng.state ^= (rng.state << 5);
+            }
+        }
+
+//    template <typename MATH_DEV, typename TI, typename RNG>
+//    auto split(const devices::random::Generic<MATH_DEV>& dev, TI split_id, RNG& rng){
+//        // this operation should not alter the state of rng
+//        RNG rng_copy = rng;
+//        auto next_value = generic::next(dev, rng_copy);
+//        return default_engine(dev, next_value + split_id);
+//    }
+
+        template<typename MATH_DEV, typename T, typename RNG>
+        RL_TOOLS_FUNCTION_PLACEMENT T uniform_int_distribution(const devices::random::Generic<MATH_DEV>& dev, T low, T high, RNG& rng){
+            // static_assert(utils::typing::is_same_v<typename RNG::STATE_TYPE, typename MATH_DEV::index_t>);
+            using TI = typename MATH_DEV::index_t;
+            TI range = static_cast<typename MATH_DEV::index_t>(high - low) + 1;
+            generic::next(dev, rng);
+            TI r = rng.state % range;
+            return static_cast<T>(r) + low;
+        }
+        template<typename MATH_DEV, typename T, typename RNG>
+        RL_TOOLS_FUNCTION_PLACEMENT T uniform_real_distribution(const devices::random::Generic<MATH_DEV>& dev, T low, T high, RNG& rng){
+            // static_assert(utils::typing::is_same_v<typename RNG::STATE_TYPE, typename MATH_DEV::index_t>);
+            static_assert(utils::typing::is_same_v<T, double> || utils::typing::is_same_v<T, float>);
+            generic::next(dev, rng);
+            constexpr auto rng_max = static_cast<decltype(rng.state)>(-1);
+            return (rng.state / static_cast<T>(rng_max)) * (high - low) + low;
+        }
+        namespace normal_distribution{
+            template<typename MATH_DEV, typename T, typename RNG>
+            RL_TOOLS_FUNCTION_PLACEMENT T sample(const devices::random::Generic<MATH_DEV>& dev, T mean, T std, RNG& rng){
+                // static_assert(utils::typing::is_same_v<typename RNG::STATE_TYPE, typename MATH_DEV::index_t>);
+                static_assert(utils::typing::is_same_v<T, double> || utils::typing::is_same_v<T, float>);
+                constexpr auto rng_max = static_cast<decltype(rng.state)>(-1);
+                generic::next(dev, rng);
+                T u1 = rng.state / static_cast<T>(rng_max);
+                generic::next(dev, rng);
+                T u2 = rng.state / static_cast<T>(rng_max);
+                T x = math::sqrt(MATH_DEV{}, -2.0 * math::log(MATH_DEV{}, u1));
+                T y = 2.0 * math::PI<T> * u2;
+                T z = x * math::cos(MATH_DEV{}, y);
+                return z * std + mean;
+            }
+            template<typename RANDOM_DEVICE, typename T>
+            RL_TOOLS_FUNCTION_PLACEMENT T log_prob(const RANDOM_DEVICE& dev, T mean, T log_std, T value){
+                static_assert(utils::typing::is_same_v<T, float> || utils::typing::is_same_v<T, double>);
+                using MATH_DEV = typename RANDOM_DEVICE::MATH_DEVICE;
+                T neg_log_sqrt_pi = -0.5 * math::log(MATH_DEV{}, 2 * math::PI<T>);
+                T diff = (value - mean);
+                T std = math::exp(MATH_DEV{}, log_std);
+                T pre_square = diff/std;
+                return neg_log_sqrt_pi - log_std - 0.5 * pre_square * pre_square;
+            }
+            template<typename RANDOM_DEVICE, typename T>
+            RL_TOOLS_FUNCTION_PLACEMENT T d_log_prob_d_mean(RANDOM_DEVICE& dev, T mean, T log_std, T value){
+                using MATH_DEV = typename RANDOM_DEVICE::MATH_DEVICE;
+                T diff = (value - mean);
+                T std = math::exp(MATH_DEV{}, log_std);
+                T pre_square = diff/std;
+                return pre_square / std;
+            }
+            template<typename RANDOM_DEVICE, typename T>
+            RL_TOOLS_FUNCTION_PLACEMENT T d_log_prob_d_log_std(RANDOM_DEVICE& dev, T mean, T log_std, T value){
+                using MATH_DEV = typename RANDOM_DEVICE::MATH_DEVICE;
+                T diff = (value - mean);
+                T std = math::exp(MATH_DEV{}, log_std);
+                T pre_square = diff/std;
+                return - 1 + pre_square * pre_square;
+            }
+            template<typename RANDOM_DEVICE, typename T>
+            RL_TOOLS_FUNCTION_PLACEMENT T d_log_prob_d_sample(RANDOM_DEVICE& dev, T mean, T log_std, T value){
+                using MATH_DEV = typename RANDOM_DEVICE::MATH_DEVICE;
+                T diff = (value - mean);
+                T std = math::exp(MATH_DEV{}, log_std);
+                T pre_square = diff/std;
+                return - pre_square / std;
+            }
+        }
+    }
+    // Convenience overloads: scalar random calls on ArrayENGINE delegate to engine 0
+    namespace random{
+        template<typename MATH_DEV, typename T, typename SPEC>
+        RL_TOOLS_FUNCTION_PLACEMENT T uniform_real_distribution(const devices::random::Generic<MATH_DEV>& dev, T low, T high, devices::generic::random::ArrayENGINE<SPEC>& rng){
+            auto& rng_state = get(rng.states, 0, 0);
+            return uniform_real_distribution(dev, low, high, rng_state);
+        }
+        template<typename MATH_DEV, typename T, typename SPEC>
+        RL_TOOLS_FUNCTION_PLACEMENT T uniform_int_distribution(const devices::random::Generic<MATH_DEV>& dev, T low, T high, devices::generic::random::ArrayENGINE<SPEC>& rng){
+            auto& rng_state = get(rng.states, 0, 0);
+            return uniform_int_distribution(dev, low, high, rng_state);
+        }
+        namespace normal_distribution{
+            template<typename MATH_DEV, typename T, typename SPEC>
+            RL_TOOLS_FUNCTION_PLACEMENT T sample(const devices::random::Generic<MATH_DEV>& dev, T mean, T std, devices::generic::random::ArrayENGINE<SPEC>& rng){
+                auto& rng_state = get(rng.states, 0, 0);
+                return sample(dev, mean, std, rng_state);
+            }
+        }
+    }
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+
+#endif

hyperdrone/_vendor/rl-tools/include/rl_tools/random/operations_generic_array.h

@@ -0,0 +1,73 @@
+#include "../version.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_RANDOM_OPERATIONS_GENERIC_ARRAY_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_RANDOM_OPERATIONS_GENERIC_ARRAY_H
+
+#include "../containers/matrix/matrix.h"
+
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools::devices::generic::random{
+    // PortableState and ArrayENGINE forward-declared in devices/devices.h
+    template <typename T_TI, T_TI T_NUM_RNGS, bool T_DYNAMIC_ALLOCATION>
+    struct ArraySpecification{
+        using TI = T_TI;
+        static constexpr TI NUM_RNGS = T_NUM_RNGS;
+        static constexpr bool DYNAMIC_ALLOCATION = T_DYNAMIC_ALLOCATION;
+    };
+    template <typename T_SPEC>
+    struct ArrayENGINE{
+        using SPEC = T_SPEC;
+        using TI = typename SPEC::TI;
+        static constexpr TI NUM_RNGS = SPEC::NUM_RNGS;
+        Matrix<matrix::Specification<PortableState, TI, 1, NUM_RNGS, SPEC::DYNAMIC_ALLOCATION>> states;
+    };
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools{
+    template <auto INSTANCES, typename RNG, typename TI>
+    RL_TOOLS_FUNCTION_PLACEMENT RNG& instance_rng(RNG& rng, TI){
+        return rng;
+    }
+    template <auto INSTANCES, typename RNG_SPEC, typename TI>
+    RL_TOOLS_FUNCTION_PLACEMENT auto& instance_rng(devices::generic::random::ArrayENGINE<RNG_SPEC>& rng, TI instance_i){
+        static_assert(RNG_SPEC::NUM_RNGS >= INSTANCES, "the batch needs one RNG state per environment instance");
+        return get(rng.states, 0, instance_i);
+    }
+    template <typename DEVICE, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT void malloc(DEVICE& device, devices::generic::random::ArrayENGINE<SPEC>& rng){
+        malloc(device, rng.states);
+    }
+    template <typename DEVICE, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT void free(DEVICE& device, devices::generic::random::ArrayENGINE<SPEC>& rng){
+        free(device, rng.states);
+    }
+    template <typename DEVICE, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT void init(DEVICE& device, devices::generic::random::ArrayENGINE<SPEC>& rng, unsigned int seed = 1){
+        using TI = typename SPEC::TI;
+        for(TI i = 0; i < SPEC::NUM_RNGS; i++){
+            devices::generic::random::PortableState element;
+            element.state = 0b10101010101010101010101010101010 + seed + static_cast<unsigned int>(i);
+            set(rng.states, 0, i, element);
+        }
+    }
+    template <typename DEVICE_SRC, typename DEVICE_DST, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT void copy(DEVICE_SRC& device_src, DEVICE_DST& device_dst, const devices::generic::random::ArrayENGINE<SPEC>& src, devices::generic::random::ArrayENGINE<SPEC>& dst){
+        copy(device_src, device_dst, src.states, dst.states);
+    }
+    template <typename DEVICE, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT typename DEVICE::index_t abs_diff(DEVICE& device, devices::generic::random::ArrayENGINE<SPEC>& a, devices::generic::random::ArrayENGINE<SPEC>& b){
+        using TI = typename DEVICE::index_t;
+        TI acc = 0;
+        for(TI i = 0; i < SPEC::NUM_RNGS; i++){
+            auto sa = get(a.states, 0, i);
+            auto sb = get(b.states, 0, i);
+            if(sa.state != sb.state) acc++;
+        }
+        return acc;
+    }
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+
+#endif

hyperdrone/_vendor/rl-tools/include/rl_tools/random/operations_wasm32.h

@@ -0,0 +1,57 @@
+#include "../version.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_UTILS_RANDOM_OPERATIONS_WASM32_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_UTILS_RANDOM_OPERATIONS_WASM32_H
+
+
+#include "../utils/generic/typing.h"
+#include "operations_generic.h"
+
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools{
+    template <typename DEV_SPEC, typename SPEC>
+    void malloc(devices::WASM32<DEV_SPEC>& device, devices::random::WASM32::ENGINE<SPEC>& rng){}
+    template <typename DEV_SPEC, typename SPEC>
+    void free(devices::WASM32<DEV_SPEC>& device, devices::random::WASM32::ENGINE<SPEC>& rng){}
+    template <typename DEV_SPEC, typename SPEC>
+    void init(devices::WASM32<DEV_SPEC>& device, devices::random::WASM32::ENGINE<SPEC>& rng, typename devices::WASM32<DEV_SPEC>::index_t seed = 1){
+        rng.state = 10000 + seed;
+    };
+    namespace random{
+        // template <typename DEV_SPEC>
+        // devices::random::WASM32::index_t default_engine(const devices::WASM32<DEV_SPEC>& dev, devices::random::WASM32::index_t seed = 1){
+        //     return default_engine(devices::random::Generic<devices::math::WASM32>{}, seed);
+        // };
+        // constexpr devices::random::WASM32::index_t next_max(const devices::random::WASM32& dev){
+        //     return devices::random::WASM32::MAX_INDEX;
+        // }
+        // template <typename TI, typename RNG>
+        // auto split(const devices::random::WASM32& dev, TI split_id, RNG& rng){
+        //     // this operation should not alter the state of rng
+        //     return split(devices::random::Generic<devices::math::WASM32>{}, split_id, rng);
+        // }
+        // template<typename RNG>
+        // void next(const devices::random::WASM32& dev, RNG& rng){
+        //     next(devices::random::Generic<devices::math::WASM32>{}, rng);
+        // }
+
+        template<typename T, typename RNG>
+        T uniform_int_distribution(const devices::random::WASM32& dev, T low, T high, RNG& rng){
+            return uniform_int_distribution(devices::random::Generic<devices::math::WASM32>{}, low, high, rng);
+        }
+        template<typename T, typename RNG>
+        T uniform_real_distribution(const devices::random::WASM32& dev, T low, T high, RNG& rng){
+            return uniform_real_distribution(devices::random::Generic<devices::math::WASM32>{}, low, high, rng);
+        }
+        namespace normal_distribution{
+            template<typename T, typename RNG>
+            T sample(const devices::random::WASM32& dev, T mean, T std, RNG& rng){
+                return sample(devices::random::Generic<devices::math::WASM32>{}, mean, std, rng);
+            }
+        }
+    }
+
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+
+#endif

hyperdrone/_vendor/rl-tools/include/rl_tools/random/persist.h

@@ -0,0 +1,77 @@
+#include "../version.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_RANDOM_PERSIST_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_RANDOM_PERSIST_H
+#include "../devices/cpu.h"
+#include <sstream>
+#include <cstring>
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools{
+    namespace random_persist{
+        constexpr auto RNG_STATE_MAX_SIZE = 8192; // mt19937 state is ~5KB
+    }
+    template<typename DEV_SPEC, typename SPEC, typename GROUP>
+    void save(devices::CPU<DEV_SPEC>& device, devices::random::CPU::ENGINE<SPEC>& rng, GROUP& group) {
+        using TI = typename devices::CPU<DEV_SPEC>::index_t;
+        std::stringstream ss;
+        ss << rng.engine;
+        std::string state_str = ss.str();
+        utils::assert_exit(device, state_str.length() < random_persist::RNG_STATE_MAX_SIZE, "RNG state string exceeds maximum size");
+        Tensor<tensor::Specification<uint8_t, TI, tensor::Shape<TI, random_persist::RNG_STATE_MAX_SIZE>>> state_tensor;
+        malloc(device, state_tensor);
+        std::memset(data(state_tensor), 0, random_persist::RNG_STATE_MAX_SIZE);
+        std::memcpy(data(state_tensor), state_str.c_str(), state_str.length() + 1); // include null terminator
+        auto rng_group = create_group(device, group, "rng");
+        save(device, state_tensor, rng_group, "state");
+        free(device, state_tensor);
+    }
+    template<typename DEV_SPEC, typename SPEC, typename GROUP>
+    bool load(devices::CPU<DEV_SPEC>& device, devices::random::CPU::ENGINE<SPEC>& rng, GROUP& group) {
+        using TI = typename devices::CPU<DEV_SPEC>::index_t;
+        Tensor<tensor::Specification<uint8_t, TI, tensor::Shape<TI, random_persist::RNG_STATE_MAX_SIZE>>> state_tensor;
+        malloc(device, state_tensor);
+        auto rng_group = get_group(device, group, "rng");
+        if(!load(device, state_tensor, rng_group, "state")){
+            free(device, state_tensor);
+            return false;
+        }
+        std::string state_str(reinterpret_cast<const char*>(data(state_tensor)));
+        free(device, state_tensor);
+        std::stringstream ss(state_str);
+        ss >> rng.engine;
+        return !ss.fail();
+    }
+    // ArrayENGINE: save states as a double tensor (double has 53-bit mantissa, exactly represents all uint32 values)
+    template<typename DEV_SPEC, typename SPEC, typename GROUP>
+    void save(devices::CPU<DEV_SPEC>& device, devices::generic::random::ArrayENGINE<SPEC>& rng, GROUP& group) {
+        using TI = typename devices::CPU<DEV_SPEC>::index_t;
+        constexpr TI NUM_RNGS = SPEC::NUM_RNGS;
+        Tensor<tensor::Specification<double, TI, tensor::Shape<TI, NUM_RNGS>>> state_tensor;
+        malloc(device, state_tensor);
+        for(TI i = 0; i < NUM_RNGS; i++){
+            set(device, state_tensor, (double)get(rng.states, 0, i).state, i);
+        }
+        save(device, state_tensor, group, "states");
+        free(device, state_tensor);
+    }
+    template<typename DEV_SPEC, typename SPEC, typename GROUP>
+    bool load(devices::CPU<DEV_SPEC>& device, devices::generic::random::ArrayENGINE<SPEC>& rng, GROUP& group) {
+        using TI = typename devices::CPU<DEV_SPEC>::index_t;
+        constexpr TI NUM_RNGS = SPEC::NUM_RNGS;
+        Tensor<tensor::Specification<double, TI, tensor::Shape<TI, NUM_RNGS>>> state_tensor;
+        malloc(device, state_tensor);
+        if(!load(device, state_tensor, group, "states")){
+            free(device, state_tensor);
+            return false;
+        }
+        for(TI i = 0; i < NUM_RNGS; i++){
+            devices::generic::random::PortableState element;
+            element.state = static_cast<unsigned int>(get(device, state_tensor, i));
+            set(rng.states, 0, i, element);
+        }
+        free(device, state_tensor);
+        return true;
+    }
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+#endif

hyperdrone/_vendor/rl-tools/include/rl_tools/rendering/camera.h

@@ -0,0 +1,105 @@
+#include "../version.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_RENDERING_CAMERA_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_RENDERING_CAMERA_H
+
+#include "../rl_tools.h"
+
+#include <math.h>
+
+
+// producer-side camera vocabulary: the pinhole parameterization consumed by the renderer plus the
+// vector math to construct it (CUDA producers define RL_TOOLS_FUNCTION_PLACEMENT before including)
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools {
+    namespace rendering{
+        template <typename T_T>
+        struct Camera {
+            T_T pos[3];
+            T_T dir_00[3];
+            T_T dir_du[3];
+            T_T dir_dv[3];
+        };
+
+        // user-facing FOV values are degrees everywhere; trig consumers convert through this —
+        // the double-precision product keeps float FOVs bit-identical to the legacy radian
+        // constants (e.g. 80 degrees reproduces the golden-pinned 1.3962634015954636 exactly)
+        template <typename T>
+        RL_TOOLS_FUNCTION_PLACEMENT constexpr T degrees_to_radians(T degrees){
+            return (T)((double)degrees * 0.017453292519943295);
+        }
+    }
+    namespace rendering::vec3{
+        template <typename T>
+        RL_TOOLS_FUNCTION_PLACEMENT void sub(const T a[3], const T b[3], T out[3]){
+            out[0] = a[0] - b[0]; out[1] = a[1] - b[1]; out[2] = a[2] - b[2];
+        }
+        template <typename T>
+        RL_TOOLS_FUNCTION_PLACEMENT T dot(const T a[3], const T b[3]){
+            return a[0]*b[0] + a[1]*b[1] + a[2]*b[2];
+        }
+        template <typename T>
+        RL_TOOLS_FUNCTION_PLACEMENT void cross(const T a[3], const T b[3], T out[3]){
+            out[0] = a[1]*b[2] - a[2]*b[1];
+            out[1] = a[2]*b[0] - a[0]*b[2];
+            out[2] = a[0]*b[1] - a[1]*b[0];
+        }
+        template <typename T>
+        RL_TOOLS_FUNCTION_PLACEMENT T length(const T v[3]){
+            return sqrtf(dot(v, v));
+        }
+        template <typename T>
+        RL_TOOLS_FUNCTION_PLACEMENT void normalize(const T v[3], T out[3]){
+            T len = length(v);
+            out[0] = v[0]/len; out[1] = v[1]/len; out[2] = v[2]/len;
+        }
+        template <typename T>
+        RL_TOOLS_FUNCTION_PLACEMENT void scale(const T v[3], T s, T out[3]){
+            out[0] = v[0]*s; out[1] = v[1]*s; out[2] = v[2]*s;
+        }
+        template <typename T>
+        RL_TOOLS_FUNCTION_PLACEMENT void add(const T a[3], const T b[3], T out[3]){
+            out[0] = a[0] + b[0]; out[1] = a[1] + b[1]; out[2] = a[2] + b[2];
+        }
+        template <typename T>
+        RL_TOOLS_FUNCTION_PLACEMENT void cross_normalized(const T a[3], const T b[3], T out[3]){
+            T tmp[3];
+            cross(a, b, tmp);
+            normalize(tmp, out);
+        }
+    }
+
+    template <typename T>
+    RL_TOOLS_FUNCTION_PLACEMENT rendering::Camera<T> make_camera_data(const T position[3], const T look_at[3], const T up[3], T fov_degrees, T aspect){
+        namespace v3 = rendering::vec3;
+        T raw_dir[3], dir[3];
+        v3::sub(look_at, position, raw_dir);
+        v3::normalize(raw_dir, dir);
+
+        T fov = rendering::degrees_to_radians(fov_degrees);
+        T image_plane_scale = T{2} * tanf(fov / T{2});
+
+        T du_dir[3], du[3];
+        v3::cross_normalized(dir, up, du_dir);
+        v3::scale(du_dir, image_plane_scale, du);
+
+        T dv_dir[3], dv[3];
+        v3::cross_normalized(du, dir, dv_dir);
+        v3::scale(dv_dir, image_plane_scale / aspect, dv);
+
+        T half_du[3], half_dv[3], tmp[3];
+        v3::scale(du, T{-0.5}, half_du);
+        v3::scale(dv, T{0.5}, half_dv);
+        v3::add(dir, half_du, tmp);
+        rendering::Camera<T> cam;
+        v3::add(tmp, half_dv, cam.dir_00);
+        cam.pos[0] = position[0]; cam.pos[1] = position[1]; cam.pos[2] = position[2];
+        cam.dir_du[0] = du[0]; cam.dir_du[1] = du[1]; cam.dir_du[2] = du[2];
+        v3::scale(dv, T{-1}, cam.dir_dv);
+        return cam;
+    }
+
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+
+#endif

hyperdrone/_vendor/rl-tools/include/rl_tools/rendering/datasets/annotations/cache.h

@@ -0,0 +1,26 @@
+#include "../../../version.h"
+#include "../../../rl_tools.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_RENDERING_DATASETS_ANNOTATIONS_CACHE_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_RENDERING_DATASETS_ANNOTATIONS_CACHE_H
+
+#include <cstdlib>
+#include <string>
+
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools::rendering::datasets::annotations {
+    // opt-in persistence for derived-annotation scans (empty directory = disabled). Entries are
+    // content-addressed on (artifact hash x algorithm version x scoring identity), so scenes
+    // without a content hash are computed but never cached
+    struct Cache {
+        std::string directory;
+    };
+
+    inline std::string default_cache_directory() {
+        const char* home = std::getenv("HOME");
+        return (home != nullptr ? std::string(home) + "/.cache" : std::string(".")) + "/rl_tools/annotations";
+    }
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+
+#endif

hyperdrone/_vendor/rl-tools/include/rl_tools/rendering/datasets/annotations/free_space.h

@@ -0,0 +1,60 @@
+#include "../../../version.h"
+#include "../../../rl_tools.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_RENDERING_DATASETS_ANNOTATIONS_FREE_SPACE_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_RENDERING_DATASETS_ANNOTATIONS_FREE_SPACE_H
+
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools::rendering::datasets::annotations {
+    template <typename T>
+    struct FreeSpacePosition {
+        T position[3];
+        T yaw;
+        T score;
+    };
+
+    template <typename T_T, typename T_TI, T_TI T_MAX_POSITIONS = 256>
+    struct FreeSpaceSpecification {
+        using T = T_T;
+        using TI = T_TI;
+        static constexpr TI MAX_POSITIONS = T_MAX_POSITIONS;
+    };
+
+    // task-facing, graphics-agnostic free-space poses for spawning. Plain trivially-copyable
+    // data — consumers mirror it into device memory for on-device sampling. The annotation
+    // product is the interface: producers (the probe-based annotate, later dataset-native
+    // sources) are interchangeable behind it.
+    template <typename T_SPEC>
+    struct FreeSpace {
+        using SPEC = T_SPEC;
+        using T = typename SPEC::T;
+        using TI = typename SPEC::TI;
+
+        FreeSpacePosition<T> positions[SPEC::MAX_POSITIONS];
+        TI num_positions = 0;
+    };
+
+    // pure task semantics — the probe camera construction is internal to the producer, so a
+    // default-constructed struct is a complete configuration (defaults pin the historical
+    // constants)
+    template <typename T_T, typename T_TI>
+    struct FreeSpaceParameters {
+        using T = T_T;
+        using TI = T_TI;
+        T min_clearance = 1.0;                        // candidate acceptance + search-volume margin
+        TI max_candidates_tested = 4096;
+        TI min_required_positions = 50;               // early-out once this many candidates accepted
+        T hit_ratio_threshold = 0.72;                 // acceptance: fraction of probes that must hit
+        T average_distance_threshold = 0.45;          // acceptance: normalized mean hit distance upper bound
+        T near_hit_distance = 0.25;                   // hits closer than this count as "near"
+        T forward_open_minimum = 0.6;                 // forward probe distance window for the openness bonus
+        T forward_open_maximum = 6.0;
+        T score_weight_hit_ratio = 2.0;
+        T score_weight_average_distance = 1.1;
+        T score_weight_near_ratio = 0.8;
+        T score_forward_open_bonus = 0.15;
+    };
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+
+#endif