[1.3.46] 2025-08-25

* Enhanced GitHub Actions workflows with new Windows GPU self-tests and improved CI configuration
* Upgraded documentation build system with improved cross-referencing and layout enhancements

## Context
- Implemented filesystem-based asset path resolution with fallback mechanisms for different installation types
- Added extensive new utility functions in `global.h` for asset management and path validation
- Added comprehensive test coverage for new asset resolution functionality in `Test_functions.h`

## Visualizer
- Fixed some potential segfaults that could occur when calling `Visualizer::plotInteractive()` or `Visualizer::plotUpdate()` in headless mode.

Author: bnbailey-psl

.github/workflows/linux_GPU_selftests.yaml

@@ -22,14 +22,42 @@ jobs:
           role-to-assume: ${{ secrets.OIDC_ROLE_ARN }}
           aws-region: us-west-2
       - run: |
-          aws ec2 start-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID }}
-          aws ec2 wait instance-running --instance-ids ${{ secrets.EC2_INSTANCE_ID }}
+          # Wait for instance to be in a state where it can be started (max 5 minutes)
+          echo "Waiting for instance to be in a startable state..."
+          timeout 300 bash -c '
+            while true; do
+              STATE=$(aws ec2 describe-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID_LINUX }} --query "Reservations[0].Instances[0].State.Name" --output text)
+              echo "Current instance state: $STATE"
+              if [[ "$STATE" == "stopped" || "$STATE" == "running" ]]; then
+                echo "Instance is in a startable state: $STATE"
+                break
+              fi
+              echo "Instance is in transitional state: $STATE. Waiting 10 seconds..."
+              sleep 10
+            done
+          ' || {
+            echo "Timeout waiting for instance to reach startable state"
+            exit 1
+          }
+          
+          # Only start if not already running
+          CURRENT_STATE=$(aws ec2 describe-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID_LINUX }} --query "Reservations[0].Instances[0].State.Name" --output text)
+          if [[ "$CURRENT_STATE" == "stopped" ]]; then
+            echo "Starting instance..."
+            aws ec2 start-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID_LINUX }}
+            aws ec2 wait instance-running --instance-ids ${{ secrets.EC2_INSTANCE_ID_LINUX }}
+          elif [[ "$CURRENT_STATE" == "running" ]]; then
+            echo "Instance is already running"
+          else
+            echo "Unexpected instance state: $CURRENT_STATE"
+            exit 1
+          fi
 
   run_samples_linux:
     # The CMake configure and build commands are platform agnostic and should work equally well on Windows or Mac.
     # You can convert this to a matrix build if you need cross-platform coverage.
     # See: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix
-    runs-on: [self-hosted]
+    runs-on: [self-hosted,helios]
     needs: start-gpu
     steps:
       - uses: actions/checkout@v3
@@ -53,5 +81,5 @@ jobs:
           role-to-assume: ${{ secrets.OIDC_ROLE_ARN }}
           aws-region: us-west-2
       - run: |
-          aws ec2 stop-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID }}
-          aws ec2 wait instance-stopped --instance-ids ${{ secrets.EC2_INSTANCE_ID }}
+          aws ec2 stop-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID_LINUX }}
+          aws ec2 wait instance-stopped --instance-ids ${{ secrets.EC2_INSTANCE_ID_LINUX }}

.github/workflows/windows_GPU_selftests.yaml

@@ -22,8 +22,36 @@ jobs:
           role-to-assume: ${{ secrets.OIDC_ROLE_ARN }}
           aws-region: us-west-2
       - run: |
-          aws ec2 start-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID_WIN }}
-          aws ec2 wait instance-running --instance-ids ${{ secrets.EC2_INSTANCE_ID_WIN }}
+          # Wait for instance to be in a state where it can be started (max 5 minutes)
+          echo "Waiting for instance to be in a startable state..."
+          timeout 300 bash -c '
+            while true; do
+              STATE=$(aws ec2 describe-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID_WIN }} --query "Reservations[0].Instances[0].State.Name" --output text)
+              echo "Current instance state: $STATE"
+              if [[ "$STATE" == "stopped" || "$STATE" == "running" ]]; then
+                echo "Instance is in a startable state: $STATE"
+                break
+              fi
+              echo "Instance is in transitional state: $STATE. Waiting 10 seconds..."
+              sleep 10
+            done
+          ' || {
+            echo "Timeout waiting for instance to reach startable state"
+            exit 1
+          }
+          
+          # Only start if not already running
+          CURRENT_STATE=$(aws ec2 describe-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID_WIN }} --query "Reservations[0].Instances[0].State.Name" --output text)
+          if [[ "$CURRENT_STATE" == "stopped" ]]; then
+            echo "Starting instance..."
+            aws ec2 start-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID_WIN }}
+            aws ec2 wait instance-running --instance-ids ${{ secrets.EC2_INSTANCE_ID_WIN }}
+          elif [[ "$CURRENT_STATE" == "running" ]]; then
+            echo "Instance is already running"
+          else
+            echo "Unexpected instance state: $CURRENT_STATE"
+            exit 1
+          fi
 
   run_samples_windows:
     runs-on: [self-hosted, Windows]

