(r63) DpHipeTools < Public

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

<!--
   Some short-cuts
   * Set REGISTRY   = [[DpHipeRegistry][Extension Registry]]
   * Set TOOL         = ==Tool==
   * Set ABSTRACT_TOOL= ==AbstractTool==
   * Set TASK_TOOL = ==TaskTool==
   * Set CATEGORY = ==Category==
   * Set MODIFIER = ==Modifier==
-->

<img src="%ATTACHURLPATH%/tasks.png" align="RIGHT" alt="Task, tools and variables" width='271' height='404' />

<!-- summary -->
Tools are processing units that operate on specific data elements.%BR%
From the Java point of view, a tool is an implementation of the %TOOL% interface.%BR%
Tasks are examples of tools within HIPE. In this case, %TASK_TOOL% is used under the hood. See the topic on WritingTasks for details.

If a data element is selected, a list of tools that can operate on that element should appear.
Double clicking on the tool will open an associated view (for non-task tools) or a dialogue window for settings parameters (for task tools).

%STARTINCLUDE%
This section explains the following:
   * How you can create a tool and register it, so that it becomes available for specific data.
   * How you can make HIPE aware of an existing Task.
   * How your task can react better to an active data element.
   * The default task dialogue window.
   * How you can implement and contribute a specific parameter editor
%STOPINCLUDE%

%TOC%

<br clear="all"/>

---++ Adding a task as a HIPE tool

---+++ Registering tasks
<blockquote>
You can made you task globally available to the system by specifying an instance of that task within a Jython file (usually called ==__init__.py== for HIPE internal modules) that is read by HIPE at startup (see [[MyFirstHipeTask][My first Java HIPE task]]). For example:
<pre>
    # __init__.py file
    compute = ComputeTask()
</pre>

To make your task appear in the _Tasks_ view, you need to add the following lines to the Jython file:
<pre>
    from herschel.ia.task.views import TaskToolRegistry
    toolRegistry = TaskToolRegistry.getInstance()
    <b>toolRegistry.register(compute)</b>
</pre>

You can also specify that your task belongs to one or more %CATEGORY% :
<pre>
    from herschel.ia.gui.kernel.Tool import Category
    toolRegistry.register(compute, <b>[Category.IMAGE, Category.PACS]</b>))
</pre>

Your task is now enabled whenever the users selects a session variable of the same type as the first input parameter of your task.

To define the prime parameter, modify your task constructor as follows:
<pre>
    class ComputeTask extends Task {
       ComputeTask() {
          super("compute");
          prime = new TaskParameter("spectrum", SpecificProduct.class)
          :
          getSignature().<b>setPrimeInput(prime)</b>
       }
    }
</pre>

---+++ Tasks Naming Conventions

Tasks registered in HIPE should follow the naming conventions shown in this example:
   * Name of the class: ==ReduceTask==
   * Name of the task (given by ==getName()==): ==reduce==
   * Name of the task variable in Jython: ==reduce==

%ICON{"warning"}% For naming tasks follow the Java conventions, that is, use camelCase and avoid underscores: ==reduceLight== is valid, ==reduce_light== is not. HIPE displays info log messages for invalid task names. Note that task names are used as variable names (of type ==Task==) automatically created when starting HIPE.
</blockquote>

---+++ Validating prime input
<blockquote>
If you followed the instructions in the previous section, your task now appears in the _Applicable_ category of the _Tasks_ view whenever a variable of the same type as the prime input is selected.

Sometimes this may not be enough. Your task may only run on a ==SpecificProduct== if it contains certain _contents_: a typical example is a SPIRE task operating on an !ObservationContext: clearly, such task should not be listed when a HIFI observation is selected.

