========================== User Interface Walkthrough ========================== **navigate**'s user interface is modular, and designed to be reconfigurable to a user's preferences. At a high level, it is split into a menu bar, an acquisition bar, settings notebooks, and display notebooks. .. image:: images/home_screen.png ----------------- Menu Bar ======== The menu bar is an entry point for much of **navigate**. File ---- .. image:: images/menu_file.png The :guilabel:`File` menu lets a user create, load and save :ref:`experiment files `, which store the states of the GUI and the hardware. The menu also provides an option to load and save :ref:`waveform constants files ` to store the waveform constants used for a given experiment. This is useful if a user wants to perform an experiment with the same parameters multiple times, but close the software in between acquisitions. To facilitate reproducibility, `experiment.yml` and `waveform_constants.yml` files are always saved with the collected image data. The :guilabel:`File` menu also provides access to toggle the :guilabel:`Save Data` flag, also found under :guilabel:`Timepoint Settings` in the :guilabel:`Channels Settings Notebook`, and to start an acquisition (which can also be done by pressing :guilabel:`Acquire` in the :ref:`user_guide/gui_walkthrough:acquisition bar`). Loading and unloading images only works if there is a :ref:`synthetic camera `. In this case, the camera loads images to display in lieu of the simulated noise usually generated by the synthetic camera. :guilabel:`Open Log Files` opens the folder containing the software's log files. This is helpful for debugging code and configuration problems. :guilabel:`Open Configuration Files` opens the folder containing the software's :ref:`configuration file `. ----------------- Microscope Configuration ------------------------ .. image:: images/menu_microscope_configuration.png The :guilabel:`Microscope Configuration` menu is split into two parts, above and below the horizontal divider. Above the horizontal divider it lists the names of all microscopes named in the ``microscopes`` section of the :ref:`configuration file `. This allows users to readily switch between different microscopes, each with their own hardware configurations. Mousing over a microscope name reveals all zoom values available under the :ref:`Mechanical Zoom `. Selecting one of these zoom values changes the magnification of the microscope. Below the horizontal divider is access to the :ref:`Waveform Parameters ` settings panel and the :ref:`Configure Microscope ` settings panel. ------------------- .. _stage_control_menu: Stage Control ------------- .. image:: images/menu_stage_control.png The stage control menu is split by horizontal dividers into three parts. The top part provides similar functionality to the :ref:`Stage Control Settings Notebook `. It allows movement of the stage along ``X``, ``Y``, ``Z``, ``focus`` and ``Theta``. The ``w``, ``s``, ``a`` and ``d`` keys are bound to movement in ``X`` and ``Y``, and these can be used to scroll around a sample. The middle part provides similar functionality to the :ref:`Multiposition Settings Notebook `. Here, a user can launch the :ref:`Tiling Wizard `, load and export (save) positions stored in the :guilabel:`Multiposition Settings Notebook`, and add the current stage position to the multiposition table. The bottom part of the menu is used to enable and disable the stage limits set in the configuration file (see the :ref:`stage subsection `). ------------------- Autofocus --------- .. image:: images/menu_autofocus.png The autofocus menu has two options: :guilabel:`Perform Autofocus`, which autofocus the sample using the current autofocus settings, and :guilabel:`Autofocus Settings`, which launches the :ref:`Autofocus Settings ` popup. ------------------- Features -------- .. image:: images/menu_features.png This menu provides access to acquisition feature lists. An explanation of features, feature lists, and the use and operation of this menu is provided under :doc:`Reconfigurable Acquisitions Using Features `. ------------------- Plugins ------- .. image:: images/menu_plugins.png This menu provides an access point for :doc:`plugins <../plugin/plugin_home>` that feature a popup GUI. ------------------- Window ------ .. image:: images/menu_window.png This menu is split into two parts by a horizontal divider and provides some GUI controls. The top part allows the user to switch between the main :ref:`Settings Notebooks `. The bottom part provides an option to move the camera display to a popup window and :guilabel:`Help` brings the user to the online documentation for **navigate**. ------------------- Acquisition Bar =============== Left-to-right, the acquisition bar provides * An :guilabel:`Acquire` button, which starts acquisition. * A drop-down menu providing a selection of acquisition modes. * A progress bar indicating how far the program has made it through an acquisition. The top bar indicates progress on the current z-stack, whereas the bottom indicates progress for the entire acquisition. * An approximate estimate of how much time is left in the acquisition. * An emergency :guilabel:`Stop Stage` button, which instantly halts all stage movement. * An :guilabel:`Exit Button`, which quits the software. ------------------- Settings Notebooks ================== The settings notebooks are a series of tabs that control microscope settings, including laser power, camera settings and stage positions and many others. ------------------- Channels -------- .. image:: images/settings_channels.png The :guilabel:`Channels` Settings Notebook is a tab (optionally, a popup if right-clicked on) split into five sections: :guilabel:`Channel Settings`, :guilabel:`Stack Acquisition Settings (µm)`, :guilabel:`Timepoint Settings`, :guilabel:`Multi-Position Acquisition` and :guilabel:`Quick Launch Buttons`. ------------------- Channel Settings ^^^^^^^^^^^^^^^^ This is used to set up acquisition color channels. A channel is considered to be a combination of an illuminating laser wavelength and a detection filter. Each channel has its own power, exposure time, interval and defocus. The checkbox on the left indicates if a channel should be used (is selected) during acquisition. An acquisition may loop through the channels in sequence. * :guilabel:`Laser` is the name of the laser, taken from the :doc:`configuration file `, and usually expressed in nanometers. * :guilabel:`Power` is the power of the laser between 0 and 100 percent. * :guilabel:`Filter` is the name of the filter selected in the detection path filter wheel. Filter names are stored in the configuration file. * :guilabel:`Exp. Time (ms)` is the exposure time of the camera in milliseconds. * :guilabel:`Interval` indicates how often this channel should be used in an acquisition. For example, in two-color imaging, CH1 may image a process twice as fast as what is labelled in CH2. Setting the CH2 interval to 2 allows a user to image the processes in both channels at a similar rate. This will be implemented in future releases of the software. * :guilabel:`Defocus` indicates the defocus between two channels in micrometers. The defocus values are always relative to the focus of the first channel imaged. This setting is useful for compensating for chromatic aberration. ------------------- Stack Acquisition Settings ^^^^^^^^^^^^^^^^^^^^^^^^^^ These are the settings used for a standard Z-Stack Acquisition. :guilabel:`Pos` indicates z-positions. :guilabel:`Foc` indicates focus positions. The z-stack can optionally ramp through ``focus`` along with ``Z``. :guilabel:`Start` and :guilabel:`End` are always expressed relative to the center of the z-stack. :guilabel:`Abs Z Start` and :guilabel:`Abs Z Stop` provide true stage positions at the start and end of the z-stack. The buttons :guilabel:`Set Start Pos/Foc` and :guilabel:`Set End Pos/Foc` grab the current ``Z`` and ``focus`` positions from the stage and enter them into the corresponding start and end (stop) GUI boxes. The :guilabel:`Step Size` is expressed in microns and can be modified by the user. Upon modification, :guilabel:`# slices` will automatically update. :guilabel:`Laser Cycling Settings` provide the options "Per Stack" and "Per Z". In "Per Stack" mode, the software will move through all positions before changing to another color channel. In "Per Z" mode, the software will acquire all color channels selected before moving to the next position in the z-stack. ------------------- Timepoint Settings ^^^^^^^^^^^^^^^^^^ These are used for acquiring data over multiple timepoints and for toggling the option to save data. * :guilabel:`Save Data` tells the software to save acquired data to disk when checked. If this is selected, a :ref:`saving popup window ` will appear when :guilabel:`Acquire` is pressed, unless the user is in "Continuous Scan" mode, which is designed for live previews only. * :guilabel:`Timepoints` indicates how many time points this acquisition should acquire. * :guilabel:`Stack Acq Time` provides an estimate of how long a single z-stack will take to acquire. * :guilabel:`Stack Pause (s)` indicates how much waiting time the software should introduce in between acquisition steps (e.g. in between taking z-stacks). * :guilabel:`Time Interval (hh:mm:ss)` provides an estimate of how long each time point takes to acquire. This is (stack acquisition + stack pause) x number of channels to image. * :guilabel:`Experiment Duration (hh:mm:ss)` provides an estimate of how long the full acquisition will take. .. Note:: The :guilabel:`Stack Acq Time` and :guilabel:`Experiment Duration (hh:mm:ss)` do not account for stage movement time. Thus, for stages with serial communication protocols, or stages with slow movement, these estimates will be an underestimate. Future releases will account for stage movement time to provide a more accurate estimate. ------------------- Multi-Position Acquisition ^^^^^^^^^^^^^^^^^^^^^^^^^^ This contains settings to set up acquisition over multiple positions in the sample, e.g. tiling. * :guilabel:`Enable` indicates that the software should move through the positions listed in the :ref:`Multiposition Settings Notebook ` during the acquisition. * :guilabel:`Launch Tiling Wizard` launches the :ref:`Tiling Wizard `. ------------------- Quick Launch Buttons ^^^^^^^^^^^^^^^^^^^^ This provides access to the :ref:`Waveform Parameters ` and :ref:`Autofocus Settings ` popups. ------------------- Camera Settings --------------- .. image:: images/settings_camera.png The :guilabel:`Camera Settings` Notebook is a tab (optionally, a popup) that controls the camera. It is split into three sections: :guilabel:`Camera Modes`, :guilabel:`Framerate Info` and :guilabel:`Region of Interest Settings`. ------------------- Camera Modes ^^^^^^^^^^^^ The :guilabel:`Camera Modes` section is designed for switching between normal mode of operation, where the camera exposes all pixels semi-simultaneously, and light-sheet mode (a.k.a rolling shutter mode), where the camera exposes only a few pixels at a time, and progressively images from the top to the bottom of the camera chip or vice versa. * :guilabel:`Sensor Mode` is used to switch between "Normal" and "Light-Sheet" modes. * :guilabel:`Readout Direction` indicates if the rolling shutter should move from the bottom to the top of the camera chip or vice versa. * :guilabel:`Number of Pixels` sets the rolling shutter width of the camera. ------------------- Framerate Info ^^^^^^^^^^^^^^ This displays information concerning the speed of acquisition and optionally allows the user to average these values over multiple images. * :guilabel:`Exposure Time (ms)` displays the set camera exposure time. * :guilabel:`Readout Time (ms)` displays how long it takes to read a frame from the camera. This includes exposure time. * :guilabel:`Framerate (Hz)` displays how long it takes to acquire an image. This is based on an internal "wait ticket" approach, where the software times how long it waits for a frame to come in after receiving the previous frame. This frequency includes not only camera readout time, but, e.g. how long the software had to wait for the stage to finish moving before taking the next image in a z-stack. It is the most accurate time estimate in the software. * :guilabel:`Images to Average` tells the camera to average frames. This will be implemented in future releases of the software. ------------------- Region of Interest Settings ^^^^^^^^^^^^^^^^^^^^^^^^^^^ These allows the user to set the size of the region of interest in pixels. The camera can also be told to bin pixels. The corresponding field of view is displayed by calculating the number of pixels multiplied by the camera's effective pixel size, which is set in the :ref:`Mechanical Zoom ` section of the configuration file. :guilabel:`Default FOVs` includes buttons to quickly change the FOV to preset values. :guilabel:`ROI center` indicates about what point the pixels crop on the camera. ------------------- .. _stage_control_notebook: Stage Control ------------- .. image:: images/settings_stage.png The :guilabel:`Stage Control` Settings Notebook is a tab (optionally, a popup) that controls the stage positions. It is split into six parts: :guilabel:`Stage Positions`, :guilabel:`X Y Movement`, :guilabel:`Z Movement`, :guilabel:`Focus Movement`, :guilabel:`Theta Movement`, and includes an emergency :guilabel:`STOP` button, as well as a button to :guilabel:`Enable Joystick`/:guilabel:`Disable Joystick`. .. Note:: * The joystick button will only appear if the ``configuration.yaml`` file specifies which axes are controlled by the joystick. For example: .. code-block:: yaml stage: hardware: - name: stage type: PI axes: [x, y, z, theta, f] axes_mapping: [1, 2, 3, 4, 5] joystick_axes: [x, y, z] * Any stage axes that are loaded as a `synthetic_stage` will have disabled buttons. By default, the stage is expected to have ``X``, ``Y``, ``Z``, ``Focus`` and ``Theta`` (rotation) axes. If a stage does not have one of these axes, the user can choose to not use that control. See the :ref:`stage subsection ` for more information. ------------------- Stage Positions ^^^^^^^^^^^^^^^ The entry boxes report the current position of each stage axis. If a user changes a value in an entry box, the stage axis will move to that value (provided it is within the stage bounds if stage limits are enabled, see :any:`here `). .. Warning:: If the value in the entry box is changed, the stage will move to that value. Such actions may result in the stage crashing into the sample or the objective lens. As such, we highly recommend that you keep the stage limits enabled. ------------------- XY Movement ^^^^^^^^^^^ This includes the movement buttons for the ``X`` and ``Y`` axes. The left and right buttons control ``X``, while the up and down buttons control ``Y.`` The entry box in the middle of the buttons indicates the step size along these axes in microns. It can be changed by the user. ------------------- Z Movement ^^^^^^^^^^ This controls the movement of the ``Z`` stage. The entry box indicates the step size along this axis and it can be changed by the user. ------------------- Focus Movement ^^^^^^^^^^^^^^ This controls the movement of the ``Focus`` stage. The entry box indicates the step size along this axis and it can be changed by the user. ------------------- Theta Movement ^^^^^^^^^^^^^^ This controls the movement of the ``Theta`` stage (i.e., sample rotation). The entry box indicates the step size along this axis and it can be changed by the user. ------------------- Buttons ^^^^^^^ The :guilabel:`STOP` button halts all stage axes and updates the stage positions to wherever the stage stopped. The :guilabel:`Enable Joystick` button disables control over the axes associated with the joystick (see the :ref:`stage subsection `). .. note:: It is not necessary to press this button to use a joystick. The joystick can be used along with the software controls. However, if a user is running the acquisition in "Continuous Scan" mode and uses the joystick without pressing :guilabel:`Enable Joystick`, the stage positions may not update unless :guilabel:`STOP` is also pressed. In "Continuous Scan" mode, if a user tries to move with the joystick and then the software stage controls without first pressing :guilabel:`STOP`, it is likely the stage will update to the software's position of choice and undo the joystick movement. .. tip:: For a large monitor, it is often helpful to convert the :guilabel:`Stage Control Settings Notebook` to a popup. Right click on the tab and press :guilabel:`Popout Tab`. .. image:: images/popout_right_click.png | Once this is done, it should be possible to move the stage controls next to the main **navigate** window. .. image:: images/popout_stage.png ------------------- Multiposition ------------- .. image:: images/settings_multiposition.png The :guilabel:`Multiposition` Settings Notebook is a tab (optionally, a popup) that helps the user set up and visualize a multi-position acquisition for tiling a large sample. It it split into two parts: buttons and the multi-position table. ------------------- Buttons ^^^^^^^ * :guilabel:`Launch Tiling Wizard` launches the :ref:`Tiling Wizard ` * :guilabel:`Eliminate Empty Positions` is not implemented and does nothing. * :guilabel:`Save Positions To Disk` saves the multi-position table to a file. * :guilabel:`Load Positions From Disk` loads a multi-position file into the table. ------------------- Multi-Position Table ^^^^^^^^^^^^^^^^^^^^ The multi-position table lists stage positions that are included in a multi-position acquisition. * :kbd:`Double-clicking` on the integer to the left of a row moves the stage to that position. * :kbd:`Double-clicking` on a table cell allows the user to edit the stage position in that cell. * :kbd:`Right-clicking` on the integer to the left of a row yields a popup with four options: .. image:: images/multiposition_right_click.png * :guilabel:`Insert New Position` adds an empy row to the table. * :guilabel:`Add Current Position` adds a row containing the current stage position to the table. * :guilabel:`Add New Position(s)` yields a popup that asks the user how many new rows to add and then inserts that number of empty rows upon confirmation. * :guilabel:`Delete Position(s)` deletes the selected positions. Selection is indicated by a blue highlight of the integer to the left of a row. ------------------- Display Notebooks ================== The display notebooks provide visual feedback of the images taken on the camera and of the galvo and remote focus waveforms sent to the DAQ. ------------------- Camera View ----------- .. image:: images/display_camera.png The :guilabel:`Camera View` Notebook is is a tab (optionally, a popup) that is split into two parts. The left part displays the latest image acquired by the camera. The right part modifies this display and is split into :guilabel:`LUT`, :guilabel:`Image Metrics`, and :guilabel:`Image Display`. :kbd:`Left-clicking` on the image toggles crosshairs that indicate the center of the field of view. ------------------- LUT ^^^ The :guilabel:`LUT` section of the camera view allows the user to change the lookup table the image uses to display. The options are :guilabel:`Gray`, :guilabel:`Gradient` and :guilabel:`Rainbow`. :guilabel:`Flip XY` transposes the image in the display. This can produce intuitive results in the display when clicking on the ``X`` or ``Y`` stage movements buttons (i.e. with :guilabel:`Flip XY` enabled, the sample moves along the direction expected when a stage movement button is clicked). :guilabel:`Autoscale` toggles automatic image histogram scaling on and off. When :guilabel:`Autoscale` is enabled, the image automatically scales intensity between the minimum and maximum pixel value in the image produced by the camera. When :guilabel:`Autoscale` is disabled, the image is scaled between :guilabel:`Min Counts` and :guilabel:`Max Counts`. ------------------- Image Metrics ^^^^^^^^^^^^^ :guilabel:`Frames to Avg` is unimplemented, but should average this many frames coming from the camera and display the average in the viewer. It will be implemented in future releases of the software. :guilabel:`Image Max Counts` displays the maximum pixel count in the image. :guilabel:`Channel` indicates which color channel is displayed. It indexes into the selected channels in the :ref:`Channel Settings ` (i.e. ``0`` is the first selected channel). ------------------- Image Display ^^^^^^^^^^^^^ This should toggle in between live mode and maximum projections in multiple dimensions, but it is currently not implemented. This is useful for visual inspection of the data as it is being acquired, and will be implemented in future releases of the software. ------------------- Waveform Settings ----------------- .. image:: images/display_waveform.png :guilabel:`Waveform Settings` is a tab (optionally, a popup) split into two sections: a waveform display section at the top and a :guilabel:`Settings` section at the bottom. ------------------- Waveform Display ^^^^^^^^^^^^^^^^ The waveform display shows the waveforms sent to the remote focus devices (top) and the galvos (bottom). Each channel and each device gets its own color, which is then displayed in the legend. The dotted black line indicates when the camera is acquiring in relation to the waveforms. This can be considered identical to what is sent to the DAQ. ------------------- Settings ^^^^^^^^ :guilabel:`Sample Rate` changes the frequency of the samples sent to the DAQ. It is not recommended that a user change this. :guilabel:`Waveform Template` changes the :ref:`waveform template ` used to generate the waveforms. ------------------- Additional GUIs =============== This section includes popups and other non-main sections of the GUI. ------------------- File Saving Dialog ------------------ .. image:: images/save_dialog.png The file saving dialog pops up if an :ref:`acquisition mode ` other than "Continuous Scan" is selected and :ref:`Save Data ` is checked. * :guilabel:`Root Directory` indicates the local directory to which the software will save the data. * :guilabel:`User` is the name of the user acquiring the data. * :guilabel:`Tissue Type` is the type of tissue being imaged. * :guilabel:`Cell Type` is the cell type being imaged. * :guilabel:`Label` indicates the dyes used in the acquisition. * :guilabel:`Solvent` indicates the immersion solvent of the tissue/cell. * :guilabel:`File Type` indicates what type of file to save to. * :guilabel:`Notes` is for any additional information the user wants to store with the file. Waveform Parameters ------------------- .. image:: images/waveform_parameters.png This is used to update the waveforms shown in :ref:`Waveform Settings `. * For each laser, the :guilabel:`Amplitude` and :guilabel:`Offset` correspond to the amplitude and offset of the waveform sent to the remote focus device. * For each galvo, the :guilabel:`Amplitude` and :guilabel:`Offset` correspond to the amplitude and offset of the waveform sent to the galvo, by default a triangle wave. * The :guilabel:`Galvo 0 Frequency (Hz)` sets the frequency of the waveform sent to the galvo. :guilabel:`Estimate Frequency` estimates the frequency needed for a sawtooth wave to sweep over the camera region of interest without aliasing with the light-sheet for a given rolling shutter size and speed (e.g., in a digitally scanned light-sheet format). * Additional galvos from the :ref:`configuration file ` file are incrementally added here (e.g., :guilabel:`Galvo 1 Frequency (Hz)`, ...). * :guilabel:`Percent Delay` introduces a delay before the remote focus waveform starts. * :guilabel:`Percent Smoothing` smooths the remote focus waveform. * :guilabel:`Settle Duration (ms)` introduces a delay after the remote focus sawtooth ends. ------------------- Configure Microscopes --------------------- .. image:: images/configure_microscopes.png The :guilabel:`Configure Microscopes` window allows a user with multiple microscopes defined in their :ref:`configuration file ` to select which microscope is primary and launch both microscopes simultaneously. The primary microscope will have control over any hardware shared between both microscopes. This window also provides a GUI interface to look at what hardware is in use. ------------------- Multi-Position Tiling Wizard ---------------------------- .. image:: images/tiling_wizard.png The tiling wizard helps the user set up a tiled acquisition of a sample large enough that it cannot be imaged in a single field of view. * :guilabel:`Set Start` indicates the starting position of an axis. * :guilabel:`Set End` indicates the end position of an axis. * :guilabel:` Distance` indicates difference between the start and end position. * :guilabel:` FOV Dist` indicates the field of view along that axis. The Distance between start and end will be split into tiles of this size along this axis. * :guilabel:`Num. Tiles` indicates how many tiles exist along this axis. It is roughly (End - Start)/FOV dist. * :guilabel:`% Overlap` indicates the percent of the the that should overlap along each axis. It is a percent of the FOV Dist. * :guilabel:`Populate Multi-Position Table` puts all of the tiles in the :ref:`multi-position table `. For an example of how to use the tiling wizard, see :ref:`Tiling a sample larger than the field of view `. ------------------- Autofocus Settings ------------------ .. image:: case_studies/images/autofocus_settings.png The :guilabel:`Autofocus Settings` panel controls parameters of the autofocus :doc:`feature `. * :guilabel:`Device Type` indicates if the autofocus routine should be applied to a stage or to a remote focus device. * :guilabel:`Device Reference` indicates the stage axis, or the DAQ analog output for the remote focus device, to use. * The :guilabel:`Coarse` and :guilabel:`Fine` rows allow users to select a range and step size, both in microns (or volts, if using the remote focus device), over which the autofocus routine should search for an optimal focus value. If coarse and fine are selected, the coarse search will be performed first and the fine search will be performed about the coarse position with the highest value. * :guilabel:`Inverse Power Tent Fit` will attempt to find a more accurate position for the optimal focus based on fitting a power tent to the search values. It will only use the fit if its :math:`R^2` value is higher than ``0.9``. * :guilabel:`Autofocus` runs the autofocus with the set parameters. Once the settings have been updated here, any run autofocus operation will use the new settings.