[1.3.42] 2025-07-30

- Split tutorials into separate files for better organization.
- `detect_GPU_compute.cmake` script updated to fix some issues on Windows systems.

  🚨+ NEW PLUG-IN + 🚨
- Added a new `collisiondetection` plug-in for efficiently calculating primitive and object collisions.

# Context
- `Context::generateColormap()` is now public. An error with the "cool" colormap was also fixed.

# LiDAR
- Added tutorials for several LiDAR application examples.
- `LiDARcloud::addGridWireframeToVisualizer()` now has an optional argument to specify the line width.
- All of the file exporting methods now try to create the output directory if it does not exist.
- Updated error throwing to use `helios_runtime_error()`.
- Added `LiDARcloud::loadTreeQSM()` and `LiDARcloud::loadTreeQSMColormap()` methods to load a TreeQSM output file and build it in the Context using tube objects.
- Made `LiDARcloud::loadASCIIFile()` public, and modified it to take a file name rather than a parameters structure.
- Added overloaded `LiDARcloud::addHitsToVisualizer()` that allows specification of the point color.

# Visualizer
- Added option to `Visualizer::addLine()` to be able to specify the line width.
- Added option to `Visualizer::addPoint()` to be able to specify the point size.
- Refactored how points are visualized to add automatic culling that speeds up rendering of large point clouds.
- Broke `Visualizer.cpp` into four different files, as it was getting huge.
- Fixed an issue introduced in v1.3.40 causing images to be written up-side down when using the `Visualizer::printWindow()` method.
- Fixed an issue that could cause `Visualizer::printWindow()` to write black images on Linux.

# Plant Architecture
- Added `PlantArchitecture::writeQSMCylinderFile()` method to export the plant geometry as a TreeQSM cylinder file.
- Added collision detection capabilities within the plant architecture plug-in. This is in the intial testing phase for now, and will be further developed in future versions.

# Radiation
- Added `RadiationModel::writeImageSegmentationMasks()` and `RadiationModel::writeImageSegmentationMasks_ObjectData()` to directly write COCO JSON segmentation masks for objects in the scene.
- Moved camera-related code to separate file `RadiationCamera.cpp` to improve organization.
- Many modifications to `CMakeLists.txt` file to fix an issue on Windows systems introduced in v1.3.40.
- Fixed an error checking issue with camera processing pipeline functions to allow cameras with more than 3 channels.

# Aerial LiDAR, LiDAR, Energy Balance, and Voxel Intersection
- Some modifications to `CMakeLists.txt` to allow building with the project builder on Windows systems.

Author: bnbailey-psl

AGENTS.md

@@ -8,6 +8,7 @@
 - Standard C++ library include headers are listed in the file `core/include/global.h`. Check these includes to make sure you do not add unnecessary includes.
 - Prefer descriptive variable names that 'self-document' the code.
 - Prefer clearer code over clever optimized code that provides only marginal performance improvements.
+- When implementing new function/method definitions, be aware of the organization of the source file. Don't just automatically add them at the end of the file, but keep them grouped with similar definitions if possible.
 
 ## Code Structure
 - The code is organized into a core library and plugins. The core library contains the main functionality, while plugins provide additional features.
@@ -39,6 +40,7 @@
 2. **Running Tests**: 
    - For core tests: `./context_tests` (from context_selftest/build/)
    - For plugin tests: `./{plugin_name}_selftest` or `./{plugin_name}_tests`
+   - If you need to run custom test code from a new .cpp file, add it to the `CMakeLists.txt` in the appropriate sample directory and rebuild.
 
 3. **Common Build Issues**:
    - Always check compilation errors carefully for missing includes or function signature mismatches

core/CMake_project.cmake

@@ -1,5 +1,16 @@
 option(ENABLE_OPENMP "Enable building with OpenMP" OFF)
 
+# Set CMake policies to avoid warnings on newer CMake versions
+if(POLICY CMP0074)
+    cmake_policy(SET CMP0074 NEW)
+endif()
+if(POLICY CMP0077)
+    cmake_policy(SET CMP0077 NEW)
+endif()
+if(POLICY CMP0076)
+    cmake_policy(SET CMP0076 NEW)
+endif()
+
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)

