RadiationModel.h

Go to the documentation of this file.

 
#ifndef RADIATION_MODEL
#define RADIATION_MODEL
 
#include "CameraCalibration.h"
#include "Context.h"
#include "RayTracingBackend.h"
#include "json.hpp"
 
#include <utility>
 
struct CameraProperties {
 
    bool operator!=(const CameraProperties &rhs) const {
        return !(rhs == *this);
    }
 
    helios::int2 camera_resolution;
 
    float focal_plane_distance;
 
    float lens_focal_length;
 
    float lens_diameter;
 
    float HFOV;
 
    float FOV_aspect_ratio;
 
    float sensor_width_mm;
 
    std::string model;
 
    std::string lens_make;
 
    std::string lens_model;
 
    std::string lens_specification;
 
    std::string exposure;
 
    float shutter_speed;
 
    std::string white_balance;
 
    float camera_zoom;
 
    CameraProperties() {
        camera_resolution = helios::make_int2(512, 512);
        focal_plane_distance = 1;
        lens_focal_length = 0.05; // 50mm default
        lens_diameter = 0.05;
        FOV_aspect_ratio = 0.f; // Sentinel value: 0 means auto-calculate from camera_resolution
        HFOV = 20.f;
        sensor_width_mm = 35.f;
        model = "generic";
        exposure = "auto";
        shutter_speed = 1.f / 125.f; // 1/125 second (standard default)
        white_balance = "auto";
        camera_zoom = 1.0f;
    }
 
    bool operator==(const CameraProperties &rhs) const {
        return camera_resolution == rhs.camera_resolution && focal_plane_distance == rhs.focal_plane_distance && lens_focal_length == rhs.lens_focal_length && lens_diameter == rhs.lens_diameter && FOV_aspect_ratio == rhs.FOV_aspect_ratio &&
               HFOV == rhs.HFOV && sensor_width_mm == rhs.sensor_width_mm && model == rhs.model && lens_make == rhs.lens_make && lens_model == rhs.lens_model && lens_specification == rhs.lens_specification && exposure == rhs.exposure &&
               shutter_speed == rhs.shutter_speed && white_balance == rhs.white_balance && camera_zoom == rhs.camera_zoom;
    }
};
 
struct LensFlareProperties {
 
    int aperture_blade_count = 6;
 
    float coating_efficiency = 0.96f;
 
    float ghost_intensity = 1.0f;
 
    float starburst_intensity = 1.0f;
 
    float intensity_threshold = 0.8f;
 
    int ghost_count = 5;
 
    bool operator==(const LensFlareProperties &rhs) const {
        return aperture_blade_count == rhs.aperture_blade_count && coating_efficiency == rhs.coating_efficiency && ghost_intensity == rhs.ghost_intensity && starburst_intensity == rhs.starburst_intensity &&
               intensity_threshold == rhs.intensity_threshold && ghost_count == rhs.ghost_count;
    }
 
    bool operator!=(const LensFlareProperties &rhs) const {
        return !(rhs == *this);
    }
};
 
struct RadiationCamera {
 
    // Constructor
    RadiationCamera(std::string initlabel, const std::vector<std::string> &band_label, const helios::vec3 &initposition, const helios::vec3 &initlookat, const CameraProperties &camera_properties, uint initantialiasing_samples) :
        label(std::move(initlabel)), band_labels(band_label), position(initposition), lookat(initlookat), antialiasing_samples(initantialiasing_samples) {
        for (const auto &band: band_label) {
            band_spectral_response[band] = "uniform";
        }
        focal_length = camera_properties.focal_plane_distance; // working distance for ray generation
        lens_focal_length = camera_properties.lens_focal_length; // optical focal length for aperture
        resolution = camera_properties.camera_resolution;
        lens_diameter = camera_properties.lens_diameter;
        HFOV_degrees = camera_properties.HFOV;
        FOV_aspect_ratio = camera_properties.FOV_aspect_ratio;
        sensor_width_mm = camera_properties.sensor_width_mm;
        model = camera_properties.model;
        lens_make = camera_properties.lens_make;
        lens_model = camera_properties.lens_model;
        lens_specification = camera_properties.lens_specification;
        exposure = camera_properties.exposure;
        shutter_speed = camera_properties.shutter_speed;
        white_balance = camera_properties.white_balance;
        camera_zoom = camera_properties.camera_zoom;
    }
 
