(r3) DpHipeTools < Public

Public Web>DpHipe>DpHipeTools (revision 3) (raw view)~~EditAttach~~
---+ !!Adding Tools to HIPE

<img src="%ATTACHURLPATH%/hipe-tools.jpg" align="RIGHT" alt="Task, tools and variables" width='359' height='215' />

%STARTINCLUDE%
<!-- summary -->
Tools are processing units that operate on specific data elements. The well-known Tasks are examples of tools within [[DpHipe][HIPE]]. If a data element is selected, a list of tools that can operate on that data should appear.

This section explains:
   * how you can make [[DpHipe][HIPE]] aware of an existing Task,
   * how your task can react better on an active data element,
   * the default task dialog and how you implement and contribute a dedicated the input dialog for your task,
   * how you can implement and contribute a specific parameter editor
%STOPINCLUDE%

%TOC%


<br clear="all"/>

---++ Task Registry

Up to now you have made you task globally available to the system by specifying an instance of that task within the ==__init__.py== file of your sub-system, e.g.:
<pre>
    # __init__.py file
    myTask=MyTask()
</pre>

To make your task appear in the "Run Tools" view, you have to change the above by:
<pre>
    from herschel.ia.task.views import TaskToolFactory
    <b>TaskToolFactory.register(MyTask())</b>
</pre>

You can also specify that your task belongs to one or more categories:
<pre>
    from herschel.ia.core.Tool import Category
    TaskToolFactory.register(MyTask(), <b>[Category.IMAGE, Category.PACS]</b>))
</pre>
Your task will now be enabled whenever a session variable is selected which matches the type of the *first* input parameter within your task!

Within your task, you can control which parameter signs-up to be the prime parameter (the one which reacts on a selected data variable) by the Task API:
<pre>
    class MyTask extends Task {
       MyTask() {
          prime=new TaskParameter("spectrum",SpecificProduct.class)
          :
          getSignature().<b>setPrimeInput(prime)</b>
       }
    }
</pre>

---++ Prime input validation
The mechanism above makes you task to become a tool within the system and it appears whenever a variable of type ==SpecificProduct== is selected.

Sometimes this may not be enough, e.g. is certain situations your task will only run on a ==SpecificProduct== if it contains certain _contents_. A typical situation would be when a SPIRE reduction operates on a ObservationContext: such a task should not be listed whenever a HIFI observation is selected...

You can write a ==ParameterValidator== to do just that:
<pre>
    prime=new TaskParameter("spectrum",SpecificProduct.class)
    prime.setValidator(new ParameterValidatorAdapter() {
        public void validate(Object value) throws ParameterValidationException {
            SpecificProduct s=(SpecificProduct)value;
            if (! (logic that would validate the contents of the value...)) {
                throw new ParameterValidationException(reason);
            }
        }
    });
</pre>

In other words, rather than writing this logic within the pre-amble or execution block of your task, we recommend you to move that logic into the parameter validation. This way we achieve two things:
   * make the logic appear where it should be and therefore keeping the execution block of your task concentrated to the _algorithm_, and
   * make your task appear as a _tool_ within [[DpHipe][HIPE]] that can be ran against _specific_ data.

---++ Task Input Dialog
_Default dialog, drag-and-drop features, dedicated dialogs_
The application is generating a default input dialog for all registered tasks within the software. As the system does not know the intent of your task, it can only
provide a dry-listing of all requested parameters; such a dialog may not be suitable for your purposes.

However, you may want to have more control over how the input parameters are presented to the user:
   * you may only want to provide a sub-set of parameters (and leave the full-set to expert users on the command-line)
   * you may want to organize your parameters by grouping them in tabs, or putting a border around a group of parameters
   * you may want to have more informative tooltips, labels or even input fields that are more suitable for your task.

For that you can implement a ==herschel.ia.task.gui.dialog.SignatureComponent== and register it as follows (again in the ==__init__.py==):
<pre>
    REGISTRY.register(COMPONENT,Extension(
        id,                           # string
        implSignatureComponent,       # string
        "factory.editor.tool.task",
        implTask));                   # string
</pre>
, where:
   * id is a unique identifier
   * implSignatureComponent - implementation of SignatureComponent interface
   * implTask - implementation of your task for which this input dialog applies
and the registry elements are defined as:
<pre>
from herschel.ia.core import ExtensionRegistry, Extension
FACTORY=ExtensionRegistry.FACTORY
COMPONENT=ExtensionRegistry.COMPONENT
REGISTRY=ExtensionRegistry.getInstance()
</pre>


An example (which you can find in the prototype):
<pre>
    REGISTRY.register(COMPONENT,Extension(
        "herschel.ia.gui.components.editor.tasks.RotateSignatureComponent",
        "herschel.ia.gui.components.editor.tasks.RotateSignatureComponent",
        "factory.editor.tool.task",
        "herschel.ia.image.Rotate"));
</pre>

Note that your GUI component must have a default constructor!

---++ Parameter Modifiers
_TODO: Default modifiers, specialized modifiers_

---++ Task compliance
   * write user documentation (jtags)! That will be automatically picked up whenever a user asks the system for help on your task.
   * the name of the task should be a legal variable name in the global name-space. For example your instance of MyTask should report itself as e.g.: "myTask" and not  "This is my task".
   * if your prime parameter is not the first parameter in your task, specify the prime parameter using the ==setPrimeInput== method in the signature
   * write a parameter validator for your prime parameter if your task should be listed not only on prime data type but on prime data contents as well.

-- Main.JorgoBakker - 21 Dec 2007
Topic revision: r3 - 2008-01-09 - NicolaDeCandussio
Public
Webs
Public
TWiki