(r14) DpHipeTools < Public

Public Web>DpHipe>DpHipeTools (revision 14) (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. Double clicking on the tool will open a dialog for settings parameters.

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"/>

<!--
   Some short-cuts
   * Set REGISTRY   = [[DpHipeRegistry][Extension Registry]]
-->

---++ Task Registry
<blockquote>
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.kernel.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>
</blockquote>

---++ Prime input validation
<blockquote>
The mechanism above makes you task to become a tool within the system and it appears whenever a variable of type ==SpecificProduct== (i.e. the type of the value of the Parameter) 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.
</blockquote>

---++ Tools dialog
<blockquote>

The system generates 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.

  The default dialog for the crop task: <br />
     <img src="%ATTACHURLPATH%/crop.jpg" alt="crop.jpg" width='354' height='371' />

As for instance 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.

To adapt to these scenarios and more, the system provides three  ways for customizing you Task dialogs:
   * Parameter Modifiers
   * Signature Components
   * Task Panels.

</blockquote>

---++ Parameter Modifiers
<blockquote>
The system provides a default dialog displaying an input area  for setting the values of the parameter based on a composition of  [[HcssDoc:api/herschel/ia/gui/apps/modifier/Modifier.html][Modifiers]] 

    The input area for the crop task: <br />
     <img src="%ATTACHURLPATH%/crop_input.jpg" alt="crop_input.jpg" width='354' height='371' />

The composition of  [[HcssDoc:api/herschel/ia/gui/apps/modifier/Modifier.html][Modifiers]] is created based on the types of the values of the Task Parameters of the Task  Signature.

      The Modifier for the first Parameter of the crop task: <br />
     <img src="%ATTACHURLPATH%/crop_modifier.jpg" alt="crop_modifier.jpg" width='354' height='371' />

Currently the system contains basic implementation for the simple [[HcssDoc:api/herschel/ia/gui/apps/modifier/package-summary.html][types]]  Integer, Float, Long, Double so there's still a lot of space for improvements and contribution. 

If your Task Parameter isn't one of the mentioned types you need to:
   * Implement a Modifier
   * Register it to the system.
</blockquote>

----+++ Implement a Modifier
<blockquote>
 The [[HcssDoc:api/herschel/ia/gui/apps/modifier/Modifier.html][Modifier]] interface consists of two explicit contracts
   * Support the drag and drop features (the set/getVariableSelection)
   * Support the inspection for Object (the set/getObject)
and two implicit contracts inherited by the %EXTENSION_REGISTRY%
   * Be JComponent 
   * Have an empty constructor
</blockquote> 

----+++ Register a Modifier
<blockquote>
The registration of the Modifier is done again in the ==__init__.py==  via theExtensionRegistry with the usual syntax (please note the name of the factory: factory.modifier).

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

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

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 Task Parameter itself:

<pre>
        // In your task constructor
        TaskParameter parameter =  new TaskParameter("input", String.class);
        parameter.setModifier(new MyModifer());
</pre>


</blockquote>

---++ Signature Components

<blockquote>
In case the default input area based on Modifiers doesn't fit your needs you can just replace it by your own implementation. 

   Rotate Alternative Signature: <br />
     <img src="%ATTACHURLPATH%/rotate.jpg" alt="rotate.jpg" width='361' height='371' />

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

----+++ Implement a Task Signature Component

<blockquote> 
 The [[HcssDoc:api/herschel/ia/task/gui/dialog/TaskSignatureComponent.html][TaskSignatureComponent]] interface consists of four explicit contracts
   * Support the setVariableSelection for initial assignment from the Tool Window
   * Assign the Signature to display ( the setSignature)
   * Return a map of parameters and assigned values ( the getParameters *note* return value ca be simplified to  Map<TaskParameter, VariableSelection> )
   * Clear and check user inputs (used by the default buttons)
and the two implicit contracts inherited by the %REGISTRY%
   * Be JComponent 
   * Have an empty constructor
</blockquote>

----+++ 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.Rotate"))
</pre>


 See also the %REGISTRY% documentation for more details.

</blockquote>


---++ 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 [[HcssDoc:api/herschel/ia/task/gui/dialog/TaskPanel.html][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 [[HcssDoc:api/herschel/ia/gui/kernel/SiteEventHandler.html][SiteEventHandler]] passing  [[HcssDoc:api/herschel/ia/gui/kernel/event/ExecutionRequestEvent.html][ExecutionRequestEvent]]   (a viable implementation called [[HcssDoc:api/herschel/ia/task/gui/dialog/TaskExecutionEvent.html][TaskExecutionEvent]]  is available.
and the two implicit contracts inherited by the %REGISTRY%
   * Be JComponent 
   * Have an empty constructor
</blockquote>

----+++ 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.Rotate"));
</pre>


 See also the %REGISTRY% documentation for more details.

</blockquote>


---++ Task compliance
<blockquote>
   * 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.
</blockquote>

<!-- Author: Main.JorgoBakker - 21 Dec 2007 -->
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
jpg	crop_input.jpg	r1	manage	16.6 K	2008-02-15 - 10:21	UnknownUser
Topic revision: r14 - 2008-02-20 - NicolaDeCandussio
Public
Webs
Public
TWiki