    // Label for camera array
    std::string label;
    // Cartesian (x,y,z) position of camera array center
    helios::vec3 position;
    // Direction camera is pointed (normal vector of camera surface). This vector will automatically be normalized
    helios::vec3 lookat;
    // Physical dimensions of the camera lens
    float lens_diameter;
    // Resolution of camera sub-divisions (i.e., pixels)
    helios::int2 resolution;
    // camera focal length (working distance for ray generation)
    float focal_length;
    // lens optical focal length (for f-number and aperture calculations). This is the physical focal length, not the 35mm equivalent.
    float lens_focal_length;
    // camera horizontal field of view (degrees)
    float HFOV_degrees;
    // Ratio of camera horizontal field of view to vertical field of view
    float FOV_aspect_ratio;
    // Physical sensor width in mm
    float sensor_width_mm;
    // Camera model name
    std::string model;
    // Lens make/manufacturer
    std::string lens_make;
    // Lens model name
    std::string lens_model;
    // Lens specification
    std::string lens_specification;
    // Exposure mode: "auto", "ISOXXX" (e.g., "ISO100"), or "manual"
    std::string exposure;
    // Camera shutter speed in seconds
    float shutter_speed;
    // White balance mode: "auto" or "off"
    std::string white_balance;
    // Camera optical zoom multiplier
    float camera_zoom;
    // Camera type (rgb, spectral, or thermal)
    std::string camera_type;
    // Number of antialiasing samples per pixel
    uint antialiasing_samples;
 
    std::vector<std::string> band_labels;
 
    std::map<std::string, std::string> band_spectral_response;
 
    std::map<std::string, std::vector<float>> pixel_data;
 
    std::vector<uint> pixel_label_UUID;
    std::vector<float> pixel_depth;
 
    bool lens_flare_enabled = false;
 
    LensFlareProperties lens_flare_properties;
 
    void normalizePixels();
 
 
 
    void whiteBalance(const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label, float p = 5.0);
 
 
    void whiteBalanceGrayEdge(const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label, int derivative_order = 1, float p = 5.0);
 
 
    void whiteBalanceWhitePatch(const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label, float percentile = 0.99f);
 
 
 
    void whiteBalanceSpectral(const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label, helios::Context *context);
 
 
    void reinhardToneMapping(const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label);
 
 
    void applyGain(const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label, float percentile = 0.95f);
 
 
    void adjustSBC(const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label, float saturation, float brightness, float contrast);
 
 
    // void applyCCM(const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label);
 
 
    void gammaCompress(const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label);
 
    void globalHistogramEqualization(const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label);
 
 
    void autoExposure(const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label, float gain_multiplier);
 
 
    void applyCameraExposure(helios::Context *context);
 
 
    void applyCameraWhiteBalance(helios::Context *context);
 
 
    void adjustBrightnessContrast(const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label, float brightness, float contrast);
 
 
    void adjustSaturation(const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label, float saturation);
 
 
    static float lin_to_srgb(float x) noexcept {
        // Clamp negative values to 0, bright values > 1.0 to white (1.0)
        if (x <= 0.0f)
            return 0.0f;
        if (x >= 1.0f)
            return 1.0f; // Bright pixels clipped to white
        return (x <= 0.0031308f) ? 12.92f * x : 1.055f * std::pow(x, 1.0f / 2.4f) - 0.055f;
    }
 
 
    static float srgb_to_lin(float v) noexcept {
        return (v <= 0.04045f) ? v / 12.92f : std::pow((v + 0.055f) / 1.055f, 2.4f);
    }
 
private:
 
    static float luminance(float red, float green, float blue) noexcept {
        return 0.2126f * red + 0.7152f * green + 0.0722f * blue;
    }
};
 
struct CameraTile {
    helios::int2 resolution; 
    helios::int2 offset; 
};
 
struct CameraMetadata {
 
    std::string path;
 
    struct CameraProperties {
        int height; 
        int width; 
        int channels; 
        std::string type; 
        float focal_length; 
        std::string aperture; 
        float sensor_width; 
        float sensor_height; 
        std::string model; 
        std::string lens_make; 
        std::string lens_model; 
        std::string lens_specification; 
        std::string exposure; 
        float shutter_speed; 
        std::string white_balance; 
        float camera_zoom; 
    } camera_properties;
 
    struct LocationProperties {
        float latitude; 
        float longitude; 
    } location_properties;
 
    struct AcquisitionProperties {
        std::string date; 
        std::string time; 
        float UTC_offset; 
        float camera_height_m; 
        float camera_angle_deg; 
        std::string light_source; 
    } acquisition_properties;
 
    struct ImageProcessingProperties {
        float saturation_adjustment = 1.f; 
        float brightness_adjustment = 1.f; 
        float contrast_adjustment = 1.f; 
        std::string color_space = "linear"; 
    } image_processing;
 
    struct AgronomicProperties {
        std::vector<std::string> plant_species; 
        std::vector<int> plant_count; 
        std::vector<float> plant_height_m; 
        std::vector<float> plant_age_days; 
        std::vector<std::string> plant_stage; 
        std::vector<float> leaf_area_m2; 
        std::string weed_pressure; 
    } agronomic_properties;
};
 
struct RadiationBand {
 
