global.h

Go to the documentation of this file.

 
#ifndef HELIOS_GLOBAL
#define HELIOS_GLOBAL
 
#ifndef M_PI
#define M_PI 3.14159265358979323846
#endif
 
constexpr float PI_F = 3.14159265358979323846f;
 
#include <algorithm>
#include <array>
#include <cassert>
#include <chrono>
#include <cmath>
#include <cstdio>
#include <cstdlib>
#include <cstring>
#include <ctime>
#include <exception>
#include <filesystem>
#include <fstream>
#include <functional>
#include <iomanip>
#include <iostream>
#include <map>
#include <memory>
#include <random>
#include <set>
#include <sstream>
#include <stdexcept>
#include <thread>
#include <type_traits>
#include <unordered_map>
#include <vector>
 
#ifdef USE_OPENMP
#include <omp.h>
#endif
 
typedef unsigned int uint;
 
template<typename To, typename From>
constexpr To scast(From &&v) noexcept {
    return static_cast<To>(std::forward<From>(v));
}
 
 
#include "helios_vector_types.h"
#include "image_metadata.h"
 
// pugi XML parser
#include "pugixml.hpp"
 
// Standard library for file path resolution
#include <filesystem>
 
// Thread synchronization
#include <mutex>
 
// *** Groups *** //
 
 
 
 
namespace helios {
 
 
    void helios_runtime_error(const std::string &error_message);
 
