Unit XML Specification

Dahie edited this page Mar 8, 2011 · 7 revisions

Imageflow comes with a selection of unit-elements that can be already used in the application to build your own workflows. Of course ImageJ has a much richer inventory of Plugins and Commandos, that can be translated to Imageflow. This can be done quite easily by defining a XML-file, which serves as a description of the elements capabilities.

Everyone is invited to add more units and to submit them, so they can be included in future versions. Of course, feel free to use the existing Units as examples and as reference.

XML Documentation

General

<?xml version="1.0" encoding="UTF-8"?>
<UnitDescription>
<General>
    <UnitName>Image Calculator</UnitName>

Typename of the defined unit. This is also used as the default-label when the unit is inserted in the workflow.

   <PathToIcon>ImageCalculator_Unit.png</PathToIcon>

You can add an icon to your unit, either simply by creating an PNG with the same name as the unit-XML or by defining a name here.
The icon file is placed in the xml_icons/ folder.

   <ImageJSyntax>run("Image Calculator...", "image1=TITLE_1 operation=PARA_STRING_1 image2=TITLE_2 create PARA_BOOLEAN_1");</ImageJSyntax>

The syntax is the heart of the unit. This is an abstract form of the Macro-Command called in ImageJ. For multiline commands use CDATA-XML-annotation.

   <Color>0x6e91de</Color>

The color is in Hex-format. The unit will be drawn in this color in the workflow.

   <HelpString>Performs a mathematical calculation of two images</HelpString>

The HelpString describes what this unit does in roughly one sentence. This is used in the user interface as description and short help. You can use basic HTML allowed by the Java Swing Components.

   <IconSize>big</IconSize>

The representation icon on the workflow can be of different sizes. Possible are big, medium and small. Only big and small are implemented right now. This is handy to save screen real estate.

   <DoDisplay>true</DoDisplay>

Defines this unit as Display, which means that the results created by this processing node will be displayed in a result window. Usually all outputs will be displayed. This field also applies for units who have no outputs.

   <DoDisplaySilent>false</DoDisplaySilent>

Silent-Displays act similar to DoDisplay. It marks the processing node to create and store its output, however the output will not be displayed when executing the workflow. This field is required for automatic workflow execution. This field also applies for units who have no outputs.

</General>

Wildcards

The Variables in the define wildcards for the Parameters, Inputs and Outputs defined later in this XML. The wildcards for the placeholders have a certain structure. The number denotes the number of Parameter-wildcards of this datatype. This counting index starts with 1. The different Parameter-wildcards are:

  • PARA_INTEGER_x
  • PARA_DOUBLE_x
  • PARA_STRING_x
  • PARA_BOOLEAN_x

It is also possible to address Inputs in a similar way. The following Input-wildcards are possible:

  • INPUT_INTEGER_x
  • INPUT_DOUBLE_x
  • INPUT_NUMBER_x
  • INPUT_IMAGE_x
  • TITLE_x

In this case NUMBER is a general datatype for any numbers, superior to Integer and Double. So a unit with this input can handle Integer values as well as Double values. The wildcards INPUT_IMAGE_x and TITLE_x refer to an image input and will do exactly the same.

To use several macros for Stacks it is necessary to add a flag to their method-arguments. The wildcard is simply called STACK. If the workflow is handling regular images, this is simply empty, when we are dealing with stacks, it is replaced with the necessary flag.

Output-wildcards:

  • OUTPUT_INTEGER_x
  • OUTPUT_DOUBLE_x
  • OUTPUT_IMAGE_x

An Attribute-wildcard provides the option to take a value either from a parameter or a input. If an input is connected, the value of the input will be chosen, else the value is taken from the parameter.

  • ATTRIBUTE_INPUT_x_PARAMETER_x

If the number in the wildcard is higher than the actual number of parameters/inputs/outputs, this wildcard is ignored and cannot be replaced.

ImageFlow can also process stacks. Some command syntaxes need therefore the special “stack” parameter, which replaces the following wildcard:

  • STACK

Parameters

Parameters are values, that influence the processing the unit does.

<Parameters>
    <Parameter>
        <Name>Math</Name>

The name will be displayed in the titel of this unit’s properties window.

       <ReadOnly>false</ReadOnly>

The parameter can be defined as ReadOnly, meaning it will be displayed in the guy, but can not be changed by the user.

       <Hidden>false</Hidden>

