4.13. GUI Interaction¶

4.13.1. Loading the GUI¶

Initializing the GUI

First, we need to import the TraceGUI into the current namespace:

from optrace.gui.trace_gui import TraceGUI

Create an example geometry as follows:

RT = ot.Raytracer(outline=[-10, 10, -10, 10, -10, 60])

disc = ot.CircularSurface(r=3)
RS = ot.RaySource(disc, pos=[0, 0, -5])
RT.add(RS)

eye = ot.presets.geometry.legrand_eye()
RT.add(eye)

To create a TraceGUI, we need to pass the Raytracer as an argument:

sim = TraceGUI(RT)

Running the GUI

Run the GUI using:

sim.run()

This displays the main window and also raytraces the geometry if it hasn’t already been traced. Note that TraceGUI.run is a blocking operation.

Parameters

When creating the GUI, additional properties can be assigned. To set the scene to high contrast mode and increase the amount of rays, we can call:

sim = TraceGUI(RT, high_contrast=True, ray_count=2000000)

Available properties are discussed in Section 4.13.3.

Initial Camera View

The initial_camera parameter sets an initial camera view.

sim = TraceGUI(RT, high_contrast=True, ray_count=2000000,
               initial_camera=dict(center=[-50, -50, 0],
               direction=[-1, -1, -1], height=150, roll=-120))

These properties are directly passed to the TraceGUI.set_camera function. You can read more about the camera settings in Section 4.14.4.

4.13.2. UI Overview¶

4.13.2.1. Full UI¶

4.13.2.2. Scene¶

Overview

An overview of the mouse navigation and keyboard shortcuts is provided below.

Table 4.22 Available mouse and keyboards shortcuts inside the scene¶
Shortcut	Function
Mouse drag	Rotate the camera view
Mouse wheel	Zoom in or out
Shift + Mouse drag	Move the camera view
Ctrl + Mouse drag	Rotate the camera view around the center of the scene window
Keys `+` and `-`	Zoom in or out
Arrow keys	Move the camera view
Shift + arrow keys	Rotate the camera view around the left-right or top-bottom axis of the scene
Key `i`	Sets the scene view to default view set by GUI parameter `initial_camera` (y-side view if not provided)
Key `h`	Maximize scene (hides the sidebar)
Key `v`	Toggle minimalistic view option
Key `c`	Toggle high contrast mode
Key `b`	Toggle label visibility
Key `d`	Render detector image with the current settings
Key `0`	Close all open pyplot plots
Key `n`	Randomly re-choose the plotted rays

There are orientation axes in the bottom left of the scene that display the directions of the cartesian axes in the 3D view. The labels on the handles are clickable and set the camera to the corresponding view.

When an action/tasks is running, you are informed by a status text in the bottom right of the scene.

Picking and Clicking

After clicking a ray intersection on a surface, a list of properties on the selected ray section is displayed. The intersection position is also marked with a red crosshair, while the picked ray is highlighted in red. Even more properties are shown when using Shift + Click.

Right-clicking inside the scene displays the coordinates of the picked position. Shift + Right Click moves the currently selected detector to the picked z-position.

High Contrast Mode

Activate the high contrast mode to make the background white and show all other elements in grayscale. This is useful when creating scene views for academic output, as the background color in these documents is also white.

../_images/example_double_gauss.png — Fig. 4.68 Double Gauss example with `high_contrast`-mode enabled.¶

4.13.2.3. Sidebar¶

The sidebar is positioned at the right side of the scene and consists of multiple tabs:

Main Tab	Includes settings for raytracing, scene visualization and buttons for opening additional windows
Image Tab	Features options for rendering source and detector images
Spectrum Tab	Settings for the rendering of source or detector light spectrum histograms
Focus Tab	Focus search settings and results
Custom Tab	Custom UI elements be created before running the GUI

4.13.2.4. Additional Windows¶

There are additional windows in the interface besides the main window. These will be discussed in Section 4.13.4, but a quick overview is provided here:

Window	Access	Function
Command Window	Button in the main tab of the sidebar	Command execution and history for controlling the GUI and raytracer
Property Browser	Button in the main tab of the sidebar	Overview of raytracer, scene and ray properties as well as cardinal points

4.13.3. Sidebar Tabs¶

4.13.3.1. Main Tab¶