    //--------------------- HELPER FUNCTIONS -----------------------------------//
 
 
    void makeRotationMatrix(float rotation, const char *axis, float (&transform)[16]);
 
 
    void makeRotationMatrix(float rotation, const helios::vec3 &axis, float (&transform)[16]);
 
 
    void makeRotationMatrix(float rotation, const helios::vec3 &origin, const helios::vec3 &axis, float (&transform)[16]);
 
 
    void makeTranslationMatrix(const helios::vec3 &translation, float (&transform)[16]);
 
 
    void makeScaleMatrix(const helios::vec3 &scale, float (&transform)[16]);
 
 
    void makeScaleMatrix(const helios::vec3 &scale, const helios::vec3 &point, float (&transform)[16]);
 
 
    void matmult(const float ML[16], const float MR[16], float (&T)[16]);
 
 
    void vecmult(const float M[16], const float v[3], float (&result)[3]);
 
 
    void vecmult(const float M[16], const helios::vec3 &v3, helios::vec3 &result);
 
 
    void makeIdentityMatrix(float (&T)[16]);
 
 
    [[nodiscard]] float deg2rad(float deg);
 
 
    [[nodiscard]] float rad2deg(float rad);
 
 
    [[nodiscard]] float atan2_2pi(float y, float x);
 
 
    [[nodiscard]] SphericalCoord cart2sphere(const vec3 &Cartesian);
 
 
    [[nodiscard]] vec3 sphere2cart(const SphericalCoord &Spherical);
 
 
    [[nodiscard]] vec2 string2vec2(const char *str);
 
 
    [[nodiscard]] vec3 string2vec3(const char *str);
 
 
    [[nodiscard]] vec4 string2vec4(const char *str);
 
 
    [[nodiscard]] int2 string2int2(const char *str);
 
 
    [[nodiscard]] int3 string2int3(const char *str);
 
 
    [[nodiscard]] int4 string2int4(const char *str);
 
 
    bool parse_float(const std::string &input_string, float &converted_float);
 
 
    bool parse_double(const std::string &input_string, double &converted_double);
 
 
    bool parse_int(const std::string &input_string, int &converted_int);
 
 
    bool parse_int2(const std::string &input_string, int2 &converted_int2);
 
 
    bool parse_int3(const std::string &input_string, int3 &converted_int3);
 
 
    bool parse_uint(const std::string &input_string, uint &converted_uint);
 
 
    bool parse_vec2(const std::string &input_string, vec2 &converted_vec2);
 
 
    bool parse_vec3(const std::string &input_string, vec3 &converted_vec3);
 
 
    bool parse_RGBcolor(const std::string &input_string, RGBcolor &converted_rgb);
 
 
    bool open_xml_file(const std::string &xml_file, pugi::xml_document &xmldoc, std::string &error_string);
 
 
    [[nodiscard]] int parse_xml_tag_int(const pugi::xml_node &node, const std::string &tag, const std::string &calling_function);
 
 
    [[nodiscard]] float parse_xml_tag_float(const pugi::xml_node &node, const std::string &tag, const std::string &calling_function);
 
 
    [[nodiscard]] vec2 parse_xml_tag_vec2(const pugi::xml_node &node, const std::string &tag, const std::string &calling_function);
 
 
    [[nodiscard]] vec3 parse_xml_tag_vec3(const pugi::xml_node &node, const std::string &tag, const std::string &calling_function);
 
 
    [[nodiscard]] std::string parse_xml_tag_string(const pugi::xml_node &node, const std::string &tag, const std::string &calling_function);
 
 
    [[nodiscard]] RGBAcolor string2RGBcolor(const char *str);
 
 
    [[nodiscard]] std::string deblank(const char *input);
 
 
    [[nodiscard]] std::string deblank(const std::string &input);
 
 
    [[nodiscard]] std::string trim_whitespace(const std::string &input);
 
 
    [[nodiscard]] std::vector<std::string> separate_string_by_delimiter(const std::string &inputstring, const std::string &delimiter);
 
 
    template<typename anytype>
    [[nodiscard]] anytype clamp(anytype value, anytype min, anytype max) {
        static_assert(std::is_same_v<anytype, int> || std::is_same_v<anytype, uint> || std::is_same_v<anytype, float> || std::is_same_v<anytype, double> || std::is_same_v<anytype, char> || std::is_same_v<anytype, unsigned char>,
                      "helios::clamp() was called with an unsupported type.");
        if (value < min) {
            value = min;
        } else if (value > max) {
            value = max;
        }
        return value;
    }
 
 
    [[nodiscard]] float sum(const std::vector<float> &vect);
 
 
    [[nodiscard]] float mean(const std::vector<float> &vect);
 
 
    [[nodiscard]] float min(const std::vector<float> &vect);
 
 
    [[nodiscard]] int min(const std::vector<int> &vect);
 
 
    [[nodiscard]] vec3 min(const std::vector<vec3> &vect);
 
 
    [[nodiscard]] float max(const std::vector<float> &vect);
 
 
    [[nodiscard]] int max(const std::vector<int> &vect);
 
 
    [[nodiscard]] vec3 max(const std::vector<vec3> &vect);
 
 
    [[nodiscard]] float stdev(const std::vector<float> &vect);
 
 
    [[nodiscard]] float median(std::vector<float> vect);
 
 
    template<typename anytype>
    typename std::enable_if<std::is_default_constructible<anytype>::value>::type resize_vector(std::vector<std::vector<anytype>> &vec, size_t Nx, size_t Ny) {
        vec.assign(Ny, std::vector<anytype>(Nx));
    }
 
 
    template<typename anytype>
    typename std::enable_if<std::is_default_constructible<anytype>::value>::type resize_vector(std::vector<std::vector<std::vector<anytype>>> &vec, size_t Nx, size_t Ny, size_t Nz) {
        vec.assign(Nz, std::vector<std::vector<anytype>>(Ny, std::vector<anytype>(Nx)));
    }
 
 
    template<typename anytype>
    typename std::enable_if<std::is_default_constructible<anytype>::value>::type resize_vector(std::vector<std::vector<std::vector<std::vector<anytype>>>> &vec, size_t Nx, size_t Ny, size_t Nz, size_t Nw) {
        vec.assign(Nw, std::vector<std::vector<std::vector<anytype>>>(Nz, std::vector<std::vector<anytype>>(Ny, std::vector<anytype>(Nx))));
    }
 
 
    [[nodiscard]] RGBcolor blend(const RGBcolor &color0, const RGBcolor &color1, float weight);
 
 
    [[nodiscard]] RGBAcolor blend(const RGBAcolor &color0, const RGBAcolor &color1, float weight);
 
 
    [[nodiscard]] vec3 rotatePoint(const vec3 &position, const SphericalCoord &rotation);
 
 
    [[nodiscard]] vec3 rotatePoint(const vec3 &position, float theta, float phi);
 
 
    [[nodiscard]] vec3 rotatePointAboutLine(const vec3 &point, const vec3 &line_base, const vec3 &line_direction, float theta);
 
 
    [[nodiscard]] float calculateTriangleArea(const vec3 &v0, const vec3 &v1, const vec3 &v2);
 
 
    [[nodiscard]] Date CalendarDay(int Julian_day, int year);
 
 
    [[nodiscard]] int JulianDay(int day, int month, int year);
 
 
    [[nodiscard]] int JulianDay(const Date &date);
 
 
    [[nodiscard]] float randu();
 
 
    [[nodiscard]] int randu(int imin, int imax);
 
 
    [[nodiscard]] float acos_safe(float x);
 
 
    [[nodiscard]] float asin_safe(float x);
 
 
    template<typename T>
    T powi(T base, std::size_t exp) {
        static_assert(std::is_same_v<T, uint> || std::is_same_v<T, int> || std::is_same_v<T, float> || std::is_same_v<T, double> || std::is_same_v<T, char> || std::is_same_v<T, size_t>, "helios::powi() was called with an unsupported type.");
        T result = static_cast<T>(1);
        while (exp > 0) {
            // If the low bit is set, multiply result by current base
            if (exp & 1) {
                result *= base;
            }
            // Square the base for the next bit
            base *= base;
            // Shift off the processed bit
            exp >>= 1;
        }
        return result;
    }
 
 
    [[nodiscard]] bool lineIntersection(const vec2 &p1, const vec2 &q1, const vec2 &p2, const vec2 &q2);
 
 
    [[nodiscard]] bool pointOnSegment(const vec2 &point, const vec2 &seg_start, const vec2 &seg_end);
 
 
    [[nodiscard]] bool pointInPolygon(const vec2 &point, const std::vector<vec2> &polygon_verts);
 
 
    struct Timer {
    public:
        Timer() {
            running = false;
        }
 
        void tic() {
            timer_start = std::chrono::high_resolution_clock::now();
            running = true;
        };
 
        double toc() const {
            return toc("");
        }
 
 
        double toc(const char *message) const {
            if (!running) {
                std::cerr << "ERROR (Timer): You must call `tic' before calling `toc'. Ignoring call to `toc'..." << std::endl;
                return 0;
            }
 
            auto timer_end = std::chrono::high_resolution_clock::now();
            ;
            double duration = std::chrono::duration<double>(timer_end - timer_start).count();
            if (strcmp(message, "mute") != 0) {
                std::cout << "Elapsed time is " << duration << " seconds: " << message << std::endl;
            }
            return duration;
        }
 
    private:
        bool running;
        std::chrono::high_resolution_clock::time_point timer_start;
    };
 
 
    class ProgressBar {
    private:
        size_t total_steps;
        size_t current_step;
        int bar_width;
        bool enabled;
        std::string message;
        std::function<void(float, const std::string&)> callback;
 
    public:
 
        ProgressBar(size_t total, int width = 50, bool enable = true, const std::string &progress_message = "Progress");
 
        void update();
 
 
        void update(size_t step_number);
 
        void finish();
 
 
        void setEnabled(bool enable);
 
 
        [[nodiscard]] bool isEnabled() const;
 