    explicit RadiationBand(std::string a_label, size_t directRayCount_default, size_t diffuseRayCount_default, float diffuseFlux_default, uint scatteringDepth_default, float minScatterEnergy_default) : label(std::move(a_label)) {
        directRayCount = directRayCount_default;
        diffuseRayCount = diffuseRayCount_default;
        diffuseFlux = diffuseFlux_default;
        scatteringDepth = scatteringDepth_default;
        minScatterEnergy = minScatterEnergy_default;
        diffuseExtinction = 0.f;
        diffuseDistNorm = 1.f;
        emissionFlag = true;
        wavebandBounds = helios::make_vec2(0, 0);
    }
 
    std::string label;
 
    size_t directRayCount;
 
    size_t diffuseRayCount;
 
    float diffuseFlux;
 
    float diffuseExtinction;
 
    helios::vec3 diffusePeakDir;
 
    float diffuseDistNorm;
 
    helios::vec4 diffusePragueParams = helios::make_vec4(0, 0, 0, 0);
 
    std::vector<helios::vec2> diffuse_spectrum;
 
    uint scatteringDepth;
 
    float minScatterEnergy;
 
    bool emissionFlag;
 
    helios::vec2 wavebandBounds;
};
 
enum RadiationSourceType { RADIATION_SOURCE_TYPE_COLLIMATED = 0, RADIATION_SOURCE_TYPE_SPHERE = 1, RADIATION_SOURCE_TYPE_SUN_SPHERE = 2, RADIATION_SOURCE_TYPE_RECTANGLE = 3, RADIATION_SOURCE_TYPE_DISK = 4 };
 
struct RadiationSource {
public:
    explicit RadiationSource(const helios::vec3 &position) : source_position(position) {
        source_type = RADIATION_SOURCE_TYPE_COLLIMATED;
 
        // initialize other unused variables
        source_position_scaling_factor = 1.f;
        source_flux_scaling_factor = 1.f;
    };
 
    RadiationSource(const helios::vec3 &position, float width) : source_position(position) {
        source_type = RADIATION_SOURCE_TYPE_SPHERE;
 
        source_width = helios::make_vec2(width, width);
 
        // initialize other unused variables
        source_position_scaling_factor = 1.f;
        source_flux_scaling_factor = 1.f;
    };
 
    RadiationSource(const helios::vec3 &position, float position_scaling_factor, float width, float flux_scaling_factor) :
        source_position(position), source_position_scaling_factor(position_scaling_factor), source_flux_scaling_factor(flux_scaling_factor) {
        source_type = RADIATION_SOURCE_TYPE_SUN_SPHERE;
        source_width = helios::make_vec2(width, width);
    };
 
 
    RadiationSource(const helios::vec3 &position, const helios::vec2 &size, const helios::vec3 &rotation) : source_position(position), source_width(size), source_rotation(rotation) {
        source_type = RADIATION_SOURCE_TYPE_RECTANGLE;
 
        // initialize other unused variables
        source_position_scaling_factor = 1.f;
        source_flux_scaling_factor = 1.f;
    };
 
    RadiationSource(const helios::vec3 &position, float width, const helios::vec3 &rotation) : source_position(position), source_rotation(rotation) {
        source_type = RADIATION_SOURCE_TYPE_DISK;
 
        source_width = helios::make_vec2(width, width);
 
        // initialize other unused variables
        source_position_scaling_factor = 1.f;
        source_flux_scaling_factor = 1.f;
    };
 
    helios::vec3 source_position;
 
    float source_position_scaling_factor;
 
    std::vector<helios::vec2> source_spectrum;
 
    std::string source_spectrum_label = "none";
 
    uint64_t source_spectrum_version = 0;
 
    helios::vec2 source_width;
 
    helios::vec3 source_rotation;
 
    float source_flux_scaling_factor;
 
    RadiationSourceType source_type;
 
    std::map<std::string, float> source_fluxes;
};
 
class RadiationModel {
public:
    explicit RadiationModel(helios::Context *context);
 
    ~RadiationModel();
 
 
    static int selfTest(int argc = 0, char **argv = nullptr);
 
 
    void disableMessages();
 
