Medical Imaging Interaction Toolkit  2016.11.0
Medical Imaging Interaction Toolkit
mitk::DICOMITKSeriesGDCMReader Class Reference

Flexible reader based on itk::ImageSeriesReader and GDCM, for single-slice modalities like CT, MR, PET, CR, etc. More...

#include <mitkDICOMITKSeriesGDCMReader.h>

Inheritance diagram for mitk::DICOMITKSeriesGDCMReader:
Collaboration diagram for mitk::DICOMITKSeriesGDCMReader:

Public Types

typedef const std::list< DICOMDatasetSorter::ConstPointer > ConstSorterList
 
- Public Types inherited from mitk::DICOMFileReader
typedef DICOMImageBlockDescriptor::AdditionalTagsMapType AdditionalTagsMapType
 

Public Member Functions

 mitkClassMacro (DICOMITKSeriesGDCMReader, DICOMFileReader)
 
 mitkCloneMacro (DICOMITKSeriesGDCMReader)
 
 mitkNewMacro1Param (DICOMITKSeriesGDCMReader, unsigned int)
 
virtual void AnalyzeInputFiles () override
 Runs the sorting / splitting process described in Loading strategy. Method required by DICOMFileReader. More...
 
virtual bool LoadImages () override
 Loads images using itk::ImageSeriesReader, potentially applies shearing to correct gantry tilt. More...
 
virtual bool CanHandleFile (const std::string &filename) override
 Indicate whether this reader can handle given file. More...
 
virtual void AddSortingElement (DICOMDatasetSorter *sorter, bool atFront=false)
 Add an element to the sorting procedure described in Loading strategy. More...
 
ConstSorterList GetFreelyConfiguredSortingElements () const
 
void SetFixTiltByShearing (bool on)
 Controls whether to "fix" tilted acquisitions by shearing the output (see Gantry tilt handling). More...
 
bool GetFixTiltByShearing () const
 
void SetAcceptTwoSlicesGroups (bool accept) const
 Controls whether groups of only two images are accepted when ensuring consecutive slices via EquiDistantBlocksSorter. More...
 
bool GetAcceptTwoSlicesGroups () const
 
void SetToleratedOriginOffsetToAdaptive (double fractionOfInterSliceDistanct=0.3) const
 See Forced Configuration. More...
 
void SetToleratedOriginOffset (double millimeters=0.005) const
 See Forced Configuration. More...
 
double GetToleratedOriginError () const
 
bool IsToleratedOriginOffsetAbsolute () const
 
double GetDecimalPlacesForOrientation () const
 
virtual bool operator== (const DICOMFileReader &other) const override
 
virtual DICOMTagPathList GetTagsOfInterest () const override
 
- Public Member Functions inherited from mitk::DICOMFileReader
 mitkClassMacroItkParent (DICOMFileReader, itk::Object)
 
void SetInputFiles (const StringList &filenames)
 This input files. More...
 
const StringListGetInputFiles () const
 This input files. More...
 
unsigned int GetNumberOfOutputs () const
 Number of outputs, only meaningful after calling AnalyzeInputFiles() More...
 
const DICOMImageBlockDescriptorGetOutput (unsigned int index) const
 Individual outputs, only meaningful after calling AnalyzeInputFiles(). More...
 
void SetConfigurationLabel (const std::string &)
 Short label/name to describe this reader. More...
 
std::string GetConfigurationLabel () const
 Short label/name to describe this reader. More...
 
void SetConfigurationDescription (const std::string &)
 One-sentence description of the reader's loading "strategy". More...
 
std::string GetConfigurationDescription () const
 One-sentence description of the reader's loading "strategy". More...
 
void PrintConfiguration (std::ostream &os) const
 Print configuration description to given stream, for human reader. More...
 
void PrintOutputs (std::ostream &os, bool filenameDetails=false) const
 Print output description to given stream, for human reader. More...
 
