lsurf 1.0.0__py3-none-any.whl

lsurf/gui/app.py

@@ -0,0 +1,903 @@
+# 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.
+
+"""L-SURF GUI Application - Main entry point.
+
+Provides the main window, menu bar, and coordinates all GUI components.
+"""
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import dearpygui.dearpygui as dpg
+
+# Lazy imports - these are loaded after splash screen is shown
+Scene = None
+SimulationRunner = None
+SimulationState = None
+ConfigEditorPanel = None
+ResultsPanel = None
+SceneTreePanel = None
+Viewport3D = None
+VisualizationPanel = None
+
+if TYPE_CHECKING:
+    from lsurf.geometry import Geometry
+    from lsurf.simulation import SimulationConfig
+    from lsurf.sources import RaySource
+
+    from .core.simulation import SimulationProgress
+
+
+def _load_components() -> None:
+    """Load heavy components after splash screen is shown."""
+    global Scene, SimulationRunner, SimulationState
+    global ConfigEditorPanel, ResultsPanel, SceneTreePanel, Viewport3D, VisualizationPanel
+
+    from .core.scene import Scene
+    from .core.simulation import SimulationRunner, SimulationState
+    from .views.config_editor import ConfigEditorPanel
+    from .views.results import ResultsPanel
+    from .views.scene_tree import SceneTreePanel
+    from .views.viewport_3d import Viewport3D
+    from .views.visualizations import VisualizationPanel
+
+
+class LSurfApp:
+    """Main L-SURF GUI application."""
+
+    def __init__(self) -> None:
+        self.scene = Scene()
+        self.simulation_runner = SimulationRunner()
+
+        # View components
+        self.viewport_3d: Viewport3D | None = None
+        self.scene_tree: SceneTreePanel | None = None
+        self.results: ResultsPanel | None = None
+        self.config_editor: ConfigEditorPanel | None = None
+        self.visualization: VisualizationPanel | None = None
+        self._showing_visualizations: bool = False
+
+        # Configuration state
+        self._config_path: Path | None = None
+        self._geometry: "Geometry | None" = None
+        self._source: "RaySource | None" = None
+        self._sim_config: "SimulationConfig | None" = None
+
+        # Font scaling
+        self._font_scale: float = 1.0  # Starting scale
+        self._min_font_scale: float = 0.5
+        self._max_font_scale: float = 5.0
+        self._font_scale_step: float = 0.25
+
+        # Register simulation callbacks
+        self.simulation_runner.on_progress(self._on_simulation_progress)
+        self.simulation_runner.on_complete(self._on_simulation_complete)
+
+    def setup(self) -> None:
+        """Set up Dear PyGui context and create the main window."""
+        dpg.create_context()
+
+        # Configure viewport (resizable window)
+        # Panel widths: left=280, right=480, center fills remaining
+        # Total fixed = 280 + 480 = 760, plus ~40 for borders/padding
+        dpg.create_viewport(
+            title="L-SURF - GPU Ray Tracing Visualization",
+            width=1920,
+            height=1080,
+            resizable=True,
+        )
+
+        # Load modern font
+        self._setup_font()
+
+        # Set dark theme
+        self._setup_theme()
+
+        # Create main window
+        self._create_main_window()
+
+        # Setup and show viewport
+        dpg.setup_dearpygui()
+        dpg.show_viewport()
+
+        # Set viewport resize callback to update main window
+        dpg.set_viewport_resize_callback(self._on_viewport_resize)
+
+        # Force initial resize to fill viewport properly
+        self._on_viewport_resize()
+
+    def _on_viewport_resize(self) -> None:
+        """Handle viewport resize - update main window and panels to fill viewport."""
+        width = dpg.get_viewport_client_width()
+        height = dpg.get_viewport_client_height()
+        if width > 0 and height > 0:
+            dpg.configure_item("main_window", width=width, height=height)
+
+            # Resize panels proportionally (left ~13%, right ~28%, center fills rest)
+            left_width = max(150, int(width * 0.13))
+            right_width = max(520, int(width * 0.28))
+
+            if dpg.does_item_exist("left_panel"):
+                dpg.configure_item("left_panel", width=left_width)
+            if dpg.does_item_exist("right_panel"):
+                dpg.configure_item("right_panel", width=right_width)
+            if dpg.does_item_exist("center_panel"):
+                # Center panel fills remaining space (negative width relative to right panel)
+                dpg.configure_item("center_panel", width=-right_width)
+
+            # Force viewport refresh to update drawlist size
+            if self.viewport_3d:
+                self.viewport_3d._size_printed = False  # Reset to re-print size
+                self.viewport_3d.refresh()
+
+    def _setup_font(self) -> None:
+        """Set up a modern font for the UI."""
+        import platform
+
+        # Try to find a modern sans-serif font
+        font_paths = []
+        system = platform.system()
+
+        if system == "Linux":
+            font_paths = [
+                "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+                "/usr/share/fonts/TTF/DejaVuSans.ttf",
+                "/usr/share/fonts/dejavu-sans-fonts/DejaVuSans.ttf",
+                "/usr/share/fonts/truetype/ubuntu/Ubuntu-R.ttf",
+                "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
+                "/usr/share/fonts/google-noto/NotoSans-Regular.ttf",
+                "/usr/share/fonts/noto/NotoSans-Regular.ttf",
+            ]
+        elif system == "Darwin":  # macOS
+            font_paths = [
+                "/System/Library/Fonts/SFNSText.ttf",
+                "/System/Library/Fonts/Helvetica.ttc",
+                "/Library/Fonts/Arial.ttf",
+            ]
+        elif system == "Windows":
+            font_paths = [
+                "C:/Windows/Fonts/segoeui.ttf",
+                "C:/Windows/Fonts/arial.ttf",
+                "C:/Windows/Fonts/calibri.ttf",
+            ]
+
+        # Find first available font
+        font_path = None
+        for path in font_paths:
+            if Path(path).exists():
+                font_path = path
+                break
+
+        # Load font or use default with scaling
+        if font_path:
+            with dpg.font_registry():
+                # Load at base size, will scale with global font scale
+                default_font = dpg.add_font(font_path, 18)
+            dpg.bind_font(default_font)
+
+        # Apply initial font scale
+        dpg.set_global_font_scale(self._font_scale)
+
+    def _increase_font_size(self) -> None:
+        """Increase the global font size."""
+        self._font_scale = min(
+            self._font_scale + self._font_scale_step, self._max_font_scale
+        )
+        dpg.set_global_font_scale(self._font_scale)
+
+    def _decrease_font_size(self) -> None:
+        """Decrease the global font size."""
+        self._font_scale = max(
+            self._font_scale - self._font_scale_step, self._min_font_scale
+        )
+        dpg.set_global_font_scale(self._font_scale)
+
+    def run(self) -> None:
+        """Run the main application loop."""
+        while dpg.is_dearpygui_running():
+            # Refresh viewport (for animation, camera updates, etc.)
+            if self.viewport_3d:
+                self.viewport_3d.refresh()
+
+            dpg.render_dearpygui_frame()
+
+        dpg.destroy_context()
+
+    def load_config(self, config_path: str | Path) -> bool:
+        """Load a configuration file (YAML or TOML).
+
+        Args:
+            config_path: Path to configuration file
+
+        Returns:
+            True if loaded successfully
+        """
+        config_path = Path(config_path)
+
+        if not config_path.exists():
+            self._show_error(f"File not found: {config_path}")
+            return False
+
+        try:
+            # Import config loading utilities
+            from lsurf.cli.config_schema import load_config_file
+
+            config = load_config_file(config_path)
+
+            # Build geometry
+            self._geometry = config.build_geometry()
+            self.scene.load_geometry(self._geometry)
+
+            # Build source
+            self._source = config.build_source()
+            self.scene.load_source(self._source)
+
+            # Store simulation config
+            self._sim_config = config.build_simulation_config()
+
+            self._config_path = config_path
+            self._update_title()
+
+            return True
+
+        except Exception as e:
+            self._show_error(f"Failed to load config: {e}")
+            return False
+
+    def run_simulation(self) -> bool:
+        """Run the simulation with current configuration.
+
+        Returns:
+            True if simulation started successfully
+        """
+        if self._geometry is None:
+            self._show_error("No geometry loaded. Load a configuration first.")
+            return False
+
+        if self._source is None:
+            self._show_error("No source loaded. Load a configuration first.")
+            return False
+
+        if self.simulation_runner.is_running():
+            self._show_error("Simulation already running.")
+            return False
+
+        # Clear previous results
+        if self.results:
+            self.results.clear()
+
+        # Start simulation
+        return self.simulation_runner.start(
+            self._geometry, self._source, self._sim_config
+        )
+
+    def _setup_theme(self) -> None:
+        """Set up the dark theme."""
+        with dpg.theme() as global_theme:
+            with dpg.theme_component(dpg.mvAll):
+                # Dark background
+                dpg.add_theme_color(dpg.mvThemeCol_WindowBg, (30, 30, 35, 255))
+                dpg.add_theme_color(dpg.mvThemeCol_ChildBg, (25, 25, 30, 255))
+                dpg.add_theme_color(dpg.mvThemeCol_FrameBg, (45, 45, 50, 255))
+                dpg.add_theme_color(dpg.mvThemeCol_FrameBgHovered, (60, 60, 70, 255))
+                dpg.add_theme_color(dpg.mvThemeCol_FrameBgActive, (70, 70, 80, 255))
+
+                # Headers
+                dpg.add_theme_color(dpg.mvThemeCol_Header, (60, 80, 120, 255))
+                dpg.add_theme_color(dpg.mvThemeCol_HeaderHovered, (70, 90, 140, 255))
+                dpg.add_theme_color(dpg.mvThemeCol_HeaderActive, (80, 100, 160, 255))
+
+                # Buttons
+                dpg.add_theme_color(dpg.mvThemeCol_Button, (60, 80, 120, 255))
+                dpg.add_theme_color(dpg.mvThemeCol_ButtonHovered, (80, 100, 150, 255))
+                dpg.add_theme_color(dpg.mvThemeCol_ButtonActive, (100, 120, 180, 255))
+
+                # Separators and borders
+                dpg.add_theme_color(dpg.mvThemeCol_Separator, (60, 60, 70, 255))
+                dpg.add_theme_color(dpg.mvThemeCol_Border, (50, 50, 60, 255))
+
+                # Text
+                dpg.add_theme_color(dpg.mvThemeCol_Text, (220, 220, 220, 255))
+                dpg.add_theme_color(dpg.mvThemeCol_TextDisabled, (128, 128, 128, 255))
+
+                # Slider/scroll
+                dpg.add_theme_color(dpg.mvThemeCol_SliderGrab, (80, 120, 180, 255))
+                dpg.add_theme_color(
+                    dpg.mvThemeCol_SliderGrabActive, (100, 140, 200, 255)
+                )
+
+                # Style
+                dpg.add_theme_style(dpg.mvStyleVar_FrameRounding, 4)
+                dpg.add_theme_style(dpg.mvStyleVar_WindowRounding, 6)
+                dpg.add_theme_style(dpg.mvStyleVar_ChildRounding, 4)
+                dpg.add_theme_style(dpg.mvStyleVar_FramePadding, 6, 4)
+                dpg.add_theme_style(dpg.mvStyleVar_ItemSpacing, 8, 6)
+
+        dpg.bind_theme(global_theme)
+
+    def _create_main_window(self) -> None:
+        """Create the main application window with all panels."""
+        # Get viewport size to fill it completely
+        vp_width = dpg.get_viewport_client_width() or 1920
+        vp_height = dpg.get_viewport_client_height() or 1080
+
+        with dpg.window(
+            tag="main_window",
+            no_title_bar=True,
+            no_move=True,
+            no_resize=False,  # Allow resizing
+            no_collapse=True,
+            width=vp_width,
+            height=vp_height,
+        ):
+            # Menu bar
+            self._create_menu_bar()
+
+            # Main content area - use horizontal group
+            # Window is 1920 wide, panels: left=250, center=flexible, right=520
+            with dpg.group(horizontal=True, tag="main_content"):
+                # Left panel: Scene tree (resizable width)
+                with dpg.child_window(
+                    width=250, height=-1, tag="left_panel", resizable_x=True
+                ):
+                    self.scene_tree = SceneTreePanel(self.scene)
+                    self.scene_tree.create("left_panel")
+
+                # Center: 3D Viewport / Visualizations + Results (takes remaining space)
+                with dpg.child_window(
+                    width=-520,
+                    height=-1,
+                    tag="center_panel",
+                    resizable_x=True,
+                    border=False,
+                ):
+                    # Toggle button for switching between 3D view and visualizations
+                    with dpg.group(horizontal=True):
+                        dpg.add_button(
+                            label="3D View",
+                            callback=lambda: self._show_3d_view(),
+                            tag="btn_3d_view",
+                        )
+                        dpg.add_button(
+                            label="Visualizations",
+                            callback=lambda: self._show_visualizations(),
+                            tag="btn_visualizations",
+                        )
+                    dpg.add_separator()
+
+                    # Container for viewport (shown by default)
+                    with dpg.group(tag="viewport_container", show=True):
+                        self.viewport_3d = Viewport3D(self.scene)
+                        self.viewport_3d.create("viewport_container")
+
+                    # Container for visualizations (hidden by default)
+                    with dpg.group(tag="viz_container", show=False):
+                        self.visualization = VisualizationPanel(
+                            on_close=self._show_3d_view,
+                        )
+                        self.visualization.create("viz_container")
+
+                    # Results panel at bottom (resizable height)
+                    self.results = ResultsPanel(self.scene)
+                    self.results.create("center_panel")
+
+                # Right panel: Config Editor (resizable width)
+                with dpg.child_window(
+                    width=520, height=-1, tag="right_panel", resizable_x=True
+                ):
+                    self.config_editor = ConfigEditorPanel(
+                        self.scene,
+                        on_config_change=self._on_config_editor_change,
+                        on_simulate=self._on_run_simulation,
+                        results_panel=self.results,
+                        visualization_panel=self.visualization,
+                    )
+                    self.config_editor.create("right_panel")
+
+        # Set primary window
+        dpg.set_primary_window("main_window", True)
+
+        # Register viewport mouse handlers (must be outside container context)
+        if self.viewport_3d:
+            self.viewport_3d.register_handlers()
+
+    def _on_config_editor_change(self) -> None:
+        """Handle config editor changes."""
+        # Update internal state from config editor
+        if self.config_editor:
+            self._geometry = self.scene.geometry
+            self._source = self.scene.source
+
+    def _show_3d_view(self) -> None:
+        """Show the 3D viewport and hide visualizations."""
+        self._showing_visualizations = False
+        if dpg.does_item_exist("viewport_container"):
+            dpg.show_item("viewport_container")
+        if dpg.does_item_exist("viz_container"):
+            dpg.hide_item("viz_container")
+        # Refresh viewport
+        if self.viewport_3d:
+            self.viewport_3d.refresh()
+
+    def _show_visualizations(self) -> None:
+        """Show the visualizations panel and hide 3D viewport."""
+        self._showing_visualizations = True
+        if dpg.does_item_exist("viewport_container"):
+            dpg.hide_item("viewport_container")
+        if dpg.does_item_exist("viz_container"):
+            dpg.show_item("viz_container")
+
+    def _create_menu_bar(self) -> None:
+        """Create the menu bar."""
+        with dpg.menu_bar():
+            with dpg.menu(label="File"):
+                dpg.add_menu_item(
+                    label="New Config",
+                    callback=self._on_new_config,
+                    shortcut="Ctrl+N",
+                )
+                dpg.add_menu_item(
+                    label="Open Config...",
+                    callback=self._on_open_config,
+                    shortcut="Ctrl+O",
+                )
+                dpg.add_menu_item(
+                    label="Save Config...",
+                    callback=self._on_save_config,
+                    shortcut="Ctrl+S",
+                )
+                dpg.add_menu_item(
+                    label="Reload Config",
+                    callback=self._on_reload_config,
+                    shortcut="Ctrl+R",
+                )
+                dpg.add_separator()
+                dpg.add_menu_item(
+                    label="Exit",
+                    callback=lambda: dpg.stop_dearpygui(),
+                    shortcut="Ctrl+Q",
+                )
+
+            with dpg.menu(label="View"):
+                dpg.add_menu_item(
+                    label="Fit to Scene",
+                    callback=self._on_fit_to_scene,
+                    shortcut="F",
+                )
+                dpg.add_separator()
+                dpg.add_menu_item(
+                    label="Increase Font Size",
+                    callback=lambda: self._increase_font_size(),
+                    shortcut="Ctrl++",
+                )
+                dpg.add_menu_item(
+                    label="Decrease Font Size",
+                    callback=lambda: self._decrease_font_size(),
+                    shortcut="Ctrl+-",
+                )
+                dpg.add_separator()
+                dpg.add_menu_item(
+                    label="Top View",
+                    callback=lambda: self._on_camera_preset("top"),
+                    shortcut="Numpad 7",
+                )
+                dpg.add_menu_item(
+                    label="Front View",
+                    callback=lambda: self._on_camera_preset("front"),
+                    shortcut="Numpad 1",
+                )
+                dpg.add_menu_item(
+                    label="Side View",
+                    callback=lambda: self._on_camera_preset("side"),
+                    shortcut="Numpad 3",
+                )
+                dpg.add_menu_item(
+                    label="Isometric View",
+                    callback=lambda: self._on_camera_preset("isometric"),
+                    shortcut="Numpad 5",
+                )
+                dpg.add_separator()
+                dpg.add_menu_item(
+                    label="Show 3D Viewport",
+                    callback=lambda: self._show_3d_view(),
+                    shortcut="1",
+                )
+                dpg.add_menu_item(
+                    label="Show Visualizations",
+                    callback=lambda: self._show_visualizations(),
+                    shortcut="2",
+                )
+
+            with dpg.menu(label="Simulation"):
+                dpg.add_menu_item(
+                    label="Run Simulation",
+                    callback=self._on_run_simulation,
+                    shortcut="F5",
+                )
+                dpg.add_menu_item(
+                    label="Cancel Simulation",
+                    callback=self._on_cancel_simulation,
+                    shortcut="Escape",
+                )
+                dpg.add_separator()
+                dpg.add_menu_item(
+                    label="Clear Results",
+                    callback=self._on_clear_results,
+                )
+
+            with dpg.menu(label="Help"):
+                dpg.add_menu_item(
+                    label="About",
+                    callback=self._on_about,
+                )
+                dpg.add_menu_item(
+                    label="Keyboard Shortcuts",
+                    callback=self._on_shortcuts,
+                )
+
+        # Register keyboard shortcuts
+        with dpg.handler_registry():
+            dpg.add_key_press_handler(
+                dpg.mvKey_O,
+                callback=lambda: (
+                    self._on_open_config()
+                    if dpg.is_key_down(dpg.mvKey_Control)
+                    else None
+                ),
+            )
+            dpg.add_key_press_handler(
+                dpg.mvKey_R,
+                callback=lambda: (
+                    self._on_reload_config()
+                    if dpg.is_key_down(dpg.mvKey_Control)
+                    else None
+                ),
+            )
+            dpg.add_key_press_handler(dpg.mvKey_F5, callback=self._on_run_simulation)
+            dpg.add_key_press_handler(dpg.mvKey_F, callback=self._on_fit_to_scene)
+            dpg.add_key_press_handler(
+                dpg.mvKey_Escape, callback=self._on_cancel_simulation
+            )
+            # Font size shortcuts: Ctrl++/Ctrl+- and numpad +/-
+            dpg.add_key_press_handler(
+                dpg.mvKey_Plus,  # + key
+                callback=lambda: (
+                    self._increase_font_size()
+                    if dpg.is_key_down(dpg.mvKey_LControl)
+                    or dpg.is_key_down(dpg.mvKey_RControl)
+                    else None
+                ),
+            )
+            dpg.add_key_press_handler(
+                dpg.mvKey_Minus,  # - key
+                callback=lambda: (
+                    self._decrease_font_size()
+                    if dpg.is_key_down(dpg.mvKey_LControl)
+                    or dpg.is_key_down(dpg.mvKey_RControl)
+                    else None
+                ),
+            )
+            # Also support numpad + and - (no Ctrl needed)
+            dpg.add_key_press_handler(
+                dpg.mvKey_Add,
+                callback=lambda: self._increase_font_size(),
+            )
+            dpg.add_key_press_handler(
+                dpg.mvKey_Subtract,
+                callback=lambda: self._decrease_font_size(),
+            )
+            # View toggle shortcuts: 1 for 3D, 2 for visualizations
+            dpg.add_key_press_handler(
+                dpg.mvKey_1,
+                callback=lambda: self._show_3d_view(),
+            )
+            dpg.add_key_press_handler(
+                dpg.mvKey_2,
+                callback=lambda: self._show_visualizations(),
+            )
+
+    def _on_new_config(self) -> None:
+        """Create a new empty configuration."""
+        if self.config_editor:
+            self.config_editor._on_new_config()
+        self._config_path = None
+        self._update_title()
+
+    def _on_open_config(self) -> None:
+        """Handle open config menu item."""
+
+        # Use file dialog
+        def callback(sender, app_data):
+            if app_data.get("file_path_name"):
+                file_path = app_data["file_path_name"]
+                # Load into config editor (which also applies to scene)
+                if self.config_editor:
+                    self.config_editor.load_from_file(file_path)
+                else:
+                    # Fallback if no config editor
+                    self.load_config(file_path)
+
+        with dpg.file_dialog(
+            callback=callback,
+            width=800,
+            height=500,
+            modal=True,
+            show=True,
+        ):
+            dpg.add_file_extension(".yaml", color=(0, 255, 0))
+            dpg.add_file_extension(".yml", color=(0, 255, 0))
+            dpg.add_file_extension(".toml", color=(0, 200, 255))
+
+    def _on_save_config(self) -> None:
+        """Save current configuration to file."""
+        if self.config_editor:
+            self.config_editor._on_export_yaml()
+
+    def _on_reload_config(self) -> None:
+        """Reload the current configuration file."""
+        if self._config_path:
+            self.load_config(self._config_path)
+        else:
+            self._show_error("No configuration file loaded.")
+
+    def _on_fit_to_scene(self) -> None:
+        """Fit camera to scene bounds."""
+        self.scene.fit_camera_to_scene()
+        if self.viewport_3d:
+            min_bounds, max_bounds = self.scene.get_bounds()
+            self.viewport_3d.camera.fit_to_bounds(min_bounds, max_bounds)
+            self.viewport_3d.refresh()
+
+    def _on_camera_preset(self, preset: str) -> None:
+        """Set camera to preset view."""
+        if self.viewport_3d:
+            self.viewport_3d.camera.set_preset(preset)
+            self.viewport_3d.refresh()
+
+    def _on_run_simulation(self) -> None:
+        """Run simulation."""
+        self.run_simulation()
+
+    def _on_cancel_simulation(self) -> None:
+        """Cancel running simulation."""
+        if self.simulation_runner.is_running():
+            self.simulation_runner.cancel()
+
+    def _on_clear_results(self) -> None:
+        """Clear simulation results."""
+        # Remove result objects from scene
+        from .core.scene import ObjectType
+
+        to_remove = [
+            name
+            for name, obj in self.scene.objects.items()
+            if obj.obj_type in (ObjectType.RAY_PATHS, ObjectType.DETECTIONS)
+        ]
+        for name in to_remove:
+            self.scene.remove_object(name)
+
+        self.scene.result = None
+        if self.results:
+            self.results.clear()
+
+    def _on_about(self) -> None:
+        """Show about dialog."""
+        with dpg.window(
+            label="About L-SURF",
+            modal=True,
+            width=400,
+            height=200,
+            no_resize=True,
+        ):
+            dpg.add_text("L-SURF GUI", color=(100, 200, 255))
+            dpg.add_text("GPU-Accelerated Ray Tracing Visualization")
+            dpg.add_separator()
+            dpg.add_text("Interactive 3D visualization for ray tracing simulations.")
+            dpg.add_text("")
+            dpg.add_text("Controls:")
+            dpg.add_text("  Left Mouse: Orbit camera")
+            dpg.add_text("  Middle Mouse: Pan camera")
+            dpg.add_text("  Right Mouse/Scroll: Zoom")
+            dpg.add_separator()
+            dpg.add_button(
+                label="Close",
+                callback=lambda s, a: dpg.delete_item(dpg.get_item_parent(s)),
+            )
+
+    def _on_shortcuts(self) -> None:
+        """Show keyboard shortcuts."""
+        with dpg.window(
+            label="Keyboard Shortcuts",
+            modal=True,
+            width=400,
+            height=440,
+            no_resize=True,
+        ):
+            shortcuts = [
+                ("Ctrl+O", "Open configuration file"),
+                ("Ctrl+S", "Save configuration file"),
+                ("Ctrl+R", "Reload configuration"),
+                ("F5", "Run simulation"),
+                ("Escape", "Cancel simulation"),
+                ("F", "Fit camera to scene"),
+                ("1", "Show 3D viewport"),
+                ("2", "Show visualizations"),
+                ("Ctrl++", "Increase font size"),
+                ("Ctrl+-", "Decrease font size"),
+                ("Numpad 7", "Top view"),
+                ("Numpad 1", "Front view"),
+                ("Numpad 3", "Side view"),
+                ("Numpad 5", "Isometric view"),
+            ]
+
+            for key, desc in shortcuts:
+                with dpg.group(horizontal=True):
+                    dpg.add_text(key, color=(255, 200, 100))
+                    dpg.add_spacer(width=20)
+                    dpg.add_text(desc)
+
+            dpg.add_separator()
+            dpg.add_button(
+                label="Close",
+                callback=lambda s, a: dpg.delete_item(dpg.get_item_parent(s)),
+            )
+
+    def _on_simulation_progress(self, progress: "SimulationProgress") -> None:
+        """Handle simulation progress updates."""
+        if self.results:
+            self.results.update_progress(progress)
+
+    def _on_simulation_complete(self, result) -> None:
+        """Handle simulation completion."""
+        if result is not None:
+            self.scene.load_result(result)
+            if self.results:
+                self.results.update_results(result)
+            # Update visualization panel with results
+            if self.visualization:
+                self.visualization.set_result(result)
+
+    def _update_title(self) -> None:
+        """Update viewport title with current file."""
+        title = "L-SURF - GPU Ray Tracing Visualization"
+        if self._config_path:
+            title = f"{self._config_path.name} - {title}"
+        dpg.set_viewport_title(title)
+
+    def _show_error(self, message: str) -> None:
+        """Show an error dialog."""
+        with dpg.window(
+            label="Error",
+            modal=True,
+            width=400,
+            height=150,
+            no_resize=True,
+        ):
+            dpg.add_text(message, wrap=380, color=(255, 100, 100))
+            dpg.add_separator()
+            dpg.add_button(
+                label="OK",
+                callback=lambda s, a: dpg.delete_item(dpg.get_item_parent(s)),
+                width=-1,
+            )
+
+
+def _show_splash_screen() -> None:
+    """Show a splash screen while loading."""
+    dpg.create_context()
+
+    # Create a minimal viewport for the splash
+    dpg.create_viewport(
+        title="L-SURF",
+        width=500,
+        height=300,
+        decorated=False,  # No window decorations for splash
+    )
+
+    # Create splash window
+    with dpg.window(
+        tag="splash_window",
+        no_title_bar=True,
+        no_resize=True,
+        no_move=True,
+        no_scrollbar=True,
+        no_collapse=True,
+        width=500,
+        height=300,
+    ):
+        dpg.add_spacer(height=60)
+        dpg.add_text(
+            "L-SURF",
+            color=(100, 200, 255),
+        )
+        dpg.add_spacer(height=20)
+        dpg.add_text(
+            "GPU Ray Tracing Visualization",
+            color=(180, 180, 180),
+        )
+        dpg.add_spacer(height=40)
+        dpg.add_text(
+            "Loading...",
+            tag="splash_status",
+            color=(128, 128, 128),
+        )
+        dpg.add_loading_indicator(
+            style=1,  # Circular style
+            radius=4.0,
+            color=(100, 200, 255, 255),
+        )
+
+    # Center the splash window
+    dpg.set_primary_window("splash_window", True)
+
+    dpg.setup_dearpygui()
+    dpg.show_viewport()
+
+    # Render one frame to show the splash
+    dpg.render_dearpygui_frame()
+
+
+def _update_splash_status(message: str) -> None:
+    """Update the splash screen status message."""
+    if dpg.does_item_exist("splash_status"):
+        dpg.set_value("splash_status", message)
+        dpg.render_dearpygui_frame()
+
+
+def launch_gui(config_path: str | Path | None = None) -> None:
+    """Launch the L-SURF GUI application.
+
+    Args:
+        config_path: Optional path to a configuration file to load on startup
+    """
+    # Show splash screen immediately
+    _show_splash_screen()
+
+    # Load components while splash is visible
+    _update_splash_status("Loading components...")
+    _load_components()
+
+    # Clean up splash and create main app
+    _update_splash_status("Initializing...")
+    dpg.stop_dearpygui()
+    dpg.destroy_context()
+
+    # Now create the main application
+    app = LSurfApp()
+    app.setup()
+
+    if config_path:
+        app.load_config(config_path)
+
+    app.run()