    void enableMessages();
 
 
    void optionalOutputPrimitiveData(const char *label);
 
 
    void setDirectRayCount(const std::string &label, size_t N);
 
 
    void setDiffuseRayCount(const std::string &label, size_t N);
 
 
    void setDiffuseRadiationFlux(const std::string &label, float flux);
 
 
    void setDiffuseRadiationExtinctionCoeff(const std::string &label, float K, const helios::vec3 &peak_dir);
 
 
    void setDiffuseRadiationExtinctionCoeff(const std::string &label, float K, const helios::SphericalCoord &peak_dir);
 
 
    void setDiffuseSpectrumIntegral(float spectrum_integral);
 
 
    void setDiffuseSpectrumIntegral(float spectrum_integral, float wavelength_min, float wavelength_max);
 
 
    void setDiffuseSpectrumIntegral(const std::string &band_label, float spectrum_integral);
 
 
    void setDiffuseSpectrumIntegral(const std::string &band_label, float spectrum_integral, float wavelength_min, float wavelength_max);
 
 
    void addRadiationBand(const std::string &label);
 
 
    void addRadiationBand(const std::string &label, float wavelength_min, float wavelength_max);
 
 
    void copyRadiationBand(const std::string &old_label, const std::string &new_label);
 
 
    void copyRadiationBand(const std::string &old_label, const std::string &new_label, float wavelength_min, float wavelength_max);
 
 
    bool doesBandExist(const std::string &label) const;
 
 
    void disableEmission(const std::string &label);
 
 
    void enableEmission(const std::string &label);
 
 
    uint addCollimatedRadiationSource();
 
 
    uint addCollimatedRadiationSource(const helios::SphericalCoord &direction);
 
 
    uint addCollimatedRadiationSource(const helios::vec3 &direction);
 
 
    uint addSphereRadiationSource(const helios::vec3 &position, float radius);
 
 
    uint addSunSphereRadiationSource();
 
 
    uint addSunSphereRadiationSource(const helios::SphericalCoord &sun_direction);
 
 
    uint addSunSphereRadiationSource(const helios::vec3 &sun_direction);
 
 
    uint addRectangleRadiationSource(const helios::vec3 &position, const helios::vec2 &size, const helios::vec3 &rotation_rad);
 
 
    uint addDiskRadiationSource(const helios::vec3 &position, float radius, const helios::vec3 &rotation_rad);
 
 
    void deleteRadiationSource(uint sourceID);
 
 
    void setSourceSpectrumIntegral(uint source_ID, float source_integral);
 
 
    void setSourceSpectrumIntegral(uint source_ID, float source_integral, float wavelength_min, float wavelength_max);
 
 
    void setSourceFlux(uint source_ID, const std::string &band_label, float flux);
 
 
    void setSourceFlux(const std::vector<uint> &source_ID, const std::string &band_label, float flux);
 
 
    float getSourceFlux(uint source_ID, const std::string &band_label) const;
 
 
    void setSourcePosition(uint source_ID, const helios::vec3 &position);
 
 
    void setSourcePosition(uint source_ID, const helios::SphericalCoord &position);
 
 
    helios::vec3 getSourcePosition(uint source_ID) const;
 
 
    void setSourceSpectrum(uint source_ID, const std::vector<helios::vec2> &spectrum);
 
 
    void setSourceSpectrum(const std::vector<uint> &source_ID, const std::vector<helios::vec2> &spectrum);
 
 
    void setSourceSpectrum(uint source_ID, const std::string &spectrum_label);
 
 
    void setSourceSpectrum(const std::vector<uint> &source_ID, const std::string &spectrum_label);
 
 
    void setDiffuseSpectrum(const std::string &spectrum_label);
 
 
    float getDiffuseFlux(const std::string &band_label) const;
 
    void enableLightModelVisualization();
 
    void disableLightModelVisualization();
 
    void enableCameraModelVisualization();
 
    void disableCameraModelVisualization();
 
 
    float integrateSpectrum(const std::vector<helios::vec2> &object_spectrum, float wavelength_min, float wavelength_max) const;
 
 
    float integrateSpectrum(const std::vector<helios::vec2> &object_spectrum) const;
 
 
    float integrateSpectrum(uint source_ID, const std::vector<helios::vec2> &object_spectrum, float wavelength_min, float wavelength_max) const;
 
 
    float integrateSpectrum(uint source_ID, const std::vector<helios::vec2> &object_spectrum, const std::vector<helios::vec2> &camera_spectrum) const;
 
 
    float integrateSpectrum(const std::vector<helios::vec2> &object_spectrum, const std::vector<helios::vec2> &camera_spectrum) const;
 
 
    float integrateSourceSpectrum(uint source_ID, float wavelength_min, float wavelength_max) const;
 
 
    void scaleSpectrum(const std::string &existing_global_data_label, const std::string &new_global_data_label, float scale_factor) const;
 
 
    void scaleSpectrum(const std::string &global_data_label, float scale_factor) const;
 
 
    void scaleSpectrumRandomly(const std::string &existing_global_data_label, const std::string &new_global_data_label, float minimum_scale_factor, float maximum_scale_factor) const;
 
 
    void blendSpectra(const std::string &new_spectrum_label, const std::vector<std::string> &spectrum_labels, const std::vector<float> &weights) const;
 
 
    void blendSpectraRandomly(const std::string &new_spectrum_label, const std::vector<std::string> &spectrum_labels) const;
 
 
    void interpolateSpectrumFromPrimitiveData(const std::vector<uint> &primitive_UUIDs, const std::vector<std::string> &spectra, const std::vector<float> &values, const std::string &primitive_data_query_label,
                                              const std::string &primitive_data_radprop_label);
 
 
    void interpolateSpectrumFromObjectData(const std::vector<uint> &object_IDs, const std::vector<std::string> &spectra, const std::vector<float> &values, const std::string &object_data_query_label, const std::string &primitive_data_radprop_label);
 
 
    void setScatteringDepth(const std::string &label, uint depth);
 
 
    void setMinScatterEnergy(const std::string &label, uint energy);
 
 
    void enforcePeriodicBoundary(const std::string &boundary);
 
 
    void addRadiationCamera(const std::string &camera_label, const std::vector<std::string> &band_label, const helios::vec3 &position, const helios::vec3 &lookat, const CameraProperties &camera_properties, uint antialiasing_samples);
 
 
    void addRadiationCamera(const std::string &camera_label, const std::vector<std::string> &band_label, const helios::vec3 &position, const helios::SphericalCoord &viewing_direction, const CameraProperties &camera_properties,
                            uint antialiasing_samples);
 
 
 
