Technical Notes of the Wrapping of ITK Algorithms in MeVisLab

Technical Notes

For release notes see the official MeVisLab release notes, the section MeVisLab2.3 to MeVisLab2.6 , and further sections of this document.

  • See Integration of ITK Algorithms in MeVisLab for details about the ITK-MeVisLab bindings.
  • All ITK modules are compiled to filter 2D, and/or 3D and 6D images if they support that. A few filters only work on 2D or 3D as described in at ModuleDetails.txt. If any filter is not compiled for 6D and it is used to process higher images > 3D then all 3D subsets of the higher dimensional image are handled as independent 3D images which then are filtered. The same holds for 3D and 2D, respectively
  • Most ITK modules in MeVisLab currently process the following voxel types:
    • 8, 16 and 32 bit signed and unsigned integer
    • float and double
    • Some (covariant) vector, tensor and complex type related modules are implemented. They work on types such as vec2, vec3, vec4, vec8, vec16, complexf or complexd. The MeVisLab type vec6 is used for the currently used tensor pixel types (modules e.g. SymmetricRankTensor2D and DiffusionTensor3D).
    • Some ITK filters do not support all types or combinations. They either automatically convert the input pixel type to the required one or they invalidate the output image.
    • Have a look at ModuleDetails.txt for detailed information about wrapped ITK modules, their limitations and the data types they require/support.
    • Two different strategies are used in order to handle input images whose voxel data do not match:
      • The voxel data is implicitly converted. For example complex values or higher dimensional vector are automatically cast to 2D vectors if the filter requires vec2 or vec2f voxel data.
      • The output image of the filter is invalidated, for example if a vector voxel type is connected to a filter which requires scalar voxels. Notes:
        • A cast from a non-scalar voxel type to another one is performed component by component. For example a cast from a 3D vec3 (3,5,7) results to a 2D vec2 (3,5). A cast from a 2D vector vec2 (9,5) to a 3D vec3 results to (9,5,0). That means higher components are lost when casting to lower dimensions and ?new? higher dimensional components are set to 0.
        • A cast from a scalar to a vector type results in a vector whose components are set to the scalar value.
        • A cast from a scalar to a complex number results to a complex with a real part given by the scalar value and an imaginary part equal to 0.
  • A few modules appear to be slower than expected; this is typically a result from page based image processing. These module recalculate the entire or large fragments of the image for each requested page of the output image. A workaround is to set the page extent of the input image to the image extent and the output images to the previous page extent when using such modules. The modules PageToImageExtent and SetPageExtent do these operations. That, however, only works fine if the ML cache is at least 3 times larger than the size of the image; otherwise it might lead to performance downgrades or memory problems.
  • The RGB pixel type is still not supported since colour model handling works different in ML modules. Nevertheless there is a number of ML modules in MeVisLab related to colour conversions, transfer functions, look up tables. Thus in many cases equivalents for the ITK modules will be available.

Release Notes

MeVisLab2.3 to MeVisLab2.6

Upgrade to ITK version 4.6.0 from December, 27th, 2013, 02-53pm MET from the master GIT repository from http://www.itk.org.

  • Changes:

    • Many modules have new parameters from base classes such as Coordinate Tolerance and Direction Tolerance inherited from itkImageToImageFilter and an additional mask image input in classes inherited from itkHistogramThresholdImageFilter.
    • Modules wrapping deprecated and V3Compatibility toolkit classes have been removed.
    • Help file layouts are in mhelp format now.
    • Some example networks and general robustness have been improved, generated codes create less warnings at compilation time, some incorrectly working class wrappers and instabilities have been fixed.
    • The directory structure of generated modules classes have same structure as other MeVisLab packages and manually developed and generated codes have been separated into different directories. Generated wrapper codes do not use old-style C-/C++-statements any more. Generated code and the 3rd-party ITK toolkit class binding have been made mostly C++-11 compliant.

  • Added module(s):

    itkBinShrinkImageFilter

  • Removed deprecated modules:

    itkCompose2DCovariantVectorImageFilter, itkCompose2DVectorImageFilter, itkCompose3DCovariantVectorImageFilter, itkCompose3DVectorImageFilter, itkReflectImageFilter, itkShiftScaleInPlaceImageFilter .

  • Removed V3Compatibility module(s):

    itkGradientToMagnitudeImageFilter.

