8.3 ITK Filter Description

The ITK filter description XML file describes a filter's inputs, outputs, parameters, parameter modifying member functions, templated data types, and other filter information. This file contains no SCIRun specific information.

ITK filter description files are located in directory SCIRun/src/Packages/Insight/ITK. ITK filter description files follow the naming convention:

  itk_filter_name.xml

for example:

  itk_BinaryThresholdImageFilter.xml

The following XML code illustrates the overall content of an ITK filter description file:

  <?xml version="1.0" encoding="iso-8859-1"?>
  <!DOCTYPE filter SYSTEM "itk_filter.dtd">
  <filter-itk name="filter_name">
     <description>
     ⋮
     </description>
     <templated>
     ⋮
     </templated>
     <datatypes>
     ⋮
     </datatypes>
     <inputs>
     ⋮
     </inputs>
     <outputs>
     ⋮
     </outputs>
     <parameters>
     ⋮
     </parameters>
     <includes>
     ⋮   
     </includes>
  </filter-itk>

Each element is discussed below.

8.3.1 Element <filter-itk>

Element <filter-itk> is the top-level element. All other elements are enclosed in element <filter-itk>. The value of the required ``name'' attribute is the qualified C++ filter name.

For example:

  <filter-itk name="itk::ReflectImageFilter">
    ⋮
  </filter>

8.3.2 Element <description>

Element <description> should provide a short (several sentences) filter description.

For example:

  <description>
    Implements a Reflection of an image along a selected
    direction. This class is parameterized over the type
    of the input image and the type of the output image.
  </description>

8.3.3 Element <templated>

ITK filters are templated (parameterized) C++ classes and generally support one or two template parameters. The <templated> element describes a filter's template information. Specifically, <templated> contains elements that name a filter's template parameters and list suitable data types for filter instantiations.

<templated>
  <template>template_parameter_name1</template>
  <template>template_parameter_name2</template>
  ⋮
  <defaults>
    <default>data_type_for_parameter_name1</default>
    <default>data_type_for_parameter_name2</default>
    ⋮
  </defaults>
  <defaults>
    <default>data_type_for_parameter_name1</default>
    <default>data_type_for_parameter_name2</default>
    ⋮
  </defaults>
  ⋮
</templated>

Each <template> element declares and names a template parameter. Template parameter names may be used in subsequent <input> and <output> elements--see below.

Each <defaults> element corresponds to one filter class instantiation. Each <default> element names a type that corresponds (in order) with previous <template> elements.

For example, the following <templated> element:

  <templated>
    <template>InputImageType</template>
    <template>OutputImageType</template>
    <defaults>
       <default>itk::Image&lt;float, 2&gt;</default>
       <default>itk::Image&lt;float, 2&gt;</default>
    </defaults>
  </templated>

corresponds to filter class template:

  template <class InputImageType, class OutputImageType>
  class AnITKFilterClass... mathend000#

and filter type instantiation:

  AnITKFilterClass<itk::Image<float,2>,itk::Image<float,2> >

Note that characters ``<'' and ``>'' cannot be typed literally into an XML file. The character entities '&lt;' and '&gt;', respectively, must be used.

A <template> element and its corresponding <default> element can describe a parameterized built-in value. In this case, a <template> element's ``type'' attribute specifies a C++ built-in type, and a corresponding <default> element specifies the type's value:

  <templated>
    <template type="unsigned int">ImageDimension</template>
    ⋮
    <defaults>
      <default>2</default>
      ⋮
    </defaults>
  </templated>

A SCIRun filter module knows all possible filter instantiations. When executed at runtime, a module uses the filter instantiation with data input and output types matching data types passing through the module's input and output ports.

8.3.4 Element <datatypes>

Element <datatypes> declares filter parameter data types that are not C++ built-in types. Names of declared data types are used in <parameter> elements that describe filter parameters (see Element). <parameters>). Element <datatypes> is optional, it is needed only when a parameter is not a C++ built-in type.

The structure of the <datatypes> element follows:

  <datatypes>
    <data_type_element name="data_type_name">
    ⋮
    </data_type_element>
    ⋮  
  </datatypes>

where data_type_element is the name of a data type element.

Each <data_type_element> describes the properties of one data type. Element <datatypes> enclose one or more data type elements.

At this time, element <array> is the only supported data type element. The array-like type described by element <array> is subject to the following conditions:

• It must support operator[]()
• Its array elements must be a built-in type
• It must support a member function that returns the array length

The structure of element <array> follows:

  <array name="FilterType::data_type_name">
    <elem-type>built-in_type</elem-type>
    <size-call>member_function</size-call>
  </array>