    void setCameraSpectralResponse(const std::string &camera_label, const std::string &band_label, const std::string &global_data);
 
 
    void setCameraSpectralResponseFromLibrary(const std::string &camera_label, const std::string &camera_library_name);
 
 
    void addRadiationCameraFromLibrary(const std::string &camera_label, const std::string &library_camera_label, const helios::vec3 &position, const helios::vec3 &lookat, uint antialiasing_samples);
 
 
    void addRadiationCameraFromLibrary(const std::string &camera_label, const std::string &library_camera_label, const helios::vec3 &position, const helios::vec3 &lookat, uint antialiasing_samples, const std::vector<std::string> &band_labels);
 
 
    void setCameraPosition(const std::string &camera_label, const helios::vec3 &position);
 
 
    helios::vec3 getCameraPosition(const std::string &camera_label) const;
 
 
    void setCameraLookat(const std::string &camera_label, const helios::vec3 &lookat);
 
 
    helios::vec3 getCameraLookat(const std::string &camera_label) const;
 
 
    void setCameraOrientation(const std::string &camera_label, const helios::vec3 &direction);
 
 
    void setCameraOrientation(const std::string &camera_label, const helios::SphericalCoord &direction);
 
 
    helios::SphericalCoord getCameraOrientation(const std::string &camera_label) const;
 
 
    CameraProperties getCameraParameters(const std::string &camera_label) const;
 
 
    void updateCameraParameters(const std::string &camera_label, const CameraProperties &camera_properties);
 
 
    std::vector<std::string> getAllCameraLabels();
 
 
    void enableCameraMetadata(const std::string &camera_label);
 
 
    void enableCameraMetadata(const std::vector<std::string> &camera_labels);
 
 
    CameraMetadata getCameraMetadata(const std::string &camera_label) const;
 
 
    void setCameraMetadata(const std::string &camera_label, const CameraMetadata &metadata);
 
 
    void enableCameraLensFlare(const std::string &camera_label);
 
 
    void disableCameraLensFlare(const std::string &camera_label);
 
 
    [[nodiscard]] bool isCameraLensFlareEnabled(const std::string &camera_label) const;
 
 
    void setCameraLensFlareProperties(const std::string &camera_label, const LensFlareProperties &properties);
 
 
    [[nodiscard]] LensFlareProperties getCameraLensFlareProperties(const std::string &camera_label) const;
 
 
    void updateGeometry();
 
 
    void updateGeometry(const std::vector<uint> &UUIDs);
 
 
    void runBand(const std::string &label);
 
 
    void runBand(const std::vector<std::string> &labels);
 
    std::vector<float> getTotalAbsorbedFlux();
 
    float getSkyEnergy();
 
 
    float calculateGtheta(helios::Context *context, helios::vec3 view_direction);
 
    void setCameraCalibration(CameraCalibration *CameraCalibration);
 
 
    void updateCameraResponse(const std::string &orginalcameralabel, const std::vector<std::string> &sourcelabels_raw, const std::vector<std::string> &cameraresponselabels, helios::vec2 &wavelengthrange,
                              const std::vector<std::vector<float>> &truevalues, const std::string &calibratedmark);
 
 
    float getCameraResponseScale(const std::string &orginalcameralabel, const std::vector<std::string> &cameraresponselabels, const std::vector<std::string> &bandlabels, const std::vector<std::string> &sourcelabels, helios::vec2 &wavelengthrange,
                                 const std::vector<std::vector<float>> &truevalues);
 
 
    void runRadiationImaging(const std::string &cameralabel, const std::vector<std::string> &sourcelabels, const std::vector<std::string> &bandlabels, const std::vector<std::string> &cameraresponselabels, helios::vec2 wavelengthrange,
                             float fluxscale = 1, float diffusefactor = 0.0005, uint scatteringdepth = 4);
 
 
    void runRadiationImaging(const std::vector<std::string> &cameralabels, const std::vector<std::string> &sourcelabels, const std::vector<std::string> &bandlabels, const std::vector<std::string> &cameraresponselabels, helios::vec2 wavelengthrange,
                             float fluxscale = 1, float diffusefactor = 0.0005, uint scatteringdepth = 4);
 
 
    void applyCameraImageCorrections(const std::string &cameralabel, const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label, float saturation_adjustment = 1.f, float brightness_adjustment = 1.f,
                                     float contrast_adjustment = 1.f);
 
