Graphical user interface ************************ This part of TeraPy documentation is dedicated to users, whose main goal is measurement. It concentrates on TeraPy graphical user interface. .. contents:: .. |list-add| image:: icons/list-add.png .. |list-remove| image:: icons/list-remove.png .. |go-up| image:: icons/go-up.png .. |go-down| image:: icons/go-down.png .. |event-list| image:: icons/event-list.png .. |scan-start| image:: icons/scan-start.png .. |scan-stop| image:: icons/scan-stop.png .. |icon_0D| image:: icons/icon_0D.png .. |icon_1D| image:: icons/icon_1D.png .. |icon_2D| image:: icons/icon_2D.png .. |icon_3D| image:: icons/icon_3D.png Starting TeraPy =============== TeraPy can be run in a number of different ways: - create a shortcut to the main script in the work folder - run TeraPy from the command line by typing ``terapy`` (the executable must be in the system search path) - import TeraPy Python module from within Python and create the wx application yourself - for example this way: .. code-block:: python import wx from terapy import TeraPyMainFrame app = wx.App(redirect=False) frame = TeraPyMainFrame() frame.Show(True) app.MainLoop() At this point, the main interface should appear and widgets associated with the devices described in ``devices.ini`` should be displayed at the bottom of the central panel. If the interface doesn't show or for any other problem, see the :ref:`troubleshooting` section. TeraPy main window ================== An overview of the main TeraPy window is found below (:ref:`user_fig1`). The interface is divided into distinct sections, which are described in details below. .. _user_fig1: .. figure:: screenshots/main.png :align: center TeraPy main window .. _user_menus: Menus ===== TeraPy's menus host several actions and options: - File menu - **Open scan**: load data from file. Supported file formats depend on available modules (see :ref:`file_formats` for details) - **Settings**: open main settings configuration panel. See :ref:`config_folders` for details. - **Default units**: open default units configuration panel. See :ref:`user_units` for details. - **About**: some informations about TeraPy - **Exit**: close TeraPy - Hardware menu - **Reset current devices**: reset devices that are currently loaded in memory - **Scan hardware**: scan for supported devices - **Configure**: sub-menu populated with loaded devices. Call configuration dialog for selected device .. _user_units: Physical units ============== TeraPy handles physical units. Devices can provide informations about the units they measure. These will be remembered throughout the post-processing chain. Units can be either set globally through the *Default units* menu (see :ref:`user_menus` for details), or locally depending on the plot canvas used. Physical units are managed with the `Pint `_ package. .. _user_events: Scan events =========== The *Scan settings* control allows to define scan sequences. A scan sequence (|event-list| icon) is presented as a list of scan events. Scan events can be added to sequences and to events that support children (for example loops). A scan sequence will run only if a measurement event is present. Also, some events, which require measured data (such as save or plot events), can't run before the data has been measured. Before running a sequence, TeraPy will check these rules for you and issue a warning if necessary. One data container and one history entry will be created for each measurement event present in the sequence. .. _user_fig2: .. figure:: screenshots/scan_01.png :align: center Scan settings with open popup menu Scan events are added to the tree either with the |list-add| button, or through the right-click popup menu (see :ref:`user_fig2`). The additional functions accessible through this menu are - **Remove**: remove selected event (and event children, if any). Same effect as |list-remove| button - **Rename**: rename selected event. Also accessible with left-click on selected event name - **Load sequence**: load scan sequence from XML file (see :ref:`file_formats` for details) - **Save sequence**: save scan sequence to XML file (see :ref:`file_formats` for details). Only available for *Sequence* (|event-list|) events - **Run sequence**: run selected sequence. Only available for scan sequences (|event-list|). Same effect as |scan-start| button - **Replace with**: replace selected event with another event of the same type (i.e. loop with any other kind of loop, measurement event with any other kind of measurement event, ...) - **Disable/Enable**: disable/enable selected event. Also accessible with Shift+left click Events can be re-organized with the |go-up| |go-down| buttons or by drag and drop. Scan events are configured either by double-clicking on their tree entry or by changing the properties in the Properties folder shown under the event tree entry. Clicking |scan-start| will run the sequence, which contains the selected event. During measurement, the button turns red and displays |scan-stop|. Click it to stop the ongoing measurement. Scan history ============ The *Scan history* shows a list of data containers in memory. The adjacent icon gives the data dimension - |icon_0D| point measurement (0D) - |icon_1D| one dimensional (1D) - |icon_2D| two dimensional (2D) - |icon_3D| three dimensional (3D) New entries can be added either by a measurement sequence or by loading from a file. Entries in **bold** letters are displayed in one plot canvas. Entries are shown/hidden by double-clicking on their name in the list. Plots are added to the 1st available canvas (if none is found, a new canvas is created). If possible, entries are colored like their associated plot. Several actions are available through right-click (see :ref:`user_fig3`) - **Load scan**: load data from file. Supported file formats depend on available modules (see :ref:`file_formats` for details) - **Rename**: rename list entry (also tries to rename associated file, if possible). Also accessible with left click on selected item - **Delete**: remove entry from list. This won't delete the associated file, if one exists - **Save as...**: save data (along with post-processed copies) to a file - **Change color**: change plot color (if allowed for associated plot type) - **Reset color**: if color has been manually changed, this will reset plot color to automatic - **Set as reference**: set selected data as reference for currently displayed plot canvas. This option only appears if the plot canvas supports filter banks. If the filter bank already contains a reference filter, the filter will be updated with the new reference array. Otherwise, a new reference filter is added. Icons of entries set as reference are highlighted. - **Clear reference**: if selected data is set as reference for some plot canvas, this option sets the status of selected item back to normal. .. _user_fig3: .. figure:: screenshots/history_03.png :align: center Scan history with open popup menu Plots ===== Scan data can be displayed in plot canvases. Upon display request, TeraPy will search for an appropriate canvas. If one is found, a plot will be added. Otherwise, TeraPy adds one canvas from the list of available canvas modules, then add a plot to it. Currently, 1D and 2D data are supported. Plot canvases are either **data canvases** or **post-processing canvases**. Data canvases can only display raw, non-processed, data. A Post-processing canvas can be linked with a data canvas or another post-processing canvas (nested post-processing). Commands and options are available by right-click on the canvas tab (see :ref:`user_fig4`), and are - **Add...**: add empty data canvas of selected type. Available types depend, on which modules are present (see :ref:`add_plots` for details). - **Rename**: rename plot canvas - **Remove canvas**: delete canvas. This will also remove associated post-processing canvases. - **Clear canvas**: delete all plots from canvas and from associated post-processing canvases. Option only available for data canvases. - **Edit axes**: open dialog to edit axes labels and units. TeraPy will automatically try to convert the units to default units set in the *Default units* selection dialog (see :ref:`user_menus` and :ref:`user_units`). - **Add post-processing canvas**: add post-processing canvas with selected filter bank. Listed filter banks are taken from the `filter_path` directory (see :ref:`config_folders` for details). - **Remove post-processing canvases**: delete associated post-processing canvases. Option only available if post-processing canvases are present. .. _user_fig4: .. figure:: screenshots/plot_01.png :align: center Plot canvas tab with open popup menu Additional features for 1D canvases ___________________________________ 1D data canvases support zooming by click and drag. Simply select the area, which you want to zoom on. Right click restores canvas to original state. In addition, right click on 1D post-processing canvases switches between linear and logarithmic scales. .. _user_filters: Post-processing filters ======================= Post-processing filters are only available if a post-processing canvas is displayed. If so, the post-processing filter control is enabled. The displayed list of filters corresponds to the currently visible plot canvas. A preview of apodization filters is displayed at the bottom of the control. Apodization filters are windowing functions that are applied in view of a domain transform (e.g. Fourier transform). Internally, these filters have the `is_pre_filter` property set to True (see programmer's guide :ref:`prog_filters` section for details). Post-processing filters can be added with the |list-add| button, removed with |list-remove|, and re-arranged with |go-down| |go-up| or by drag and drop. Right-clicking on an item shows a popup menu with additional options (see :ref:`user_fig5`): - **Add...**: add filter above selected item. Available filters depend, on which modules are present. - **Remove**: remove filter from list - **Disable/Enable**: disable/enable filter. Disabled filter name will be shown in italic. Same effect as with Shift+left click. - **Load filter list**: load filter bank from file (see :ref:`file_formats` for details) - **Save filter list**: save filter bank to file (see :ref:`file_formats` for details) .. _user_fig5: .. figure:: screenshots/filter_01.png :align: center Post-processing filter list with open popup menu .. _user_devices: Device widgets ============== Device drivers can (optionally) provide one or several widgets, which will be added to the device widgets area. Widgets are meant to display instantaneous informations on the device or allow control of some device parameters. Additional informations may be found in the :ref:`add_drivers` section. Device widgets aren't accessible while a measurement sequence is running. Device parameters, which you want to set dynamically during measurement, must be treated by a scan event.