core/include/Context.h

@@ -11,7 +11,7 @@
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
-*/
+ */
 
 #ifndef HELIOS_CONTEXT
 #define HELIOS_CONTEXT
@@ -2226,12 +2226,6 @@ namespace helios {
 
         void writeDataToXMLstream(const char *data_group, const std::vector<std::string> &data_labels, void *ptr, std::ofstream &outfile) const;
 
-        std::vector<std::string> generateTexturesFromColormap(const std::string &texturefile, const std::vector<RGBcolor> &colormap_data);
-
-        std::vector<RGBcolor> generateColormap(const std::string &colormap, uint Ncolors);
-
-        std::vector<RGBcolor> generateColormap(const std::vector<helios::RGBcolor> &ctable, const std::vector<float> &cfrac, uint Ncolors);
-
 
         //---------- CONTEXT INITIALIZATION FLAGS ---------//
 
@@ -6188,6 +6182,38 @@ namespace helios {
          * \note If object data does not exist, or object data does not have type of 'std::string', the object is excluded.
          */
         [[nodiscard]] std::vector<uint> filterObjectsByData(const std::vector<uint> &objIDs, const std::string &object_data_label, const std::string &filter_value) const;
+
+        //! Generates texture files by applying a colormap to an input texture image.
+        /**
+         * This function reads an existing texture file and modifies its colors based
+         * on a provided colormap. A new set of texture files is created, one for each
+         * color in the colormap. Each texture file reflects the applied color from
+         * the colormap while preserving the texture's original alpha values.
+         *
+         * \param[in] texturefile The path to the input texture file that will be used as the base for generating new textures.
+         * \param[in] colormap_data A vector containing the RGB colors that will be applied to the texture file. Each color in the colormap results in the generation of one texture file.
+         * \return A vector of strings, where each string is the filename of a newly generated texture file.
+         */
+        std::vector<std::string> generateTexturesFromColormap(const std::string &texturefile, const std::vector<RGBcolor> &colormap_data);
+
+        //! Generates a colormap with a specified number of colors based on the selected colormap type
+        /**
+         * \param[in] colormap The name of the colormap to generate (e.g., "hot", "cool", "lava", etc.).
+         * \param[in] Ncolors The desired number of colors in the output colormap.
+         * \return A vector of RGBcolor objects representing the generated colormap.
+         */
+        std::vector<RGBcolor> generateColormap(const std::string &colormap, uint Ncolors);
+
+        //! Generates a colormap of interpolated colors based on input color table and fractions.
+        /**
+         * \param[in] ctable A vector of RGB colors defining the input color points for interpolation.
+         * \param[in] cfrac A vector of fractional values corresponding to each color in the color table, must match the size of ctable.
+         * \param[in] Ncolors Desired number of output colors in the generated colormap. Must be greater than 0.
+         * \return A vector of RGB colors representing the generated colormap.
+         * \note The input vectors ctable and cfrac must have the same size, and neither can be empty. If the requested Ncolors exceeds the internal limit, it will be truncated to 9999, with a warning issued.
+         */
+        std::vector<RGBcolor> generateColormap(const std::vector<helios::RGBcolor> &ctable, const std::vector<float> &cfrac, uint Ncolors);
+
     };
 
 } // namespace helios

core/include/global.h

@@ -11,7 +11,7 @@
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
-*/
+ */
 
 #ifndef HELIOS_GLOBAL
 #define HELIOS_GLOBAL
@@ -57,6 +57,7 @@ constexpr float PI_F = 3.14159265358979323846f;
 #include <type_traits>
 #include <unordered_map>
 #include <vector>
+#include <set>
 
 #ifdef USE_OPENMP
 #include <omp.h>
@@ -1162,6 +1163,48 @@ namespace helios {
         }
     };
 