    [[deprecated("Use applyCameraImageCorrections() instead")]]
    void applyImageProcessingPipeline(const std::string &cameralabel, const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label, float saturation_adjustment = 1.f, float brightness_adjustment = 1.f,
                                      float contrast_adjustment = 1.f, float gain_adjustment = 1.f);
 
 
    void applyCameraColorCorrectionMatrix(const std::string &camera_label, const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label, const std::string &ccm_file_path);
 
 
 
    std::string writeCameraImage(const std::string &camera, const std::vector<std::string> &bands, const std::string &imagefile_base, const std::string &image_path = "./", int frame = -1, float flux_to_pixel_conversion = 1.f);
 
 
    std::string writeNormCameraImage(const std::string &camera, const std::vector<std::string> &bands, const std::string &imagefile_base, const std::string &image_path = "./", int frame = -1);
 
 
    void writeCameraImageData(const std::string &camera, const std::string &band, const std::string &imagefile_base, const std::string &image_path = "./", int frame = -1);
 
 
    void writePrimitiveDataLabelMap(const std::string &cameralabel, const std::string &primitive_data_label, const std::string &imagefile_base, const std::string &image_path = "./", int frame = -1, float padvalue = NAN);
 
 
    void writeObjectDataLabelMap(const std::string &cameralabel, const std::string &object_data_label, const std::string &imagefile_base, const std::string &image_path = "./", int frame = -1, float padvalue = NAN);
 
 
    void writeDepthImageData(const std::string &cameralabel, const std::string &imagefile_base, const std::string &image_path = "./", int frame = -1);
 
 
    void writeNormDepthImage(const std::string &cameralabel, const std::string &imagefile_base, float max_depth, const std::string &image_path = "./", int frame = -1);
 
 
    [[deprecated]]
    void writeImageBoundingBoxes(const std::string &cameralabel, const std::string &primitive_data_label, uint object_class_ID, const std::string &imagefile_base, const std::string &image_path = "./", bool append_label_file = false, int frame = -1);
 
 
    [[deprecated]]
    void writeImageBoundingBoxes_ObjectData(const std::string &cameralabel, const std::string &object_data_label, uint object_class_ID, const std::string &imagefile_base, const std::string &image_path = "./", bool append_label_file = false,
                                            int frame = -1);
 
 
    void writeImageBoundingBoxes(const std::string &cameralabel, const std::string &primitive_data_label, const uint &object_class_ID, const std::string &image_file, const std::string &classes_txt_file = "classes.txt",
                                 const std::string &image_path = "./");
 
 
    void writeImageBoundingBoxes(const std::string &cameralabel, const std::vector<std::string> &primitive_data_label, const std::vector<uint> &object_class_ID, const std::string &image_file, const std::string &classes_txt_file = "classes.txt",
                                 const std::string &image_path = "./");
 
 
    void writeImageBoundingBoxes_ObjectData(const std::string &cameralabel, const std::string &object_data_label, const uint &object_class_ID, const std::string &image_file, const std::string &classes_txt_file = "classes.txt",
                                            const std::string &image_path = "./");
 
 
    void writeImageBoundingBoxes_ObjectData(const std::string &cameralabel, const std::vector<std::string> &object_data_label, const std::vector<uint> &object_class_ID, const std::string &image_file,
                                            const std::string &classes_txt_file = "classes.txt", const std::string &image_path = "./");
 
 
    void writeImageSegmentationMasks(const std::string &cameralabel, const std::string &primitive_data_label, const uint &object_class_ID, const std::string &json_filename, const std::string &image_file,
                                     const std::vector<std::string> &data_attribute_labels = {}, bool append_file = false);
 
 
    void writeImageSegmentationMasks(const std::string &cameralabel, const std::vector<std::string> &primitive_data_label, const std::vector<uint> &object_class_ID, const std::string &json_filename, const std::string &image_file,
                                     const std::vector<std::string> &data_attribute_labels = {}, bool append_file = false);
 
 
    void writeImageSegmentationMasks_ObjectData(const std::string &cameralabel, const std::string &object_data_label, const uint &object_class_ID, const std::string &json_filename, const std::string &image_file,
                                                const std::vector<std::string> &data_attribute_labels = {}, bool append_file = false);
 
 
    void writeImageSegmentationMasks_ObjectData(const std::string &cameralabel, const std::vector<std::string> &object_data_label, const std::vector<uint> &object_class_ID, const std::string &json_filename, const std::string &image_file,
                                                const std::vector<std::string> &data_attribute_labels = {}, bool append_file = false);
 
private:
    // Helper functions for COCO JSON handling
    std::pair<nlohmann::json, int> initializeCOCOJsonWithImageId(const std::string &filename, bool append_file, const std::string &cameralabel, const helios::int2 &camera_resolution, const std::string &image_file);
    nlohmann::json initializeCOCOJson(const std::string &filename, bool append_file, const std::string &cameralabel, const helios::int2 &camera_resolution, const std::string &image_file);
    void addCategoryToCOCO(nlohmann::json &coco_json, const std::vector<uint> &object_class_ID, const std::vector<std::string> &category_name);
    void writeCOCOJson(const nlohmann::json &coco_json, const std::string &filename);
 
