[v0.0.5] 2025-08-27

- Helios native C++ had several bugs that was causing errors in the last version. Merged in patched version of 1.3.46.

## Visualizer
- Fixed some issues that could cause the visualizer tests to crash in headless mode.

Author: bnbailey-psl

.github/workflows/docs.yml

@@ -56,9 +56,13 @@ jobs:
         
     - name: Sync version to Doxygen config
       run: |
-        # Get version from setuptools-scm and update Doxyfile
-        export PYHELIOS_DEV_MODE=1
-        VERSION=$(python -c "from pyhelios._version import __version__; print(__version__)")
+        # Get version directly from _version.py to avoid importing PyHelios
+        VERSION=$(python -c "
+import sys
+sys.path.insert(0, 'pyhelios')
+from _version import __version__
+print(__version__)
+        ")
         echo "Updating Doxygen PROJECT_NUMBER to: $VERSION"
         sed -i "s/^PROJECT_NUMBER.*$/PROJECT_NUMBER         = $VERSION/" docs/Doxyfile.python
 
@@ -128,9 +132,13 @@ jobs:
         
     - name: Sync version to Doxygen config (preview)
       run: |
-        # Get version from setuptools-scm and update Doxyfile
-        export PYHELIOS_DEV_MODE=1
-        VERSION=$(python -c "from pyhelios._version import __version__; print(__version__)")
+        # Get version directly from _version.py to avoid importing PyHelios
+        VERSION=$(python -c "
+import sys
+sys.path.insert(0, 'pyhelios')
+from _version import __version__
+print(__version__)
+        ")
         echo "Updating Doxygen PROJECT_NUMBER to: $VERSION"
         sed -i "s/^PROJECT_NUMBER.*$/PROJECT_NUMBER         = $VERSION/" docs/Doxyfile.python
 

docs/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+# [v0.0.5] 2025-08-27
+
+- Helios native C++ had several bugs that was causing errors in the last version. Merged in patched version of 1.3.46.
+
+## Visualizer
+- Fixed some issues that could cause the visualizer tests to crash in headless mode.
+
 # [v0.0.4] 2025-08-25
 
 🚨++ New Plug-in Integrated ++ 🚨

helios-core

@@ -18,13 +18,31 @@ extern "C" {
     //=============================================================================
 
     Visualizer* createVisualizer(unsigned int width, unsigned int height, bool headless) {
-        // Enable window decorations by default (true), headless parameter controls window visibility
-        return new Visualizer(width, height, 4, true, headless); // 4 antialiasing samples, decorations enabled
+        try {
+            clearError();
+            // Enable window decorations by default (true), headless parameter controls window visibility
+            return new Visualizer(width, height, 4, true, headless); // 4 antialiasing samples, decorations enabled
+        } catch (const std::exception& e) {
+            setError(PYHELIOS_ERROR_RUNTIME, std::string("ERROR (createVisualizer): Failed to create visualizer: ") + e.what());
+            return nullptr;
+        } catch (...) {
+            setError(PYHELIOS_ERROR_UNKNOWN, "ERROR (createVisualizer): Unknown error creating visualizer. This may indicate OpenGL/graphics initialization problems in headless environments.");
+            return nullptr;
+        }
     }
 
     Visualizer* createVisualizerWithAntialiasing(unsigned int width, unsigned int height, unsigned int samples, bool headless) {
-        // Enable window decorations by default (true), headless parameter controls window visibility  
-        return new Visualizer(width, height, samples, true, headless);
+        try {
+            clearError();
+            // Enable window decorations by default (true), headless parameter controls window visibility  
+            return new Visualizer(width, height, samples, true, headless);
+        } catch (const std::exception& e) {
+            setError(PYHELIOS_ERROR_RUNTIME, std::string("ERROR (createVisualizerWithAntialiasing): Failed to create visualizer: ") + e.what());
+            return nullptr;
+        } catch (...) {
+            setError(PYHELIOS_ERROR_UNKNOWN, "ERROR (createVisualizerWithAntialiasing): Unknown error creating visualizer. This may indicate OpenGL/graphics initialization problems in headless environments.");
+            return nullptr;
+        }
     }
 
     void destroyVisualizer(Visualizer* visualizer) {

native/src/pyhelios_wrapper_visualizer.cpp

@@ -23,9 +23,26 @@ class UVisualizer(ctypes.Structure):
     # Visualizer creation and destruction
     helios_lib.createVisualizer.argtypes = [ctypes.c_uint32, ctypes.c_uint32, ctypes.c_bool]
     helios_lib.createVisualizer.restype = ctypes.POINTER(UVisualizer)
+    
+    # Add errcheck to automatically handle errors and nulls
+    def _check_visualizer_creation(result, func, args):
+        if _ERROR_MANAGEMENT_AVAILABLE:
+            check_helios_error(helios_lib.getLastError, helios_lib.getLastErrorMessage)
+        if not result:
+            raise RuntimeError(
+                "Failed to create Visualizer. This may indicate:\n"
+                "1. OpenGL/graphics initialization problems in headless environments\n"
+                "2. Missing graphics drivers or display support\n" 
+                "3. Insufficient system resources for graphics context creation\n"
+                "4. XQuartz or display server configuration issues on macOS/Linux"
+            )
+        return result
+    
+    helios_lib.createVisualizer.errcheck = _check_visualizer_creation
 
     helios_lib.createVisualizerWithAntialiasing.argtypes = [ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_bool]
     helios_lib.createVisualizerWithAntialiasing.restype = ctypes.POINTER(UVisualizer)
+    helios_lib.createVisualizerWithAntialiasing.errcheck = _check_visualizer_creation
 
     helios_lib.destroyVisualizer.argtypes = [ctypes.POINTER(UVisualizer)]
     helios_lib.destroyVisualizer.restype = None
@@ -118,25 +135,21 @@ def create_visualizer(width: int, height: int, headless: bool = False) -> Option
         )
 
     try:
+        # The errcheck callback will handle error checking and null pointer validation
         visualizer = helios_lib.createVisualizer(
             ctypes.c_uint32(width),
             ctypes.c_uint32(height), 
             ctypes.c_bool(headless)
         )
-        _check_for_helios_error()
-        
-        if not visualizer:
-            raise RuntimeError("Failed to create Visualizer")
+        return visualizer
     except OSError as e:
         # Handle low-level system errors (e.g., graphics context failures)
         raise RuntimeError(
-            f"Visualizer plugin failed to initialize: {e}. "
+            f"Visualizer plugin failed to initialize due to system error: {e}. "
             "This may indicate missing graphics drivers, OpenGL issues, or "
             "incompatible system configuration. Try building with different options "
             "or check system requirements."
         )
-    
-    return visualizer
 
 def create_visualizer_with_antialiasing(width: int, height: int, antialiasing_samples: int, headless: bool = False) -> Optional[ctypes.POINTER(UVisualizer)]:
     """
@@ -161,18 +174,23 @@ def create_visualizer_with_antialiasing(width: int, height: int, antialiasing_sa
             "Rebuild with visualizer plugin enabled."
         )
 
-    visualizer = helios_lib.createVisualizerWithAntialiasing(
-        ctypes.c_uint32(width),
-        ctypes.c_uint32(height),
-        ctypes.c_uint32(antialiasing_samples),
-        ctypes.c_bool(headless)
-    )
-    _check_for_helios_error()
-    
-    if not visualizer:
-        raise RuntimeError("Failed to create Visualizer with antialiasing")
-    
-    return visualizer
+    try:
+        # The errcheck callback will handle error checking and null pointer validation
+        visualizer = helios_lib.createVisualizerWithAntialiasing(
+            ctypes.c_uint32(width),
+            ctypes.c_uint32(height),
+            ctypes.c_uint32(antialiasing_samples),
+            ctypes.c_bool(headless)
+        )
+        return visualizer
+    except OSError as e:
+        # Handle low-level system errors (e.g., graphics context failures)
+        raise RuntimeError(
+            f"Visualizer plugin failed to initialize due to system error: {e}. "
+            "This may indicate missing graphics drivers, OpenGL issues, or "
+            "incompatible system configuration. Try building with different options "
+            "or check system requirements."
+        )
 
 def destroy_visualizer(visualizer: ctypes.POINTER(UVisualizer)) -> None:
     """

pyhelios/wrappers/UVisualizerWrapper.py

@@ -394,8 +394,11 @@ def test_visualizer_context_manager_protocol(self):
 
             # Clean up
             visualizer.__exit__(None, None, None)
-        except VisualizerError:
-            # Expected in mock mode
+        except (VisualizerError, RuntimeError) as e:
+            # Expected in mock mode or when graphics initialization fails in CI
+            # Log the specific error for debugging
+            import sys
+            print(f"Visualizer initialization failed as expected in CI/mock mode: {e}", file=sys.stderr)
             pass
 
     def test_visualizer_method_signatures(self):
@@ -487,8 +490,8 @@ def visualizer_and_context(self):
             visualizer = Visualizer(400, 300, headless=True)
             visualizer.buildContextGeometry(context)
             yield visualizer, context, [patch1, patch2, patch3]
-        except VisualizerError as e:
-            pytest.skip(f"Visualizer plugin not available: {e}")
+        except (VisualizerError, RuntimeError) as e:
+            pytest.skip(f"Visualizer plugin not available or graphics initialization failed: {e}")
         finally:
             # Cleanup
             if 'visualizer' in locals():
@@ -622,13 +625,13 @@ def test_color_primitives_mock_mode_error(self):
             pytest.skip("Visualizer plugin available - not testing mock mode")
 
         # In mock mode, visualizer creation should fail
-        with pytest.raises(VisualizerError) as exc_info:
+        with pytest.raises((VisualizerError, RuntimeError)) as exc_info:
             Visualizer(400, 300, headless=True)
 
         error_msg = str(exc_info.value).lower()
-        # Error should mention rebuilding
+        # Error should mention rebuilding or graphics issues
         assert any(keyword in error_msg for keyword in 
-                  ['rebuild', 'build', 'enable', 'visualizer'])
+                  ['rebuild', 'build', 'enable', 'visualizer', 'opengl', 'graphics', 'initialize', 'create'])
 
 
 if __name__ == "__main__":