+    //! A utility struct to capture and store what is written to `std::cout`.
+    /**
+     * This struct redirects the `std::cout` stream to an internal string stream
+     * while an instance of the struct exists. When the struct is destroyed,
+     * it restores the original `std::cout` output stream. The captured output
+     * can be queried and cleared as needed.
+     */
+    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);
+        }
+
+        //! Get the captured cout output as a string
+        std::string get_captured_output() const {
+            return captured_stream.str();
+        }
+
+        //! Check if any output has been captured
+        bool has_output() const {
+            return !captured_stream.str().empty();
+        }
+
+        //! Clear the captured output
+        void clear() {
+            captured_stream.str("");
+            captured_stream.clear();
+        }
+
+        //! Get the number of characters captured
+        size_t size() const {
+            return captured_stream.str().size();
+        }
+    };
+
+
     //! Default null SphericalCoord that applies no rotation
     extern SphericalCoord nullrotation;
     //! Default null vec3 that gives the origin (0,0,0)

core/include/helios_vector_types.h

@@ -11,7 +11,7 @@
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
-*/
+ */
 
 #ifndef HELIOS_VECTOR_TYPES
 #define HELIOS_VECTOR_TYPES

core/lib/detect_GPU_compute.cmake

@@ -1,29 +1,33 @@
 set(NVCC_EXECUTABLE "${CUDAToolkit_NVCC_EXECUTABLE}")
 
 # ask nvcc for all supported GPU codes (sm_* and compute_*)
-execute_process( COMMAND ${NVCC_EXECUTABLE} --list-gpu-code OUTPUT_VARIABLE _nvcc_gpu_codes OUTPUT_STRIP_TRAILING_WHITESPACE )
-
-# split lines into a CMake list
-string(REPLACE "\n" ";" _gpu_codes "${_nvcc_gpu_codes}")
-
-# separate out real (sm_XX) and virtual (compute_XX) architectures
-set(_sm_codes "")
-set(_virtual_codes "")
-foreach(_code IN LISTS _gpu_codes)
-    if(_code MATCHES "^sm_[0-9]+$")
-        list(APPEND _sm_codes ${_code})
-    elseif(_code MATCHES "^compute_[0-9]+$")
-        list(APPEND _virtual_codes ${_code})
-    endif()
-endforeach()
-
-# Extract architecture numbers for CMAKE_CUDA_ARCHITECTURES
-set(_cuda_architectures "")
-foreach(_sm IN LISTS _sm_codes)
-    # Extract the number from sm_XX
-    string(REGEX REPLACE "sm_(.+)" "\\1" _arch_num "${_sm}")
-    list(APPEND _cuda_architectures ${_arch_num})
-endforeach()
+execute_process( COMMAND ${NVCC_EXECUTABLE} --list-gpu-code OUTPUT_VARIABLE _nvcc_gpu_codes OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET RESULT_VARIABLE _nvcc_result)
+
+if(_nvcc_result EQUAL 0)
+    # split lines into a CMake list
+    string(REPLACE "\n" ";" _gpu_codes "${_nvcc_gpu_codes}")
+    
+    # separate out real (sm_XX) and virtual (compute_XX) architectures
+    set(_sm_codes "")
+    set(_virtual_codes "")
+    foreach(_code IN LISTS _gpu_codes)
+        if(_code MATCHES "^sm_[0-9]+$")
+            list(APPEND _sm_codes ${_code})
+        elseif(_code MATCHES "^compute_[0-9]+$")
+            list(APPEND _virtual_codes ${_code})
+        endif()
+    endforeach()
+    
+    # Extract architecture numbers for CMAKE_CUDA_ARCHITECTURES
+    set(_cuda_architectures "")
+    foreach(_sm IN LISTS _sm_codes)
+        # Extract the number from sm_XX
+        string(REGEX REPLACE "sm_(.+)" "\\1" _arch_num "${_sm}")
+        list(APPEND _cuda_architectures ${_arch_num})
+    endforeach()
+else()
+    set(_cuda_architectures "")
+endif()
 
 # if no architectures were detected, fall back to SM 5.0
 if(NOT _cuda_architectures)
@@ -35,21 +39,24 @@ endif()
 set(CMAKE_CUDA_ARCHITECTURES "${_cuda_architectures}")
 
 # Also build gencode flags for compatibility (if needed elsewhere)