virtual void SetAdditionalTagsOfInterest (const AdditionalTagsMapType &tagList)
 Set a list of DICOMTagPaths that specifiy all DICOM-Tags that will be copied into the property of the mitk::Image. More...
 
virtual void SetTagLookupTableToPropertyFunctor (mitk::DICOMImageBlockDescriptor::TagLookupTableToPropertyFunctor functor)
 Set a functor that defines how the slice-specific tag-values are stored in a Property. More...
 

Static Public Member Functions

static Pointer New ()
 
- Static Public Member Functions inherited from mitk::DICOMFileReader
static bool IsDICOM (const std::string &filename)
 Test whether a file is DICOM at all. More...
 

Protected Types

typedef std::vector< DICOMDatasetAccessingImageFrameListSortingBlockList
 

Protected Member Functions

virtual void InternalPrintConfiguration (std::ostream &os) const override
 Configuration description for human reader, to be implemented by sub-classes. More...
 
void PushLocale () const
 Remember current locale on stack, activate "C" locale. "C" locale is required for correct parsing of numbers by itk::ImageSeriesReader. More...
 
void PopLocale () const
 Activate last remembered locale from locale stack "C" locale is required for correct parsing of numbers by itk::ImageSeriesReader. More...
 
 DICOMITKSeriesGDCMReader (unsigned int decimalPlacesForOrientation=5)
 
virtual ~DICOMITKSeriesGDCMReader ()
 
 DICOMITKSeriesGDCMReader (const DICOMITKSeriesGDCMReader &other)
 
DICOMITKSeriesGDCMReaderoperator= (const DICOMITKSeriesGDCMReader &other)
 
virtual SortingBlockList Condense3DBlocks (SortingBlockList &resultOf3DGrouping)
 "Hook" for sub-classes, see Sub-classes can condense multiple blocks into a single larger block More...
 
virtual DICOMTagCache::Pointer GetTagCache () const
 
void SetTagCache (const DICOMTagCache::Pointer &) override
 A way to provide external knowledge about files and tag values is appreciated. More...
 
virtual bool LoadMitkImageForOutput (unsigned int o)
 Loads the mitk::Image by means of an itk::ImageSeriesReader. More...
 
virtual bool LoadMitkImageForImageBlockDescriptor (DICOMImageBlockDescriptor &block) const
 
- Protected Member Functions inherited from mitk::DICOMFileReader
 DICOMFileReader ()
 
virtual ~DICOMFileReader ()
 
 DICOMFileReader (const DICOMFileReader &other)
 
DICOMFileReaderoperator= (const DICOMFileReader &other)
 
void ClearOutputs ()
 
void SetNumberOfOutputs (unsigned int numberOfOutputs)
 
void SetOutput (unsigned int index, const DICOMImageBlockDescriptor &output)
 
DICOMImageBlockDescriptorInternalGetOutput (unsigned int index)
 non-const access to the DICOMImageBlockDescriptor More...
 
virtual AdditionalTagsMapType GetAdditionalTagsOfInterest () const
 
mitk::DICOMImageBlockDescriptor::TagLookupTableToPropertyFunctor GetTagLookupTableToPropertyFunctor () const
 

Static Protected Member Functions

static std::string GetActiveLocale ()
 Return active C locale. More...
 
static SortingBlockList InternalExecuteSortingStep (unsigned int sortingStepIndex, const DICOMDatasetSorter::Pointer &sorter, const SortingBlockList &input)
 Sorting step as described in Loading strategy. More...
 
static ReaderImplementationLevel GetReaderImplementationLevel (const std::string sopClassUID)
 Describe this reader's confidence for given SOP class UID. More...
 

Protected Attributes

bool m_FixTiltByShearing
 
mitk::EquiDistantBlocksSorter::Pointer m_EquiDistantBlocksSorter
 
mitk::NormalDirectionConsistencySorter::Pointer m_NormalDirectionConsistencySorter
 

Detailed Description

Flexible reader based on itk::ImageSeriesReader and GDCM, for single-slice modalities like CT, MR, PET, CR, etc.

