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.