Difference: DpHipeTools (57 vs. 58)

Revision 582010-06-25 - DavideRizzo

Line: 1 to 1
 
META TOPICPARENT name="DpHipe"

Adding Tools to HIPE

Deleted:
<
<
 

Task, tools and variables

Line: 19 to 17
 
<-- summary -->
Tools are processing units that operate on specific data elements.
From the Java point of view, a tool is an implementation of the Tool interface.
Changed:
<
<		The well-known Tasks are examples of tools within HIPE. In this case, TaskTool is used under the hood.
>
>		Tasks are examples of tools within HIPE. In this case, TaskTool is used under the hood.
 
Changed:
<
<		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 an associated view (for non-task tools) or a dialog for settings parameters (for task tools).
>
>		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).
 
Changed:
<
<		This section explains:
  • how you can create a Tool and register it for being available for dedicated data
  • 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 input dialog for your task,
  • how you can implement and contribute a specific parameter editor
>
>		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
 
Deleted:
<
<
 


Changed:
<
<

Adding a Tool as a Task

>
>

Adding a task as a HIPE tool

 
Changed:
<
<

Task Registry

>
>

Registering tasks

 
Changed:
<
<		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.:
>
>		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 My first Java HIPE task). For example:
 
    # __init__.py file
    compute = ComputeTask()
Changed:
<
<		To make your task appear in the "Tasks" view, you need to add the following lines:
>
>		To make your task appear in the Tasks view, you need to add the following lines to the Jython file:
 
    from herschel.ia.task.views import TaskToolRegistry
    toolRegistry = TaskToolRegistry.getInstance()
    toolRegistry.register(compute)
Deleted:
<
<		For PACS users, this __init__.py file is located at $install_dir/data/toolbox/your_sub_system.
 You can also specify that your task belongs to one or more Category : 
    from herschel.ia.gui.kernel.Tool import Category
    toolRegistry.register(compute, [Category.IMAGE, Category.PACS]))
Deleted:
<
<		Your task will now be enabled whenever a session variable is selected which matches the type of the first input parameter within your task!
 