Implements the loading processed as structured by DICOMFileReader offers configuration of its loading strategy.

Documentation sections:

Loading strategy

The set of input files is processed by a number of DICOMDatasetSorter objects which may do two sort of things:

  1. split a list of input frames into multiple lists, based on DICOM tags such as "Rows", "Columns", which cannot be mixed within a single mitk::Image
  2. sort the frames within the input lists, based on the values of DICOM tags such as "Image Position Patient"

When the DICOMITKSeriesGDCMReader is configured with DICOMDatasetSorters, the list of input files is processed as follows:

  1. build an initial set of output groups, simply by grouping all input files.
  2. for each configured DICOMDatasetSorter, process:
    • for each output group:
      1. set this group's files as input to the sorter
      2. let the sorter sort (and split)
      3. integrate the sorter's output groups with our own output groups

Forced Configuration

In all cases, the reader will add two DICOMDatasetSorter objects that are required to load mitk::Images properly via itk::ImageSeriesReader:

  1. As a first step, the input files will be split into groups that are not compatible because they differ in essential aspects:
    • (0028,0010) Number of Rows
    • (0028,0011) Number of Columns
    • (0028,0030) Pixel Spacing
    • (0018,1164) Imager Pixel Spacing
    • (0020,0037) Image Orientation (Patient)
    • (0018,0050) Slice Thickness
    • (0028,0008) Number of Frames

As are two forced last steps:

  1. There will always be an instance of EquiDistantBlocksSorter, which ensures that there is an equal distance between all the frames of an Image. This is required to achieve correct geometrical positions in the mitk::Image, i.e. it is essential to be able to make measurements in images.
  2. There is always an instance of NormalDirectionConsistencySorter, which makes the order of images go along the image normals (see NormalDirectionConsistencySorter)

User Configuration

The user of this class can add more sorting steps (similar to the one described in above section) by calling AddSortingElement().

Usually, an application will add sorting by "Image Position Patient", by "Instance Number", and by other relevant tags here.

Gantry tilt handling

When CT gantry tilt is used, the gantry plane (= X-Ray source and detector ring) and the vertical plane do not align anymore. This scanner feature is used for example to reduce metal artifacs (e.g. Lee C , Evaluation of Using CT Gantry Tilt Scan on Head and Neck Cancer Patients with Dental Structure: Scans Show Less Metal Artifacts. Presented at: Radiological Society of North America 2011 Scientific Assembly and Annual Meeting; November 27- December 2, 2011 Chicago IL.).

The acquired planes of such CT series do not match the expectations of a orthogonal geometry in mitk::Image: if you stack the slices, they show a small shift along the Y axis:

    without tilt       with tilt

      ||||||             //////
      ||||||            //////
  --  |||||| --------- ////// -------- table orientation
      ||||||          //////
      ||||||         //////

  Stacked slices:

    without tilt       with tilt

   --------------    --------------
   --------------     --------------
   --------------      --------------
   --------------       --------------
   --------------        --------------

As such gemetries do not "work" in conjunction with mitk::Image, DICOMITKSeriesGDCMReader is able to perform a correction for such series. Whether or not such correction should be attempted is controlled by SetFixTiltByShearing(), the default being correction. For details, see "Internals" below.

Testing

A number of tests is implemented in module DICOMTesting, which is documented at MITK DICOM testing.

Class internals

Internally, the class is based on GDCM and it depends heavily on the gdcm::Scanner class.

Since the sorting elements (see DICOMDatasetSorter and DICOMSortCriterion) can access tags only via the DICOMDatasetAccess interface, BUT DICOMITKSeriesGDCMReader holds a list of more specific classes DICOMGDCMImageFrameInfo, we must convert between the two types sometimes. This explains the methods ToDICOMDatasetList(), FromDICOMDatasetList().

The intermediate result of all the sorting efforts is held in m_SortingResultInProgress, which is modified through InternalExecuteSortingStep().

Overview of related classes

The following diagram gives an overview of the related classes:

