Adding Tools to HIPE

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.

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

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

    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!

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.