MeVisLab2.2 to MeVisLab2.3

Upgrade to ITK version 4.1 from January, 31st, 2012, 12-05am MET from the master GIT repository from http://www.itk.org.

MeVisLab2.1 to MeVisLab2.2

Upgrade to ITK version 4.0 from April, 1st, 2011, 9-45am MET from the master GIT repository from http://www.itk.org.

MeVisLab2.0 to MeVisLab2.1

Upgrade to ITK version 3.19 from April, 29th, 2010, 10-20pm MET from the CVS repository from http://www.itk.org.

  • Wrapper of itkSTAPLEImageFilter now uses global image filtering instead of region based filtering.
  • Fix in conversion between ML and ITK patient coordinate system which occurred when coordinate systems were rotated.
  • Revised: itkImageFileReader which loads images with non scalar voxels now, uses less memory, has new open and close buttons, provides better path proposals while browsing and the options to enable/disable sub voxel shift in patient coordinate system.
  • New: itkImageFileWriter wrapped, providing the option to save images in numerous file formats and scalar and non scalar voxels types.
  • Many modules now are compiled also for 6 dimensions to support non 2D/3D cases.
  • Some improved example networks (of some itkLevelSet-, itkFastMarching-, and itkVectorConnectedComponentImage filters).
  • Invalid usage of flat kernel elements removed.
  • Some modules compiled with incorrect input/output type combinations fixed.
  • Metric modules revised: New setting makes it configurable when to update the FixedImageRegions parameter.

MeVisLab1.6.x to MeVisLab2.0

Upgrade to ITK version 3.9 from September, 4th, 2008, 11-09pm from the CVS repository from http://www.itk.org.

  • Some modules wrapping classes from ITK review directory have been removed since licensing is not clear or since they were not useful: itkBinaryMorphologicalClosingImageFilter, itkBinaryMorphologicalOpeningImageFilter, itkMorphologicalWatershedFromMarkersImageFilter, itkMorphologicalWatershedImageFilter, itkRegionalMaximaImageFilter, itkRegionalMinimaImageFilter, itkValuedRegionalMaximaImageFilter, itkValuedRegionalMinimaImageFilter, itkVectorLinearInterpolateImageFunction, itkVectorNearestNeighborInterpolateImageFunction.
  • New module: itkDisplacementFieldJacobianDeterminantFilter.

MeVisLab1.5 to MeVisLab1.6.x

Upgrade to ITK version 3.5 from January, 25th, 2008, 12-34pm from the CVS repository from http://www.itk.org.

MeVisLab1.4 to MeVisLab1.5

Upgrade to ITK version 3.3 from April, 16th, 2007, 14-23pm from the CVS repository from http://www.itk.org.

  • ITK related modules are part of the MeVisLab1.5 now, and not an AddOn installer any more.
  • Module wrapper generator is available to wrap ITK and VTK user classes as MeVisLab modules. See new module ITKVTKGenerator and its module help for details.
  • Many filters formerly failing on 2D images work now (e.g. itkShapeDetectionLevelSetImageFilter).
  • Error messages occurring when using or loading filters with same name from different libraries (ITK/VTK/ML) have been removed. Internally these module use different names now.
  • A number of functions have been added. They can be connected e.g. to LevelSetFilters now. Some of them are still unused.
  • Registration metrics set sizes of voxels of output image correctly now.
  • Some filters which do not support paging correctly, thus have been switched to operate globally on images.
  • The ITK book examples which are available as MeVisLab networks have been revised and updated.
  • A number of new example networks have been added.
  • All string passes to ITK and VTK objects covert from UTF8 to Latin1 unicoding, and when reading strings then the other way round is converted. This is due to the Latin1 code usage of ITK/VTK and the UTF8 code usage of MeVisLab.
  • For added and removed modules see tables with added/removed modules in MeVisLab1.5 release notes.
  • Fixed Filters:
  • For further issues see Bugs, Limitations and Workarounds. and release notes of former releases.