    // Helper functions for mask generation and boundary tracing
    std::map<int, std::vector<std::vector<bool>>> generateLabelMasks(const std::string &cameralabel, const std::string &data_label, bool use_object_data);
    std::pair<int, int> findStartingBoundaryPixel(const std::vector<std::vector<bool>> &mask, const helios::int2 &camera_resolution);
    std::vector<std::pair<int, int>> traceBoundaryMoore(const std::vector<std::vector<bool>> &mask, int start_x, int start_y, const helios::int2 &camera_resolution);
    std::vector<std::pair<int, int>> traceBoundarySimple(const std::vector<std::vector<bool>> &mask, int start_x, int start_y, const helios::int2 &camera_resolution);
    std::vector<std::map<std::string, std::vector<float>>> generateAnnotationsFromMasks(const std::map<int, std::vector<std::vector<bool>>> &label_masks, uint object_class_ID, const helios::int2 &camera_resolution, int image_id);
 
    // Helper functions for camera metadata export
    std::string detectLightingType() const;
    float calculateCameraTiltAngle(const helios::vec3 &position, const helios::vec3 &lookat) const;
    void computeAgronomicProperties(const std::string &camera_label, CameraMetadata::AgronomicProperties &props) const;
    void populateCameraMetadata(const std::string &camera_label, CameraMetadata &metadata) const;
    std::string writeCameraMetadataFile(const std::string &camera_label, const std::string &output_path = "./") const;
 
public:
 
    void setPadValue(const std::string &cameralabel, const std::vector<std::string> &bandlabels, const std::vector<float> &padvalues);
 
 
    void calibrateCamera(const std::string &orginalcameralabel, const std::vector<std::string> &sourcelabels, const std::vector<std::string> &cameraresponselabels, const std::vector<std::string> &bandlabels, const float scalefactor,
                         const std::vector<std::vector<float>> &truevalues, const std::string &calibratedmark);
 
 
    void calibrateCamera(const std::string &originalcameralabel, const float scalefactor, const std::vector<std::vector<float>> &truevalues, const std::string &calibratedmark);
 
    enum class ColorCorrectionAlgorithm {
        DIAGONAL_ONLY, 
        MATRIX_3X3_AUTO, 
        MATRIX_3X3_FORCE 
    };
 
 
    std::string autoCalibrateCameraImage(const std::string &camera_label, const std::string &red_band_label, const std::string &green_band_label, const std::string &blue_band_label, const std::string &output_file_path,
                                         bool print_quality_report = false, ColorCorrectionAlgorithm algorithm = ColorCorrectionAlgorithm::MATRIX_3X3_AUTO, const std::string &ccm_export_file_path = "");
 
    void exportColorCorrectionMatrixXML(const std::string &file_path, const std::string &camera_label, const std::vector<std::vector<float>> &matrix, const std::string &source_image_path, const std::string &colorboard_type, float average_delta_e);
 
    std::vector<std::vector<float>> loadColorCorrectionMatrixXML(const std::string &file_path, std::string &camera_label_out);
 
    std::vector<float> getCameraPixelData(const std::string &camera_label, const std::string &band_label);
 
    void setCameraPixelData(const std::string &camera_label, const std::string &band_label, const std::vector<float> &pixel_data);
 
 
    void queryBackendGPUMemory() const;
 
 
    size_t testBuildGeometryData();
 
    helios::RayTracingBackend *getBackend();
 
    helios::RayTracingGeometry &getGeometryData();
 
    helios::RayTracingMaterial &getMaterialData();
 
    std::vector<helios::RayTracingSource> &getSourceData();
 
    void testBuildAllBackendData();
 
protected:
    bool message_flag;
 
    uint specular_reflection_mode = 0;
 
    helios::Context *context;
 
    CameraCalibration *cameracalibration;
    bool calibration_flag = false;
 
    std::string getCurrentDateTime();
 
    std::vector<uint> primitiveID;
 
    std::vector<uint> context_UUIDs;
 
    std::unordered_map<uint, size_t> uuid_to_position;
 
