TWiki> Public Web>DpHipe>DpHipeTools (revision 10)EditAttach

Adding Tools to HIPE

Task, tools and variables

Tools are processing units that operate on specific data elements. The well-known Tasks are examples of tools within 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 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


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.:
    # __init__.py file
    myTask=MyTask()

To make your task appear in the "Run Tools" view, you have to change the above by:

    from herschel.ia.task.views import TaskToolFactory
    TaskToolFactory.register(MyTask())

You can also specify that your task belongs to one or more categories:

    from herschel.ia.kernel.Tool import Category
    TaskToolFactory.register(MyTask(), [Category.IMAGE, Category.PACS]))
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:

    class MyTask extends Task {
       MyTask() {
          prime=new TaskParameter("spectrum",SpecificProduct.class)
          :
          getSignature().setPrimeInput(prime)
       }
    }

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 (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:

    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);
            }
        }
    });

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 HIPE that can be ran against specific data.

Tools dialog

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:
crop.jpg

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 Dialogs.

Parameter Modifiers

The system provides a default dialog displaying an input area for setting the values of the parameter. Based on the type of the value of the Task Parameter the input area dinamically loads the most appropriated (and registered) component satisfying the contract of the Modifier.

Currently the system contains basic implementation for the simple types Integer, Float, Long, Double so there's still a lot of space for improvements and contribution.

If your Task Parameter doesn't follow into the mentioned types you need to:

  • Implement a Modifier
  • Register it to the system.

Implement a Modifier

The 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 ExtensionRegistry
  • Be JComponent
  • Have an empty constructor

Register a Modifier

The registration of the Modifier is done again in the __init__.py via the ModifierFactory with the same syntax (please note the name of the factory: factory.modifier).

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

Signature Components

For that you can implement a herschel.ia.task.gui.dialog.SignatureComponent and register it as follows (again in the __init__.py):

    REGISTRY.register(COMPONENT,Extension(
        id,                           # string
        implSignatureComponent,       # string
        "factory.editor.tool.task",
        implTask));                   # string
, where:
  • id is a unique identifier
  • implSignatureComponent - implementation of SignatureComponent interface
  • implTask - implementation of your task for which this input dialog applies

An example (which you can find in the prototype):

    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"));
See also the Extension Registry documentation for more details.

Note that your GUI component must have a default constructor!

Task Dialogs

The default dialog provided by the system is result of the composition of a main input area (TaskSignatureComponent) and a panel containing the buttons (JTaskButtonsPanel). The main panel is based

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.

Edit | Attach | Watch | Print version | History: r113 | r12 < r11 < r10 < r9 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r10 - 2008-02-14 - NicolaDeCandussio
 
This site is powered by the TWiki collaboration platform Powered by Perl