Graphical User Interface (GUI) ============================== L-SURF includes an interactive graphical user interface for configuring simulations, visualizing geometry, running simulations, and analyzing results. The GUI is built with Dear PyGui and provides a user-friendly way to work with the ray tracing system. Launching the GUI ----------------- Launch the GUI from the command line: .. code-block:: bash # Launch empty GUI lsurf gui # Launch with a configuration file lsurf gui simulation.yaml The GUI requires additional dependencies. Install them with: .. code-block:: bash pip install 'lsurf[gui]' Interface Overview ------------------ The GUI is organized into several panels: **Left Sidebar:** - **Scene Tree** - Hierarchical view of all objects in the scene (surfaces, detectors, sources, ray paths, detection results) - **Configuration Editor** - Tabbed interface for editing simulation parameters **Main Panel:** - **3D Viewport** - Interactive 3D visualization of geometry and ray paths - **Visualizations** - 2D plots for analyzing simulation results Use the toolbar buttons to switch between 3D view and visualizations, or use keyboard shortcuts (press ``1`` for 3D, ``2`` for visualizations). Scene Tree Panel ---------------- The scene tree shows all objects in your simulation: - **Surfaces** - Optical surfaces and their visibility - **Detectors** - Detection surfaces - **Sources** - Ray source configurations - **Ray Paths** - Traced ray trajectories (after simulation) - **Detections** - Recorded ray hits (after simulation) Each object has: - **Visibility checkbox** - Toggle visibility in the 3D view - **Selection** - Click to select and view/edit properties Configuration Editor -------------------- The configuration editor has four tabs: Surfaces Tab ~~~~~~~~~~~~ Add and configure optical surfaces: 1. Click **Add Surface** to create a new surface 2. Configure surface properties: - **Name** - Unique identifier for the surface - **Type** - Surface geometry (plane, sphere, bounded_plane, etc.) - **Role** - How the surface interacts with rays: - **optical** - Reflects and/or refracts rays (Fresnel equations) - **detector** - Records rays that hit (terminates them) - **absorber** - Terminates rays without recording - **Front Medium** - Material on the front side (normal direction) - **Back Medium** - Material on the back side - **Customize** - Open popup to customize material parameters 3. Set geometry-specific parameters (position, normal, radius, etc.) 4. Click **Remove** to delete a surface **Material Selection:** Each optical surface has front and back medium selections. Available materials: - vacuum, air, water, glass - exponential_atmosphere, duct_atmosphere - homogeneous (custom refractive index) Click the **Customize** button to modify material parameters like refractive index or absorption coefficient. Detectors Tab ~~~~~~~~~~~~~ Add and configure detection surfaces: 1. Click **Add Detector** to create a new detector 2. Configure detector properties: - **Name** - Unique identifier - **Type** - Detector geometry (planar, spherical, recording_sphere, etc.) - Geometry-specific parameters (center, radius, width, height, etc.) 3. Click **Remove** to delete a detector Source Tab ~~~~~~~~~~ Configure the ray source: - **Source Type** - Beam geometry: - **point** - Isotropic emission from a point - **collimated_beam** - Parallel rays - **diverging_beam** - Conical beam with angular spread - **gaussian_beam** - Gaussian intensity profile - **Position/Origin** - Source location in 3D space - **Direction** - Mean propagation direction (for directional sources) - **Divergence Angle** - Beam spread in degrees (for diverging sources) - **Number of Rays** - Total rays to generate - **Wavelength** - Light wavelength in nanometers - **Power** - Total source power (for intensity calculations) Simulation Tab ~~~~~~~~~~~~~~ Configure simulation parameters: **Stepping:** - **Step Size** - Maximum propagation step (meters) - **Min Step Size** - Minimum step for adaptive stepping (meters) - **Adaptive Stepping** - Use smaller steps near surfaces **Termination:** - **Max Bounces** - Maximum surface interactions before terminating - **Min Intensity** - Terminate rays below this intensity threshold - **Bounding Radius** - Terminate rays outside this radius **Hardware:** - **Use GPU** - Enable CUDA acceleration (recommended) - **Polarization** - s, p, or unpolarized **Output:** - **Directory** - Where to save results - **Prefix** - Filename prefix for output files - **Format** - hdf5, numpy, or csv **Actions:** - **Check Geometry** - Validate geometry for material consistency - **Simulate** - Run the simulation with current settings 3D Viewport ----------- The 3D viewport provides interactive visualization: **Navigation:** - **Left mouse drag** - Rotate view - **Right mouse drag** - Pan view - **Scroll wheel** - Zoom in/out - **Middle mouse drag** - Alternative pan **Display:** - Surfaces are rendered as wireframes or solid meshes - Detectors are shown with distinct colors - Ray paths (after simulation) show traced trajectories - Detection points are highlighted **Keyboard Shortcuts:** - ``1`` - Switch to 3D viewport - ``2`` - Switch to visualizations panel Visualizations Panel -------------------- After running a simulation, the visualizations panel provides analysis tools: **Available Plots:** - **Detector Heatmap (X-Y)** - 2D histogram of detection positions - **Detector Heatmap (X-Z)** - Alternative projection - **Arrival Time Distribution** - Histogram of ray arrival times - **Intensity Distribution** - Distribution of detected ray intensities - **Wavelength Distribution** - Distribution of detected wavelengths - **Detection Positions (3D Projections)** - X-Y, X-Z, Y-Z scatter plots - **Arrival Time vs Position** - Time as a function of position **Usage:** 1. Run a simulation (or load results from file) 2. Switch to the visualizations panel (press ``2`` or click toolbar) 3. Select a visualization type from the dropdown 4. Click **Generate** to create the plot 5. Use **Load Results** to load previously saved simulation results 6. Use **Save Results** to save current results for later analysis Running Simulations ------------------- To run a simulation from the GUI: 1. Configure surfaces, detectors, and source in the Configuration Editor 2. Set simulation parameters in the Simulation tab 3. (Optional) Click **Check Geometry** to validate material consistency 4. Click **Simulate** 5. Monitor progress in the status text 6. When complete, switch to Visualizations to analyze results The simulation runs the CLI ``lsurf run`` command internally, which: 1. Exports the current configuration to a temporary YAML file 2. Executes the simulation 3. Loads results for visualization Loading and Saving ------------------ **Configuration Files:** - Launch GUI with a config file: ``lsurf gui simulation.yaml`` - Export current configuration: Use File menu or configure output settings **Simulation Results:** - Results are saved to the configured output directory - Load previous results in the Visualizations panel with **Load Results** - Supported formats: ``.npz`` (numpy), ``.h5`` (hdf5) Typical Workflow ---------------- 1. **Launch GUI:** .. code-block:: bash lsurf gui 2. **Add surfaces:** - Go to Surfaces tab - Click Add Surface - Configure surface geometry and materials 3. **Add detectors:** - Go to Detectors tab - Click Add Detector - Position detector to capture rays of interest 4. **Configure source:** - Go to Source tab - Select beam type - Set position, direction, and ray count 5. **Set simulation parameters:** - Go to Simulation tab - Adjust step size and max bounces - Configure output directory 6. **Validate geometry:** - Click Check Geometry - Review any warnings about material inconsistencies 7. **Run simulation:** - Click Simulate - Wait for completion 8. **Analyze results:** - Press ``2`` to switch to Visualizations - Generate plots to analyze detection patterns Tips ---- - Use **Check Geometry** before running to catch material assignment issues - Start with fewer rays (1000-10000) for quick tests - Enable **Adaptive Stepping** for better accuracy near surfaces - Use **GPU acceleration** for large ray counts - Save configuration files for reproducibility