    std::vector<uint> position_to_uuid;
 
    // --- Radiation Band Variables --- //
 
    std::map<std::string, RadiationBand> radiation_bands;
 
    std::vector<helios::vec2> global_diffuse_spectrum;
 
    std::string global_diffuse_spectrum_label = "none";
 
    uint64_t global_diffuse_spectrum_version = 0;
 
    std::map<std::string, bool> scattering_iterations_needed;
 
    // --- radiation source variables --- //
 
    std::vector<RadiationSource> radiation_sources;
 
    // --- Camera Variables --- //
 
    std::map<std::string, RadiationCamera> cameras;
 
    std::map<std::string, CameraMetadata> camera_metadata;
 
    std::set<std::string> metadata_enabled_cameras;
 
    std::map<std::string, std::vector<uint>> spectral_reflectivity_data;
 
    std::map<std::string, std::vector<uint>> spectral_transmissivity_data;
 
    struct SpectrumInterpolationConfig {
        std::unordered_set<uint> primitive_UUIDs; // Primitive UUIDs to apply this config to
        std::unordered_set<uint> object_IDs; // Object IDs to apply this config to
        std::vector<std::string> spectra_labels; // Global data labels for spectra
        std::vector<float> mapping_values; // Values corresponding to each spectrum
        std::string query_data_label; // Primitive/object data to query (e.g., "age")
        std::string target_data_label; // Primitive data to set (e.g., "reflectivity_spectrum")
    };
 
    std::vector<SpectrumInterpolationConfig> spectrum_interpolation_configs;
 
    std::vector<helios::vec2> generateGaussianCameraResponse(float FWHM, float mu, float centrawavelength, const helios::int2 &wavebandrange);
 
    // --- Constants and Defaults --- //
 
    float sigma = 5.6703744E-8;
 
    float rho_default;
 
    float tau_default;
 
    float eps_default;
 
    float kappa_default;
 
    float sigmas_default;
 
    float temperature_default;
 
    size_t directRayCount_default;
 
    size_t diffuseRayCount_default;
 
    float diffuseFlux_default;
 
    float minScatterEnergy_default;
 
    uint scatteringDepth_default;
 
    // --- Functions --- //
 
    void initializeOptiX();
 
 
    void updateRadiativeProperties();
 
 
    std::vector<float> updateAtmosphericSkyModel(const std::vector<std::string> &band_labels, const RadiationCamera &camera);
 
 
    void updatePragueParametersForGeneralDiffuse(const std::vector<std::string> &band_labels);
 
 
    std::vector<helios::vec2> loadSpectralData(const std::string &global_data_label) const;
 
 
 
    void buildLightModelGeometry(uint sourceID);
 
    void buildCameraModelGeometry(const std::string &cameralabel);
 
    void updateLightModelPosition(uint sourceID, const helios::vec3 &delta_position);
 
    void updateCameraModelPosition(const std::string &cameralabel);
 
 
    helios::RayTracingLaunchParams buildCameraLaunchParams(const RadiationCamera &camera, uint camera_id, uint antialiasing_samples, const helios::int2 &tile_resolution, const helios::int2 &tile_offset);
 
 
    std::vector<CameraTile> computeCameraTiles(const RadiationCamera &camera, size_t maxRays);
 
 
    void buildGeometryData();
 
 
    void buildTextureData();
 
    void buildUUIDMapping();
 
    void buildMaterialData();
 
    void buildSourceData();
 
    std::map<uint, std::vector<uint>> source_model_UUIDs;
    std::map<std::string, std::vector<uint>> camera_model_UUIDs;
 
    /* Phase 1: Backend abstraction layer (for incremental OptiX code replacement) */
 
    std::unique_ptr<helios::RayTracingBackend> backend;
 
    helios::RayTracingGeometry geometry_data;
 
    helios::RayTracingMaterial material_data;
 
    std::vector<helios::RayTracingSource> source_data;
 
 
    bool isgeometryinitialized;
 
    helios::vec2 periodic_flag;
 
    bool radiativepropertiesneedupdate = true;
 
    std::vector<bool> isbandpropertyinitialized;
 
    bool islightvisualizationenabled = false;
    bool iscameravisualizationenabled = false;
 
    std::vector<std::string> output_prim_data;
 
    std::vector<std::string> spectral_library_files;
 
    // Helper methods for Prague Sky Model spectral integration from Context
    float integrateOverResponse(const std::vector<float> &wavelengths, const std::vector<float> &values, const std::vector<helios::vec2> &camera_response) const;
 
    float weightedAverageOverResponse(const std::vector<float> &wavelengths, const std::vector<float> &param_values, const std::vector<float> &weight_values, const std::vector<helios::vec2> &camera_response) const;
 
    float computeAngularNormalization(float circ_str, float circ_width, float horiz_bright) const;
};
 
#endif