Medical Imaging Interaction Toolkit  2022.10.99-c744ead5 Medical Imaging Interaction Toolkit

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

#include <mitkDICOMITKSeriesGDCMReader.h>

Public Member Functions

void AnalyzeInputFiles () override

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

bool CanHandleFile (const std::string &filename) override
Indicate whether this reader can handle given file. More...

virtual void AddSortingElement (DICOMDatasetSorter *sorter, bool atFront=false)

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

See Forced Configuration. More...

void SetToleratedOriginOffset (double millimeters=0.005) const
See Forced Configuration. More...

Ignore all dicom tags that are non-essential for simple 3D volume import. More...

Ignore all dicom tags that are non-essential for simple 3D volume import. More...

double GetToleratedOriginError () const

bool IsToleratedOriginOffsetAbsolute () const

double GetDecimalPlacesForOrientation () const

bool operator== (const DICOMFileReader &other) const override

DICOMTagPathList GetTagsOfInterest () const override

Public Member Functions inherited from mitk::DICOMFileReader

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 &)

std::string GetConfigurationDescription () const

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...

Set a list of DICOMTagPaths that specify 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 int GetDefaultDecimalPlacesForOrientation ()

static bool GetDefaultSimpleVolumeImport ()

static bool GetDefaultFixTiltByShearing ()

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

Public Attributes

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

Protected Types

typedef std::vector< DICOMDatasetAccessingImageFrameListSortingBlockList

Protected Member Functions

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=m_DefaultDecimalPlacesForOrientation, bool simpleVolumeImport=m_DefaultSimpleVolumeImport)

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)

virtual bool LoadMitkImageForImageBlockDescriptor (DICOMImageBlockDescriptor &block) const

Protected Member Functions inherited from mitk::DICOMFileReader

void ClearOutputs ()

void SetNumberOfOutputs (unsigned int numberOfOutputs)

void SetOutput (unsigned int index, const DICOMImageBlockDescriptor &output)

DICOMImageBlockDescriptorInternalGetOutput (unsigned int index)

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)

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

Static Protected Attributes

const static int m_DefaultDecimalPlacesForOrientation

const static bool m_DefaultSimpleVolumeImport

const static bool m_DefaultFixTiltByShearing

Detailed Description

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

Documentation sections:

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

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
2. 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 artifacts (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:

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

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 190 of file mitkDICOMITKSeriesGDCMReader.h.

◆ SortingBlockList

protected

Definition at line 313 of file mitkDICOMITKSeriesGDCMReader.h.

Constructor & Destructor Documentation

 mitk::DICOMITKSeriesGDCMReader::DICOMITKSeriesGDCMReader ( unsigned int decimalPlacesForOrientation = m_DefaultDecimalPlacesForOrientation, bool simpleVolumeImport = m_DefaultSimpleVolumeImport )
protected

overrideprotected

protected

Member Function Documentation

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

overridevirtual

◆ CanHandleFile()

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

Indicate whether this reader can handle given file.

◆ Condense3DBlocks()

 virtual 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

◆ GetActiveLocale()

staticprotected

Return active C locale.

◆ GetDefaultDecimalPlacesForOrientation()

inlinestatic

Definition at line 271 of file mitkDICOMITKSeriesGDCMReader.h.

◆ GetDefaultFixTiltByShearing()

inlinestatic

Definition at line 281 of file mitkDICOMITKSeriesGDCMReader.h.

◆ GetDefaultSimpleVolumeImport()

inlinestatic

Definition at line 276 of file mitkDICOMITKSeriesGDCMReader.h.

◆ GetFreelyConfiguredSortingElements()

staticprotected

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

inline

Ignore all dicom tags that are non-essential for simple 3D volume import.

Definition at line 257 of file mitkDICOMITKSeriesGDCMReader.h.

◆ GetTagCache()

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

overridevirtual

◆ InternalExecuteSortingStep()

 static SortingBlockList mitk::DICOMITKSeriesGDCMReader::InternalExecuteSortingStep ( unsigned int sortingStepIndex, const DICOMDatasetSorter::Pointer & sorter, const SortingBlockList & input )
staticprotected

◆ InternalPrintConfiguration()

 void mitk::DICOMITKSeriesGDCMReader::InternalPrintConfiguration ( std::ostream & os ) const
overrideprotectedvirtual

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

overridevirtual

protectedvirtual

protectedvirtual

static

protected

overridevirtual

◆ PopLocale()

protected

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

◆ PushLocale()

protected

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

◆ SetAcceptTwoSlicesGroups()

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

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

◆ SetFixTiltByShearing()

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

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

inline

Ignore all dicom tags that are non-essential for simple 3D volume import.

Definition at line 249 of file mitkDICOMITKSeriesGDCMReader.h.

◆ SetTagCache()

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

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

◆ SetToleratedOriginOffset()

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

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

◆ ConstSorterList

Definition at line 220 of file mitkDICOMITKSeriesGDCMReader.h.

◆ m_DefaultDecimalPlacesForOrientation

staticprotected

Definition at line 303 of file mitkDICOMITKSeriesGDCMReader.h.

◆ m_DefaultFixTiltByShearing

staticprotected

Definition at line 305 of file mitkDICOMITKSeriesGDCMReader.h.

◆ m_DefaultSimpleVolumeImport

staticprotected

Definition at line 304 of file mitkDICOMITKSeriesGDCMReader.h.

◆ m_EquiDistantBlocksSorter

protected

Definition at line 358 of file mitkDICOMITKSeriesGDCMReader.h.

◆ m_FixTiltByShearing

protected

Definition at line 344 of file mitkDICOMITKSeriesGDCMReader.h.