Difference between revisions of "Postprocessing plugins"

From Dynamo
Jump to navigation Jump to search
Line 74: Line 74:
  
 
===The project database===
 
===The project database===
 +
 +
The execution pipeline of ''Dynamo'' defines a series of items in a database, corresponding to the elements produced and used during the averaging procedure.
 +
 +
The typical action of a plugin is typically to access some of these elements, analyze and operate of them, and possibly replace some of them with the results of an operation defined inside the plugin.
 +
 +
The most important items are:
 +
* <tt>refined_table</tt>
 +
* <tt>average</tt>
 +
 +
 +
They represent the results of the iteration in course. Also, they are passed to the next iteration to produce the starting positions and reference for the next computation.
  
 
==== In Matlab====
 
==== In Matlab====
 +
 +
Both <tt>refined_table</tt> and <tt>average</tt> are identified by iteration and reference number (in case you have a multireference project);
  
 
==== In a non-matlab executable ====
 
==== In a non-matlab executable ====
Line 82: Line 95:
 
# providing the right paths for all project items
 
# providing the right paths for all project items
 
# using their own IO tools to read and write map and table files.
 
# using their own IO tools to read and write map and table files.
 +
 +
====Other database items====
 +
 +
A complete list of database items and their identification methods can be created with <tt>ddhelp</tt>
  
 
==Example script==
 
==Example script==

Revision as of 13:42, 3 March 2017

Postprocessing plugins are a tool for customization of the alignment procedure in Dynamo. With this kind of plugin, the user can define an action that Dynamo will execute after each iteration during a project alignment.

Applications of plugins

Users have reported the use of plugins in very different scenarios and with very different levels of complexity. Here some examples:

  • Online definition of mask, depending on the average computed in the iteration.
  • Online definition of symmetrization operator;
  • Customization of golden-standard policy.
  • Fine tuning of MRA policy by PCA classification after each iteration.

Naming of a plugin script

Matlab plugin

Dynamo requires that the plugin script itself is named with the pattern

dynamo_plugin_post_PLUGINNAME.m

where PLUGINNAME is the shortname of the plugin.

The script should be in the execution path of Matlab (i.e., you should use addpath on the directory where you have defined your plugin). We recommend not to save your plugin files inside the folders of a Dynamo installation, but in your own folders.

System executables

If you put your plugin as a system executable, the same naming convention will be used. You just need to skip the file extension .m.

Linking plugin and project

You need two orders. With the first one you tell Dynamo that round 1 (for instance) will look for a plugin after normal Dynamo execution. For a project called ptest, you would write:

dvput ptest plugin_post_r1 1

Then, you pass the plugin itself:

dvput ptest plugin_post_order_r1 myExample().

This assumes that the plugin script has the name dynamo_plugin_post_myExample.m. If necessary, you can also pass parameters.

dvput ptest plugin_post_order_r1 myExample parameterForPlugin1 parameterForPlugin2.

The parentheses are necessary to tell Dynamo that the plugin is a Matlab script. If you skip them

Do not forget to unfold again the project before running it.

Syntax of a plugin script

Input arguments

The execution pipeline of Dynamo will deliver to the plugin function a text card with all the parameter values used in the project for the iteration that just got executed. It also identifies the iteration number currently on execution.

Thus, when creating your script, your first input variable should be reserved to accept this file.

function dynamo_plugin_post_example(iterationCard);


Location of iteration and round

In Matlab

In a Matlab-written plugin, you can use some tools in order to extract the information in the iterartionCard text file delievered to the plugin script in runtime

scard=dynamo_read(iterationCard);

%   1 from which iteration it is being executed:
ite = scard.database_ite;

%   2 from which project it is being invoked
name_projec t= scard.name_project;

% 3 we read the corresponding virtual project 
vpr=dynamo_vpr_load(name_project)

In a non-matlab executable

If your plugin is an executable, youll have to parse the input text file in order to find the parameters needed by the plugin.

The project database

The execution pipeline of Dynamo defines a series of items in a database, corresponding to the elements produced and used during the averaging procedure.

The typical action of a plugin is typically to access some of these elements, analyze and operate of them, and possibly replace some of them with the results of an operation defined inside the plugin.

The most important items are:

  • refined_table
  • average


They represent the results of the iteration in course. Also, they are passed to the next iteration to produce the starting positions and reference for the next computation.

In Matlab

Both refined_table and average are identified by iteration and reference number (in case you have a multireference project);

In a non-matlab executable

Working outside Matlab, the user will have two tasks:

  1. providing the right paths for all project items
  2. using their own IO tools to read and write map and table files.

Other database items

A complete list of database items and their identification methods can be created with ddhelp

Example script