[1.3.55] 2025-10-18

## Core
- Added `Context::setObjectDataFromPrimitiveDataMean()` method to calculate the mean of primitive data values across all child primitives of an object and set it as object data. Supports float, double, vec2, vec3, and vec4 data types. Only primitives with the specified data label are included in the calculation.
- Improved XML formatting for vector global data types (vec2, vec3, vec4, int2, int3, int4) - now writes each value on a separate line with proper indentation for better readability instead of all values on one line

## Visualizer
- Fixed issue with navigation gizmo where it could be blocked by objects extending past the camera near plane by moving it closer to the near plane (z-position changed from 0.01 to -0.9999)

## Leaf Optics
- Added `LeafOptics::getPropertiesFromSpectrum()` methods to retrieve PROSPECT model parameters from primitives based on their assigned reflectivity spectra. Available as both single primitive and vector overloads. The method queries primitives for their "reflectivity_spectrum" data and assigns the corresponding PROSPECT parameters (chlorophyll, carotenoid, anthocyanin, water, etc.) as primitive data if the spectrum matches one generated by the LeafOptics instance.

## Plant Architecture
- Fixed a bug when `petioles_per_internode` is set to 0, which caused child shoot insertion angles to be incorrect. This caused major issues in the weed models "puncturevine" and "bindweed"
- Fixed a bug where internodes that start out extremely small were only being scaled in the radius but not length. This caused major issues in the weed model "cheeseweed"
- Improved `ShootParameters` documentation comments for `insertion_angle_tip` and `insertion_angle_decay_rate` for clarity

## Radiation
- Cleaned up camera_spectral_library.xml by removing duplicate copyright comments for Canon 20D, Nikon D700, Nikon D50, and SONY NEX-5N camera spectral data

Author: bnbailey-psl

README.md

@@ -8,4 +8,10 @@ Helios is a C++ library for 3D physical simulation of plant and environmental sy
 
 In order to build and compile the core library, you will need to install a C/C++ compiler (recommended are the GNU C compilers version 7.0+), and CMake. In order to run many of the model plug-ins, you will need to install NVIDIA CUDA 10.2+, and a GPU with compute capability 5.0+. The software has been tested on Linux, Mac, and Windows platforms. The YouTube channel linked above has a number of tutorials for getting started.
 
+**NEW** : Helios now has a Python API! Please see the [PyHelios API documentation](https://plantsimulationlab.github.io/PyHelios/) for more information.
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/PlantSimulationLab/PyHelios/master/docs/images/PyHelios_logo_whiteborder.png"  alt="" width="100" />
+</div>
+
 ![Almond Reconstruction](doc/images/AlmondVarietyReconstruction.png)

core/include/Context.h

@@ -4221,6 +4221,16 @@ namespace helios {
             }
         }
 