Parameters can be hidden in the GUI. This applies to the Wdiget-Dashboard. For now the Properties-Dialog will always display all Parameter, but disable the hidden ones.

       <DataType>StringArray</DataType>

The DataType defines the Type of the Parameter. There are a few, which are used for different purposes and have different requirements to the XML-syntax.

Parameter Description XML-Requirements
String Stores a single String-Object
StringArray Stores an Array of Strings seperated by semicolons
and the index of the selected item, beginning with 0.
The wildcard for a StringArray is also PARA_STRING_x
<Value>Red;Black;Blue;Green;Yellow

<ChoiceNumber>0</ChoiceNumber>
boolean Stores the boolean values and a String. ImageJ-Macros can have this string inserted into the command if true.
<Value>true

<TrueString>32-bit</TrueString>
integer Stores a simple integer value.
double Stores a simple double value.
       <Value>Add;Subtract;Multiply;Divide;AND;OR;XOR</Value>
        <HelpString>Defines what math should be used to merge both images</HelpString>
        <ChoiceNumber>1</ChoiceNumber>
    </Parameter>
    <Parameter>
        <Name>32 bit result</Name>
        <DataType>boolean</DataType>
        <Value>true</Value>
        <HelpString>create 32 bit result?</HelpString>
        <TrueString>32-bit</TrueString>
    </Parameter> 
</Parameters>

Inputs

Inputs are pins, which return receive the data that will be processed in this unit. The unit can have multiple inputs.

<Inputs>
    <Input>
        <Name>Input1</Name>
        <ShortName>I1</ShortName>

Name and Shortname are currently not used in the interface, but exist as wildcards for possible additions to the User interface later on.

       <ImageType>31</ImageType>

An input can either have one ore more defined imagetypes. If you want to predefine the type, use the ImageType constants defined in ImageJ:

Image Type Constant
8 bit greyscale 1
8 bit Color 2
16 bit greyscale 4
32 bit greyscale 8
RGB Color 16
Stack 32
All 31
Stacks 32

More constants are currently not supported. To combine different ImageTypes, add the constants. For example:

  • 13 permits 8bit greyscale, 16bit greyscale and 32bit greyscale
  • 18 permits RGB Color and 8bit RGB indexed
  • 31 permits everything supported

Only for Outputs exist 2 more types:

  • -1: The Output assumes the ImageType taken from the first incoming Input
  • -2: The Output assumes the ImageType taken from the first incoming Input and converts this from a Stack to a regular Image.
       <NeedToCopyInput>false</NeedToCopyInput>

Certain macro commands in ImageJ require this option to work. This creates a copy of the image which is processed in the following units. This is required when you get the error message “Image -xx not found or no image open.”

       <Required>true</Required>

Inputs don’t have to be mandatory. They can be defined as optional. It is useful when combining Inputs with Parameters to Attributes.

       <Protected>false</Protected>

Pins can be locked if necessary. This means, changing the connections on this input will be prohibited. They can be defined as optional.

</Inputs>
    <Input>
        <Name>Input2</Name>
        <ShortName>I2</ShortName>
        <ImageType>31</ImageType>
        <NeedToCopyInput>false</NeedToCopyInput>
    </Input>
</Inputs>

Outputs

Outputs are pins, which return the result of the processing done by the unit.
Theoretically more than one output is supported, but not completely tested. Having no output is fine as well.

<Outputs>
    <Output>
        <Name>Output</Name>
        <ShortName>O</ShortName>

Name and Shortname are currently not used in the interface, but exist as wildcards for possible additions to the User interface later on.

       <ImageType>-1</ImageType>

An output can either have one ore more defined imagetypes or allow any kind of type. If you want to predefine the type, use the ImageType constants defined in ImageJ as listed above.

You don’t have to specify an output type. In most cases the output type depends on the input type. In this case you define -1. This will return the imagetype it gets from the first input.

       <DoDisplay>false</DoDisplay>

Defines this Output as Display. In the application, at the moment only a unit is set as display. This is because with one output there is no difference whether the option is attached to the unit or the output. Since there is the possibility of requiring multiple outputs in later versions and the option to display only selected outputs, this setting is defined here.

       <Protected>false</Protected>

Pins can be locked if necessary. This means, changing the connections on this input will be prohibited. They can be defined as optional.

   </Output>
</Outputs>
</UnitDescription>	

Troubleshooting

Q: I build an unit-xml and when I execute it in the graph ImageJ returns the error message “Image -xx not found or no images open.”
A: Your unit’s input requires the setting set to true. Read above why.