        void disableMessages();
 
 
        void setCallback(std::function<void(float, const std::string&)> cb);
    };
 
 
    void wait(float seconds);
 
 
    [[nodiscard]] bool PNGHasAlpha(const char *filename);
 
 
    [[nodiscard]] std::vector<std::vector<bool>> readPNGAlpha(const std::string &filename);
 
 
    void readPNG(const std::string &filename, uint &width, uint &height, std::vector<helios::RGBAcolor> &pixel_data);
 
 
    void writePNG(const std::string &filename, uint width, uint height, const std::vector<helios::RGBAcolor> &pixel_data);
 
 
    void writePNG(const std::string &filename, uint width, uint height, const std::vector<unsigned char> &pixel_data);
 
 
    void readJPEG(const std::string &filename, uint &width, uint &height, std::vector<helios::RGBcolor> &pixel_data);
 
 
    [[nodiscard]] helios::int2 getImageResolutionJPEG(const std::string &filename);
 
 
    void writeJPEG(const std::string &filename, uint width, uint height, const std::vector<helios::RGBcolor> &pixel_data);
 
 
    void writeJPEG(const std::string &filename, uint width, uint height, const std::vector<unsigned char> &pixel_data);
 
 
    void writeJPEG(const std::string &filename, uint width, uint height, const std::vector<helios::RGBcolor> &pixel_data, const helios::ImageEXIFData &metadata);
 
 
    void writeEXR(const std::string &filename, uint width, uint height, const std::vector<float> &pixel_data, const std::string &channel_name = "Y");
 
 
    void writeEXR(const std::string &filename, uint width, uint height, const std::vector<std::vector<float>> &channel_data, const std::vector<std::string> &channel_names);
 
 
    template<typename T>
    [[nodiscard]] std::vector<T> flatten(const std::vector<std::vector<T>> &vec) {
        std::vector<T> result;
        for (const auto &row: vec) {
            result.insert(result.end(), row.begin(), row.end());
        }
        return result;
    }
 
 
    template<typename T>
    [[nodiscard]] std::vector<T> flatten(const std::vector<std::vector<std::vector<T>>> &vec) {
        std::vector<T> result;
        for (const auto &matrix: vec) {
            for (const auto &row: matrix) {
                result.insert(result.end(), row.begin(), row.end());
            }
        }
        return result;
    }
 
 
    template<typename T>
    [[nodiscard]] std::vector<T> flatten(const std::vector<std::vector<std::vector<std::vector<T>>>> &vec) {
        std::vector<T> result;
        for (const auto &tensor: vec) {
            for (const auto &matrix: tensor) {
                for (const auto &row: matrix) {
                    result.insert(result.end(), row.begin(), row.end());
                }
            }
        }
        return result;
    }
 
 
    [[nodiscard]] helios::vec3 spline_interp3(float u, const vec3 &x_start, const vec3 &tan_start, const vec3 &x_end, const vec3 &tan_end);
 
 
    [[nodiscard]] float XMLloadfloat(pugi::xml_node node, const char *field);
 
 
    [[nodiscard]] int XMLloadint(pugi::xml_node node, const char *field);
 
 
    [[nodiscard]] std::string XMLloadstring(pugi::xml_node node, const char *field);
 
 
    [[nodiscard]] helios::vec2 XMLloadvec2(pugi::xml_node node, const char *field);
 
 
    [[nodiscard]] helios::vec3 XMLloadvec3(pugi::xml_node node, const char *field);
 
 
    [[nodiscard]] helios::vec4 XMLloadvec4(pugi::xml_node node, const char *field);
 
 
    [[nodiscard]] helios::int2 XMLloadint2(pugi::xml_node node, const char *field);
 
 
    [[nodiscard]] helios::int3 XMLloadint3(pugi::xml_node node, const char *field);
 
 
    [[nodiscard]] helios::int4 XMLloadint4(pugi::xml_node node, const char *field);
 
 
    [[nodiscard]] helios::RGBcolor XMLloadrgb(pugi::xml_node node, const char *field);
 
 
    [[nodiscard]] helios::RGBAcolor XMLloadrgba(pugi::xml_node node, const char *field);
 