From Alpha2 to Alpha3 (MeVisLab1.4)

  • Upgraded to ITK 2.7.
  • New filters: itkInvertIntensityImageFilter, itkModulusImageFilter, itkMorphologicalGradientImageFilter.
  • Old filters now wrapped: itkVectorConnectedComponentImageFilter
  • Filters removed from ITK: itkLazyEdgeDetectionImageFilter3D
  • Some filters which did not support paging correctly, have been switched to work globally now (itkScalarConnectedComponent- and itk*Reconstruction*ImageFilters).
  • Metrics support optional mask images and interpolation of image data now.

Bugs, Limitations and Workarounds

General Limitations

  • Missing ITK Algorithms. Several ITK algorithms are still not wrapped or explicitly excluded. This includes:

    • VTK, mesh or FEM related filters
    • Algorithms with complex template arguments or parameters which have no direct or similar correspondence to MeVisLab parameter classes
    • Functions. Although they can be wrapped easily as ML modules, only a few of them are wrapped, because their application is still limited.
    • Internally used ITK classes

    Future versions may include these algorithms. However, many (at least partial) equivalents or similar modules are already available in MeVisLab:

    ITK Algorithm MeVisLab Equivalent
    itkBinaryFunctorImageFilter Arithmetic2
    itkCastImageFilter ImgPropConvert, SubImage, TensorArithmetic1
    itkChangeInformationImageFilter ImgPropConvert
    itkComposeRGBImageFilter ConcatImages, ImageComposer
    itkCropImageFilter SubImage, ROISelect
    itkEigenAnalysis2DImageFilter TensorArithmetic1, TensorArithmetic2
    itkExtractImageFilter SubImage, ROISelect
    itkDoubleThresholdImageFilter IntervalThresh or two Threshold modules
    itkJoinImageFilter TypeComposer
    itkJoinSeriesImageFilter ImageComposer, Compose3DFrom2DFiles, ConcatImages, DirectDicomImport
    itkMatrixIndexSelectionImageFilter TensorArithmetic1
    itkNaryAddImageFilter Cascaded Arithmetic2 modules TensorArithmetic2
    itkNonThreadedShrinkImageFilter Resample3D, itkBinShrinkImageFilter
    itkOrientImageFilter OrthoReformat3, MPR, Reformat
    itkRandomImageSource AddNoise
    itkScalarToArrayCastImageFilter TypeComposer, TypeFromScalars, TensorArithmetic1
    itkStatisticsImageFilter ImageStat, MinMaxScan
    itkThresholdImageFilter Threshold, IntervalThresh
    itkUnaryFunctorImageFilter Arithmetic1, TensorArithmetic1, TypeFromScalars
    itkVTKImageExport MLToVTKImage
    itkVTKImageImport VTKToMLImage

  • Out-Of-Range Checks.

    Many ITK algorithms still do not check for invalid or out-of-range parameters. This especially holds for indexing/range parameters, missing or empty parameter, sets or NULL pointers. These problems are difficult to find and even more difficult to fix in the automatically generated ITK module set for MeVisLab. Thus, be careful especially when using non-standard parameter settings.

  • Window Settings.

    Viewers in example networks often have no optimal window settings. You can move the mouse with pressed right mouse button to optimize the settings manually.

  • Removed Filters.

    Some filters could not be built and to be removed from the previous version, such as itkFastIncrementalBinaryDilateImageFilter and itkSignedDanielssonDistanceMapImageFilter. The itkWarpImageFilter and itkWarpVectorImageFilter for some reason do not work correctly any more and have been removed, too.

  • Missing Filter Parameters.

    The following parameters from base classes are not made available in user interfaces to avoid invalid manipulations of the filter operations and to avoid too large user interfaces: InPlace, Debug, GlobalWarningDisplay, MetaDataDictionary, AbortGenerateData, ReleaseDataBeforeUpdateFlag, Progress, NumberOfThreads, ReferenceCount, ReleaseDataFlag

  • Disabled Filter Parameters:

    Some modules do not provide all parameters of the corresponding ITK classes. In future versions some of them will be supported. Currently, these parameters are typically marked with ?(N/A)? in the user interface of the modules, since they are of complex nature, difficult to wrap, or they are not useful for the current filter implementation. The following ITK types of parameters belong to them:

    • AccessorType, AuxValueContainer
    • NarrowBandType, NeighborhoodRadiusType, NormalVariateGeneratorType, NumberOfComponentsCallbackType
    • BufferPointerCallbackType, BulkTransformType
    • OutputNeighborhoodType, OriginCallbackType
    • ClassifierType, CoordinateOrientationCode, CostFunctionType
    • PipelineModifiedCallbackType, PropagateUpdateExtentCallbackType
    • DataExtentCallbackType, DeformationFieldType
    • RegistrationType
    • ExpandFactorsType (only available as single scalar), Element
    • ScaleType, ScalarTypeCallbackType, ScheduleType, SpacingCallbackType, std::vector<double>, StatusType
    • FiniteDifferenceFunctionType, FixedImageMaskType, FixedImagePyramidType, FixedImageType, FixedPointSetType, FloatOriginCallbackType, FloatSpacingCallbackType
    • InputPath, TLabelImage, TransformType
    • ImageMaskType, InputPixelObjectType, InterpolatorType
    • UpdateDataCallbackType, UpdateInformationCallbackType
    • KernelTransformType
    • VersorType, VnlQuaternionType, void, void*
    • LandmarkContainer, LaplacianFilterPointer
    • WholeExtentCallbackType
    • MaterialType, MeasureType, MetricBaseTypePointer, MovingImagePyramidType, MovingImageMaskType, MovingImageType

