4.13. GUI Interaction¶

4.13.1. Loading the GUI¶

Initializing the GUI

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

from optrace.gui.trace_gui import TraceGUI

Let’s create some exemplary geometry:

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 argument:

sim = TraceGUI(RT)

Running the GUI

The GUI is run with:

sim.run()

This loads the main window and also raytraces the geometry if it hasn’t already been traced.

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

Details on the scene navigation are available in the mayavi documentation here under “Mouse Interaction”. Inside the scene in the bottom left you can find orientation axes, that display the directions of the cartesian axes in the 3D view. When an action/tasks is running, you are informed by a status text in the bottom right. A list of keyboard shortcuts is provided below.

Table 4.22 Available keyboards shortcuts inside the scene¶
Shortcut	Function
`i`	sets the scene view to default view set by GUI parameter initial_camera or the y-side view if not provided
`h`	maximize scene (hide toolbar and sidebar)
`v`	toggle minimalistic view option
`c`	toggle high contrast mode
`b`	toggle label visibility
`d`	render detector image with the current settings
`q`	close all open pyplot plots
`n`	randomly re-chose the plotted rays
`s`	save a screenshot of the scene
`f`	set the camera focal point to the position of the mouse. Useful for scene rotations, since the geometry is rotated around this point.
`l`	change lighting properties
`3`	anaglyph view (view for red-cyan 3D glasses)

Picking and Clicking

A list of properties for the selected ray is shown when clicking on the ray intersection of ray and surface. 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 point. Shift + Right Click moves the currently selected detector to the picked z-position.

High Contrast Mode

By activating the high contrast mode the background becomes white and all geometry elements grey or black. This is useful when creating scene views for academic output, as the background color in documents is also white.

../_images/example_double_gauss.png — Fig. 4.68 With `plot_dark_mode` enabled.¶

4.13.2.4. 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	Option View and result output for finding the focus in the optical setup
Custom Tab	Custom UI elements that can be created before running the GUI

The UI elements will be discussed in the following sections.

4.13.2.5. Additional Windows¶

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

Window	Access	Function
Pipeline View	Leftmost button in the toolbar	Access to viewing and editing the mayavi graphical elements
Scene Settings	Rightmost button in the toolbar	mayavi settings, including lighting and scene properties
Command Window	button at the bottom of the main tab in the sidebar	command execution and history for controlling the GUI and raytracer
Property Browser	button at the bottom of the main tab in 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¶

Property	Variable Name / Method	Values	Description
Rays	`ray_count`	`int, 0 - 6000000`	number of rays for raytracing
Plotting	`plotting_mode`	`'Rays'` or `'Points'`	visulation 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 - 1000`	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 tool- and side bar 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¶

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 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`	resolution filter filter constant

4.13.3.3. Spectrum Tab¶

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¶

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 with bindings to a function. Examples using such additional elements include Image Render or Arizona Eye Model.

The elements must be 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 value, selection or checkbox automatically calls the function after enter has been pressed. 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 of set to None. This can be useful when using a field as setting for another action.

The following examples 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. Pipeline View¶

The pipeline of the mayavi scene allows for the viewing and alteration of different geometry objects of the visible scene. For instance, you can change the colors or representation of different elements. Note that editing the visualization objects inside the scene is different from changing the geometry objects inside the Raytracer. The former does not update the underlying geometry and does not update the rays.

A more detailed information about the pipeline view and the different objects populating the view are available in the mayavi documentation.

4.13.4.2. Property Viewer¶

The property viewer provides an interactive tree view to the following properties:

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

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

4.13.4.3. Command Window¶

Inside this window commands can run from inside the TraceGUI class. Scripting on the GUI or change Raytracer properties is possible, like 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, therefore 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 th Replot/Retrace Button.

The command is added to the history 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 history.

The commands are run from within the TraceGUI object. To avoid race conditions and issues with scene rendering, all actions are run sequential. This leads to the UI being unresponsive while running the command.

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

Table 4.23 Some object aliases¶
Alias	Reference
`GUI`	the TraceGUI object (same as `self`)
`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, inside the command window 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 in the command window as GUI.important_function(), GUI.important_variable, ....