UI Property	Variable Name / Method	Values	Description
Rays	`ray_count`	`int`	number of rays for raytracing (count limited by `Raytracer.MAX_RAY_STORAGE_RAM`)
Plotting	`plotting_mode`	`'Rays'` or `'Points'`	visualization type of the rays
Coloring	`coloring_mode`	`'Plain', 'Power', 'Wavelength', 'Source', 'Polarization xz', 'Polarization yz', 'Refractive Index'`	quantity for color mapping
Count	`rays_visible`	`int, 1 - 50000`	number of visible rays in the scene
Opacity	`ray_opacity`	`float, 1e-05 - 1.0`	opacity of the rays/points
Width	`ray_width`	`float, 1.0 - 20.0`	ray width/ point size
More Minimalistic Scene	`minimalistic_view`	`True` or `False`	should axis labels and long descriptions be hidden
Maximize Scene	`maximize_scene`	`True` or `False`	should the sidebar be hidden
High Contrast Mode	`high_contrast`	`True` or `False`	plot dark elements on white background
Vertical Labels	`vertical_labels`	`True` or `False`	if object labels are justified vertically (in lateral direction)
Hide Labels	`hide_labels`	`True` or `False`	if object labels should be hidden
Open Property Browser	`open_property_browser()`		opens the property browser
Open Command Window	`open_command_window()`		opens the command window
Online Documentation	`open_documentation()`		opens the online documentation in a web browser

4.13.3.2. Image Tab¶

UI Property	Variable Name / Method	Values	Description
Source	`source_selection`	`str`	selection of the ray source
Detector	`detector_selection`	`str`	selection of the detector
z_det	`z_det`	`float`	position of the currently selected detector
Image Mode	`image_mode`	`str`, one of `RenderImage.image_modes`	image rendering mode
Projection Method	`projection_method`	`str`, one of `SphericalSurface.sphere_projection_methods`	sphere projection method for spherical detectors
Pixels_xy	`image_pixels`	`int`, one of `RImage.SIZES`	number of pixels in the smaller image dimension
Logarithmic Scaling	`log_image`	`True` or `False`	if image values should be scaled logarithmically
Flip Detector Image	`flip_detector_image`	`True` or `False`	if the detector image should be flipped (rotated by 180 degrees)
Rays from Selected Source Only	`detector_image_single_source`	`True` or `False`	if only the selected ray source should contribute to the image
Source Image	`source_image()`		renders a source image with the given settings
Detector Image	`detector_image()`		renders a detector image with the given settings
Cut at	`profile_position_dimension`	`'x', 'y'`	image profile dimension
Cut Value	`profile_position`	`float`	image profile value for the chosen dimension
Source Image Cut	`source_profile()`		renders a source image profile
Detector Image Cut	`detector_profile()`		renders a detector image profile
Activate Filter	`activate_filter`	`True` or `False`	activate the smoothing / resolution limit filter
Resolution Limit	`filter_constant`	`float, 0.3 - 40`	filter constant of the resolution limit filter

4.13.3.3. Spectrum Tab¶

UI Property	Variable Name / Method	Values	Description
Source	`source_selection`	`str`	the selected ray source
Detector	`detector_selection`	`str`	the selected detector
z_det	`z_det`	`float`	position of the selected detector
Source Spectrum	`source_spectrum()`		render a source spectrum for the chosen source
Rays from Selected Source Only	`detector_spectrum_single_source`	`True` or `False`	if only the selected ray source should contribute to the detector spectrum
Detector Spectrum	`detector_spectrum()`		render a detector image
Spectrum Properties			output field for spectrum properties

4.13.3.4. Focus Tab¶

UI Property	Variable Name / Method	Values	Description
Source	`source_selection`	`str`	the selected source
Detector	`detector_selection`	`str`	the selected detector
z_det	`z_det`	`float`	position of the selected detector
Focus Mode	`focus_search_method`	`str`, one of `Raytracer.focus_search_methods`	mode for focus search
Rays From Selected Source Only	`focus_search_single_source`	`True` or `False`	only use the rays from the selected source for focus search
Plot Cost Function	`plot_cost_function`	`True` or `False`	plots the evaluated cost function
Find Focus and move the currently selected detector to it	`move_to_focus()`		execute the focus search
Optimization Output			output for displaying optimization information

4.13.3.5. Custom Tab¶