Changed:
<
<		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:
>
>		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:

 
    class ComputeTask extends Task {
       ComputeTask() {
Line: 79 to 72
  }
Changed:
<
<		Naming conventions for task when to be registered in HIPE should follow this example assuming that the task will perform the functionality named "reduce" : 
     Name of the Class              : ReduceTask
     Name of the Task (getName())   : reduce
     Name of the variable in Jython : reduce
>
>		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
 
Changed:
<
<		Warning, important For naming tasks we follow the Java conventions, we use camel-case , not underscores : "reduceLight" is valid, "reduce_light" is not. Info log messages are produced for invalid task names. Note that the task names are used as variable names (of type task) automatically created when starting HIPE.
>
>		Warning, important 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.
 
Changed:
<
<

Prime input validation

>
>

Validating prime input

 
Changed:
<
<		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.
>
>		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.
 
Changed:
<
<		Sometimes this may not be enough, e.g. in 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 an ObservationContext: such a task should not be listed whenever a HIFI observation 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.
 
Changed:
<
<		You can write a ParameterValidator to do just that:
>
>		To restrict a task to certain product contents, write a ParameterValidator:
 
    prime = new TaskParameter("spectrum", SpecificProduct.class)
    prime.setParameterValidator(new ParameterValidatorAdapter() {
        public void validate(Object value) throws ParameterValidationException {
            SpecificProduct s = (SpecificProduct)value;
Changed:
<
<		 if (! (logic that would validate the contents of the value...)) { throw new ParameterValidationException(reason);
>
>		 if (! ( [logic that would validate the contents of the value] )) { throw new ParameterValidationException( [reason] );
  } } });
Changed:
<
<		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.
>
>		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.
 
Changed:
<
<

Task Dialogs

Default Task Dialog

>
>

Task dialogue windows

 
Changed:
<
<		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.
>
>		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:
 
Deleted:
<
<		 The default dialog for the crop task:
  crop_closed.png
Deleted:
<
<		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.

Warning, important A new default dialog layout has been implemented following the request of the DPUG: It puts two parameters per line: lines are filled left to right, and then top to bottom. If you only have 1 input (or output) it will fill the whole line. Modifiers implementors should take care that the preferred size of their modifier is smaller (about 20 chars max). Provided modifiers have been updated but some modifiers are too wide for this layout (for instance, AngleModifier can have three texts and one combo in a line, see rotate later).
The default dialog for the crop task, with all sections opened:

  crop_new.png
Changed:
<
<		To adapt to these scenarios and more, the system provides three ways for customizing you Task dialogs:
  • Parameter Modifiers
  • Signature Components
  • Task Panels.
>
>		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.
 
Changed:
<
<
>
>		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.
 
Changed:
<
<

Parameter Modifiers

The system provides a default dialog displaying an input area for setting the values of the parameter based on a composition of Modifier objects.
>
>		 rotate_new.png
 
Changed:
<
<		 The input area for the crop task:
crop_input_new.png
>
>		The following sections explore three ways to customise your task dialogue windows:
  • Parameter modifiers
  • Signature components
  • Custom task panels
 
Changed:
<
<		The composition of Modifier objects is created based on the types of the values of the Task Parameters of the Task Signature.
>
>
 
Changed:
<
<		 The Modifier for the row1 Parameter of the crop task:
crop_modifier_new.png
>
>

Parameter modifiers

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.
 
Changed:
<
<		Currently the system contains basic implementation for the simple types Boolean, Integer, Float, Long, Double, String and few more, so there's still a lot of space for improvements and contribution. You can find the general available modifiers in package herschel.ia.gui.apps.modifier; please consult the Javadoc of your HIPE installation.
>
>		 For instance, the crop task displays five input parameters: image, row1, column1, row2, column2:
 
Changed:
<
<		If the default parameter doesn't fit for your Task Parameter, you can:
  • Implement a Modifier,
  • Register it to the system.
>
>		 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.

 
Changed:
<
<		Alternatively, you could want to write your specific Modifier for one of the already available types. In that case, you could create your modifier in a custom Signature Component.
>
>		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 custom Signature Component.
  Warning, important NOTE:
The following behaviours and limitations are present in the provided modifiers:
Changed:
<
<
  • While you can always write SomeTask(param = null) in Console, using a task dialog you will get SomeTask(): for GUIs "null is not allowed". The task machinery will take nulls as if the parameter has been ignored by the user.
>
>
  • 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.
Changed:
<
<
  • Specialized modifiers:
    • Will mark as errorenous variables incompatible with the type (dynamically), but will accept any variable.
>
>
  • Specialized modifiers will mark as erroneous any variables incompatible with the type (dynamically), but will accept any variable.
 
Changed:
<
<
Implement a Modifier
>
>
Implementing a modifier
 
Changed:
<
<		 The ia.gui.apps.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:
>
>		 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 Extension Registry, providing an empty constructor
 
Changed:
<
<
Register a Modifier
>
>
Registering a modifier
 
Changed:
<
<		The registration of the Modifier is done again in the __init__.py via the Extension Registry 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.

>
>		You can register your modifier via the Extension Registry with the following syntax (please note the name of the factory: factory.modifier):
  
 REGISTRY.register(COMPONENT,Extension(
Line: 195 to 171
  "herschel.ia.MyClass")
Changed:
<
<		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:
>
>		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:

  
    // YourTask constructor
Line: 204 to 182
  ... }
Changed:
<
<		 // Customize your modifiers
>
>		 // Customise your modifiers
  @Override public Map<String, Modifier> getCustomModifiers() { Map<String, Modifier> map = new LinkedHashMap<String, Modifier>();
Line: 213 to 191
  }
Deleted:
<
<
 
Changed:
<
<

Signature Components

>
>

Signature components

 
Changed:
<
<		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 (old):
rotate.jpg

Rotate Alternative Signature (new):
rotate_new.png

>
>		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.
 
Changed:
<
<		If this is the case you need to:
  • Implement a Task Signature Component
  • Register it to the system.

Implement a Task Signature Component
>
>
Implementing a task signature component
 
Changed:
<
<		 The ia.task.gui.dialog.TaskSignatureComponent interface consists of four explicit contracts:
>
>		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)
Deleted:
<
<		and the two implicit contracts inherited by the Extension Registry
  • Be JComponent
  • Have an empty constructor
 
Changed:
<
<		Conventions for labels for input parameters: to construct the labels of your parameters you can use the static function of class JTaskSignatureComponent 
 public static JLabel getDecoratedLabel(TaskParameter tp, boolean isPrimeInput, String altName)
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.
>
>		Task signature components must also honour two implicit contracts:
  • Deriving from JComponent
  • If registered in the Extension Registry, providing an empty constructor
 
Changed:
<
<		An easy way of implementing TaskSignatureComponent is by extending ia.task.gui.dialog.JTaskSignatureComponent and providing your own implementation for the makeModifierMap() method.
>
>		Conventions for labels for input parameters: to construct the labels of your parameters you can use the static function of class JTaskSignatureComponent 
 public static JLabel getDecoratedLabel(TaskParameter tp, boolean isPrimeInput, String altName)
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:
Line: 912 to 879
  }

Deleted:
<
<

 
<-- Author: JorgoBakker - 21 Dec 2007 -->

View topic | History: r113 < r112 < r111 < r110 | More topic actions...
 
This site is powered by the TWiki collaboration platform Powered by Perl