To restrict a task to certain product contents, write a ==ParameterValidator==:
<pre>
    prime = new TaskParameter("spectrum", SpecificProduct.class)
    prime.setParameterValidator(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>

Note how the validation logic is now within the parameter validation block, rather than in the preamble or execution block of your task. One advantage is that the execution block of your task can concentrate on the core algorithm.
</blockquote>

---+++ Task dialogue windows

<blockquote>

HIPE generates a default input dialog for all registered tasks. The dialog has three sections: _Input_, _Output_ and _Info_, each of which can be collapsed. The following two figures show the interface of the ==crop== task, with extended and collapsed sections:

<img src="%ATTACHURLPATH%/crop_closed.png" alt="crop_closed.png"  />

<img src="%ATTACHURLPATH%/crop_new.png" alt="crop_new.png"  />

Parameters are listed in two columns. HIPE lists the parameters from left to right and top to bottom. If a single input or output parameter is present, this fills a whole line.

This automatic layout may not suit your task for several reasons:
   * A parameter may need several input fields (see for instance the ==angle== parameter of the ==rotate== task, in the figure below).
   * 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 organise 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 to your task.

     <img src="%ATTACHURLPATH%/rotate_new.png" alt="rotate_new.png" />

The following sections explore three ways to customise your task dialogue windows:
   * Parameter modifiers
   * Signature components
   * Custom task panels

</blockquote>

---++++ Parameter modifiers
<blockquote>
Each parameter field in the input area of a task dialogue window corresponds to a %MODIFIER% object. HIPE adds %MODIFIER% objects according to the types of input parameters in the task signature.

    For instance, the ==crop== task displays five input parameters: ==image==, ==row1==, ==column1==, ==row2==, ==column2==:

     <img src="%ATTACHURLPATH%/crop_input_new.png" alt="crop_input_new.png" />

HIPE provides modifiers for the simple types =Boolean=, =Integer=, =Float=, =Long=, =Double=, =String= and few more, so there is still a lot of room for improvements and contributions. You can find the general available modifiers in the ==herschel.ia.gui.apps.modifier== package; please consult the Javadoc of your HIPE installation.

If no default modifier fits your task parameter, you can implement a custom %MODIFIER% and register it to the system. You can also write your specific %MODIFIER% for one of the already available types. In that case, you can create your modifier in a [[#Implement_a_Task_Signature_Compo][custom Signature Component]].

%ICON{"warning"}% *NOTE:* %BR%
The following behaviours and limitations are present in the provided modifiers:
   * While you can always write =SomeTask(param = null)= on the command line, using a task dialog you will get =SomeTask()=: the task will interpret =null= as if the parameter has been ignored by the user.
   * Modifiers have no notion of the optionality of parameters: if they have a valid value, they will return it. The task machinery will not generate a parameter assignment if the value equals the default.
   * Specialized modifiers will mark as erroneous any variables incompatible with the type (dynamically), but will accept any variable.
</blockquote>

----+++++ Implementing a modifier
<blockquote>
 Your modifier should extend ==AbstractModifier==, which in turn implements the ==Modifier== interface. Both reside in the ==ia.gui.apps.modifier== package. The ==Modifier== interface consists of two explicit contracts:
   * Support of drag and drop features (by indirectly extending ==setVariableSelection== and ==getVariableSelection== in the ==ia.gui.kernel== package)
   * Support object inspection (via the ==setObject== and ==getObject== methods)

Modifiers must also honour two implicit contracts:
   * Deriving from ==JComponent== 
   * If registered in the %REGISTRY%, providing an empty constructor 
</blockquote> 

----+++++ Registering a modifier
<blockquote>
You can register your modifier via the %REGISTRY% with the following syntax (please note the name of the factory: ==factory.modifier==):

<pre>
 REGISTRY.register(COMPONENT,Extension(
        "MyModifier",
        "herschel.ia.mymodifier.MyModifier",
        "factory.modifier",
        "herschel.ia.MyClass")
</pre>

Be aware that the registration is system-wise, so it overrides any other registered modifier for that type. 

In case the modifier you have created is only applicable to a specific task or even to a specific parameter of a specific task, you can simply assign it to the applicable task parameter:

<pre>
    // YourTask constructor
    public YourTask() {
        addTaskParameter(new TaskParameter("someInput", MyClass.class));
        ...
    }

    // Customise your modifiers
    @Override
    public Map&lt;String, Modifier&gt; getCustomModifiers() {
	Map&lt;String, Modifier&gt; map = new LinkedHashMap&lt;String, Modifier&gt;();
	map.put("someInput", new MyModifier());
	return map;
    }
</pre>

</blockquote>

---++++ Signature components

<blockquote>
In case the default input area based on modifiers does not fit your needs, you can replace it by your own implementation, and register it to the system. The following sections show you how this is done.

----+++++ Implementing a task signature component

<blockquote> 
You can create a task signature component by extending ==JTaskSignatureComponent== in the ==ia.task.gui.dialog== package, and providing your own implementation of the =makeModifierMap()= method.

 The ==JTaskSignatureComponent== class implements the ==TaskSignatureComponent== interface, which consists of four explicit contracts:
   * Support the =setVariableSelection= for initial assignment from the Tool Window
   * Assign the Signature to display (=setSignature=)
   * Return a map of parameters and assigned values (in =Map<TaskParameter, !VariableSelection> getParameters=)
   * Clear and check user inputs implementations (used by the default buttons)

Task signature components must also honour two implicit contracts:
   * Deriving from ==JComponent== 
   * If registered in the %REGISTRY%, providing an empty constructor 

Conventions for labels for input parameters: to construct the labels of your parameters you can use the static function of class JTaskSignatureComponent  <pre> public static JLabel getDecoratedLabel(TaskParameter tp, boolean isPrimeInput, String altName) </pre> it provides a decorated label (including tooltip) that follows the standard style. For the function to work properly your task parameters should be fully configured (for example, the parameter description will be the tooltip of the label) if present.

For example, if you want to use a custom Signature Component that just wants to use ia.gui.apps.modifier.JFilePathModifier for a parameter aimed for a file name, you could do it like this:

<pre>
public class MySignatureComponent extends JTaskSignatureComponent {

    private static final long serialVersionUID = 1L;

    protected Map&lt;TaskParameter, Modifier&gt; makeModifierMap() {

	SignatureApi signature = getSignature();
	Map&lt;TaskParameter, Modifier&gt; m = new LinkedHashMap&lt;TaskParameter, Modifier&gt;();

	m.put(signature.getTaskParameter("file"), new JFilePathModifier(SAVE));
	m.put(signature.getTaskParameter("number"), new JIntegerModifier());

	return m;
    }
}
</pre>

</blockquote>

%ICON{"warning"}% NOTE:<br/>
You no longer need a signature component to choose your own modifiers for your task (and link them with events ...):  Task has a new function <pre>public Map&lt;String, Modifier&gt; getCustomModifiers()</pre> where you can do just that, see above "Register a Modifier". <br/>


----+++++ Register a Task Signature Component

<blockquote> 
 
The registration of the Task Signature Component is done again in the ==__init__.py==  via the %REGISTRY%  with the usual syntax (please note the name of the factory: factory.editor.tool.task.signature).
<pre>
REGISTRY.register(COMPONENT,Extension(
        "Rotate Signature",
        "herschel.ia.task.example.RotateSignatureComponent",
        "factory.editor.tool.task.signature",
        "herschel.ia.image.RotateTask"))
</pre>


 See also the %REGISTRY% documentation for more details.

</blockquote>


---++++ Custom Task Dialogs
Eventually, if the above options still do not accommodate you needs you can replace the the default Task Panel with your own implementation

If this is the case you need to:
   * Implement a Task Panel 
   * Register it to the system. 

----+++++ Implement a Task Panel 

<blockquote> 
 The ia.task.gui.dialog.TaskPanel interface consists of three explicit contracts:
   * Support the setVariableSelection for initial assignment from the Tool Window
   * Assign the Task to display ( the setTask)
   * Notify request of executions to the framework  by
      * Allow for setting the Site Event handler for notifying request of execution (the setSiteEventHandler method)
      * Notify the execution requests calling the trigger method of ia.gui.kernel.SiteEventHandler passing a ia.gui.kernel.event.CommandExecutionRequestEvent.%BR%You can create this event through the ia.task.gui.dialog.TaskCommandExecutionEventFactory.
   * Return the ==javax.swing.Actions== for running the task and resetting (clear) the signature (the actions that are invoked when pressing "Accept" and "Clear" buttons, if present), to allow to execute them from the toolbar of HIPE.  The simplest implementation would be to create and assign those actions to your buttons in your ==setTask(TaskApi)== method and then to return them from the buttons when asked:
<pre>
    public Action getRunAction() {
        return runbutton.getAction();
    }

    public Action getResetAction() {
        return resetButton.getAction();
    }
</pre>
and the two implicit contracts inherited by the %REGISTRY%
   * Be JComponent 
   * Have an empty constructor
</blockquote>


   The Rotate Panel example (herschel.ia.task.example.RotatePanel): <br />
     <img src="%ATTACHURLPATH%/rotate_panel.jpg" alt="rotate_panel.jpg" width='323' height='326' />


----+++++ Register a Task Panel 

<blockquote> 
 
The registration of the Task Panel Component is done again in the ==__init__.py==  via the %REGISTRY% with the usual syntax (please note the name of the factory: factory.editor.tool.task.signature).
<pre>
REGISTRY.register(COMPONENT,Extension(
        "Rotate Task Panel",
        "herschel.ia.task.example.RotatePanel",
        "factory.editor.tool.task",
        "herschel.ia.image.RotateTask"));
</pre>


 See also the %REGISTRY% documentation for more details.

</blockquote>

---++ Adding a Tool that is not a Task

If you have an existing task and want to make it available in HIPE, you just need to follow the steps described in the [[#Adding_a_Task_as_a_Tool][above section]].

Now, a task has its limitations. It is somewhat an atomic operation for which you provide some inputs and expect some result.%BR%
Therefore, it is not expected for acting interactively with a user, and it is not meant for holding internal status either, that a user can modify during its execution.

If you need more flexibility, you can write your own implementation of the %TOOL% interface.%BR%
Besides, you would most probably need a viewer associated to your tool, for letting the user interact with it.

This follows in some way the MVC pattern: your target data is the Model, your associated viewer is the View, and your tool is the Controller.

---+++ Tool Implementation
In order to write a tool, %TOOL% interface needs to be implemented. Instead of doing it directly, it is encouraged to extend %ABSTRACT_TOOL%.

The information to be provided is passed to one of its constructors in a ==super== call from the derived class:

<pre>
    /** Constructor for a tool with a single parameter and general category. */
    protected AbstractTool(String name, Parameter primeInput)

    /** Constructor for a tool with a single input parameter. */
    protected AbstractTool(String name, Parameter primeInput, Category... categories)

    /** Constructor for a tool with multiple input parameters and general category. */
    protected AbstractTool(String name, Parameter primeInput, List&lt;? extends Parameter&gt; inputs)

    /** Constructor with all arguments. */
    protected AbstractTool(String name,
                           Parameter primeInput,
                           List&lt;? extends Parameter&gt; inputs,
                           Category... categories)
</pre>
You provide the variable types you are interested in within the prime input: just return a ia.gui.kernel.ToolParameter initiated with the proper class of data you want to handle:
<blockquote>
<pre>
new ToolParameter("data", MyTargetDataType.class)
</pre>
</blockquote>

More conditions for checking whether the tool can react on a particular variable can be added by providing a =ParameterValidator= to the prime input.

The actual job to be done can be delegated to a third object (the "tool object"), or just be executed by the tool class itself.%BR%
This latter case is the default, otherwise, you need to call =setToolObject(Object toolObject)= in your constructor.

Moreover, you may return the categories you think the tool is meaningful for, by providing the proper ones in the ==super== call.

---+++ Naming conventions

Conventions for names of a tool class and its variable in the Tasks view are similar than those for tasks. For example, a tool for spectrum filtering could be called:

<pre>
     Name of the Class              : SpectrumFilterTool
     Name of the Tool (getName())   : spectrumFilter
     Name of the variable in Jython : spectrumFilter
 </pre>

---+++ Tool Viewer
Every tool has an associated viewer, which must implement ia.gui.kernel.parts.EditorComponent (by extending ia.gui.kernel.parts.AbstractEditorComponent or one of its subclasses).

---+++ Tool Registry
Once you have your tool and the corresponding viewer, you need to register them like this:
<blockquote>
<pre>
# Associate the tool with the viewer
REGISTRY.register(COMPONENT,Extension(
                 "Spectrum Filter Tool",
                 "herschel.path.to.SpectrumFilterToolComponent",
                 "factory.editor.tool",
                 "herschel.path.to.SpectrumFilterTool"))

# Register the tool so it is automatically available for the proper variables in HIPE
from herschel.ia.gui.kernel import ToolRegistry
from herschel.path.to import SpectrumFilterTool
spectrumFilter = SpectrumFilterTool()
ToolRegistry.getInstance().register(spectrumFilter)

__all__ = [ "spectrumFilter", "SpectrumFilterTool", ... ]
</pre>
</blockquote>

---+++ Communicating Tool & Viewer
In the viewer, you can access the tool and the selected data within the =makeEditorContent= method provided by =AbstractEditorComponent=.%BR%
At this point, you can let the tool know about the viewer as well, if you want:
<blockquote>
<pre>
protected boolean makeEditorContent() {

    // Get the tool and the selected data
    ToolSelection selection = getSelection();
    Tool   tool = selection.getTool();
    Object data = selection.getSelection().getValue();

    // Optional - you would need to provide a setViewer method
    ((MyTool)tool).setViewer(this);

    // Build the editor contents ...
}
</pre>
</blockquote>

---+++ Simple sample
This simple reproducible example wraps up the just explained steps altogether.%BR%
It is just a button whose label is changed by the tool when the user clicks on it:

&nbsp;&nbsp;&nbsp;&nbsp;1. *The tool class*
<blockquote>
<pre>
public class SimpleButtonTool extends AbstractTool {

    private ArrayData _data;
    private boolean _flag = true;

    public SimpleButtonTool() {
	super("simpleButton", new ToolParameter("data", ArrayData.class));
    }

    void setData(ArrayData data) {
	_data = data;
    }

    void updateLabel(JButton button) {
	int size = _data.getSize();
	int rank = _data.getRank();
	button.setText("Data has " + (_flag? "size " + size : "rank " + rank));
	_flag = !_flag;
    }
}
</pre>
</blockquote>

&nbsp;&nbsp;&nbsp;&nbsp;2. *The viewer class*
<blockquote>
<pre>
public class SimpleButtonToolComponent extends AbstractEditorComponent&lt;ToolSelection&gt; {

    private static final long serialVersionUID = 1L;
    private static int _counter = 1;
    private SimpleButtonTool _tool;

    public SimpleButtonToolComponent() {
	super(new BorderLayout());
    }

    protected Class<ToolSelection> getSelectionType() {
	return ToolSelection.class;
    }

    protected boolean makeEditorContent() {
	final JButton button = new JButton();
	setName("Button Tool " + _counter++);
	_tool = (SimpleButtonTool)getSelection().getTool();
	_tool.setData((ArrayData)getSelection().getSelection().getValue());
	_tool.updateLabel(button);
	button.addActionListener(new ActionListener() {
	    public void actionPerformed(ActionEvent e) {
	        _tool.updateLabel(button);
            }
	});
	add(button);
	return true;
    }

    public Icon getComponentIcon() {
	return IconLibrary.VARIABLE;
    }
}
</pre>
</blockquote>

&nbsp;&nbsp;&nbsp;&nbsp;3. *The registration*
<blockquote>
<pre>
COMPONENT = ExtensionRegistry.COMPONENT
REGISTRY  = ExtensionRegistry.getInstance()

REGISTRY.register(COMPONENT,Extension(
                 "Button Tool",
                 "herschel.path.to.SimpleButtonToolComponent",
                 "factory.editor.tool",
                 "herschel.path.to.SimpleButtonTool"))

from herschel.ia.gui.kernel import ToolRegistry
from herschel.path.to import SimpleButtonTool
simpleButton = SimpleButtonTool()
ToolRegistry.getInstance().register(simpleButton)

# cleanup
del(ExtensionRegistry, Extension, REGISTRY, COMPONENT)

__all__ = [ "simpleButton", "SimpleButtonTool" ]
</pre>
</blockquote>

&nbsp;&nbsp;&nbsp;&nbsp;4. *Executing the example*
<blockquote>
For executing this simple tool, just include it in a package owned by you, open the workbench in HIPE, and execute the following in the console:
<pre>
x = Int1d.range(12)
y = Double2d([[1,2,3],[4,5,6]])
</pre>
Then open the x and y variables with the Button Tool and click the button: its label is updated by the tool.
</blockquote>

---++ Triggering Events
For a full detailed section about triggering events have a look at DpHipeCommonUtilities.

<!--
   * Set ALLOWTOPICCHANGE = Main.RegisteredUsersGroup, Main.TWikiAdminGroup
-->
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
png	crop_input_new.png	r1	manage	13.8 K	2010-06-02 - 11:54	JavierDiaz	crop input updated to the new look of tasks
png	crop_modifier_new.png	r1	manage	13.7 K	2010-06-02 - 11:53	JavierDiaz	crop modifier updated to the new look of tasks
png	crop_input.png	r1	manage	14.5 K	2009-09-29 - 16:09	JaimeSaiz	crop task with input highlighted
png	crop_modifier.png	r1	manage	14.4 K	2009-09-29 - 16:09	JaimeSaiz	crop task with modifier highlighted
png	crop_new.png	r1	manage	13.9 K	2010-06-02 - 11:55	JavierDiaz	crop updated to the new look of tasks
png	crop_closed.png	r1	manage	8.1 K	2010-06-02 - 11:55	JavierDiaz	crop with closed sections updated to the new look of tasks
png	crop.png	r1	manage	13.7 K	2009-09-29 - 15:55	JaimeSaiz
png	rotate_new.png	r1	manage	10.6 K	2010-06-02 - 11:52	JavierDiaz	rotate panel updated to the new look of tasks
png	tasks.png	r1	manage	13.0 K	2009-09-29 - 16:11	JaimeSaiz	Tasks and variables
Topic revision: r63 - 2010-12-16 - JulioRamirez
Public
Webs
Public
TWiki