Known Limitations and Bugs of Specific Filters

  • itkApproximateSignedDistanceMapImageFilter:

    Seems not to work with images containing 0 values.

    Workaround: Use images without 0 values inside. IntervalThresh can be configured easily to do that.

  • itkDanielssonDistanceMapImageFilter:

    Currently only one output supported.

    Workaround: None.

  • itkExpandImageFilter:

    Permits only specification of one expand factor for all dimensions and produces gaps in image for some expand factors, for example 5, 6.

    Workaround: Use MeVisLab Resample3D instead.

  • itkKLMRegionGrowImageFilter:

    Sensitive for inappropriate parameters which lead to crashes or very long calculation times.

  • itkWarpImageFilter, itkWarpVectorImageFilter:

    Has internal problem calculating the output image.

  • Many modules do not use region based processing (as listed in ModuleDetails.txt):

    All these filters require the regions requested at their outputs to be equal to the largest possible region (in these cases that is identical with the image extents). Otherwise they seem to calculate incorrect results or they become very inefficient in MeVisLab contexts. Hence, these filters have been configured so that they use a page extent equal to image extent which leads to the desired effect. However, a disadvantage of this approach is that the performance of page based image processing of subsequent modules in module networks degrades due to the (usually) large page/image extents. It also leads to more inefficient memory usage and assumes that the output image can be stored in the ML cache. Furthermore, this only works properly if the ML cache is at least 3 times larger than the size of the image; otherwise it might lead to performance downgrades or memory problems.

    Workarounds:

    A workaround for the large page extent at the module output is to connect a SetPageExtent module between the output and subsequent modules. So a smaller page extent can be used in the subsequent modules.

    The performance of the filter can degrade heavily in the case that the output result does not fit in the ML cache, because on each page request on the image output the entire image needs to be recalculated. Use smaller images or set a higher ML cache size in MeVisLab preferences such that the output image can remain in cache.

  • itkPolylineMaskImageFilter and itkPolylineMask2DImageFilter:

    Both modules are experimental wrappings and do not operate reliably; they still produce errors while using them.