mitkDicomSeriesReader.h

Go to the documentation of this file.

/*============================================================================

The Medical Imaging Interaction Toolkit (MITK)

Copyright (c) German Cancer Research Center (DKFZ)
All rights reserved.

Use of this source code is governed by a 3-clause BSD license that can be
found in the LICENSE file.

============================================================================*/

#ifndef mitkDicomSeriesReader_h
#define mitkDicomSeriesReader_h

#include "mitkConfig.h"
#include "mitkDataNode.h"

#include <itkGDCMImageIO.h>

#include <itkCommand.h>
#include <itkImageSeriesReader.h>

#ifdef NOMINMAX
#define DEF_NOMINMAX
#undef NOMINMAX
#endif

#include <gdcmConfigure.h>

#ifdef DEF_NOMINMAX
#ifndef NOMINMAX
#define NOMINMAX
#endif
#undef DEF_NOMINMAX
#endif

#include <gdcmDataSet.h>
#include <gdcmScanner.h>

namespace mitk
{
  class Image;

  class DicomSeriesReader
  {
  public:
    typedef std::vector<std::string> StringContainer;

    typedef void (*UpdateCallBackMethod)(float);

    typedef enum {
      ReaderImplementationLevel_Supported,       
      ReaderImplementationLevel_PartlySupported, 
      ReaderImplementationLevel_Implemented,     
      ReaderImplementationLevel_Unsupported,     
    } ReaderImplementationLevel;

    typedef enum {
      PixelSpacingInterpretation_SpacingInPatient,  
      PixelSpacingInterpretation_SpacingAtDetector, 
      PixelSpacingInterpretation_SpacingUnknown     
    } PixelSpacingInterpretation;

    class ImageBlockDescriptor
    {
    public:
      StringContainer GetFilenames() const;

      std::string GetImageBlockUID() const;

      std::string GetSeriesInstanceUID() const;

      std::string GetModality() const;

      std::string GetSOPClassUIDAsString() const;

      std::string GetSOPClassUID() const;

      ReaderImplementationLevel GetReaderImplementationLevel() const;

      bool HasGantryTiltCorrected() const;

      bool PixelSpacingRelatesToPatient() const;
      bool PixelSpacingRelatesToDetector() const;
      bool PixelSpacingIsUnknown() const;

      PixelSpacingInterpretation GetPixelSpacingType() const;

      bool HasMultipleTimePoints() const;

      bool IsMultiFrameImage() const;

      ImageBlockDescriptor();
      ~ImageBlockDescriptor();

    private:
      friend class DicomSeriesReader;

      ImageBlockDescriptor(const StringContainer &files);

      void AddFile(const std::string &file);
      void AddFiles(const StringContainer &files);

      void SetImageBlockUID(const std::string &uid);

      void SetSeriesInstanceUID(const std::string &uid);

      void SetModality(const std::string &modality);

      void SetNumberOfFrames(const std::string &);

      void SetSOPClassUID(const std::string &mediaStorageSOPClassUID);

      void SetHasGantryTiltCorrected(bool);

      void SetPixelSpacingInformation(const std::string &pixelSpacing, const std::string &imagerPixelSpacing);

      void SetHasMultipleTimePoints(bool);

      void GetDesiredMITKImagePixelSpacing(ScalarType &spacingX, ScalarType &spacingY) const;

      StringContainer m_Filenames;
      std::string m_ImageBlockUID;
      std::string m_SeriesInstanceUID;
      std::string m_Modality;
      std::string m_SOPClassUID;
      bool m_HasGantryTiltCorrected;
      std::string m_PixelSpacing;
      std::string m_ImagerPixelSpacing;
      bool m_HasMultipleTimePoints;
      bool m_IsMultiFrameImage;
    };

    typedef std::map<std::string, ImageBlockDescriptor> FileNamesGrouping;

    static std::string GetConfigurationString();

    static bool IsDicom(const std::string &filename);

    static FileNamesGrouping GetSeries(const std::string &dir,
                                       bool groupImagesWithGantryTilt,
                                       const StringContainer &restrictions = StringContainer());

    static StringContainer GetSeries(const std::string &dir,
                                     const std::string &series_uid,
                                     bool groupImagesWithGantryTilt,
                                     const StringContainer &restrictions = StringContainer());

    static FileNamesGrouping GetSeries(const StringContainer &files,
                                       bool sortTo3DPlust,
                                       bool groupImagesWithGantryTilt,
                                       const StringContainer &restrictions = StringContainer());

    static FileNamesGrouping GetSeries(const StringContainer &files,
                                       bool groupImagesWithGantryTilt,
                                       const StringContainer &restrictions = StringContainer());