implementeditkseriesgdcmreader.jpg

Details about the tilt correction

The gantry tilt "correction" algorithm fixes two errors introduced by ITK's ImageSeriesReader:

  • the plane shift that is ignored by ITK's reader is recreated by applying a shearing transformation using itk::ResampleFilter.
  • the spacing is corrected (it is calculated by ITK's reader from the distance between two origins, which is NOT the slice distance in this special case)

Both errors are introduced in itkImageSeriesReader.txx (ImageSeriesReader<TOutputImage>::GenerateOutputInformation(void)), lines 176 to 245 (as of ITK 3.20)

For the correction, we examine two consecutive slices of a series, both described as a pair (origin/orientation):

  • we calculate if the first origin is on a line along the normal of the second slice
    • if this is not the case, the geometry will not fit a normal mitk::Image/mitk::Geometry3D
    • we then project the second origin into the first slice's coordinate system to quantify the shift
    • both is done in class GantryTiltInformation with quite some comments.

The geometry of image stacks with tilted geometries is illustrated below:

  • green: the DICOM images as described by their tags: origin as a point with the line indicating the orientation
  • red: the output of ITK ImageSeriesReader: wrong, larger spacing, no tilt
  • blue: how much a shear must correct
tilt-correction.jpg

Sub-classes can condense multiple blocks into a single larger block

The sorting/splitting process described above is helpful for at least two more DICOM readers, which either try to load 3D+t images or which load diffusion data.

In both cases, a single pixel of the mitk::Image is made up of multiple values, in one case values over time, in the other case multiple measurements of a single point.

The specialized readers for these cases (e.g. ThreeDnTDICOMSeriesReader) can reuse most of the methods in DICOMITKSeriesGDCMReader, except that they need an extra step after the usual sorting, in which they can merge already grouped 3D blocks. What blocks are merged depends on the specialized reader's understanding of these images. To allow for such merging, a method Condense3DBlocks() is called as an absolute last step of AnalyzeInputFiles(). Given this, a sub-class could implement only LoadImages() and Condense3DBlocks() instead repeating most of AnalyzeInputFiles().

Definition at line 194 of file mitkDICOMITKSeriesGDCMReader.h.

Member Typedef Documentation

typedef const std::list<DICOMDatasetSorter::ConstPointer> mitk::DICOMITKSeriesGDCMReader::ConstSorterList

Definition at line 223 of file mitkDICOMITKSeriesGDCMReader.h.

Constructor & Destructor Documentation

mitk::DICOMITKSeriesGDCMReader::DICOMITKSeriesGDCMReader ( unsigned int  decimalPlacesForOrientation = 5)
protected

Definition at line 31 of file mitkDICOMITKSeriesGDCMReader.cpp.

mitk::DICOMITKSeriesGDCMReader::~DICOMITKSeriesGDCMReader ( )
protectedvirtual

Definition at line 56 of file mitkDICOMITKSeriesGDCMReader.cpp.

mitk::DICOMITKSeriesGDCMReader::DICOMITKSeriesGDCMReader ( const DICOMITKSeriesGDCMReader other)
protected

Definition at line 41 of file mitkDICOMITKSeriesGDCMReader.cpp.

Member Function Documentation

void mitk::DICOMITKSeriesGDCMReader::AddSortingElement ( DICOMDatasetSorter sorter,
bool  atFront = false 
)
virtual

Add an element to the sorting procedure described in Loading strategy.

Definition at line 480 of file mitkDICOMITKSeriesGDCMReader.cpp.

Referenced by mitk::ClassicDICOMSeriesReader::ClassicDICOMSeriesReader().

void mitk::DICOMITKSeriesGDCMReader::AnalyzeInputFiles ( )
overridevirtual
bool mitk::DICOMITKSeriesGDCMReader::CanHandleFile ( const std::string &  filename)
overridevirtual

Indicate whether this reader can handle given file.

Implements mitk::DICOMFileReader.

Reimplemented in mitk::DiffusionDICOMFileReader.

Definition at line 475 of file mitkDICOMITKSeriesGDCMReader.cpp.

References mitk::ITKDICOMSeriesReaderHelper::CanHandleFile().

mitk::DICOMITKSeriesGDCMReader::SortingBlockList mitk::DICOMITKSeriesGDCMReader::Condense3DBlocks ( SortingBlockList resultOf3DGrouping)
protectedvirtual

"Hook" for sub-classes, see Sub-classes can condense multiple blocks into a single larger block

Returns
REMAINING blocks

Reimplemented in mitk::ThreeDnTDICOMSeriesReader.

Definition at line 199 of file mitkDICOMITKSeriesGDCMReader.cpp.

bool mitk::DICOMITKSeriesGDCMReader::GetAcceptTwoSlicesGroups ( ) const

Definition at line 131 of file mitkDICOMITKSeriesGDCMReader.cpp.

std::string mitk::DICOMITKSeriesGDCMReader::GetActiveLocale ( )
staticprotected

Return active C locale.

Definition at line 150 of file mitkDICOMITKSeriesGDCMReader.cpp.

double mitk::DICOMITKSeriesGDCMReader::GetDecimalPlacesForOrientation ( ) const

Definition at line 563 of file mitkDICOMITKSeriesGDCMReader.cpp.

bool mitk::DICOMITKSeriesGDCMReader::GetFixTiltByShearing ( ) const

Definition at line 120 of file mitkDICOMITKSeriesGDCMReader.cpp.

mitk::DICOMITKSeriesGDCMReader::ConstSorterList mitk::DICOMITKSeriesGDCMReader::GetFreelyConfiguredSortingElements ( ) const

Definition at line 496 of file mitkDICOMITKSeriesGDCMReader.cpp.

mitk::ReaderImplementationLevel mitk::DICOMITKSeriesGDCMReader::GetReaderImplementationLevel ( const std::string  sopClassUID)
staticprotected

Describe this reader's confidence for given SOP class UID.

Definition at line 386 of file mitkDICOMITKSeriesGDCMReader.cpp.

References mitk::SOPClassImplemented, mitk::SOPClassPartlySupported, mitk::SOPClassSupported, mitk::SOPClassUnknown, and mitk::SOPClassUnsupported.

mitk::DICOMTagCache::Pointer mitk::DICOMITKSeriesGDCMReader::GetTagCache ( ) const
protectedvirtual

Definition at line 568 of file mitkDICOMITKSeriesGDCMReader.cpp.

mitk::DICOMTagPathList mitk::DICOMITKSeriesGDCMReader::GetTagsOfInterest ( ) const
overridevirtual
double mitk::DICOMITKSeriesGDCMReader::GetToleratedOriginError ( ) const

Definition at line 551 of file mitkDICOMITKSeriesGDCMReader.cpp.

mitk::DICOMITKSeriesGDCMReader::SortingBlockList mitk::DICOMITKSeriesGDCMReader::InternalExecuteSortingStep ( unsigned int  sortingStepIndex,
const DICOMDatasetSorter::Pointer &  sorter,
const SortingBlockList input 
)
staticprotected
void mitk::DICOMITKSeriesGDCMReader::InternalPrintConfiguration ( std::ostream &  os) const
overrideprotectedvirtual

Configuration description for human reader, to be implemented by sub-classes.

Implements mitk::DICOMFileReader.

Definition at line 136 of file mitkDICOMITKSeriesGDCMReader.cpp.

bool mitk::DICOMITKSeriesGDCMReader::IsToleratedOriginOffsetAbsolute ( ) const

Definition at line 557 of file mitkDICOMITKSeriesGDCMReader.cpp.

bool mitk::DICOMITKSeriesGDCMReader::LoadImages ( )
overridevirtual

Loads images using itk::ImageSeriesReader, potentially applies shearing to correct gantry tilt.

Implements mitk::DICOMFileReader.

Reimplemented in mitk::ThreeDnTDICOMSeriesReader, and mitk::DiffusionDICOMFileReader.

Definition at line 421 of file mitkDICOMITKSeriesGDCMReader.cpp.

bool mitk::DICOMITKSeriesGDCMReader::LoadMitkImageForOutput ( unsigned int  o)
protectedvirtual

Loads the mitk::Image by means of an itk::ImageSeriesReader.

Definition at line 468 of file mitkDICOMITKSeriesGDCMReader.cpp.

Referenced by mitk::ThreeDnTDICOMSeriesReader::LoadImages().

mitk::DICOMITKSeriesGDCMReader::mitkClassMacro ( DICOMITKSeriesGDCMReader  ,
DICOMFileReader   
)
mitk::DICOMITKSeriesGDCMReader::mitkCloneMacro ( DICOMITKSeriesGDCMReader  )
mitk::DICOMITKSeriesGDCMReader::mitkNewMacro1Param ( DICOMITKSeriesGDCMReader  ,
unsigned  int 
)
static Pointer mitk::DICOMITKSeriesGDCMReader::New ( )
static
bool mitk::DICOMITKSeriesGDCMReader::operator== ( const DICOMFileReader other) const
overridevirtual
void mitk::DICOMITKSeriesGDCMReader::PopLocale ( ) const
protected

Activate last remembered locale from locale stack "C" locale is required for correct parsing of numbers by itk::ImageSeriesReader.

Definition at line 171 of file mitkDICOMITKSeriesGDCMReader.cpp.

References MITK_WARN.

void mitk::DICOMITKSeriesGDCMReader::PushLocale ( ) const
protected

Remember current locale on stack, activate "C" locale. "C" locale is required for correct parsing of numbers by itk::ImageSeriesReader.

Definition at line 155 of file mitkDICOMITKSeriesGDCMReader.cpp.

void mitk::DICOMITKSeriesGDCMReader::SetAcceptTwoSlicesGroups ( bool  accept) const

Controls whether groups of only two images are accepted when ensuring consecutive slices via EquiDistantBlocksSorter.

Definition at line 125 of file mitkDICOMITKSeriesGDCMReader.cpp.

void mitk::DICOMITKSeriesGDCMReader::SetFixTiltByShearing ( bool  on)

Controls whether to "fix" tilted acquisitions by shearing the output (see Gantry tilt handling).

Definition at line 114 of file mitkDICOMITKSeriesGDCMReader.cpp.

Referenced by mitk::ClassicDICOMSeriesReader::ClassicDICOMSeriesReader().

void mitk::DICOMITKSeriesGDCMReader::SetTagCache ( const DICOMTagCache::Pointer &  )
overrideprotectedvirtual

A way to provide external knowledge about files and tag values is appreciated.

Implements mitk::DICOMFileReader.

Definition at line 573 of file mitkDICOMITKSeriesGDCMReader.cpp.

void mitk::DICOMITKSeriesGDCMReader::SetToleratedOriginOffset ( double  millimeters = 0.005) const
void mitk::DICOMITKSeriesGDCMReader::SetToleratedOriginOffsetToAdaptive ( double  fractionOfInterSliceDistanct = 0.3) const

See Forced Configuration.

Definition at line 537 of file mitkDICOMITKSeriesGDCMReader.cpp.

Member Data Documentation

mitk::EquiDistantBlocksSorter::Pointer mitk::DICOMITKSeriesGDCMReader::m_EquiDistantBlocksSorter
protected
bool mitk::DICOMITKSeriesGDCMReader::m_FixTiltByShearing
protected

Definition at line 312 of file mitkDICOMITKSeriesGDCMReader.h.

Referenced by operator=().

mitk::NormalDirectionConsistencySorter::Pointer mitk::DICOMITKSeriesGDCMReader::m_NormalDirectionConsistencySorter
protected

Definition at line 326 of file mitkDICOMITKSeriesGDCMReader.h.

Referenced by operator=().


The documentation for this class was generated from the following files: