ITK/MetaIO: Difference between revisions

From KitwarePublic
< ITK
Jump to navigationJump to search
m (moved MetaIO to ITK/MetaIO: Follow naming convention.)
 
(20 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= MetaIO Documentation =
= MetaIO Documentation =
* MetaIO began in 1996 to address the growing complexity and inflexibility of medical image formats that were available at that time.
* MetaIO has maintained backward compatibility since its initial public release in 2000 as part of the [http://www.itk.org Insight Toolkit (ITK)]
* MetaIO is used for the majority of tests and examples in the ITK framework


==Highlights==
==Highlights==
Line 16: Line 20:
* ND Data in a single file
* ND Data in a single file
* ND Data as a sequence of (N-1)D files
* ND Data as a sequence of (N-1)D files
* Easily extended to handle user-defined fields on a per application basis .
* Optional compression
* Easily extended to handle user-defined fields on a per application basis


== Documentation ==
== Documentation ==


[[media:MetaIO-Introduction.pdf|Documentation in PDF]] (266KB)
* [[MetaIO/Documentation | MetaIO documentation]] is available as a wiki page.
* [[MetaIO/MetaCommand_Documentation | MetaCommand and MetaOutput documentation]] is also available as a wiki page.


== Get the software ==
== Get the software ==


'''Most recent version available as part of the [http://www.itk.org Insight Toolkit]''' in the directory Insight/Utilities/MetaIO
* Most recent version available as part of the [http://www.itk.org Insight Toolkit] in the directory Insight/Utilities/MetaIO
 
* MetaIO is also available as part of the [http://www.vtk.org Visualization Toolkit] in the directory VTK/Utilities/vtkmetaio
 
'''MetaIO is alao available as part of the [http://www.vtk.org Visualization Toolkit]''' in the directory VTK/Utilities/vtkmetaio


== VTK MetaIO -vs- ITK MetaIO ==
== VTK MetaIO -vs- ITK MetaIO ==
Line 50: Line 54:
* When using MetaIO from within ITK, call the function without a namespace
* When using MetaIO from within ITK, call the function without a namespace
* Developers should never issue "using namespace vtkmetaio" in a program if VTK and ITK are to be used in that program.
* Developers should never issue "using namespace vtkmetaio" in a program if VTK and ITK are to be used in that program.
== FAQ ==
# <em> I am trying to use MetaIO to point to and read my set of png (or tiff or jpeg) files, but it isn't working.  What is wrong with MetaIO?</em>
#* More than likely your files are using compressed versions of those image formats.  MetaIO only supports its own type of image compression - it cannot read data that is compressed in other formats.  Sorry.
# <em> Should I use Origin, Position, or Offset (and similarly Orientation, Rotation, or TransformMatrix) to represent the recorded location of my data? </em>
#* Due to backward compatibility constraints, any of these variations is supported and produces identical results.
# <em> What is the difference between BinaryDataByteOrderMSB and ElementDataByteOrderMSB? </em>
#* Again backward compatibility is the driving force.  Over the past decade some inconsistencies crept into the implementation of derived classes, and when we go back and standardize, we must maintain backward compatibility.  Therefore, equivalent terms are often defined in the tag dictionary.
# <em> I think MetaIO is encoding my image's orientation incorrectly... </em>
#* We greatly appreciate your feedback -- particularly if you can provide the data and/or data conversion program that is exhibiting this behavior.  We've tried to get it "right" but data orientation is both critical and tricky.  Please send your data and details to stephen.aylward@kitware.com
# <em> What orientation convention is MetaIO using? </em>
#* MetaIO uses the same orientation convention as ITK - which is OPPOSITE FROM DICOM.  This is extremely unfortunate, but again...backward compatibility.  Direction cosines (orientation), spacing, and origin should map consistently as your image moves from DICOM to MetaIO and back - however, the anatomical orientations should FLIP - L <-> R, I <-> S, and A <-> P.  For more information, see:
#** http://www.itk.org/Wiki/Proposals:Orientation#Some_notes_on_the_DICOM_convention_and_current_ITK_usage
#** http://www.itk.org/cgi-bin/viewcvs.cgi/Code/Common/itkSpatialOrientation.h?rev=1.1&root=Insight&view=markup


== Related Links ==
== Related Links ==
Line 58: Line 77:
*[http://fusionviewer.sourceforge.net/ FusionViewer] - U of Washington tool for pet/ct visualization
*[http://fusionviewer.sourceforge.net/ FusionViewer] - U of Washington tool for pet/ct visualization
*[http://www.fi.muni.cz/~pem/i3dlib/html/index.html I3DLib] - Microscopy software - Masaryk University
*[http://www.fi.muni.cz/~pem/i3dlib/html/index.html I3DLib] - Microscopy software - Masaryk University
*[http://www.batchmake.org BatchMake] - Simple scripting for GRID processing


= MetaCommand =
= MetaCommand and MetaOutput =
== Introduction: ==
Thanks to MetaCommand you can easily receive parameters in your software from the command line.The purpose of this class is to provide a unified framework for command line parsing.
 
For instance, all programs that use MetaCommand are self-described using the command line –vxml:
 
$ ./AtlasSummation -vxml
<option>
<number>0</number>
<name>Outputcount</name>
<tag>oc</tag>
<description>Image of count values for each voxel</description>
<required>0</required>
<nvalues>1</nvalues>
<field>
<name>filename</name>
<description></description>
<type>string</type>
<value></value>
<external>0</external>
<required>1</required>
…
 
Moreover, The description of the parameters can be easily retrieve at runtime via
./your_program –v :
 
 
$ ./AtlasSummation -v
Usage : d:\Work\itkUNCApplications-VC++\bin\debug\AtlasSummation.exe
[-oc <filename>  : Image of count values for each voxel]
[-ao  : Adjust the mean origin to the input images]
[-as  : Adjust the mean size to fit the input images]
[-stdev <bool> (true) : Is the sigma image standard deviation?]
[-LT [number] (4) : lowerThreshold : Minimum number of contributing images for pixel to be counted in output]
[-OS <X> <Y> <Z>  : outputImageSize X Y Z : output size (can't use with adjust size)]
[-OSp <X> <Y> <Z>  : output spacing (default- initial image spacing)]
<infile>  : infile filename
<outputmean>  : output mean filename
<outputvar>  : output variance filename
 
All these advantages are provided for you in the MetaCommand class.
 
== MetaCommand in use: ==
 
'''Definitions:'''
 
Metacommand differentiates the term ‘Option’ and ‘Field’. Basically an option can be placed anywhere in the command line as long as it is defined by a tag. On the other hand, the fields are placed in order and do not require any tag.
 
'''Programmer’ point of view:'''
 
To use MetaCommand you have to include the file metaCommand.h in your code.
#include <metaCommand.h>
 
Then you need to declare a MetaCommand object, for example:
MetaCommand command;
 
To add an option (a tag + a field) you have to use 2 methods:
* To define an option:
SetOption(std::string name, std::string tag, bool required,
          std::string description)
 
There are two more arguments (the type = flag, and the default value=””) but it is not necessary to put them because they are initialized correctly by default. The first argument is the name of the tag, the second is the string to write in your command line to use this option, the third indicates if the tag is required or not, and the last one is a description of the tag.
 
AddOptionField(std::string optionName, std::string Name,
              MetaCommand::TypeEnumType Type, bool required,
              std::string defValue).
 
The first argument indicates at which tag the field belongs giving the name of the tag (see first argument of SetOption), the second argument is the name of the field, the third one is the type of the field (bool, int, float or string), the fourth argument indicates if the field is required or not, and the last one is the default value (note that you have to put a string even if it is your type is int or float). NOTE: you can use several times the method AddOptionFIeld for a same tag.
 
* To define a field:
You can also just add a field (without the tag) thanks to the following method:
 
AddField(std::string Name, std::string Description,
          MetaCommand::TypeEnumType Type, bool ExternalData).
The first argument is the name of the field, the second his description, the third one his type and the last one indicates if that data is external to your application or not (e.g : a filename is external but the size of the input image is internal).
 
'''Example'''
 
Let’s define a command line like: ./example input.mha –w 2 output.mha
This will be coded as:
MetaCommand command;
command.SetOption("Write","w",false,"writes the current image to the designated file with a type");
command.AddOptionField("Write","filename",MetaCommand::STRING,true);
command.AddOptionField("Write","Type",MetaCommand::INT,false,”1”); //by default type=1
command.AddField("infile","infile filename",MetaCommand::STRING,true);
 
Then the user can parse the command line thanks to the method:
Parse(int argc, char* argv[])
if( !command.Parse(argc,argv) )
{
return 1;
}
 
 
Finally to access the different options, one of these 4 methods can be used:
    * GetValueAsString(Option option, std::string fieldName)
    * GetValueAsFloat(Option option, std::string fieldName)
    * GetValueAsInt(Option option, std::string fieldName)
    * GetValueAsBool(Option option, std::string fieldName)
 
To recover the parameters of an option (tag + field), in the first argument of these methods the name of the tag has to be specified and in the second argument the name of the field.
To recover the parameter of a single field you just need to specify the first argument: the name of the field.
 
 
'''Example:''' to access the parameters of the previous example :
std::string imageIn = command.GetValueAsString("infile");
std::string imageOut = command.GetValueAsString("Write","filename");
int OutputType = command.GetValueAsInt(“Write","Type");
 
 
== MetaCommand Output: ==
To use MetaCommand you have to include the file metaCommand.h in your code.
#include <metaCommand.h>
 
Then you need to declare a MetaOutput object, for example:
MetaCommand output;
 
And you should be put this code, before the parsing :
  output.SetMetaCommand(&command);
  BatchMakeStream bmstream(&command);
 
Then you could add a field to see a variable in BatchMake.
In that example , x is an int variable, and we need to see its value in BatchMake:
  int x = 10;
  output.AddFloatField("Result","Computation Result",x); //Result will be the filed of output
  output.Write();


Now, you can access to the variable "x" via BatchMake with the command line :
The MetaCommand and MetaOutput classes are provided with the MetaIO library.  They simplify the parsing of command-line parameters, integration of executables with [http://www.batchmake.org BatchMake], and distributed processing.
Run(output ${example})
'''Set(result example.Result)'''
Echo(x = ${result})


But before that, you need to add this command line at the beginning of your script :
Documentation on [[MetaIO/MetaCommand_Documentation | MetaCommand and MetaOutput]] is available as a wiki page.
SetAppOption(example.GenerateXMLMetaOutput 1)

Latest revision as of 19:40, 9 June 2012

MetaIO Documentation

  • MetaIO began in 1996 to address the growing complexity and inflexibility of medical image formats that were available at that time.
  • MetaIO has maintained backward compatibility since its initial public release in 2000 as part of the Insight Toolkit (ITK)
  • MetaIO is used for the majority of tests and examples in the ITK framework

Highlights

  • Simple text descriptor using tagged field format
  • Descriptor can appear as a text header preceding binary data
  • Descriptor can be in a separate file that describes a binary data file
  • Via separate header and binary data files, multiple binary data formats are supported
    • Bmp, .im, dicom
    • UChar, Char, UShort, Short, UInt, Int, Float, Double voxels
  • Supports storage of parameters necessary for real-world medical image processing
    • Element (e.g., voxel or pixel) size
    • Image position and orientation
    • Patient position and orientation
  • Supports MSB and LSB byte ordering
  • ND Data in a single file
  • ND Data as a sequence of (N-1)D files
  • Optional compression
  • Easily extended to handle user-defined fields on a per application basis

Documentation

Get the software

  • Most recent version available as part of the Insight Toolkit in the directory Insight/Utilities/MetaIO
  • MetaIO is also available as part of the Visualization Toolkit in the directory VTK/Utilities/vtkmetaio

VTK MetaIO -vs- ITK MetaIO

The ITK and VTK distributions differ by having local include files that cause each distribution to be wrapped in a different namespace. In this manner, programs can link with the VTK and ITK libraries without receiving errors related to the same function having been previously defined.

A summary of the differences are as follows:

  • Each distribution has a file called "localMetaConfiguration.h." This file defines METAIO_USE_NAMESPACE, META_IO_NAMESPACE, include paths for vtk/itk's kwsys libraries, and namespaces for STL, STREAM, and KWSYS libraries. Important differences are as follows
    • ITK distribution:
      • Does not use a namespace - in order to preserve backward compatibility
      • Includes itk_zlib.h
      • Includes itksys/SystemTools.hxx for kwsys
    • VTK distribution:
      • Uses the namespace vtkmetaio
      • Includes vtkConfigure.h to learn about std dependencies
      • Includes vtksys/SystemTools.hxx for kwsys
      • Defines METAIO_EXTERN and METAIO_EXPORT for shared libraries
  • Each .h and .cxx file in MetaIO includes the localMetaConfiguration.h file using quotes to cause the local version of that file to be found first. Thus, a single application should be able to compile with VTK and ITK without problems/conflict

Usage:

  • When using MetaIO from within VTK, prefix with the namespace vtkmetaio::
  • When using MetaIO from within ITK, call the function without a namespace
  • Developers should never issue "using namespace vtkmetaio" in a program if VTK and ITK are to be used in that program.

FAQ

  1. I am trying to use MetaIO to point to and read my set of png (or tiff or jpeg) files, but it isn't working. What is wrong with MetaIO?
    • More than likely your files are using compressed versions of those image formats. MetaIO only supports its own type of image compression - it cannot read data that is compressed in other formats. Sorry.
  2. Should I use Origin, Position, or Offset (and similarly Orientation, Rotation, or TransformMatrix) to represent the recorded location of my data?
    • Due to backward compatibility constraints, any of these variations is supported and produces identical results.
  3. What is the difference between BinaryDataByteOrderMSB and ElementDataByteOrderMSB?
    • Again backward compatibility is the driving force. Over the past decade some inconsistencies crept into the implementation of derived classes, and when we go back and standardize, we must maintain backward compatibility. Therefore, equivalent terms are often defined in the tag dictionary.
  4. I think MetaIO is encoding my image's orientation incorrectly...
    • We greatly appreciate your feedback -- particularly if you can provide the data and/or data conversion program that is exhibiting this behavior. We've tried to get it "right" but data orientation is both critical and tricky. Please send your data and details to stephen.aylward@kitware.com
  5. What orientation convention is MetaIO using?

Related Links

  • ITK
  • VTK
  • MRIConvert - excellent tool for DICOM to MetaImage conversion
  • FusionViewer - U of Washington tool for pet/ct visualization
  • I3DLib - Microscopy software - Masaryk University
  • BatchMake - Simple scripting for GRID processing

MetaCommand and MetaOutput

The MetaCommand and MetaOutput classes are provided with the MetaIO library. They simplify the parsing of command-line parameters, integration of executables with BatchMake, and distributed processing.

Documentation on MetaCommand and MetaOutput is available as a wiki page.

Retrieved from "https://public.kitware.com/Wiki/index.php?title=ITK/MetaIO&oldid=47453"