+        //! Set object data from mean of primitive data values for all child primitives
+        /**
+         * \param[in] objID Unique identifier of compound object
+         * \param[in] label Name of primitive data to aggregate and resulting object data label
+         * \note The data type is automatically detected from the primitive data (supports float, double, vec2, vec3, vec4)
+         * \note Only primitives that have the specified primitive data are included in the calculation
+         * \note Raises error if no primitives have the specified primitive data
+         */
+        void setObjectDataFromPrimitiveDataMean(uint objID, const std::string &label);
+
         //! Get data value associated with a compound object
         /**
          * \tparam T Object data type

core/src/Context_data.cpp

@@ -537,6 +537,127 @@ void Context::calculatePrimitiveDataMean(const std::vector<uint> &UUIDs, const s
     }
 }
 
+void Context::setObjectDataFromPrimitiveDataMean(uint objID, const std::string &label) {
+#ifdef HELIOS_DEBUG
+    if (!doesObjectExist(objID)) {
+        helios_runtime_error("ERROR (Context::setObjectDataFromPrimitiveDataMean): Object ID of " + std::to_string(objID) + " does not exist in the Context.");
+    }
+#endif
+
+    // Get primitive UUIDs for this object
+    std::vector<uint> UUIDs = getObjectPrimitiveUUIDs(objID);
+
+    if (UUIDs.empty()) {
+        helios_runtime_error("ERROR (Context::setObjectDataFromPrimitiveDataMean): Object ID " + std::to_string(objID) + " has no primitive children.");
+    }
+
+    // Determine the data type by checking the first primitive that has this data
+    HeliosDataType data_type = HELIOS_TYPE_UNKNOWN;
+    for (uint UUID : UUIDs) {
+        if (doesPrimitiveExist(UUID) && doesPrimitiveDataExist(UUID, label.c_str())) {
+            data_type = getPrimitiveDataType(label.c_str());
+            break;
+        }
+    }
+
+    if (data_type == HELIOS_TYPE_UNKNOWN) {
+        helios_runtime_error("ERROR (Context::setObjectDataFromPrimitiveDataMean): Primitive data '" + label + "' does not exist for any primitives in object " + std::to_string(objID) + ".");
+    }
+
+    // Validate data type is supported for mean calculation
+    if (data_type != HELIOS_TYPE_FLOAT && data_type != HELIOS_TYPE_DOUBLE &&
+        data_type != HELIOS_TYPE_VEC2 && data_type != HELIOS_TYPE_VEC3 && data_type != HELIOS_TYPE_VEC4) {
+        helios_runtime_error("ERROR (Context::setObjectDataFromPrimitiveDataMean): Cannot calculate mean for primitive data type. Only float, double, vec2, vec3, and vec4 are supported.");
+    }
+
+    // Calculate mean based on data type
+    if (data_type == HELIOS_TYPE_FLOAT) {
+        float value;
+        float sum = 0.f;
+        size_t count = 0;
+        for (uint UUID : UUIDs) {
+            if (doesPrimitiveExist(UUID) && doesPrimitiveDataExist(UUID, label.c_str())) {
+                getPrimitiveData(UUID, label.c_str(), value);
+                sum += value;
+                count++;
+            }
+        }
+        if (count == 0) {
+            helios_runtime_error("ERROR (Context::setObjectDataFromPrimitiveDataMean): No primitives in object " + std::to_string(objID) + " have primitive data '" + label + "'.");
+        }
+        float mean = sum / float(count);
+        setObjectData(objID, label.c_str(), mean);
+
+    } else if (data_type == HELIOS_TYPE_DOUBLE) {
+        double value;
+        double sum = 0.0;
+        size_t count = 0;
+        for (uint UUID : UUIDs) {
+            if (doesPrimitiveExist(UUID) && doesPrimitiveDataExist(UUID, label.c_str())) {
+                getPrimitiveData(UUID, label.c_str(), value);
+                sum += value;
+                count++;
+            }
+        }
+        if (count == 0) {
+            helios_runtime_error("ERROR (Context::setObjectDataFromPrimitiveDataMean): No primitives in object " + std::to_string(objID) + " have primitive data '" + label + "'.");
+        }
+        double mean = sum / double(count);
+        setObjectData(objID, label.c_str(), mean);
+
+    } else if (data_type == HELIOS_TYPE_VEC2) {
+        vec2 value;
+        vec2 sum(0.f, 0.f);
+        size_t count = 0;
+        for (uint UUID : UUIDs) {
+            if (doesPrimitiveExist(UUID) && doesPrimitiveDataExist(UUID, label.c_str())) {
+                getPrimitiveData(UUID, label.c_str(), value);
+                sum = sum + value;
+                count++;
+            }
+        }
+        if (count == 0) {
+            helios_runtime_error("ERROR (Context::setObjectDataFromPrimitiveDataMean): No primitives in object " + std::to_string(objID) + " have primitive data '" + label + "'.");
+        }
+        vec2 mean = sum / float(count);
+        setObjectData(objID, label.c_str(), mean);
+
+    } else if (data_type == HELIOS_TYPE_VEC3) {
+        vec3 value;
+        vec3 sum(0.f, 0.f, 0.f);
+        size_t count = 0;
+        for (uint UUID : UUIDs) {
+            if (doesPrimitiveExist(UUID) && doesPrimitiveDataExist(UUID, label.c_str())) {
+                getPrimitiveData(UUID, label.c_str(), value);
+                sum = sum + value;
+                count++;
+            }
+        }
+        if (count == 0) {
+            helios_runtime_error("ERROR (Context::setObjectDataFromPrimitiveDataMean): No primitives in object " + std::to_string(objID) + " have primitive data '" + label + "'.");
+        }
+        vec3 mean = sum / float(count);
+        setObjectData(objID, label.c_str(), mean);
+
+    } else if (data_type == HELIOS_TYPE_VEC4) {
+        vec4 value;
+        vec4 sum(0.f, 0.f, 0.f, 0.f);
+        size_t count = 0;
+        for (uint UUID : UUIDs) {
+            if (doesPrimitiveExist(UUID) && doesPrimitiveDataExist(UUID, label.c_str())) {
+                getPrimitiveData(UUID, label.c_str(), value);
+                sum = sum + value;
+                count++;
+            }
+        }
+        if (count == 0) {
+            helios_runtime_error("ERROR (Context::setObjectDataFromPrimitiveDataMean): No primitives in object " + std::to_string(objID) + " have primitive data '" + label + "'.");
+        }
+        vec4 mean = sum / float(count);
+        setObjectData(objID, label.c_str(), mean);
+    }
+}
+
 void Context::calculatePrimitiveDataAreaWeightedMean(const std::vector<uint> &UUIDs, const std::string &label, float &awt_mean) const {
     float value, A;
     float sum = 0.f;

core/src/Context_fileIO.cpp

@@ -3082,59 +3082,41 @@ void Context::writeXML(const char *filename, const std::vector<uint> &UUIDs, boo
             }
             outfile << "</globaldata_double>" << std::endl;
         } else if (type == HELIOS_TYPE_VEC2) {
-            outfile << "   <globaldata_vec2 label=\"" << label << "\">" << std::flush;
+            outfile << "   <globaldata_vec2 label=\"" << label << "\">" << std::endl;
             for (size_t i = 0; i < data.size; i++) {
-                outfile << data.global_data_vec2.at(i).x << " " << data.global_data_vec2.at(i).y << std::flush;
-                if (i != data.size - 1) {
-                    outfile << " " << std::flush;
-                }
+                outfile << "      " << data.global_data_vec2.at(i).x << " " << data.global_data_vec2.at(i).y << std::endl;
             }
-            outfile << "</globaldata_vec2>" << std::endl;
+            outfile << "   </globaldata_vec2>" << std::endl;
         } else if (type == HELIOS_TYPE_VEC3) {
-            outfile << "   <globaldata_vec3 label=\"" << label << "\">" << std::flush;
+            outfile << "   <globaldata_vec3 label=\"" << label << "\">" << std::endl;
             for (size_t i = 0; i < data.size; i++) {
-                outfile << data.global_data_vec3.at(i).x << " " << data.global_data_vec3.at(i).y << " " << data.global_data_vec3.at(i).z << std::flush;
-                if (i != data.size - 1) {
-                    outfile << " " << std::flush;
-                }
+                outfile << "      " << data.global_data_vec3.at(i).x << " " << data.global_data_vec3.at(i).y << " " << data.global_data_vec3.at(i).z << std::endl;
             }
-            outfile << "</globaldata_vec3>" << std::endl;
+            outfile << "   </globaldata_vec3>" << std::endl;
         } else if (type == HELIOS_TYPE_VEC4) {
-            outfile << "   <globaldata_vec4 label=\"" << label << "\">" << std::flush;
+            outfile << "   <globaldata_vec4 label=\"" << label << "\">" << std::endl;
             for (size_t i = 0; i < data.size; i++) {
-                outfile << data.global_data_vec4.at(i).x << " " << data.global_data_vec4.at(i).y << " " << data.global_data_vec4.at(i).z << " " << data.global_data_vec4.at(i).w << std::flush;
-                if (i != data.size - 1) {
-                    outfile << " " << std::flush;
-                }
+                outfile << "      " << data.global_data_vec4.at(i).x << " " << data.global_data_vec4.at(i).y << " " << data.global_data_vec4.at(i).z << " " << data.global_data_vec4.at(i).w << std::endl;
             }
-            outfile << "</globaldata_vec4>" << std::endl;
+            outfile << "   </globaldata_vec4>" << std::endl;
         } else if (type == HELIOS_TYPE_INT2) {
-            outfile << "   <globaldata_int2 label=\"" << label << "\">" << std::flush;
+            outfile << "   <globaldata_int2 label=\"" << label << "\">" << std::endl;
             for (size_t i = 0; i < data.size; i++) {
-                outfile << data.global_data_int2.at(i).x << " " << data.global_data_int2.at(i).y << std::flush;
-                if (i != data.size - 1) {
-                    outfile << " " << std::flush;
-                }
+                outfile << "      " << data.global_data_int2.at(i).x << " " << data.global_data_int2.at(i).y << std::endl;
             }
-            outfile << "</globaldata_int2>" << std::endl;
+            outfile << "   </globaldata_int2>" << std::endl;
         } else if (type == HELIOS_TYPE_INT3) {
-            outfile << "   <globaldata_int3 label=\"" << label << "\">" << std::flush;
+            outfile << "   <globaldata_int3 label=\"" << label << "\">" << std::endl;
             for (size_t i = 0; i < data.size; i++) {
-                outfile << data.global_data_int3.at(i).x << " " << data.global_data_int3.at(i).y << data.global_data_int3.at(i).z << std::flush;
-                if (i != data.size - 1) {
-                    outfile << " " << std::flush;
-                }
+                outfile << "      " << data.global_data_int3.at(i).x << " " << data.global_data_int3.at(i).y << " " << data.global_data_int3.at(i).z << std::endl;
             }
-            outfile << "</globaldata_int3>" << std::endl;
+            outfile << "   </globaldata_int3>" << std::endl;
         } else if (type == HELIOS_TYPE_INT4) {
-            outfile << "   <globaldata_int4 label=\"" << label << "\">" << std::flush;
+            outfile << "   <globaldata_int4 label=\"" << label << "\">" << std::endl;
             for (size_t i = 0; i < data.size; i++) {
-                outfile << data.global_data_int4.at(i).x << " " << data.global_data_int4.at(i).y << data.global_data_int4.at(i).z << data.global_data_int4.at(i).w << std::flush;
-                if (i != data.size - 1) {
-                    outfile << " " << std::flush;
-                }
+                outfile << "      " << data.global_data_int4.at(i).x << " " << data.global_data_int4.at(i).y << " " << data.global_data_int4.at(i).z << " " << data.global_data_int4.at(i).w << std::endl;
             }
-            outfile << "</globaldata_int4>" << std::endl;
+            outfile << "   </globaldata_int4>" << std::endl;
         } else if (type == HELIOS_TYPE_STRING) {
             outfile << "   <globaldata_string label=\"" << label << "\">" << std::flush;
             for (size_t i = 0; i < data.size; i++) {

core/tests/Test_XML.h

@@ -291,5 +291,76 @@ TEST_CASE("Context XML I/O Functions") {
         std::remove(test_file);
     }
 
+    SUBCASE("vector global data XML formatting") {
+        Context ctx;
+
+        // Add various vector type global data
+        std::vector<vec2> vec2_data = {make_vec2(400, 0.0666747f), make_vec2(401, 0.0640556f), make_vec2(402, 0.0619332f)};
+        std::vector<vec3> vec3_data = {make_vec3(1.1f, 2.2f, 3.3f), make_vec3(4.4f, 5.5f, 6.6f)};
+        std::vector<vec4> vec4_data = {make_vec4(1.1f, 2.2f, 3.3f, 4.4f), make_vec4(5.5f, 6.6f, 7.7f, 8.8f)};
+        std::vector<int2> int2_data = {make_int2(1, 2), make_int2(3, 4)};
+        std::vector<int3> int3_data = {make_int3(1, 2, 3), make_int3(4, 5, 6)};
+        std::vector<int4> int4_data = {make_int4(1, 2, 3, 4), make_int4(5, 6, 7, 8)};
+
+        ctx.setGlobalData("test_vec2", vec2_data);
+        ctx.setGlobalData("test_vec3", vec3_data);
+        ctx.setGlobalData("test_vec4", vec4_data);
+        ctx.setGlobalData("test_int2", int2_data);
+        ctx.setGlobalData("test_int3", int3_data);
+        ctx.setGlobalData("test_int4", int4_data);
+
+        const char *test_file = "helios_vector_test.xml";
+        ctx.writeXML(test_file, true);
+
+        // Load and verify all vector data
+        Context ctx2;
+        ctx2.loadXML(test_file, true);
+
+        // Verify vec2
+        std::vector<vec2> loaded_vec2;
+        ctx2.getGlobalData("test_vec2", loaded_vec2);
+        DOCTEST_CHECK(loaded_vec2.size() == 3);
+        DOCTEST_CHECK(loaded_vec2[0].x == doctest::Approx(400.0f));
+        DOCTEST_CHECK(loaded_vec2[0].y == doctest::Approx(0.0666747f));
+        DOCTEST_CHECK(loaded_vec2[2].x == doctest::Approx(402.0f));
+
+        // Verify vec3
+        std::vector<vec3> loaded_vec3;
+        ctx2.getGlobalData("test_vec3", loaded_vec3);
+        DOCTEST_CHECK(loaded_vec3.size() == 2);
+        DOCTEST_CHECK(loaded_vec3[0] == vec3(1.1f, 2.2f, 3.3f));
+        DOCTEST_CHECK(loaded_vec3[1] == vec3(4.4f, 5.5f, 6.6f));
+
+        // Verify vec4
+        std::vector<vec4> loaded_vec4;
+        ctx2.getGlobalData("test_vec4", loaded_vec4);
+        DOCTEST_CHECK(loaded_vec4.size() == 2);
+        DOCTEST_CHECK(loaded_vec4[0] == vec4(1.1f, 2.2f, 3.3f, 4.4f));
+        DOCTEST_CHECK(loaded_vec4[1] == vec4(5.5f, 6.6f, 7.7f, 8.8f));
+
+        // Verify int2
+        std::vector<int2> loaded_int2;
+        ctx2.getGlobalData("test_int2", loaded_int2);
+        DOCTEST_CHECK(loaded_int2.size() == 2);
+        DOCTEST_CHECK(loaded_int2[0] == int2(1, 2));
+        DOCTEST_CHECK(loaded_int2[1] == int2(3, 4));
+
+        // Verify int3
+        std::vector<int3> loaded_int3;
+        ctx2.getGlobalData("test_int3", loaded_int3);
+        DOCTEST_CHECK(loaded_int3.size() == 2);
+        DOCTEST_CHECK(loaded_int3[0] == int3(1, 2, 3));
+        DOCTEST_CHECK(loaded_int3[1] == int3(4, 5, 6));
+
+        // Verify int4
+        std::vector<int4> loaded_int4;
+        ctx2.getGlobalData("test_int4", loaded_int4);
+        DOCTEST_CHECK(loaded_int4.size() == 2);
+        DOCTEST_CHECK(loaded_int4[0] == int4(1, 2, 3, 4));
+        DOCTEST_CHECK(loaded_int4[1] == int4(5, 6, 7, 8));
+
+        std::remove(test_file);
+    }
+
     // Note: scanXMLForTag testing removed due to complex XML tag structure requirements
 }