Plugin Development

Aus Dpdak
Wechseln zu: Navigation, Suche

Base Plug-ins

The following code is a minimal implementation of a base plug-in:

 import dpdak
 
 class BaseExample(dpdak.BasePlugin):
     
     description = {
         dpdak.NAME      : 'Base Plugin Example',
         dpdak.AUTHOR    : 'Your Name',
         dpdak.VERSION   : '0.3.4',
         dpdak.PARAMETER : {},
         dpdak.IN        : {},
         dpdak.OUT       : {}
     }     
  
     def getData(self, logger, counter, parameter, inputs):
         return {}

The class name can be chosen freely. The description dictionary holds all information needed by the framework to work with the plug-in:

  • dpdak.NAME: this is the name of the plug-in inside the dpdak framework (should be unique, short and self explaining),
  • dpdak.AUTHOR: the name of the plug-in developer,
  • dpdak.VERSION: the dpdak version the plug-in was developed (or last changed) for.

The dpdak.PARAMETER, dpdak.IN and dpdak.OUT as well as the getData method are explained in the sections below.

Parameter

The dpdak.PARAMETER dictionary defines the parameter controls generated by the GUI for the plug-in. They can be used to give the user the possibility to control the behaviour of a plug-in (e.g. set the position, width and height of a region which the plug-in should average in an image). Each entry has the following form:

 <key>: {dpdak.NAME: <name>, dpdak.TYPE: <type>, dpdak.DEFAULT: <value>}

where

  • <key> is an integer starting with 0 (for the first parameter) which also defines the order of the parameter controls in the GUI,
  • <name> is the name of the parameter displayed in the GUI as string,
  • <type> the identifier of the parameters type (all types are show in the table below),
  • <value> a default value for the control, the type is defined the parameter type (see table).
Identifier Description Default (Python Type) Preview
dpdak.INT A control for an integer number parameter. 1 (int) Int.png
dpdak.FLOAT A control for a floating point number parameter. 0.5 (float) Float.png
dpdak.STRING A control for a string input parameter. 'Text' (string) String.png
dpdak.TEXT A control for a multi line string input parameter. 'Text\nMore Text' (string) Text.png
dpdak.BOOL A control for a boolean (Yes/No) input parameter. True (bool) Bool.png
dpdak.FILE_PATH A control which allows to select a single file as input parameter. '' (string) File.png
dpdak.DIR_PATH A control which allows to select a single directory as input parameter. '' (string) File.png
dpdak.CHOICE A control which allows to select a single item from a list of choices. The list of choices is defined by adding a list of strings (e.g. ['One', 'Two', 'Three']) to the parameter dictionary with the key OPTIONS. The DEFAULT value needs to be one of the choices. 'One' (string) Choice.png

Inputs & Outputs

The data that a plug-in needs (inputs) and returns as result (outputs) are defined in dpdak.IN and dpdak.OUT dictionaries. Each entry has the following form:

 <key>: {dpdak.NAME: <name>, dpdak.TYPE: <type>, dpdak.UNIT: <unit>}

where

  • <key> is an integer (starting with 0 for the first input/output),
  • <name> is the name of the input/output displayed in the GUI as string,
  • <type> the identifier of the parameters type, all types are show in the table below,
  • <unit> is an optional string defining the unit of the input/output (currently not displayed in the framework).
Identifier Python Type Example
dpdak.INT int 1
dpdak.FLOAT float 0.5
dpdak.STRING string 'Text'
dpdak.TEXT string 'Text\nMore Text'
dpdak.BOOL bool True/False
dpdak.FILE_PATH string '/path/to/file'
dpdak.DIR_PATH string '/path/to/dir'
dpdak.INT_1D list of int values [1,2,3,4,5,6]
dpdak.INT_2D list of lists of int values [[1,2,3], [4,5,6]]
dpdak.FLOAT_1D list of float values [1.0, 1.1, 1.2, 1.3]
dpdak.FLOAT_2D list of lists of float values [[1.0, 1.1], [1.2, 1.3]]

getData Method

The getData method is called by the framework for every dataset. It is defined by:

 def getData(self, logger, counter, parameter, inputs)

