8.4 SCIRun Filter Description

A SCIRun filter description file is associated with each ITK filter. The SCIRun filter description references the ITK filter description file, the optional GUI file, and contains SCIRun specific information.

SCIRun filter description files are located in directory:

  SCIRun/src/Packages/Insight/Dataflow/Modules/Filters/XML

SCIRun filter description files follow the naming convention:

  sci_filter_name.xml

for example:

  sci_BinaryThresholdImageFilter.xml

The following XML code illustrates the overall structure of a sci-filter description file:

  <?xml version="1.0" encoding="iso-8859-1"?>
  <!DOCTYPE filter SYSTEM "sci_filter.dtd">
  <filter>
    <include href="file_path"/>
    ⋮
    <filter-sci name="SCIRun module name">
      <package>SCIRun_package_name</package>
      <category>SCIRun_category_name</category>
      <instantiations>
      ⋮
      </instantiations>
      <outputs>
      ⋮
      </outputs>
      <includes>
      ⋮
      </includes>
    </filter-sci>
  </filter>

Each element is discussed below.

8.4.1 Element <filter>

Element <filter> is the top-level element. All other elements are enclosed in element <filter>:

  <filter>
  ⋮
  </filter>

8.4.2 Element <include>

Element <include> must be used one time to reference the ITK filter description file. It can be used a second time to reference an optional GUI description file.

The path to an ITK filter description file (or a dialog description file) is provided by element <include>'s ``href'' attribute. The file path is relative to the SCIRun Insight package directory (SCIRun/src/Packages/Insight). Note that <include> is an empty element, closed with characters />:

  <include href="file_path"/>

For example:

  <include href="ITK/itk_WatershedImageFilter.xml"/>
  <include href="Dataflow/Modules/Filters/XML/gui_WatershedImageFilter.xml"/>

Two <include> element's are used above. The first references the ITK filter description file, the second references a GUI description file.

8.4.3 Element <filter-sci>

Element <filter-sci> provides module specific information.

  <filter-sci name="module_name">
    <package>package_name</package>
    <category>category_name</category>
    <instantiations>
    ⋮
    </instantiations>
    <outputs>
    ⋮
    </outputs>
    <includes>
    ⋮
    </includes>
  </filter-sci>

The value of the required name attribute determines the name of the SCIRun module produced from the filter, and the name of files generated.

For example:

  <filter-sci name="WatershedImageFilter">
  ⋮
  </filter-sci>

generates a module named WatershedImageFilter.

Elements <package> and <category> specify the package and category to which a module belongs:

  <package>package_name</package>
  <category>category_name</category>

For example:

  <package>Insight</package>
  <category>Filters</category>

8.4.3.1 Element <instantiations>

Element <instantiations> declares filter instantiations that can replace those declared in an ITK filter description file (see Element <templated>):

  <instantiations use-defaults="off">
    <instance>
      <type name="template_parameter_name1">
        <value>data_type_for_parameter_name1</value>
      </type>
    </instance>
    ⋮  
  </instantiations>

When attribute use-defaults has the value "off" then instantiations declared in the <instantiations> element replace instantiations declared in the <templated> element of the ITK filter description file. When attribute use-defaults has the value "on" then instantiations declared in the <templated> element of the ITK filter description file replace those declared in the <instantiations> element of the SCIRun filter description file.

Each <instance> element declares one filter instantiation. Each <type> element corresponds to a <template> element in an ITK filter description. The value of <type>'s name attribute must match the content of a corresponding <template> element. Element <value> declares a data type associated with a template parameter.

For example:

  <instance>
    <type name="InputImageType">
      <value>itk::Image&lt;float, 2&gt;</value>
    </type>
    <type name="OutputImageType">
      <value>itk::Image&lt;float, 2&gt;</value>
    </type>
   </instance>
   <instance>
    <type name="InputImageType">
      <value>itk::Image&lt;float, 3&gt;</value>
    </type>
    <type name="OutputImageType">
      <value>itk::Image&lt;float, 3&gt;</value>
    </type>
  </instance>

8.4.3.2 Element <outputs>

Element <outputs> is optional. <Outputs> lists outputs that are allowed to send intermediate data.

Usually data are sent on a port only after a module has finished its execution. When sending intermediate data is allowed, however, a module can send data every n_th mathend000# iteration of a calculation.

Intermediate data are useful when using, for example, any of the level-set segmentation filters--the user can visualize the segmentation region growing or shrinking in real-time.

The <outputs> element contains one or more <output> elements (but no more than are in the <outputs> element of the ITK filter description). Each <output> element names an output and determines if the output is allowed to send intermediate data:

  <outputs>
    <output name="output_name"
            send_intermediate="yes_or_no"/>
  </outputs>

For example:

  <outputs>
    <output name="OutputImage" send_intermediate="yes"/>
  </outputs>

Each <output> element corresponds to an ITK filter description <output> element. The values of the respective name attributes must match. The value of an <output> element's send_intermediate attribute is set to yes if the output is allowed to send intermediate data and no otherwise.

Note that users determine, via a module's GUI, if an output that is allowed to send intermediate data, does send intermediate data. For each output that is allowed to send intermediate data, a module's default GUI will contain: a checkbox that determines if the output will generate intermediate data; and a text entry widget specifying the number of iterations between sends of intermediate data.

For an example see file:

  src/Packages/Insight/Dataflow/Modules/Filters/XML/
    sci_ThresholdSegmentationLevelSetImageFilter.xml

8.4.3.3 Element <includes>

Element <includes> provides a list of include files needed by a module's implementation. Each <file> element provides the path name of one include file:

  <includes>
    <file>include_file_path_name</file>
    ⋮
  </includes>

For example:

  <includes>
    <file>Packages/Insight/Dataflow/Ports/ITKDatatypePort.h</file>
  </includes>

Include file paths are relative to the SCIRun src directory (SCIRun/src).