core/include/Context.h

@@ -2154,6 +2154,7 @@ namespace helios {
 
         void addTexture(const char *texture_file);
 
+
         bool doesTextureFileExist(const char *texture_file) const;
 
         bool validateTextureFileExtenstion(const char *texture_file) const;
@@ -2262,7 +2263,7 @@ namespace helios {
             OBJmaterial(const RGBcolor &a_color, std::string a_texture, uint a_materialID) : color{a_color}, texture{std::move(a_texture)}, materialID{a_materialID} {};
         };
 
-        static std::map<std::string, OBJmaterial> loadMTL(const std::string &filebase, const std::string &material_file);
+        std::map<std::string, OBJmaterial> loadMTL(const std::string &filebase, const std::string &material_file);
 
         void loadPData(pugi::xml_node p, uint UUID);
 
@@ -6129,6 +6130,8 @@ namespace helios {
          */
         void writePLY(const char *filename, const std::vector<uint> &UUIDs) const;
 
+        // Asset directory registration removed - now using HELIOS_BUILD resolution
+
         //! Load geometry contained in a Wavefront OBJ file (.obj). Model will be placed at the origin without any scaling or rotation applied.
         /**
          * \param[in] filename name of OBJ file
@@ -6199,6 +6202,16 @@ namespace helios {
          */
         void writeOBJ(const std::string &filename, const std::vector<uint> &UUIDs, const std::vector<std::string> &primitive_dat_fields, bool write_normals = false) const;
 
+        //------------ FILE PATH RESOLUTION ----------------//
+
+        //! Unified file path resolution for Context methods - resolves relative paths using build directory
+        /**
+         * \param[in] filename Relative or absolute file path to resolve
+         * \return std::filesystem::path Resolved absolute file path
+         * \note Uses HELIOS_BUILD environment variable or auto-detection to resolve relative paths
+         */
+        std::filesystem::path resolveFilePath(const std::string &filename) const;
+
         //! Set simulation date by day, month, year
         /**
          * \param[in] day Day of the month (1-31)

core/include/global.h

@@ -99,6 +99,9 @@ constexpr To scast(From &&v) noexcept {
 // pugi XML parser
 #include "pugixml.hpp"
 
+// Standard library for file path resolution
+#include <filesystem>
+
 // *** Groups *** //
 
 //! Miscellaneous helper functions
@@ -1115,6 +1118,70 @@ namespace helios {
      */
     [[nodiscard]] bool validateOutputPath(std::string &output_directory, const std::vector<std::string> &allowable_file_extensions = {});
 
+    //--------------------- ASSET PATH RESOLUTION -----------------------------------//
+
+    //! Resolve asset file path using cpplocate, allowing executables to run from any directory
+    /**
+     * \param[in] relativePath Relative path to the asset file (e.g., "plugins/visualizer/shaders/shader.vert")
+     * \return Absolute path to the asset file
+     * \note This function searches for assets in multiple locations: build directory, system install locations, and custom paths
+     * \ingroup functions
+     */
+    [[nodiscard]] std::filesystem::path resolveAssetPath(const std::string& relativePath);
+
+    //! Resolve plugin-specific asset path  
+    /**
+     * \param[in] pluginName Name of the plugin (e.g., "visualizer", "plantarchitecture", "radiation")
+     * \param[in] assetPath Relative path within the plugin's asset directory
+     * \return Absolute path to the plugin asset file
+     * \ingroup functions
+     */
+    [[nodiscard]] std::filesystem::path resolvePluginAsset(const std::string& pluginName, const std::string& assetPath);
+
+
+    //! Resolve file path using standard Helios resolution hierarchy
+    /**
+     * \param[in] filename File name with or without path (e.g., "primaryShader.vert" or "shaders/primaryShader.vert")
+     * \return Absolute path to the file
+     * \ingroup functions
+     */
+    [[nodiscard]] std::filesystem::path resolveFilePath(const std::string& filename);
+
+    //! Resolve spectral data file path
+    /**
+     * \param[in] spectraFile Spectral data filename with or without path (e.g., "camera_spectral_library.xml")
+     * \return Absolute path to the spectral data file
+     * \ingroup functions
+     */
+    [[nodiscard]] std::filesystem::path resolveSpectraPath(const std::string& spectraFile);
+
+    //! Validate that an asset file exists and is readable
+    /**
+     * \param[in] assetPath Path to the asset file to validate
+     * \return True if the file exists and is readable, false otherwise
+     * \ingroup functions
+     */
+    [[nodiscard]] bool validateAssetPath(const std::filesystem::path& assetPath);
+
+    //! Find the project root directory (directory containing top-level CMakeLists.txt)
+    /**
+     * \param[in] startPath Starting directory for search (defaults to current working directory)
+     * \return Absolute path to the project root directory, or empty path if not found
+     * \note Searches upward from startPath for a directory containing CMakeLists.txt
+     * \ingroup functions
+     */
+    [[nodiscard]] std::filesystem::path findProjectRoot(const std::filesystem::path& startPath = std::filesystem::current_path());
+
+    //! Resolve file path using project-based resolution strategy
+    /**
+     * \param[in] relativePath Relative path to the file
+     * \return Absolute path to the file
+     * \note Resolution order: 1) Current working directory, 2) Project directory, 3) Error
+     * \throws std::runtime_error if file cannot be found
+     * \ingroup functions
+     */
+    [[nodiscard]] std::filesystem::path resolveProjectFile(const std::string& relativePath);
+
     //! Read values contained in a text file into a one-dimensional vector of floats
     /**
      * \param[in] filepath Path to text file

core/src/Context.cpp

@@ -49,6 +49,13 @@ std::minstd_rand0 *Context::getRandomGenerator() {
     return &generator;
 }
 
+// Asset directory registration system removed - now using HELIOS_BUILD resolution
+
+std::filesystem::path Context::resolveFilePath(const std::string &filename) const {
+    // Use the global helios::resolveFilePath function which implements HELIOS_BUILD resolution
+    return helios::resolveFilePath(filename);
+}
+
 void Context::addTexture(const char *texture_file) {
     if (textures.find(texture_file) == textures.end()) { // texture has not already been added
 
@@ -61,12 +68,19 @@ void Context::addTexture(const char *texture_file) {
             helios_runtime_error("ERROR (Context::addTexture): Texture file " + std::string(texture_file) + " does not exist.");
         }
 
-        textures.emplace(texture_file, Texture(texture_file));
+        // Use unified path resolution
+        auto resolved_path = resolveFilePath(texture_file);
+        textures.emplace(texture_file, Texture(resolved_path.string().c_str()));
     }
 }
 
 bool Context::doesTextureFileExist(const char *texture_file) const {
-    return std::filesystem::exists(texture_file);
+    try {
+        auto resolved_path = resolveFilePath(texture_file);
+        return std::filesystem::exists(resolved_path);
+    } catch (const std::runtime_error&) {
+        return false;
+    }
 }
 
 bool Context::validateTextureFileExtenstion(const char *texture_file) const {

core/src/Context_fileIO.cpp

@@ -1119,7 +1119,11 @@ std::vector<uint> Context::loadXML(const char *filename, bool quiet) {
         helios_runtime_error("failed.\n File " + fn + " is not XML format.");
     }
 
-    XMLfiles.emplace_back(filename);
+    // Resolve file path using unified resolution
+    std::filesystem::path resolved_path = resolveFilePath(filename);
+    std::string resolved_filename = resolved_path.string();
+
+    XMLfiles.emplace_back(resolved_filename);
 
     uint ID;
     std::vector<uint> UUID;
@@ -1128,7 +1132,7 @@ std::vector<uint> Context::loadXML(const char *filename, bool quiet) {
     pugi::xml_document xmldoc;
 
     // load file
-    pugi::xml_parse_result load_result = xmldoc.load_file(filename);
+    pugi::xml_parse_result load_result = xmldoc.load_file(resolved_filename.c_str());
 
     // error checking
     if (!load_result) {
@@ -3222,8 +3226,12 @@ std::vector<uint> Context::loadPLY(const char *filename, const vec3 &origin, flo
 
     bool ifColor = false;
 
+    // Resolve file path using unified resolution
+    std::filesystem::path resolved_path = resolveFilePath(filename);
+    std::string resolved_filename = resolved_path.string();
+
     std::ifstream inputPly;
-    inputPly.open(filename);
+    inputPly.open(resolved_filename);
 
     if (!inputPly.is_open()) {
         helios_runtime_error("ERROR (Context::loadPLY): Couldn't open " + std::string(filename));
@@ -3580,16 +3588,19 @@ std::vector<uint> Context::loadOBJ(const char *filename, const vec3 &origin, con
 
     std::vector<uint> UUID;
 
+    // Resolve file path using unified resolution
+    std::filesystem::path resolved_path = resolveFilePath(filename);
+    std::string resolved_filename = resolved_path.string();
+    
     std::ifstream inputOBJ, inputMTL;
-    inputOBJ.open(filename);
+    inputOBJ.open(resolved_filename);
 
     if (!inputOBJ.is_open()) {
         helios_runtime_error("ERROR (Context::loadOBJ): Couldn't open " + std::string(filename));
     }
 
-    // determine the base file path for 'filename'
-    std::string fstring = filename;
-    std::string filebase = getFilePath(fstring);
+    // determine the base file path for resolved filename
+    std::string filebase = getFilePath(resolved_filename);
 
     // determine bounding box
     float boxmin = 100000;
@@ -3811,26 +3822,34 @@ std::map<std::string, Context::OBJmaterial> Context::loadMTL(const std::string &
     std::ifstream inputMTL;
 
     std::string file = material_file;
-
-    // first look for mtl file using path given in obj file
-    inputMTL.open(file.c_str());
-    if (!inputMTL.is_open()) {
-        // if that doesn't work, try looking in the same directory where obj file is located
-        file = filebase + file;
-        file.erase(remove(file.begin(), file.end(), ' '), file.end());
-        for (size_t i = file.size(); i-- > 0;) {
-            if (strcmp(&file.at(i), "l") == 0) {
-                break;
-            }
-
-            file.erase(file.begin() + scast<int>(i));
-        }
-        if (file.empty()) {
-            helios_runtime_error("ERROR (Context::loadMTL): Material file does not have correct file extension (.mtl).");
-        }
+    std::string resolved_file;
+
+    // Try unified resolution first
+    try {
+        std::filesystem::path resolved_path = resolveFilePath(file);
+        resolved_file = resolved_path.string();
+        inputMTL.open(resolved_file.c_str());
+    } catch (const std::runtime_error &) {
+        // If unified resolution fails, fall back to original logic
         inputMTL.open(file.c_str());
         if (!inputMTL.is_open()) {
-            helios_runtime_error("ERROR (Context::loadMTL): Material file " + std::string(file) + " given in .obj file cannot be found.");
+            // if that doesn't work, try looking in the same directory where obj file is located
+            file = filebase + file;
+            file.erase(remove(file.begin(), file.end(), ' '), file.end());
+            for (size_t i = file.size(); i-- > 0;) {
+                if (strcmp(&file.at(i), "l") == 0) {
+                    break;
+                }
+
+                file.erase(file.begin() + scast<int>(i));
+            }
+            if (file.empty()) {
+                helios_runtime_error("ERROR (Context::loadMTL): Material file does not have correct file extension (.mtl).");
+            }
+            inputMTL.open(file.c_str());
+            if (!inputMTL.is_open()) {
+                helios_runtime_error("ERROR (Context::loadMTL): Material file " + std::string(file) + " given in .obj file cannot be found.");
+            }
         }
     }
 
@@ -4430,7 +4449,11 @@ void Context::writePrimitiveData(const std::string &filename, const std::vector<
 }
 
 void Context::loadTabularTimeseriesData(const std::string &data_file, const std::vector<std::string> &col_labels, const std::string &a_delimeter, const std::string &a_date_string_format, uint headerlines) {
-    std::ifstream datafile(data_file); // open the file
+    // Resolve file path using project-based resolution
+    std::filesystem::path resolved_path = resolveProjectFile(data_file);
+    std::string resolved_filename = resolved_path.string();
+    
+    std::ifstream datafile(resolved_filename); // open the file
 
     if (!datafile.is_open()) { // check that file exists
         helios_runtime_error("ERROR (Context::loadTabularTimeseriesData): Weather data file '" + data_file + "' does not exist.");