-set(_gencode_flags "")
-foreach(_sm IN LISTS _sm_codes)
-    # derive compute_XX from sm_XX
-    string(REGEX REPLACE "sm_(.+)" "compute_\\1" _compute "${_sm}")
-
-    # always emit native cubin for each SM you found
-    list(APPEND _gencode_flags  "-gencode"  "arch=${_compute},code=${_sm}" )
-endforeach()
-
-# if no architectures were detected, fall back to SM 5.0
-if(NOT _gencode_flags)
-    message(WARNING "No CUDA architectures detected; defaulting to compute_50,code=sm_50")
-    list(APPEND _gencode_flags  "-gencode" "arch=compute_50,code=sm_50" )
-endif()
-
-# append to your CUDA flags (for compatibility)
-string (JOIN " " _joined "${_gencode_flags}")
-set(CUDA_NVCC_FLAGS "${CUDA_NVCC_FLAGS} ${_joined}")
+# NOTE: Modern CMake uses CMAKE_CUDA_ARCHITECTURES instead
+if(DEFINED _sm_codes)
+    set(_gencode_flags "")
+    foreach(_sm IN LISTS _sm_codes)
+        # derive compute_XX from sm_XX
+        string(REGEX REPLACE "sm_(.+)" "compute_\\1" _compute "${_sm}")
+        
+        # always emit native cubin for each SM you found
+        list(APPEND _gencode_flags  "-gencode"  "arch=${_compute},code=${_sm}" )
+    endforeach()
+    
+    # if no architectures were detected, fall back to SM 5.0
+    if(NOT _gencode_flags)
+        message(WARNING "No CUDA architectures detected; defaulting to compute_50,code=sm_50")
+        list(APPEND _gencode_flags  "-gencode" "arch=compute_50,code=sm_50" )
+    endif()
+    
+    # append to your CUDA flags (for compatibility with old code)
+    string (JOIN " " _joined "${_gencode_flags}")
+    set(CUDA_NVCC_FLAGS "${CUDA_NVCC_FLAGS} ${_joined}")
+endif()

core/src/Context.cpp

@@ -11,7 +11,7 @@
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
-*/
+ */
 
 #include "Context.h"
 
@@ -441,14 +441,6 @@ float Context::randn(float mean, float stddev) {
 }
 
 
-
-
-
-
-
-
-
-
 std::vector<uint> Context::getAllUUIDs() const {
     std::vector<uint> UUIDs;
     UUIDs.reserve(primitives.size());
@@ -1763,7 +1755,6 @@ void Context::setTileObjectSubdivisionCount(const std::vector<uint> &ObjIDs, flo
 }
 
 
-
 std::vector<uint> Context::addSphere(uint Ndivs, const vec3 &center, float radius) {
     RGBcolor color = make_RGBcolor(0.f, 0.75f, 0.f); // Default color is green
 
@@ -2867,12 +2858,12 @@ std::vector<RGBcolor> Context::generateColormap(const std::string &colormap, uin
         clocs_c.at(4) = 1.f;
     } else if (colormap == "cool") {
         ctable_c.resize(2);
-        ctable_c.at(1) = RGB::cyan;
-        ctable_c.at(2) = RGB::magenta;
+        ctable_c.at(0) = RGB::cyan;
+        ctable_c.at(1) = RGB::magenta;
 
         clocs_c.resize(2);
-        clocs_c.at(1) = 0.f;
-        clocs_c.at(2) = 1.f;
+        clocs_c.at(0) = 0.f;
+        clocs_c.at(1) = 1.f;
     } else if (colormap == "lava") {
         ctable_c.resize(5);
         ctable_c.at(0) = make_RGBcolor(0.f, 0.05f, 0.05f);

core/src/Context_data.cpp

@@ -11,7 +11,7 @@
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
-*/
+ */
 
 #include "Context.h"
 

core/src/Context_fileIO.cpp

@@ -11,7 +11,7 @@
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
-*/
+ */
 
 #include "Context.h"
 

core/src/Context_object.cpp

@@ -11,7 +11,7 @@
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
-*/
+ */
 
 #include "Context.h"
 
@@ -2615,4 +2615,4 @@ float Cone::getVolume() const {
     float h = getLength();
 
     return PI_F * h / 3.f * (r0 * r0 + r0 * r1 + r1 * r1);
-}
+}