where

  • logger is a reference to a logging object,
  • counter is an integer (starting with zero) referring to the dataset number (database row),
  • parameter is a dictionary with the keys defined in the dpdak.PARAMETER section of the description dictionary and the values set in the GUI,
  • inputs is a dictionary with the keys defined in the dpdak.IN section of the description dictionary and the values are the outputs of plug-ins processed before the current one.

The method should return a dictionary with the keys defined in dpdak.OUT section of the description dictionary and the corresponding values. It is also allowed to return None or False. In that case the framework will execute the plug-in chain for the current counter after some milliseconds again. On multi core CPUs with more than two cores, the dpdak framework uses multi threading for processing the datasets. This means that more than one instance of each plug-in class is created and the getData method of the instances are called with different counter values in parallel. For this reason, multiple instances of a plug-in might be created and not every instances getData method is called with all counter numbers.

Parallel plugin execution.png

Example

Export Plug-ins

Export plug-ins should be used to write data from the database info files. The following code shows a minimal implementation using the interface.

 import dpdak
 
 class MyExportPlugin(dpdak.ExportPlugin):
   
     description = {
         dpdak.NAME         : 'Export Plug-in Name',
         dpdak.AUTHOR       : 'Author Name',
         dpdak.VERSION      : '0.3.4',
         dpdak.HELP         : 'Help Text',
     }
           
     def export(self, parent, plg_config):
         return

The description dictionary needs to have the keys dpdak.NAME, dpdak.AUTHOR, dpdak.VERSION and dpdak.HELP. The export method is used to implement the functionality of the plug-in. It is called every time a user clicks on the plug-in in the Export menu. It is defined by:

 def export(self, parent, plg_config)

where

  • parent is an wx.Window instance and can be used to create GUI elements (e.g. wx.Frame, wx.Dialog ...),
  • and plg_config is an instance of PluginConfig.

To access data from the database, the base class implements two methods:

 def get_db_length(self)

which can be used to get the length (number of rows) in the database and

 def get_db_data(self, key, index=0, length=-1)

to get the data from the database where

  • key is a tuple (plugin_id, output_id),
  • index is the staring row and
  • length is number of rows to read (-1 means all from index).

Example

The following example shows an export plug-in that first opens a save dialog to select a file and then writes the length of the database and all plug-in outputs as three text columns (plugin name, output name, output type), separated by tabs, into that file.

 import wx
 
 import dpdak
 
 class MyExportPlugin(dpdak.ExportPlugin):
     
     description = {
         dpdak.NAME         : 'Example Plug-in',
         dpdak.AUTHOR       : 'Author Name',
         dpdak.VERSION      : '0.3.4',
         dpdak.HELP         : 'Mouse Over Help',
     }
           
     def export(self, parent, plg_config):
         dlg = wx.FileDialog(parent, 
                             message="Save file as ...", 
                             defaultDir=wx.GetHomeDir(), 
                             defaultFile="data.txt", 
                             wildcard="Text File (*.txt)|*.txt", 
                             style=wx.SAVE)
         dlg.SetFilterIndex(0)
         if dlg.ShowModal() == wx.ID_OK:
             path = dlg.GetPath()
             dlg.Destroy()
         else:
             dlg.Destroy()
             return
       
         f = open(path, 'w')
         f.write('#Database length: %i\n' % self.get_db_length())      
         for plugin_id in plg_config.get_plugins():
             plugin = plg_config.get_plugin(plugin_id)
             plugin_name = plugin.get_name()
             for output_id in plugin.get_output():
                 output_name = plugin.get_output_name(output_id)
                 output_type = plugin.get_output_type(output_id)
                 text = '%s\t%s\t%s\n' % (plugin_name, output_name, output_type) 
                 f.write(text)
         f.close()

Display Plug-ins

 import dpdak
 
 class MyDisplayPlugin(dpdak.DisplayPlugin):
 
     description = {
         dpdak.NAME         : 'Display Plug-in Example',
         dpdak.AUTHOR       : 'Authors Name',
         dpdak.VERSION      : '0.3.4',
         dpdak.HELP         : 'Mouse Over Help',
     }
 
     def init_display(self, panel, input_dic):
         pass
     
     def clear_display(self):
         pass
     
     def update_display(self):
         pass

Example