Flexible reader based on itk::ImageSeriesReader and GDCM, for single-slice modalities like CT, MR, PET, CR, etc.
More...
|
| mitkClassMacro (DICOMITKSeriesGDCMReader, DICOMFileReader) |
|
| mitkCloneMacro (DICOMITKSeriesGDCMReader) |
|
| mitkNewMacro1Param (DICOMITKSeriesGDCMReader, unsigned int) |
|
| mitkNewMacro2Param (DICOMITKSeriesGDCMReader, unsigned int, bool) |
|
void | AnalyzeInputFiles () override |
| Runs the sorting / splitting process described in Loading strategy. Method required by DICOMFileReader. More...
|
|
bool | LoadImages () 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) |
| 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...
|
|
void | SetSimpleVolumeReading (bool read) |
| Ignore all dicom tags that are non-essential for simple 3D volume import. More...
|
|
bool | GetSimpleVolumeReading () |
| 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 |
|
| mitkClassMacroItkParent (DICOMFileReader, itk::Object) |
|
void | SetInputFiles (const StringList &filenames) |
| This input files. More...
|
|
const StringList & | GetInputFiles () const |
| This input files. More...
|
|
unsigned int | GetNumberOfOutputs () const |
| Number of outputs, only meaningful after calling AnalyzeInputFiles() More...
|
|
const DICOMImageBlockDescriptor & | GetOutput (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 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...
|
|
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:
- 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
- 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:
- build an initial set of output groups, simply by grouping all input files.
- for each configured DICOMDatasetSorter, process:
- for each output group:
- set this group's files as input to the sorter
- let the sorter sort (and split)
- 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:
- 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:
- 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.
- 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:
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
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.