lsurf 1.0.0__py3-none-any.whl

lsurf/gui/views/visualizations.py

@@ -0,0 +1,712 @@
+# The Clear BSD License
+#
+# Copyright (c) 2026 Tobias Heibges
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted (subject to the limitations in the disclaimer
+# below) provided that the following conditions are met:
+#
+#      * Redistributions of source code must retain the above copyright notice,
+#      this list of conditions and the following disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#      * Neither the name of the copyright holder nor the names of its
+#      contributors may be used to endorse or promote products derived from this
+#      software without specific prior written permission.
+#
+# NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+# THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""Visualization panel - displays matplotlib plots of simulation results.
+
+Provides various visualization options for simulation results including
+detector heatmaps, timing histograms, and spatial distributions.
+"""
+
+from typing import TYPE_CHECKING, Callable
+import numpy as np
+
+import dearpygui.dearpygui as dpg
+
+if TYPE_CHECKING:
+    from lsurf.simulation import SimulationResult
+
+# Check for matplotlib
+try:
+    import matplotlib
+
+    matplotlib.use("Agg")  # Non-interactive backend for rendering to buffer
+    import matplotlib.pyplot as plt
+    from matplotlib.figure import Figure
+
+    HAS_MATPLOTLIB = True
+except ImportError:
+    HAS_MATPLOTLIB = False
+
+
+class VisualizationPanel:
+    """Panel for displaying matplotlib visualizations of simulation results."""
+
+    # Available visualization types
+    VISUALIZATIONS = [
+        ("detector_heatmap", "Detector Heatmap (X-Y)"),
+        ("detector_heatmap_xz", "Detector Heatmap (X-Z)"),
+        ("arrival_time", "Arrival Time Distribution"),
+        ("intensity_dist", "Intensity Distribution"),
+        ("wavelength_dist", "Wavelength Distribution"),
+        ("position_scatter", "Detection Positions (3D Projections)"),
+        ("time_vs_position", "Arrival Time vs Position"),
+    ]
+
+    def __init__(
+        self,
+        on_close: Callable[[], None] | None = None,
+    ) -> None:
+        """Initialize visualization panel.
+
+        Args:
+            on_close: Callback when panel is closed (to return to 3D view)
+        """
+        self._on_close = on_close
+        self._result: "SimulationResult | None" = None
+        self._detected = None  # Can also hold DetectorResult directly
+        self._window_tag: int | None = None
+        self._image_tag: int | None = None
+        self._texture_tag: int | None = None
+        self._current_viz: str = "detector_heatmap"
+        self._fig_width = 800
+        self._fig_height = 600
+
+    def create(self, parent: int | str) -> int:
+        """Create the visualization panel.
+
+        Args:
+            parent: Parent container tag
+
+        Returns:
+            The window tag
+        """
+        with dpg.child_window(
+            parent=parent,
+            tag="viz_panel",
+            height=-1,
+            horizontal_scrollbar=True,
+        ) as self._window_tag:
+            # Header with close button and visualization selector
+            with dpg.group(horizontal=True):
+                dpg.add_text("Visualizations", color=(100, 200, 255))
+                dpg.add_spacer(width=20)
+
+                # Visualization type selector
+                dpg.add_combo(
+                    items=[v[1] for v in self.VISUALIZATIONS],
+                    default_value=self.VISUALIZATIONS[0][1],
+                    callback=self._on_viz_changed,
+                    tag="viz_selector",
+                    width=250,
+                )
+
+                dpg.add_spacer(width=20)
+
+                # Load results button
+                dpg.add_button(
+                    label="Load Results...",
+                    callback=self._on_load_results,
+                )
+
+                dpg.add_spacer(width=10)
+
+                # Save results button
+                dpg.add_button(
+                    label="Save Results...",
+                    callback=self._on_save_results,
+                    tag="viz_save_btn",
+                )
+
+                dpg.add_spacer(width=10)
+
+                # Save plot button
+                dpg.add_button(
+                    label="Save Plot...",
+                    callback=self._on_save_plot,
+                    tag="viz_save_plot_btn",
+                )
+
+                dpg.add_spacer(width=10)
+
+                # Close button to return to 3D view
+                dpg.add_button(
+                    label="Back to 3D View",
+                    callback=self._on_close_clicked,
+                )
+
+            dpg.add_separator()
+
+            # Placeholder for when no results
+            dpg.add_text(
+                "Run a simulation or load results (.npz) to see visualizations",
+                color=(128, 128, 128),
+                tag="viz_placeholder",
+            )
+
+            # Container for the plot image
+            with dpg.group(tag="viz_image_container", show=False):
+                pass  # Image will be added dynamically
+
+        return self._window_tag
+
+    def show(self) -> None:
+        """Show the visualization panel."""
+        if self._window_tag and dpg.does_item_exist(self._window_tag):
+            dpg.show_item(self._window_tag)
+
+    def hide(self) -> None:
+        """Hide the visualization panel."""
+        if self._window_tag and dpg.does_item_exist(self._window_tag):
+            dpg.hide_item(self._window_tag)
+
+    def set_result(self, result: "SimulationResult | None") -> None:
+        """Set the simulation result to visualize.
+
+        Args:
+            result: Simulation result or None to clear
+        """
+        self._result = result
+        if result is not None:
+            self._detected = result.detected
+        else:
+            self._detected = None
+        self._update_visualization()
+
+    def set_detected(self, detected) -> None:
+        """Set DetectorResult directly for visualization.
+
+        Args:
+            detected: DetectorResult object or None to clear
+        """
+        self._result = None
+        self._detected = detected
+        self._update_visualization()
+
+    def _on_load_results(self) -> None:
+        """Handle load results button click."""
+
+        def callback(sender, app_data):
+            if app_data.get("file_path_name"):
+                file_path = app_data["file_path_name"]
+                self._load_results_file(file_path)
+
+        with dpg.file_dialog(
+            callback=callback,
+            width=800,
+            height=500,
+            modal=True,
+            show=True,
+        ):
+            dpg.add_file_extension(".npz", color=(0, 255, 0))
+            dpg.add_file_extension(".h5", color=(0, 200, 255))
+            dpg.add_file_extension(".hdf5", color=(0, 200, 255))
+
+    def _load_results_file(self, file_path: str) -> None:
+        """Load results from a file."""
+        try:
+            from lsurf.detectors.results import DetectorResult
+
+            if file_path.endswith(".npz"):
+                detected = DetectorResult.load_npz(file_path)
+            elif file_path.endswith((".h5", ".hdf5")):
+                detected = DetectorResult.load_hdf5(file_path)
+            else:
+                self._show_error(f"Unsupported file format: {file_path}")
+                return
+
+            self.set_detected(detected)
+
+        except Exception as e:
+            self._show_error(f"Failed to load results: {e}")
+
+    def _on_save_results(self) -> None:
+        """Handle save results button click."""
+        if self._detected is None or self._detected.is_empty:
+            self._show_error("No results to save")
+            return
+
+        def callback(sender, app_data):
+            if app_data.get("file_path_name"):
+                file_path = app_data["file_path_name"]
+                self._save_results_file(file_path)
+
+        with dpg.file_dialog(
+            callback=callback,
+            width=800,
+            height=500,
+            modal=True,
+            show=True,
+            default_filename="results.npz",
+        ):
+            dpg.add_file_extension(".npz", color=(0, 255, 0))
+            dpg.add_file_extension(".h5", color=(0, 200, 255))
+
+    def _save_results_file(self, file_path: str) -> None:
+        """Save results to a file."""
+        if self._detected is None:
+            return
+
+        try:
+            if file_path.endswith(".npz"):
+                self._detected.save_npz(file_path)
+            elif file_path.endswith((".h5", ".hdf5")):
+                self._detected.save_hdf5(file_path)
+            else:
+                # Default to npz
+                if not file_path.endswith(".npz"):
+                    file_path += ".npz"
+                self._detected.save_npz(file_path)
+
+        except Exception as e:
+            self._show_error(f"Failed to save results: {e}")
+
+    def _on_save_plot(self) -> None:
+        """Handle save plot button click."""
+        if self._detected is None or self._detected.is_empty:
+            self._show_error("No plot to save")
+            return
+
+        def callback(sender, app_data):
+            if app_data.get("file_path_name"):
+                file_path = app_data["file_path_name"]
+                self._save_plot_file(file_path)
+
+        with dpg.file_dialog(
+            callback=callback,
+            width=800,
+            height=500,
+            modal=True,
+            show=True,
+            default_filename="plot.png",
+        ):
+            dpg.add_file_extension(".png", color=(0, 255, 0))
+            dpg.add_file_extension(".pdf", color=(255, 100, 100))
+            dpg.add_file_extension(".svg", color=(100, 100, 255))
+
+    def _save_plot_file(self, file_path: str) -> None:
+        """Save current plot to a file."""
+        if not HAS_MATPLOTLIB:
+            return
+
+        try:
+            fig = self._create_figure()
+            if fig is None:
+                return
+
+            fig.savefig(file_path, dpi=150, bbox_inches="tight")
+            plt.close(fig)
+
+        except Exception as e:
+            self._show_error(f"Failed to save plot: {e}")
+
+    def _on_viz_changed(self, sender, app_data) -> None:
+        """Handle visualization type change."""
+        # Find the visualization key from the display name
+        for key, display_name in self.VISUALIZATIONS:
+            if display_name == app_data:
+                self._current_viz = key
+                break
+        self._update_visualization()
+
+    def _on_close_clicked(self) -> None:
+        """Handle close button click."""
+        if self._on_close:
+            self._on_close()
+
+    def _update_visualization(self) -> None:
+        """Update the displayed visualization."""
+        if not HAS_MATPLOTLIB:
+            self._show_error("matplotlib is required for visualizations")
+            return
+
+        if self._detected is None or self._detected.is_empty:
+            # Show placeholder
+            if dpg.does_item_exist("viz_placeholder"):
+                dpg.show_item("viz_placeholder")
+            if dpg.does_item_exist("viz_image_container"):
+                dpg.hide_item("viz_image_container")
+            return
+
+        # Hide placeholder, show image container
+        if dpg.does_item_exist("viz_placeholder"):
+            dpg.hide_item("viz_placeholder")
+        if dpg.does_item_exist("viz_image_container"):
+            dpg.show_item("viz_image_container")
+
+        # Generate the plot
+        fig = self._create_figure()
+        if fig is None:
+            return
+
+        # Render to texture and display
+        self._render_figure_to_texture(fig)
+        plt.close(fig)
+
+    def _create_figure(self) -> "Figure | None":
+        """Create the matplotlib figure for current visualization."""
+        if self._detected is None:
+            return None
+
+        detected = self._detected
+
+        # Dispatch to appropriate visualization function
+        viz_funcs = {
+            "detector_heatmap": self._plot_detector_heatmap,
+            "detector_heatmap_xz": self._plot_detector_heatmap_xz,
+            "arrival_time": self._plot_arrival_time,
+            "intensity_dist": self._plot_intensity_distribution,
+            "wavelength_dist": self._plot_wavelength_distribution,
+            "position_scatter": self._plot_position_scatter,
+            "time_vs_position": self._plot_time_vs_position,
+        }
+
+        func = viz_funcs.get(self._current_viz)
+        if func:
+            return func(detected)
+        return None
+
+    def _plot_detector_heatmap(self, detected) -> "Figure":
+        """Create detector heatmap (X-Y view)."""
+        fig, ax = plt.subplots(figsize=(8, 6), dpi=100)
+
+        positions = detected.positions
+        intensities = detected.intensities
+
+        # 2D histogram weighted by intensity
+        h = ax.hist2d(
+            positions[:, 0],
+            positions[:, 1],
+            bins=50,
+            weights=intensities,
+            cmap="hot",
+        )
+        plt.colorbar(h[3], ax=ax, label="Intensity")
+
+        ax.set_xlabel("X Position (m)")
+        ax.set_ylabel("Y Position (m)")
+        ax.set_title(f"Detector Heatmap (X-Y) - {detected.num_rays:,} rays")
+        ax.set_aspect("equal")
+
+        fig.tight_layout()
+        return fig
+
+    def _plot_detector_heatmap_xz(self, detected) -> "Figure":
+        """Create detector heatmap (X-Z view)."""
+        fig, ax = plt.subplots(figsize=(8, 6), dpi=100)
+
+        positions = detected.positions
+        intensities = detected.intensities
+
+        h = ax.hist2d(
+            positions[:, 0],
+            positions[:, 2],
+            bins=50,
+            weights=intensities,
+            cmap="hot",
+        )
+        plt.colorbar(h[3], ax=ax, label="Intensity")
+
+        ax.set_xlabel("X Position (m)")
+        ax.set_ylabel("Z Position (m)")
+        ax.set_title(f"Detector Heatmap (X-Z) - {detected.num_rays:,} rays")
+        ax.set_aspect("equal")
+
+        fig.tight_layout()
+        return fig
+
+    def _plot_arrival_time(self, detected) -> "Figure":
+        """Create arrival time histogram."""
+        fig, ax = plt.subplots(figsize=(8, 6), dpi=100)
+
+        times = detected.times
+        intensities = detected.intensities
+
+        # Convert to nanoseconds for readability
+        times_ns = times * 1e9
+
+        # Weighted histogram
+        ax.hist(times_ns, bins=50, weights=intensities, color="steelblue", alpha=0.7)
+
+        ax.set_xlabel("Arrival Time (ns)")
+        ax.set_ylabel("Intensity")
+        ax.set_title(f"Arrival Time Distribution - {detected.num_rays:,} rays")
+
+        # Add statistics
+        stats = detected.compute_statistics()
+        stats_text = (
+            f"Mean: {stats['mean_time']*1e9:.2f} ns\n"
+            f"Std: {stats['std_time']*1e9:.2f} ns\n"
+            f"Spread: {stats['time_spread']*1e9:.2f} ns"
+        )
+        ax.text(
+            0.95,
+            0.95,
+            stats_text,
+            transform=ax.transAxes,
+            verticalalignment="top",
+            horizontalalignment="right",
+            bbox=dict(boxstyle="round", facecolor="white", alpha=0.8),
+        )
+
+        fig.tight_layout()
+        return fig
+
+    def _plot_intensity_distribution(self, detected) -> "Figure":
+        """Create intensity distribution histogram."""
+        fig, ax = plt.subplots(figsize=(8, 6), dpi=100)
+
+        intensities = detected.intensities
+
+        # Use log scale if range is large
+        int_range = intensities.max() / (intensities.min() + 1e-10)
+        if int_range > 100:
+            ax.hist(
+                intensities[intensities > 0],
+                bins=50,
+                color="green",
+                alpha=0.7,
+                log=True,
+            )
+            ax.set_ylabel("Count (log scale)")
+        else:
+            ax.hist(intensities, bins=50, color="green", alpha=0.7)
+            ax.set_ylabel("Count")
+
+        ax.set_xlabel("Intensity")
+        ax.set_title(f"Intensity Distribution - {detected.num_rays:,} rays")
+
+        # Add statistics
+        stats_text = (
+            f"Total: {detected.total_intensity:.3e}\n"
+            f"Mean: {np.mean(intensities):.3e}\n"
+            f"Max: {np.max(intensities):.3e}"
+        )
+        ax.text(
+            0.95,
+            0.95,
+            stats_text,
+            transform=ax.transAxes,
+            verticalalignment="top",
+            horizontalalignment="right",
+            bbox=dict(boxstyle="round", facecolor="white", alpha=0.8),
+        )
+
+        fig.tight_layout()
+        return fig
+
+    def _plot_wavelength_distribution(self, detected) -> "Figure":
+        """Create wavelength distribution histogram."""
+        fig, ax = plt.subplots(figsize=(8, 6), dpi=100)
+
+        wavelengths = detected.wavelengths * 1e9  # Convert to nm
+        intensities = detected.intensities
+
+        ax.hist(wavelengths, bins=50, weights=intensities, color="purple", alpha=0.7)
+
+        ax.set_xlabel("Wavelength (nm)")
+        ax.set_ylabel("Intensity")
+        ax.set_title(f"Wavelength Distribution - {detected.num_rays:,} rays")
+
+        # Add statistics
+        mean_wl = np.average(wavelengths, weights=intensities)
+        stats_text = f"Mean: {mean_wl:.1f} nm\nRange: {wavelengths.min():.1f} - {wavelengths.max():.1f} nm"
+        ax.text(
+            0.95,
+            0.95,
+            stats_text,
+            transform=ax.transAxes,
+            verticalalignment="top",
+            horizontalalignment="right",
+            bbox=dict(boxstyle="round", facecolor="white", alpha=0.8),
+        )
+
+        fig.tight_layout()
+        return fig
+
+    def _plot_position_scatter(self, detected) -> "Figure":
+        """Create 3-panel position scatter plots."""
+        fig, axes = plt.subplots(1, 3, figsize=(12, 4), dpi=100)
+
+        positions = detected.positions
+        intensities = detected.intensities
+
+        # Normalize intensities for coloring
+        int_norm = intensities / (intensities.max() + 1e-10)
+
+        # Sample if too many points
+        max_points = 5000
+        if len(positions) > max_points:
+            idx = np.random.choice(len(positions), max_points, replace=False)
+            positions = positions[idx]
+            int_norm = int_norm[idx]
+
+        # X-Y view
+        sc = axes[0].scatter(
+            positions[:, 0],
+            positions[:, 1],
+            c=int_norm,
+            cmap="viridis",
+            s=2,
+            alpha=0.5,
+        )
+        axes[0].set_xlabel("X (m)")
+        axes[0].set_ylabel("Y (m)")
+        axes[0].set_title("X-Y View")
+        axes[0].set_aspect("equal")
+
+        # X-Z view
+        axes[1].scatter(
+            positions[:, 0],
+            positions[:, 2],
+            c=int_norm,
+            cmap="viridis",
+            s=2,
+            alpha=0.5,
+        )
+        axes[1].set_xlabel("X (m)")
+        axes[1].set_ylabel("Z (m)")
+        axes[1].set_title("X-Z View")
+        axes[1].set_aspect("equal")
+
+        # Y-Z view
+        axes[2].scatter(
+            positions[:, 1],
+            positions[:, 2],
+            c=int_norm,
+            cmap="viridis",
+            s=2,
+            alpha=0.5,
+        )
+        axes[2].set_xlabel("Y (m)")
+        axes[2].set_ylabel("Z (m)")
+        axes[2].set_title("Y-Z View")
+        axes[2].set_aspect("equal")
+
+        fig.colorbar(sc, ax=axes, label="Normalized Intensity", shrink=0.8)
+        fig.suptitle(f"Detection Positions - {detected.num_rays:,} rays")
+        fig.tight_layout()
+        return fig
+
+    def _plot_time_vs_position(self, detected) -> "Figure":
+        """Create time vs position plot."""
+        fig, axes = plt.subplots(1, 3, figsize=(12, 4), dpi=100)
+
+        positions = detected.positions
+        times = detected.times * 1e9  # ns
+        intensities = detected.intensities
+
+        # Sample if too many points
+        max_points = 5000
+        if len(positions) > max_points:
+            idx = np.random.choice(len(positions), max_points, replace=False)
+            positions = positions[idx]
+            times = times[idx]
+            intensities = intensities[idx]
+
+        # Normalize intensities for alpha
+        int_norm = intensities / (intensities.max() + 1e-10)
+
+        # Time vs X
+        sc = axes[0].scatter(
+            positions[:, 0], times, c=int_norm, cmap="plasma", s=2, alpha=0.5
+        )
+        axes[0].set_xlabel("X Position (m)")
+        axes[0].set_ylabel("Arrival Time (ns)")
+        axes[0].set_title("Time vs X")
+
+        # Time vs Y
+        axes[1].scatter(
+            positions[:, 1], times, c=int_norm, cmap="plasma", s=2, alpha=0.5
+        )
+        axes[1].set_xlabel("Y Position (m)")
+        axes[1].set_ylabel("Arrival Time (ns)")
+        axes[1].set_title("Time vs Y")
+
+        # Time vs Z
+        axes[2].scatter(
+            positions[:, 2], times, c=int_norm, cmap="plasma", s=2, alpha=0.5
+        )
+        axes[2].set_xlabel("Z Position (m)")
+        axes[2].set_ylabel("Arrival Time (ns)")
+        axes[2].set_title("Time vs Z")
+
+        fig.colorbar(sc, ax=axes, label="Normalized Intensity", shrink=0.8)
+        fig.suptitle(f"Arrival Time vs Position - {detected.num_rays:,} rays")
+        fig.tight_layout()
+        return fig
+
+    def _render_figure_to_texture(self, fig: "Figure") -> None:
+        """Render matplotlib figure to DearPyGui texture."""
+        # Render figure to RGB buffer
+        fig.canvas.draw()
+        width, height = fig.canvas.get_width_height()
+
+        # Get RGB buffer
+        buf = fig.canvas.buffer_rgba()
+        img_array = np.frombuffer(buf, dtype=np.uint8).reshape(height, width, 4)
+
+        # Convert to float for DearPyGui (RGBA, 0-1 range)
+        img_float = img_array.astype(np.float32) / 255.0
+
+        # Flatten for DearPyGui texture
+        texture_data = img_float.flatten().tolist()
+
+        # Clean up old texture if exists
+        if self._texture_tag and dpg.does_item_exist(self._texture_tag):
+            dpg.delete_item(self._texture_tag)
+        if self._image_tag and dpg.does_item_exist(self._image_tag):
+            dpg.delete_item(self._image_tag)
+
+        # Create texture registry if needed
+        if not dpg.does_item_exist("viz_texture_registry"):
+            dpg.add_texture_registry(tag="viz_texture_registry")
+
+        # Create new texture
+        self._texture_tag = dpg.add_dynamic_texture(
+            width=width,
+            height=height,
+            default_value=texture_data,
+            parent="viz_texture_registry",
+        )
+
+        # Add image to container
+        if dpg.does_item_exist("viz_image_container"):
+            dpg.delete_item("viz_image_container", children_only=True)
+            self._image_tag = dpg.add_image(
+                self._texture_tag,
+                parent="viz_image_container",
+            )
+
+    def _show_error(self, message: str) -> None:
+        """Show error message in panel."""
+        if dpg.does_item_exist("viz_placeholder"):
+            dpg.set_value("viz_placeholder", message)
+            dpg.configure_item("viz_placeholder", color=(255, 100, 100))
+            dpg.show_item("viz_placeholder")
+
+    def cleanup(self) -> None:
+        """Clean up resources."""
+        if self._texture_tag and dpg.does_item_exist(self._texture_tag):
+            dpg.delete_item(self._texture_tag)
+        if dpg.does_item_exist("viz_texture_registry"):
+            dpg.delete_item("viz_texture_registry")