itkImageIOBase.h

Go to the documentation of this file.

/*=========================================================================
 *
 *  Copyright Insight Software Consortium
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *         http://www.apache.org/licenses/LICENSE-2.0.txt
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 *=========================================================================*/
#ifndef itkImageIOBase_h
#define itkImageIOBase_h
#include "ITKIOImageBaseExport.h"

#include "itkIOConfigure.h"

#include "itkLightProcessObject.h"
#include "itkIndent.h"
#include "itkImageIORegion.h"
#include "itkRGBPixel.h"
#include "itkRGBAPixel.h"
#include "itkCovariantVector.h"
#include "itkSymmetricSecondRankTensor.h"
#include "itkDiffusionTensor3D.h"
#include "itkImageRegionSplitterBase.h"

#include "vnl/vnl_vector.h"
#include "vcl_compiler.h"

#include <fstream>
#include <string>

namespace itk
{
// Forward reference for VariableLengthVector
template <typename TValue> class VariableLengthVector;

class ITKIOImageBase_EXPORT ImageIOBase:public LightProcessObject
{
public:
  ITK_DISALLOW_COPY_AND_ASSIGN(ImageIOBase);

  using Self = ImageIOBase;
  using Superclass = LightProcessObject;
  using Pointer = SmartPointer< Self >;
  using ConstPointer = SmartPointer< const Self >;

  itkTypeMacro(ImageIOBase, Superclass);

  itkSetStringMacro(FileName);
  itkGetStringMacro(FileName);

  using IndexValueType = ::itk::IndexValueType;
  using SizeValueType = ::itk::SizeValueType;

  class UnknownType {};

  typedef  enum { UNKNOWNPIXELTYPE, SCALAR, RGB, RGBA, OFFSET, VECTOR,
                  POINT, COVARIANTVECTOR, SYMMETRICSECONDRANKTENSOR,
                  DIFFUSIONTENSOR3D, COMPLEX, FIXEDARRAY, MATRIX }  IOPixelType;

   // NOTE unsigned char, char, and signed char are 3 distinct types in C++
   // the enum value UCHAR represents 'unsigned char'
   // the enum value CHAR represents  'signed char'
   // and the 'char' type maps to one of UCHAR or CHAR based on the platforms 'signededness'
  typedef  enum { UNKNOWNCOMPONENTTYPE, UCHAR, CHAR, USHORT, SHORT, UINT, INT,
                  ULONG, LONG, ULONGLONG, LONGLONG, FLOAT, DOUBLE } IOComponentType;

  void SetNumberOfDimensions(unsigned int);

  itkGetConstMacro(NumberOfDimensions, unsigned int);

  virtual void SetDimensions(unsigned int i, SizeValueType dim);

  virtual SizeValueType GetDimensions(unsigned int i) const
  { return m_Dimensions[i]; }

  virtual void SetOrigin(unsigned int i, double origin);

  virtual double GetOrigin(unsigned int i) const
  {
    return m_Origin[i];
  }

  virtual void SetSpacing(unsigned int i, double spacing);

  virtual double GetSpacing(unsigned int i) const
  {
    return m_Spacing[i];
  }

  virtual void SetDirection(unsigned int i, const std::vector< double > & direction);

  virtual void SetDirection(unsigned int i, const vnl_vector< double > & direction);

  virtual std::vector< double > GetDirection(unsigned int i) const
  {
    return m_Direction[i];
  }

  virtual std::vector< double > GetDefaultDirection(unsigned int i) const;

  itkSetMacro(IORegion, ImageIORegion);
  itkGetConstReferenceMacro(IORegion, ImageIORegion);

  itkSetEnumMacro(PixelType, IOPixelType);
  itkGetEnumMacro(PixelType, IOPixelType);

  itkSetEnumMacro(ComponentType, IOComponentType);
  itkGetEnumMacro(ComponentType, IOComponentType);

  virtual const std::type_info & GetComponentTypeInfo() const;

  itkSetMacro(NumberOfComponents, unsigned int);
  itkGetConstReferenceMacro(NumberOfComponents, unsigned int);

  itkSetMacro(UseCompression, bool);
  itkGetConstMacro(UseCompression, bool);
  itkBooleanMacro(UseCompression);

  itkSetMacro(UseStreamedReading, bool);
  itkGetConstMacro(UseStreamedReading, bool);
  itkBooleanMacro(UseStreamedReading);

  itkSetMacro(UseStreamedWriting, bool);
  itkGetConstMacro(UseStreamedWriting, bool);
  itkBooleanMacro(UseStreamedWriting);

  itkSetMacro(ExpandRGBPalette, bool);
  itkGetConstMacro(ExpandRGBPalette, bool);
  itkBooleanMacro(ExpandRGBPalette);

  itkGetConstMacro(IsReadAsScalarPlusPalette, bool);

  static std::string GetComponentTypeAsString(IOComponentType);

  static IOComponentType GetComponentTypeFromString(const std::string &typeString);

  static std::string GetPixelTypeAsString(IOPixelType);

  static IOPixelType GetPixelTypeFromString(const std::string &pixelString);

  typedef  enum { ASCII, Binary, TypeNotApplicable } FileType;

  typedef  enum { BigEndian, LittleEndian, OrderNotApplicable } ByteOrder;

  itkSetEnumMacro(FileType, FileType);
  itkGetEnumMacro(FileType, FileType);
  void SetFileTypeToASCII()
  {
    this->SetFileType(ASCII);
  }

  void SetFileTypeToBinary()
  {
    this->SetFileType(Binary);
  }

  itkSetEnumMacro(ByteOrder, ByteOrder);
  itkGetEnumMacro(ByteOrder, ByteOrder);
  void SetByteOrderToBigEndian()
  {
    this->SetByteOrder(BigEndian);
  }

  void SetByteOrderToLittleEndian()
  {
    this->SetByteOrder(LittleEndian);
  }

  std::string GetFileTypeAsString(FileType) const;

  std::string GetByteOrderAsString(ByteOrder) const;

  using SizeType = ::itk::intmax_t;

  using BufferSizeType = ::itk::OffsetValueType;

  virtual SizeType GetPixelStride() const;

  SizeType GetImageSizeInPixels() const;

  SizeType GetImageSizeInBytes() const;

  SizeType GetImageSizeInComponents() const;

  virtual unsigned int GetComponentSize() const;

  /*-------- This part of the interfaces deals with reading data ----- */

  virtual bool CanReadFile(const char *) = 0;

  virtual bool CanStreamRead()
  {
    return false;
  }

  virtual void ReadImageInformation() = 0;

  virtual void Read(void *buffer) = 0;

  /*-------- This part of the interfaces deals with writing data ----- */

  virtual bool CanWriteFile(const char *)  = 0;

  virtual bool CanStreamWrite()
  {
    return false;
  }

  virtual void WriteImageInformation() = 0;

  virtual void Write(const void *buffer) = 0;

  /* --- Support reading and writing data as a series of files. --- */

  virtual bool SupportsDimension(unsigned long dim)
  {
    return ( dim == 2 );
  }

  virtual ImageIORegion
  GenerateStreamableReadRegionFromRequestedRegion(const ImageIORegion & requested) const;

  virtual unsigned int GetActualNumberOfSplitsForWriting(unsigned int numberOfRequestedSplits,
                                                         const ImageIORegion & pasteRegion,
                                                         const ImageIORegion & largestPossibleRegion);

  virtual ImageIORegion GetSplitRegionForWriting(unsigned int ithPiece,
                                                 unsigned int numberOfActualSplits,
                                                 const ImageIORegion & pasteRegion,
                                                 const ImageIORegion & largestPossibleRegion);

  using ArrayOfExtensionsType = std::vector< std::string >;

  const ArrayOfExtensionsType & GetSupportedReadExtensions() const;

  const ArrayOfExtensionsType & GetSupportedWriteExtensions() const;

  template <typename TPixel>
    void SetTypeInfo(const TPixel *);

  template <typename TPixel>
    struct MapPixelType
  {
    static constexpr IOComponentType CType =
      UNKNOWNCOMPONENTTYPE;
  };
  template <typename TPixel>
    void SetPixelTypeInfo(const TPixel *)
  {
    this->SetNumberOfComponents(1);
    this->SetPixelType(SCALAR);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TPixel>
    void SetPixelTypeInfo(const RGBPixel< TPixel > *)
  {
    this->SetNumberOfComponents(3);
    this->SetPixelType(RGB);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TPixel>
    void SetPixelTypeInfo(const RGBAPixel< TPixel > *)
  {
    this->SetNumberOfComponents(4);
    this->SetPixelType(RGBA);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TPixel, unsigned VLength>
    void SetPixelTypeInfo(const Vector< TPixel , VLength > *)
  {
    this->SetNumberOfComponents(VLength);
    this->SetPixelType(VECTOR);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TPixel>
    void SetPixelTypeInfo(const VariableLengthVector< TPixel > *)
  {
    this->SetNumberOfComponents(1);
    this->SetPixelType(VECTOR);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TPixel, unsigned VLength>
    void SetPixelTypeInfo(const CovariantVector< TPixel,VLength > *)
  {
    this->SetNumberOfComponents(VLength);
    this->SetPixelType(COVARIANTVECTOR);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TPixel,unsigned VLength>
    void SetPixelTypeInfo(const FixedArray< TPixel,VLength > *)
  {
    this->SetNumberOfComponents(VLength);
    this->SetPixelType(COVARIANTVECTOR);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }

  template <typename TPixel, unsigned VLength>
    void SetPixelTypeInfo(const SymmetricSecondRankTensor<TPixel,VLength> *)
  {
    this->SetNumberOfComponents(VLength * (VLength + 1) / 2 );
    this->SetPixelType(SYMMETRICSECONDRANKTENSOR);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }

  template <typename TPixel>
    inline void SetPixelTypeInfo(const DiffusionTensor3D< TPixel > *)
  {
    this->SetNumberOfComponents(6);
    this->SetPixelType(DIFFUSIONTENSOR3D);
    this->SetComponentType(MapPixelType<TPixel>::CType);
    }

  template <typename TPixel, unsigned VLength>
    void SetPixelTypeInfo(const Matrix< TPixel,VLength, VLength > *)
  {
    this->SetNumberOfComponents(VLength * VLength);
    this->SetPixelType(MATRIX);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }

  template <typename TPixel>
    void SetPixelTypeInfo(const std::complex< TPixel > *)
  {
    this->SetNumberOfComponents(2);
    this->SetPixelType(COMPLEX);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }

  template <unsigned VLength>
    void SetPixelTypeInfo(const Offset< VLength > *)
  {
    this->SetNumberOfComponents(VLength);
    this->SetPixelType(ImageIOBase::OFFSET);
    this->SetComponentType(ImageIOBase::LONG);
  }

protected:
  ImageIOBase();
  ~ImageIOBase() override;
  void PrintSelf(std::ostream & os, Indent indent) const override;

  virtual const ImageRegionSplitterBase* GetImageRegionSplitter() const;

  virtual bool HasSupportedReadExtension( const char * fileName, bool ignoreCase = true );
  virtual bool HasSupportedWriteExtension( const char * fileName, bool ignoreCase = true );

  IOPixelType m_PixelType{SCALAR};

  IOComponentType m_ComponentType{UNKNOWNCOMPONENTTYPE};

  ByteOrder m_ByteOrder{OrderNotApplicable};

  FileType m_FileType{TypeNotApplicable};

  bool m_Initialized;

  std::string m_FileName;

  unsigned int m_NumberOfComponents;

  unsigned int m_NumberOfDimensions{0};

  bool m_UseCompression;

  bool m_UseStreamedReading;

  bool m_UseStreamedWriting;

  bool m_ExpandRGBPalette;

  bool m_IsReadAsScalarPlusPalette;

  ImageIORegion m_IORegion;

  std::vector< SizeValueType > m_Dimensions;

  std::vector< double > m_Spacing;

  std::vector< double > m_Origin;

  std::vector< std::vector< double > > m_Direction;

  std::vector< SizeType > m_Strides;

  virtual void Reset(const bool freeDynamic = true);

  void Resize(const unsigned int numDimensions,
              const unsigned int *dimensions);

  virtual unsigned int GetPixelSize() const;

  void ComputeStrides();

  SizeType GetComponentStride() const;

  SizeType GetRowStride() const;

  SizeType GetSliceStride() const;

  virtual void OpenFileForReading(std::ifstream & inputStream, const std::string & filename,
                                  bool ascii = false);

  virtual void OpenFileForWriting(std::ofstream & outputStream, const std::string & filename,
                                  bool truncate = true, bool ascii = false);

  virtual void WriteBufferAsASCII(std::ostream & os, const void *buffer,
                          IOComponentType ctype,
                          SizeType numberOfBytesToWrite);

  virtual void ReadBufferAsASCII(std::istream & os, void *buffer,
                         IOComponentType ctype,
                         SizeType numberOfBytesToBeRead);

  bool ReadBufferAsBinary(std::istream & os, void *buffer, SizeType numberOfBytesToBeRead);

  void AddSupportedReadExtension(const char *extension);

  void AddSupportedWriteExtension(const char *extension);

  virtual unsigned int GetActualNumberOfSplitsForWritingCanStreamWrite(unsigned int numberOfRequestedSplits,
                                                                       const ImageIORegion & pasteRegion) const;

  virtual ImageIORegion GetSplitRegionForWritingCanStreamWrite(unsigned int ithPiece,
                                                               unsigned int numberOfActualSplits,
                                                               const ImageIORegion & pasteRegion) const;

private:

  bool HasSupportedExtension( const char * , const ArrayOfExtensionsType &, bool tolower = true );

  ArrayOfExtensionsType m_SupportedReadExtensions;
  ArrayOfExtensionsType m_SupportedWriteExtensions;
};

#define IMAGEIOBASE_TYPEMAP(type,ctype)                         \
  template <> struct ImageIOBase::MapPixelType<type>    \
  {                                                     \
    static constexpr IOComponentType CType = ctype; \
  }

// the following typemaps are not platform independent
IMAGEIOBASE_TYPEMAP(signed char, IOComponentType::CHAR);
IMAGEIOBASE_TYPEMAP(char, std::numeric_limits<char>::is_signed ? IOComponentType::CHAR : IOComponentType::UCHAR);
IMAGEIOBASE_TYPEMAP(unsigned char, IOComponentType::UCHAR);
IMAGEIOBASE_TYPEMAP(short, IOComponentType::SHORT);
IMAGEIOBASE_TYPEMAP(unsigned short, IOComponentType::USHORT);
IMAGEIOBASE_TYPEMAP(int, IOComponentType::INT);
IMAGEIOBASE_TYPEMAP(unsigned int, IOComponentType::UINT);
IMAGEIOBASE_TYPEMAP(long, IOComponentType::LONG);
IMAGEIOBASE_TYPEMAP(unsigned long, IOComponentType::ULONG);
IMAGEIOBASE_TYPEMAP(long long, IOComponentType::LONGLONG);
IMAGEIOBASE_TYPEMAP(unsigned long long, IOComponentType::ULONGLONG);
IMAGEIOBASE_TYPEMAP(float, IOComponentType::FLOAT);
IMAGEIOBASE_TYPEMAP(double, IOComponentType::DOUBLE);
#undef IMAGIOBASE_TYPEMAP

} // end namespace itk

#endif // itkImageIOBase_h