Viewer Modules

Viewer modules appear as either QDockWidgets or QWidgets to the user. They must consist of a main ModuleGUI class which inherits from either QDockWidget or QWidget. They can utilize any additional python modules, classes, etc.

Instructions

  1. Create a plugins directory if you don’t have one. Set this plugins directory in the System Configuration. This directory can contain as many custom modules as you want. All python modules within the plugins directory are automatically imported.

  2. Download the __init__.py and place it within the plugins directory.

  3. Your directory structure & System Configuration should look something like this. A __pycache__ will automatically be created when you launch mesmerize, this is normal.

../_images/plugin_dir_structure.png
  1. Create the main module file for your custom module, in this example we’ll create example_plugin.py and place it in the plugins directory that we specific in the System Configuration alongside the provided __init__.py. You can create as many plugin modules as you want, they can be named as you wish but must use the struture outlined below. In addition to this main module file you can create a separate subdirectory to house any modules or files associated to this module. You can create Qt templates using Qt Creator and convert them to .py template files using pyuic5 and use them for your custom module.

    Basic Structure

     1from PyQt5 import QtWidgets
     2
     3module_name = 'Example Module'
     4
     5
     6# You must define `module_name`
     7# This is the name that will be displayed in the "Plugins" menu of the Viewer Window.
     8# You can use this to reference the ModuleGUI instance through the Viewer Console via ``get_module(<module_name>)``
     9
    10
    11# The main GUI class MUST be named ModuleGUI.
    12# You can have other classes and more GUIs however ModuleGUI is the one that the Viewer Window directly calls.
    13
    14class ModuleGUI(QtWidgets.QDockWidget):
    15    # The Viewer MainWindow will pass its Viewer instance that
    16    # can be used to interact with the viewer and work environment.
    17    def __init__(self, parent, viewer_instance):
    18        QtWidgets.QDockWidget.__init__(self, parent)
    19        self.setWindowTitle('Example Viewer Module')
    20        self.setFloating(True)  # Must be floating
    21
    22        self.viewer_instance = viewer_instance
    23
    24        # container widget
    25        self.dockwidget_area = QtWidgets.QWidget()
    26
    27        # create a vertical layout
    28        self.vlayout = QtWidgets.QVBoxLayout(self.dockwidget_area)
    29
    30        # add a button
    31        self.button = QtWidgets.QPushButton(self.dockwidget_area)
    32        self.button.setText('button')
    33        self.button.clicked.connect(self.callback_button_clicked)
    34        self.vlayout.addWidget(self.button)
    35
    36        # add a label
    37        self.label = QtWidgets.QLabel(self.dockwidget_area)
    38        self.vlayout.addWidget(self.label)
    39
    40        # set the qdockwidget's layout
    41        self.setLayout(self.vlayout)
    42        self.setWidget(self.dockwidget_area)
    43
    44        # self.show()
    45
    46    # change the label text when the button is clicked
    47    def callback_button_clicked(self):
    48        self.label.setText('button clicked!')
    
  2. The module will be accessible through the Viewer Window’s “Plugins” menu. The names in the plugins menu will correspond to the aforementioned module_name variable.