pictures/imod_logo.png

iMOD User Manual version 4.4 (html)


7.7Plugin Tool

WHY?
The Plugin Tool is an instrument that can be used to run external executables (from complicated to simple) or batchfiles within iMOD.

WHAT?
The Plugin tool makes it possible to include advanced plugins that come close to fully software integration as well as plugins that simply run an executable file. This allows you to start a specific program within an iMOD-session without stop working in this session. A number of pre-settings and couplings are necessary before you can launch a plugin. iMOD needs information about the plugin and vice versa.

HOW?
Before starting the iMOD Plugin Tool, you need to walk through a couple of preprocessing steps before a plugin can be used within the iMOD gui.

Note: You are able to save the activated plugins for later use within the IMF-file. You can do this by saving the current iMOD project session via the Save-button or via File->Save as... in the main-menu. Also the chosen time interval (see TMO.PITools.execution how to set this interval) on which iMOD tests whether a plugin is running or not, is saved in the IMF-file.


7.7.1Plugin file description

In the PLUG-IN.INI different initialization files are listed behind the above explained keywords. Some of these files also contain a list of keywords. We will explain them here.


7.7.1.1Plugin MENU file

All keywords are optional.

Keyword

Description

TITLE=

Optional keyword that sets the title of the menu window, e.g. TITLE="This plugin computes residuals".

BUTTON1=

Optional keyword that sets the text on the Close-button, e.g. BUTTON1=Afbreken.

BUTTON2=

Optional keyword that sets the text on the Help-button, e.g. BUTTON=Hilfe.

BUTTON3=

Optional keyword that sets the text on the Apply-button, e.g. BUTTON3=Go-for-it

LIST=

Optional keyword that loads all available files from a certain place or directory. If not defined, iMOD shows a diaolog in which you need to select files yourself. The following options are available:

IMODMANAGER

Whenever LIST=IMODMANAGER, iMOD will display the selected files from the iMOD Manager in a separate window.
Be aware that iMOD places a ’+’-sign in front of the directory name in case the related file is selected in the iMOD Manager and a ’-’-sign in case the file is not selected! To be able to read the file properly the plugin needs to handle this.

Example

target="_blank" >pictures/h72-end/plugin-manager2.png

Use the buttons left and right to move the selected items from left to right or the other way around

*.IDF / *.*

Whenever LIST=*.IDF iMOD will display a dialog in which files can be selected, e.g. IDF-files. Any combination of wildcards can be uses, e.g. LIST=*.*, LIST=*.RUN, or whatsoever the plugin need as an input.
Example

pictures/h72-end/plugin-window.png

Use the "open"-button (  pictures/h1-h3/image14.png ) to add files to the dialog.

TEXT=

Refers to an addition text file with explanatory text with requirements for using the chosen plugin, e.g. TEXT=EXPLAINATION.TXT.

The list of files defined with keyword LIST or by making use of the plugin menu-dialog, is stored in a file called "PLUG-IN.IN" (see Section 7.7.1.2).

Example1

TITLE= Compute Waterbalance
BUTTON1= Quit
BUTTON2= Info
BUTTON3= Run
LIST= IMODMANAGER
TEXT= EXPLAIN.TXT

Example2

TITLE= Convert Raster settings
LIST= *.IDF
TEXT= EXPLAIN.TXT


7.7.1.2Plugin IN file

The list of files that is used by the plugin is saved in this file "PLUG-IN.IN", and can serve as a checkup for the user of the plugin. In case LIST="IMODMANAGER" is given in the MENU-file, iMOD puts a ’+’- or a ’-’-sign in front of each individual file listed in PLUG-IN.IN. The ’+’-sign is written when a file is selected in the iMOD manager, else a ’-’-sign appears.


7.7.1.3Plugin OUT file

This file needs to be written by the plugin executable after or during its execution. It needs to be prepared within the code of the plugin. To allow iMOD to interact with the plugin, it is required to include at least one of the following keywords in the OUT file.

Keyword

Description

WINDOW=

With this keyword the plotting window extent (decimal coordinates) in iMOD can be set. Once this is read, iMOD will adapt the current window extent to the extent mentioned by WINDOW. Use the format: XMIN,YMIN,XMAX,YMAX, e.g. WINDOW=10000.0,250000.0,150000.0,300000.0.

NFILE=

Number of files to be read into the iMOD Manager.

FILE{i}=

The i\(^{\rm th}\) file to be read into iMOD Manager, e.g. FILE1=FLUX.IDF. Given file needs to be available in the specific plugin-(sub)folder. Only name of the (subfolder+)file+extension are needed to be given. As mentioned the use of subfolders is allowed.

MESSAGE_{...}=

Contains some text lines to be given at a certain moment in de executable process.

{INFO}

Contains general information to be given in a popup window at a certain moment during de executable process.

{ERROR}

Contains error-information to be given in a popup window at a certain moment during de executable process.

{PROGRESS}

Contains progress-information to be given at a certain moment during de executable process. This will be visible in the information-bar at the bottom of the iMOD main-window.

Note: It is the responsibility of the plugin owner to process the message(s) of the plugin in the right way and at the right moment. After reading the OUT-file, iMOD will delete the file from disc to avoid any double interpretation of the file.

Example1

WINDOW= 140000.0,445000.0,150000.0,452000.0
NFILE= 2
FILE1 = WBAL_2014_SUMMER.IDF
FILE2 = WBAL_2014_WINTER.IDF
MESSAGE_INFO= "The waterbalance is succesfully calculated."

Example2

MESSAGE_PROGRESS= "Plugin is still busy ..."


7.7.2Using the Plugin

To start the Plugin Tool from the main menu, choose Plug-in. A sub-menu will appear. If you did define PLUGIN1 and/or PLUGIN2 in the iMOD preference file, you can choose Manage Plug-in 1 ... and/or Manage Plug-in 2 .... To start the Plugin Manager window, click on either of the two.

Example of Plugin Manager window

pictures/h72-end/plugin-manager.png

Plugins (folder name)

The list displays all sub-folders in the {PLUGIN1}\folder. Click on the sub-folder. If a {PLUGIN}.txt is available in the sub-folder an explanatory text of the plugin will appear in the sub-window below.

Active

Select the check box to (de)activate a specific plugin. When you activate a plugin, the plugin appears in the main sub-menu Tools and Plugin.

Apply

Click this button to apply your plugin-settings and to close the window.

Cancel

Click this button to close the window and not applying your modified plugin-settings.

Help…

Click this button to start the Help functionality.

After clicking on Apply button, the activated plugins are added to the Plugin menu. At maximum, 10 plugins can be activated at once into this menu list. The Plugin-menu might look like this:

pictures/h72-end/plugin_menu_running.png

It depends on the configuration of the Plugin what will happen whenever the plugin is selected from the menu. During the whole running process iMOD checks at predefined fixed moments (intervals of 60, 30, 15 or 1 seconds) if there are plugins running. The running check time interval can be changed by selecting the similar called option in the Plug-In menu (see figure below). On default this interval is set on 60 seconds. As long as a single plugin or multiply plugins are running, the plugin manager(s) cannot be reached (Menu options are grayed-out) for making changes. Though you are able to use already selected plugins from the plugin-menu.

As shown in the example above, only the plugins that are running are grayed-out. If there are still plugins running when trying to close iMOD, iMOD asks the following question for every plugin that is running:

pictures/h72-end/plugin_quit_running.png

Note: When using a batch file as a plugin to call an executable, this plugin cannot be terminated by iMOD. The plugin continues running after iMOD is closed.