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:

# Launch empty GUI
lsurf gui

# Launch with a configuration file
lsurf gui simulation.yaml

The GUI requires additional dependencies. Install them with:

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:

    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