optrace allows for the creation of custom UI elements in the “Custom” Tab that bind to user-defined functionality. Examples using such additional elements include the Image Render or Arizona Eye Model scripts.

The elements must be defined and added before running the TraceGUI. The following functions are available:

Method	Parameters	Description
`TraceGUI.add_custom_value`	title (`str`), default value (`float`), callable function	a textfield for setting a floating point value
`TraceGUI.add_custom_button`	title (`str`), callable function	a custom button that executes an action
`TraceGUI.add_custom_selection`	title (`str`), options (`list` of `str`), default value (`str`), callable function	a text selection field
`TraceGUI.add_custom_checkbox`	title (`str`), default state (`bool`), callable function	a checkbox boolean option

Changing the selection, checking the check box, or pressing the button automatically runs the underlying action. For a value field, the value is confirmed through either the loss of focus of the UI element or by pressing enter. The number of custom UI elements is limited to three of each type. The callable functions are an optional parameter (except for the button), which can be left empty or set to None. This can be useful when using a field as setting for another action.

The following example creates a custom button, checkbox, selection and value:

RT = ot.Raytracer(outline=[-5, 5, -10, 10, 0, 60])

# create geometry
...

# define custom actions

def change_aperture(RT, ap):
    ...

def change_test_image(RT, image):
    ...

def toggle_ray_info(RT, active):
    ...

# create the GUI
sim = TraceGUI(RT)

# add UI elements to "Custom Tab" in the TraceGUI
sim.add_custom_value("Aperture radius (1 - 3mm)", 2.0,
                     lambda ap: change_aperture(RT, ap))
sim.add_custom_selection("Test Image", ["Testcard", "Grid"], "Testcard",
                         lambda img: change_test_image(RT, img))
sim.add_custom_button("Detector Image", sim.detector_image)
sim.add_custom_checkbox("Print Ray Info", False, lambda b: toggle_ray_info(RT, b))

After that, the TraceGUI can be run normally with TraceGUI.run. Accessing or assigning these properties at runtime is described in Section 4.14.9.

4.13.4. Additional Windows¶

4.13.4.1. Property Viewer¶

The property viewer provides an interactive tree view of:

properties about the rays/points currently shown
cardinal points and other paraxial properties of the lenses and the whole lens setup
properties of the Raytracer class
available presets
TraceGUI properties
TraceGUI scene properties
TraceGUI scene actor properties

All displayed property values are read-only snapshots. To update the values, click on the Update button. Navigate the tabs to switch to different trees.

4.13.4.2. Command Window¶

Inside this window, commands can be defined and executed from inside the scope of the TraceGUI class. This allows for the scripting on the GUI and Raytracer at runtime, including adding, changing or removing geometries.

After entering a command in the upper text field, the Run-button needs to be pressed. Note that the command is only run, if the GUI is idle and not doing any other tasks.

After running the command, the scene is automatically updated and the geometry is retraced if the option “Retrace and replot automatically” is set. This can also be done manually with the Replot/Retrace Button.

The command is added to the history list in the lower part of the window. Copy each history field with Ctrl+C or export the whole history by pressing Copy History to Clipboard. There is also a Clear button available that empties the entire history.

All actions are run sequential to avoid race conditions and issues with scene rendering. This leads to the UI being unresponsive while running the command.

There are multiple object aliases to simplify coding inside the command window:

Table 4.23 Some object aliases¶
Alias	Reference
`GUI`	the TraceGUI object (same as `self`)
`scene`	the pyvista scene
`camera`	the camera of the pyvista scene
`RT`	the raytracer used
`LL`	the lens list of the raytracer
`AL`	the aperture list of the raytracer
`FL`	the filter list of the raytracer
`RSL`	the ray source list of the raytracer
`DL`	the detector list of the raytracer
`ML`	the marker list of the raytracer
`VL`	the volume list of the raytracer

For instance, you can write RT.remove(AL[1]) to remove the second aperture of tracing geometry. By default, you also have access to most optrace classes, e.g. Raytracer, RGBImage, Group, RingSurface, ....

To include custom objects in the class, you can simply pass them to the constructor:

var = 78.2353

def func():
    ...

sim = TraceGUI(RT, important_function=func, important_variable=var)

This also makes them available for usage inside the command window as GUI.important_function(), GUI.important_variable, ....