    // Forward declaration for fzero()
    class WarningAggregator;
 
 
    [[nodiscard]] float fzero(float (*function)(float value, std::vector<float> &variables, const void *parameters), std::vector<float> &variables, const void *parameters, float init_guess, float err_tol = 0.0001f, int max_iterations = 100,
                              WarningAggregator *warnings = nullptr);
 
 
    [[nodiscard]] float fzero(float (*function)(float value, std::vector<float> &variables, const void *parameters), std::vector<float> &variables, const void *parameters, float init_guess, bool &converged, float err_tol = 0.0001f,
                              int max_iterations = 100);
 
 
    [[nodiscard]] float interp1(const std::vector<helios::vec2> &points, float x);
 
 
    [[nodiscard]] float point_distance(const helios::vec3 &p1, const helios::vec3 &p2);
 
 
    [[nodiscard]] std::vector<float> linspace(float start, float end, int num);
 
 
    [[nodiscard]] std::vector<vec2> linspace(const vec2 &start, const vec2 &end, int num);
 
 
    [[nodiscard]] std::vector<vec3> linspace(const vec3 &start, const vec3 &end, int num);
 
 
    [[nodiscard]] std::vector<vec4> linspace(const vec4 &start, const vec4 &end, int num);
 
 
    [[nodiscard]] std::string getFileExtension(const std::string &filepath);
 
 
    [[nodiscard]] std::string getFileStem(const std::string &filepath);
 
 
    [[nodiscard]] std::string getFileName(const std::string &filepath);
 
 
    [[nodiscard]] std::string getFilePath(const std::string &filepath, bool trailingslash = true);
 
 
    [[nodiscard]] bool validateOutputPath(std::string &output_directory, const std::vector<std::string> &allowable_file_extensions = {});
 
 
    [[nodiscard]] bool isDirectoryPath(const std::string &path);
 
    //--------------------- ASSET PATH RESOLUTION -----------------------------------//
 
 
    [[nodiscard]] std::filesystem::path resolveAssetPath(const std::string &relativePath);
 
 
    [[nodiscard]] std::filesystem::path resolvePluginAsset(const std::string &pluginName, const std::string &assetPath);
 
 
    [[nodiscard]] std::filesystem::path tryResolvePluginAsset(const std::string &pluginName, const std::string &assetPath);
 
 
    [[nodiscard]] std::filesystem::path resolveFilePath(const std::string &filename);
 
 
    [[nodiscard]] std::filesystem::path tryResolveFilePath(const std::string &filename);
 
 
    [[nodiscard]] std::filesystem::path resolveSpectraPath(const std::string &spectraFile);
 
 
    [[nodiscard]] bool validateAssetPath(const std::filesystem::path &assetPath);
 
 
    [[nodiscard]] std::filesystem::path findProjectRoot(const std::filesystem::path &startPath = std::filesystem::current_path());
 
 
    [[nodiscard]] std::filesystem::path resolveProjectFile(const std::string &relativePath);
 
 
    [[nodiscard]] std::vector<float> importVectorFromFile(const std::string &filepath);
 
 
    [[nodiscard]] float sample_Beta_distribution(float mu, float nu, std::minstd_rand0 *generator);
 
    [[nodiscard]] float sample_ellipsoidal_azimuth(float e, float phi0_degrees, std::minstd_rand0 *generator);
 
    inline std::vector<float> &operator+=(std::vector<float> &lhs, const std::vector<float> &rhs) {
        // Make sure vectors have the same size
        if (lhs.size() != rhs.size()) {
            throw std::invalid_argument("Vector sizes must match for element-wise addition");
        }
 
        // Perform element-by-element addition
        for (size_t i = 0; i < lhs.size(); ++i) {
            lhs[i] += rhs[i];
        }
 
        return lhs;
    }
 