Attribute name specifies the name of an array-like data type. ``FilterType'' is a pseudo qualifier. It represents the full templated type of the current filter. FilterType is used in place of the full template name, for example, itk::MeanImageFilter<InputType,OutputType>. Data_type_name is the name of a type declared or typedef'ed in the filter's class declaration.

Element <elem-type> specifies the array's element type. Built-in_type is a C++ built-in type.

Element <size-call> specifies the name of a member function that returns the number of elements in the array.

An example <datatypes> element with an <array> sub-element follows:

  <datatypes>
    <array name="FilterType::InputSizeType">
      <elem-type>int</elem-type>
      <size-call>GetSizeDimension</size-call>
    </array>
  </datatypes>

FilterType::InputSizeType can be used in a subsequent <param> element.

8.3.5 Element <inputs>

The <inputs> element describes data types accepted by a filter's input ports, and member functions used to establish input port connections:

  <inputs>
    <input name="input_name">
      <type>data_type_name</type>
      <call>member_function</call>
    </input>
    ⋮
  </inputs>

For example:

  <inputs>
    <input name="SourceImage">
      <type>InputImageType</type>
      <call>SetInput</call>
    </input>
  </inputs>

Element <input> declares one filter input. The name attribute names an input. The value of name names the corresponding SCIRun module input port. The value of name must be unique among all inputs.

Element <type> specifies the data type accepted by a filter's input port. Data_type_name can be a name declared in a <template> element (as shown above), or a parameterized data type with parameter names declared in a <template> element. For example, the following template element associates type float with name ScalarType:

  <templates>
    <template>ScalarType</template>
    <defaults>
      <default>float</default>
    </defaults>
  </templates>

and ScalarType is used as a template parameter in the following <inputs> element:

  <inputs>
    <input name="InputImage">
      <type>itk::watershed::SegmentTree&lt;ScalarType&gt;</type>
      <call>SetInputSegmentTree</call>
    </input>
  </inputs>

Element <call> specifies a member function (commonly SetInput) that establishes an input port connection.

8.3.6 Element <outputs>

The <outputs> element describes data types transmitted on a filter's output ports, and the member functions used to establish output port connections:

  <outputs>
    <output name="output_name">
      <type>data_type_name</type>
      <call>member_function</call>
    </output>
    ⋮
  </outputs>

For example:

  <outputs>
    <output name="DestImage">
      <type>OutputImageType</type>
      <call>GetOutput</call>
    </output>
  </outputs>

The name attribute names an output. The value of name names the corresponding SCIRun module output port. The value of name must be unique among all outputs.

Element <type> specifies the data type transmitted on a filter's output port. Data_type_name can be a name declared in a <template> element (as shown above), or a parameterized data type with parameter names declared in a <template> element.

Element <call> specifies the member function (commonly GetOutput) that establishes an output port connection. If <call> element's value is a member function returning a constant pointer, <call>'s const attribute must be set to the value ``yes'', for example:

  <call const="yes">GetSpeedImage</call>

8.3.7 Element <parameters>

A filter's parameters determine its behavior. Filter member functions change parameter values. The <parameters> element describes a filter's parameters:

  <parameters>
    <param>
      <name>parameter_name</name>
      <type>data_type</type>
      <call>member_function</call>
      <default>initial_value</default>
    </param>
    ⋮  
  </parameters>

Each <param> element describes one parameter with sub-elements <name>, <type>, <call>, and optional <default> providing the parameter's name, data type, corresponding member function, and optional initial value.

For example:

  <parameters>
    <param>
      <name>upper_threshold</name>
      <type>float</type>
      <call>SetUpperThreshold</call>
      <default>1000.0</default>
    </param>
  </parameters>

The content of element <type> is either a C++ built-in type or type declared in a <datatypes> element. Element <default> is optional.

If the ITK filter class macro itkBooleanMacro is used to create a boolean parameter, two <call> elements are needed; one for setting a true value, and one for setting a false value:

  <call value="on">member_function_on</call>
  <call value="off">member_function_off</call>

For example:

  <param>
    <name>reverse_expansion_direction</name>
    <type>bool</type>
    <call value="on">ReverseExpansionDirectionOn</call>
    <call value="off">ReverseExpansionDirectionOff</call>
  </param>

To modify the parameter, each parameter requires a GUI. If a GUI description file is not created, a default GUI is generated that associates a text entry widget with each filter parameter. SCIRun GUI Description illustrates writing a GUI description for a filter module. When writing a GUI description file, note that the value of the <name> element above must match the value of a corresponding <param> element's name attribute in the GUI description file.

8.3.8 Element <includes>

Element <includes> lists ITK include files declaring filter classes and data types:

<includes>
  <file>include_file<file>
</includes>

For example:

<includes>
  <file>itkBinaryThreasholdImageFilter.h<file>
</includes>