    static DataNode::Pointer LoadDicomSeries(const StringContainer &filenames,
                                             bool sort = true,
                                             bool load4D = true,
                                             bool correctGantryTilt = true,
                                             UpdateCallBackMethod callback = nullptr,
                                             itk::SmartPointer<Image> preLoadedImageBlock = nullptr);

    static bool LoadDicomSeries(const StringContainer &filenames,
                                DataNode &node,
                                bool sort = true,
                                bool load4D = true,
                                bool correctGantryTilt = true,
                                UpdateCallBackMethod callback = nullptr,
                                itk::SmartPointer<Image> preLoadedImageBlock = nullptr);

  protected:
    class SliceGroupingAnalysisResult
    {
    public:
      SliceGroupingAnalysisResult();

      StringContainer GetBlockFilenames();

      StringContainer GetUnsortedFilenames();

      bool ContainsGantryTilt();

      void AddFileToSortedBlock(const std::string &filename);

      void AddFileToUnsortedBlock(const std::string &filename);
      void AddFilesToUnsortedBlock(const StringContainer &filenames);

      void FlagGantryTilt();

      void UndoPrematureGrouping();

    protected:
      StringContainer m_GroupedFiles;
      StringContainer m_UnsortedFiles;

      bool m_GantryTilt;
    };

    class GantryTiltInformation
    {
    public:
      // two types to avoid any rounding errors
      typedef itk::Point<double, 3> Point3Dd;
      typedef itk::Vector<double, 3> Vector3Dd;

      GantryTiltInformation();

      GantryTiltInformation(const Point3D &origin1,
                            const Point3D &origin2,
                            const Vector3D &right,
                            const Vector3D &up,
                            unsigned int numberOfSlicesApart);

      bool IsSheared() const;

      bool IsRegularGantryTilt() const;

      double GetMatrixCoefficientForCorrectionInWorldCoordinates() const;

      double GetRealZSpacing() const;

      double GetTiltCorrectedAdditionalSize() const;

      double GetTiltAngleInDegrees() const;

    protected:
      Point3D projectPointOnLine(Point3Dd p, Point3Dd lineOrigin, Vector3Dd lineDirection);

      double m_ShiftUp;
      double m_ShiftRight;
      double m_ShiftNormal;
      double m_ITKAssumedSliceSpacing;
      unsigned int m_NumberOfSlicesApart;
    };

    typedef std::pair<StringContainer, StringContainer> TwoStringContainers;

    typedef std::map<std::string, std::string> TagToPropertyMapType;

    static SliceGroupingAnalysisResult AnalyzeFileForITKImageSeriesReaderSpacingAssumption(
      const StringContainer &files, bool groupsOfSimilarImages, const gdcm::Scanner::MappingType &tagValueMappings_);

    static std::string ConstCharStarToString(const char *s);

    static bool DICOMStringToSpacing(const std::string &s, ScalarType &spacingX, ScalarType &spacingY);

    static Point3D DICOMStringToPoint3D(const std::string &s, bool &successful);

    static void DICOMStringToOrientationVectors(const std::string &s, Vector3D &right, Vector3D &up, bool &successful);

    template <typename ImageType>
    static typename ImageType::Pointer
      // TODO this is NOT inplace!
      InPlaceFixUpTiltedGeometry(ImageType *input, const GantryTiltInformation &tiltInfo);

    static StringContainer SortSeriesSlices(const StringContainer &unsortedFilenames);

  public:
    static bool IsPhilips3DDicom(const std::string &filename);

    static std::string ReaderImplementationLevelToString(const ReaderImplementationLevel &enumValue);
    static std::string PixelSpacingInterpretationToString(const PixelSpacingInterpretation &enumValue);

  protected:
    static bool ReadPhilips3DDicom(const std::string &filename, itk::SmartPointer<Image> output_image);

    static std::string CreateMoreUniqueSeriesIdentifier(gdcm::Scanner::TagToValue &tagValueMap);

    static std::string CreateSeriesIdentifierPart(gdcm::Scanner::TagToValue &tagValueMap, const gdcm::Tag &tag);

    static std::string IDifyTagValue(const std::string &value);

    typedef itk::GDCMImageIO DcmIoType;

    class CallbackCommand : public itk::Command
    {
    public:
      CallbackCommand(UpdateCallBackMethod callback) : m_Callback(callback) {}
      void Execute(const itk::Object *caller, const itk::EventObject &) override
      {
        (*this->m_Callback)(static_cast<const itk::ProcessObject *>(caller)->GetProgress());
      }

      void Execute(itk::Object *caller, const itk::EventObject &) override
      {
        (*this->m_Callback)(static_cast<itk::ProcessObject *>(caller)->GetProgress());
      }

    protected:
      UpdateCallBackMethod m_Callback;
    };

    static void FixSpacingInformation(Image *image, const ImageBlockDescriptor &imageBlockDescriptor);

    static void ScanForSliceInformation(const StringContainer &filenames, gdcm::Scanner &scanner);

    static void LoadDicom(const StringContainer &filenames,
                          DataNode &node,
                          bool sort,
                          bool check_4d,
                          bool correctTilt,
                          UpdateCallBackMethod callback,
                          itk::SmartPointer<Image> preLoadedImageBlock);

    template <typename PixelType>
    static itk::SmartPointer<Image> LoadDICOMByITK(const StringContainer &,
                                                   bool correctTilt,
                                                   const GantryTiltInformation &tiltInfo,
                                                   DcmIoType::Pointer &io,
                                                   CallbackCommand *command,
                                                   itk::SmartPointer<Image> preLoadedImageBlock);

    static itk::SmartPointer<Image> MultiplexLoadDICOMByITK(const StringContainer &,
                                                            bool correctTilt,
                                                            const GantryTiltInformation &tiltInfo,
                                                            DcmIoType::Pointer &io,
                                                            CallbackCommand *command,
                                                            itk::SmartPointer<Image> preLoadedImageBlock);

    static itk::SmartPointer<Image> MultiplexLoadDICOMByITKScalar(const StringContainer &,
                                                                  bool correctTilt,
                                                                  const GantryTiltInformation &tiltInfo,
                                                                  DcmIoType::Pointer &io,
                                                                  CallbackCommand *command,
                                                                  itk::SmartPointer<Image> preLoadedImageBlock);

    static itk::SmartPointer<Image> MultiplexLoadDICOMByITKRGBPixel(const StringContainer &,
                                                                    bool correctTilt,
                                                                    const GantryTiltInformation &tiltInfo,
                                                                    DcmIoType::Pointer &io,
                                                                    CallbackCommand *command,
                                                                    itk::SmartPointer<Image> preLoadedImageBlock);

    template <typename PixelType>
    static itk::SmartPointer<Image> LoadDICOMByITK4D(std::list<StringContainer> &imageBlocks,
                                                     ImageBlockDescriptor imageBlockDescriptor,
                                                     bool correctTilt,
                                                     const GantryTiltInformation &tiltInfo,
                                                     DcmIoType::Pointer &io,
                                                     CallbackCommand *command,
                                                     itk::SmartPointer<Image> preLoadedImageBlock);

    static itk::SmartPointer<Image> MultiplexLoadDICOMByITK4D(std::list<StringContainer> &imageBlocks,
                                                              ImageBlockDescriptor imageBlockDescriptor,
                                                              bool correctTilt,
                                                              const GantryTiltInformation &tiltInfo,
                                                              DcmIoType::Pointer &io,
                                                              CallbackCommand *command,
                                                              itk::SmartPointer<Image> preLoadedImageBlock);

    static itk::SmartPointer<Image> MultiplexLoadDICOMByITK4DScalar(std::list<StringContainer> &imageBlocks,
                                                                    ImageBlockDescriptor imageBlockDescriptor,
                                                                    bool correctTilt,
                                                                    const GantryTiltInformation &tiltInfo,
                                                                    DcmIoType::Pointer &io,
                                                                    CallbackCommand *command,
                                                                    itk::SmartPointer<Image> preLoadedImageBlock);

    static itk::SmartPointer<Image> MultiplexLoadDICOMByITK4DRGBPixel(std::list<StringContainer> &imageBlocks,
                                                                      ImageBlockDescriptor imageBlockDescriptor,
                                                                      bool correctTilt,
                                                                      const GantryTiltInformation &tiltInfo,
                                                                      DcmIoType::Pointer &io,
                                                                      CallbackCommand *command,
                                                                      itk::SmartPointer<Image> preLoadedImageBlock);

    static std::list<StringContainer> SortIntoBlocksFor3DplusT(const StringContainer &presortedFilenames,
                                                               const gdcm::Scanner::MappingType &tagValueMappings_,
                                                               bool sort,
                                                               bool &canLoadAs4D);

    static bool GdcmSortFunction(const gdcm::DataSet &ds1, const gdcm::DataSet &ds2);

    static void CopyMetaDataToImageProperties(StringContainer filenames,
                                              const gdcm::Scanner::MappingType &tagValueMappings_,
                                              DcmIoType *io,
                                              const ImageBlockDescriptor &blockInfo,
                                              Image *image);
    static void CopyMetaDataToImageProperties(std::list<StringContainer> imageBlock,
                                              const gdcm::Scanner::MappingType &tagValueMappings_,
                                              DcmIoType *io,
                                              const ImageBlockDescriptor &blockInfo,
                                              Image *image);

    static const TagToPropertyMapType &GetDICOMTagsToMITKPropertyMap();
  };
}

#endif /* mitkDicomSeriesReader_h */