    inline std::vector<float> operator+(const std::vector<float> &vector1, const std::vector<float> &vector2) {
        if (vector1.size() != vector2.size()) {
            throw std::invalid_argument("Vector sizes must match for element-wise addition");
        }
 
        std::vector<float> result(vector1.size());
        for (std::size_t i = 0; i < vector1.size(); ++i) {
            result[i] = vector1[i] + vector2[i];
        }
        return result;
    }
 
 
    inline std::vector<float> operator+(const std::vector<float> &vec, float scalar) {
        std::vector<float> result(vec.size());
        for (std::size_t i = 0; i < vec.size(); ++i) {
            result[i] = vec[i] + scalar;
        }
        return result;
    }
 
 
    inline std::vector<float> operator+(float scalar, const std::vector<float> &vec) {
        return vec + scalar;
    }
 
 
    inline std::vector<float> operator-(const std::vector<float> &vec, float scalar) {
        std::vector<float> result(vec.size());
        for (std::size_t i = 0; i < vec.size(); ++i) {
            result[i] = vec[i] - scalar;
        }
        return result;
    }
 
 
    inline std::vector<float> operator-(float scalar, const std::vector<float> &vec) {
        std::vector<float> result(vec.size());
        for (std::size_t i = 0; i < vec.size(); ++i) {
            result[i] = scalar - vec[i];
        }
        return result;
    }
 
 
    inline std::vector<float> operator*(const std::vector<float> &vec, float scalar) {
        std::vector<float> result(vec.size());
        for (std::size_t i = 0; i < vec.size(); ++i) {
            result[i] = vec[i] * scalar;
        }
        return result;
    }
 
 
    inline std::vector<float> operator*(float scalar, const std::vector<float> &vec) {
        return vec * scalar;
    }
 
 
    inline std::vector<float> operator/(const std::vector<float> &vec, float scalar) {
        std::vector<float> result(vec.size());
        for (std::size_t i = 0; i < vec.size(); ++i) {
            result[i] = vec[i] / scalar;
        }
        return result;
    }
 
 
    inline std::vector<float> operator/(float scalar, const std::vector<float> &vec) {
        std::vector<float> result(vec.size());
        for (std::size_t i = 0; i < vec.size(); ++i) {
            result[i] = scalar / vec[i];
        }
        return result;
    }
 
    struct PixelUVKey {
        std::vector<int> coords; // {x0,y0, x1,y1, …}
        bool operator==(PixelUVKey const &o) const noexcept {
            return coords == o.coords;
        }
    };
 
    struct PixelUVKeyHash {
        size_t operator()(PixelUVKey const &k) const noexcept {
            uint64_t h = 146527; // arbitrary seed
            for (int v: k.coords) {
                // mix in v
                h ^= uint64_t(v) + 0x9e3779b97f4a7c15ULL + (h << 6) + (h >> 2);
            }
            return size_t(h);
        }
    };
 
 
    struct capture_cerr {
        std::streambuf *old_buf;
        std::ostringstream captured_stream;
 
        capture_cerr() {
            old_buf = std::cerr.rdbuf(captured_stream.rdbuf());
        }
 
        ~capture_cerr() {
            std::cerr.rdbuf(old_buf);
        }
 
        std::string get_captured_output() const {
            return captured_stream.str();
        }
 
        bool has_output() const {
            return !captured_stream.str().empty();
        }
 
        void clear() {
            captured_stream.str("");
            captured_stream.clear();
        }
 
        size_t size() const {
            return captured_stream.str().size();
        }
    };
 
 
    struct capture_cout {
        std::streambuf *old_buf;
        std::ostringstream captured_stream;
 
        capture_cout() {
            old_buf = std::cout.rdbuf(captured_stream.rdbuf());
        }
 
        ~capture_cout() {
            std::cout.rdbuf(old_buf);
        }
 
        std::string get_captured_output() const {
            return captured_stream.str();
        }
 
        bool has_output() const {
            return !captured_stream.str().empty();
        }
 
        void clear() {
            captured_stream.str("");
            captured_stream.clear();
        }
 
        size_t size() const {
            return captured_stream.str().size();
        }
    };
 
 
 
    class WarningAggregator {
    public:
        WarningAggregator() = default;
 
 
        void addWarning(const std::string &category, const std::string &message);
 
 
        void report(std::ostream &stream = std::cerr, bool compact = false);
 
 
        [[nodiscard]] size_t getCount(const std::string &category) const;
 
        void clear();
 
 
        void setEnabled(bool enabled);
 
 
        [[nodiscard]] bool isEnabled() const;
 
    private:
        mutable std::mutex mutex_; 
        std::unordered_map<std::string, std::vector<std::string>> warnings_; 
        std::unordered_map<std::string, size_t> counts_; 
        bool enabled_ = true; 
        static constexpr size_t MAX_EXAMPLES = 100; 
    };
 
    extern SphericalCoord nullrotation;
    extern vec3 nullorigin;
} // namespace helios
 
#endif