itkImageIOBase.h

Go to the documentation of this file.

/*=========================================================================
 *
 *  Copyright NumFOCUS
 *
 *  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
 *
 *         https://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 "itkArray.h"
#include "itkVariableSizeMatrix.h"
#include "itkImageRegionSplitterBase.h"
#include "itkCommonEnums.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_MOVE(ImageIOBase);

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

  itkOverrideGetNameOfClassMacro(ImageIOBase);

  itkSetStringMacro(FileName);
  itkGetStringMacro(FileName);

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

  class UnknownType
  {};
 
#if !defined(ITK_LEGACY_REMOVE)
  using IOPixelType = IOPixelEnum;
  static constexpr IOPixelEnum UNKNOWNPIXELTYPE = IOPixelEnum::UNKNOWNPIXELTYPE;
  static constexpr IOPixelEnum SCALAR = IOPixelEnum::SCALAR;
  static constexpr IOPixelEnum RGB = IOPixelEnum::RGB;
  static constexpr IOPixelEnum RGBA = IOPixelEnum::RGBA;
  static constexpr IOPixelEnum OFFSET = IOPixelEnum::OFFSET;
  static constexpr IOPixelEnum VECTOR = IOPixelEnum::VECTOR;
  static constexpr IOPixelEnum POINT = IOPixelEnum::POINT;
  static constexpr IOPixelEnum COVARIANTVECTOR = IOPixelEnum::COVARIANTVECTOR;
  static constexpr IOPixelEnum SYMMETRICSECONDRANKTENSOR = IOPixelEnum::SYMMETRICSECONDRANKTENSOR;
  static constexpr IOPixelEnum DIFFUSIONTENSOR3D = IOPixelEnum::DIFFUSIONTENSOR3D;
  static constexpr IOPixelEnum COMPLEX = IOPixelEnum::COMPLEX;
  static constexpr IOPixelEnum FIXEDARRAY = IOPixelEnum::FIXEDARRAY;
  static constexpr IOPixelEnum MATRIX = IOPixelEnum::MATRIX;
#endif
 
  using IOComponentEnum = itk::IOComponentEnum;
#if !defined(ITK_LEGACY_REMOVE)
  using IOComponentType = IOComponentEnum;
  static constexpr IOComponentEnum UNKNOWNCOMPONENTTYPE = IOComponentEnum::UNKNOWNCOMPONENTTYPE;
  static constexpr IOComponentEnum UCHAR = IOComponentEnum::UCHAR;
  static constexpr IOComponentEnum CHAR = IOComponentEnum::CHAR;
  static constexpr IOComponentEnum USHORT = IOComponentEnum::USHORT;
  static constexpr IOComponentEnum SHORT = IOComponentEnum::SHORT;
  static constexpr IOComponentEnum UINT = IOComponentEnum::UINT;
  static constexpr IOComponentEnum INT = IOComponentEnum::INT;
  static constexpr IOComponentEnum ULONG = IOComponentEnum::ULONG;
  static constexpr IOComponentEnum LONG = IOComponentEnum::LONG;
  static constexpr IOComponentEnum ULONGLONG = IOComponentEnum::ULONGLONG;
  static constexpr IOComponentEnum LONGLONG = IOComponentEnum::LONGLONG;
  static constexpr IOComponentEnum FLOAT = IOComponentEnum::FLOAT;
  static constexpr IOComponentEnum DOUBLE = IOComponentEnum::DOUBLE;
#endif
 
  using IOFileEnum = itk::IOFileEnum;
#if !defined(ITK_LEGACY_REMOVE)
  static constexpr IOFileEnum ASCII = IOFileEnum::ASCII;
  static constexpr IOFileEnum Binary = IOFileEnum::Binary;
  static constexpr IOFileEnum TypeNotApplicable = IOFileEnum::TypeNotApplicable;
#endif
 
  using IOByteOrderEnum = itk::IOByteOrderEnum;
#if !defined(ITK_LEGACY_REMOVE)
  using ByteOrder = itk::IOByteOrderEnum;
  static constexpr IOByteOrderEnum BigEndian = IOByteOrderEnum::BigEndian;
  static constexpr IOByteOrderEnum LittleEndian = IOByteOrderEnum::LittleEndian;
  static constexpr IOByteOrderEnum OrderNotApplicable = IOByteOrderEnum::OrderNotApplicable;
#endif

  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 k) const;

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

  itkSetEnumMacro(PixelType, itk::CommonEnums::IOPixel);
  itkGetEnumMacro(PixelType, itk::CommonEnums::IOPixel);

  itkSetEnumMacro(ComponentType, IOComponentEnum);
  itkGetEnumMacro(ComponentType, IOComponentEnum);

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

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

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

  itkSetClampMacro(CompressionLevel, int, 1, this->GetMaximumCompressionLevel());
  itkGetConstMacro(CompressionLevel, int);

  virtual void
  SetCompressor(std::string _c);
  itkGetConstReferenceMacro(Compressor, std::string);

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

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

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

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

  itkGetConstMacro(IsReadAsScalarPlusPalette, bool);

  static std::string GetComponentTypeAsString(IOComponentEnum);

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

  static std::string GetPixelTypeAsString(IOPixelEnum);

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

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

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

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

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

  std::string GetFileTypeAsString(IOFileEnum) const;

  std::string GetByteOrderAsString(IOByteOrderEnum) 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 IOComponentEnum CType = IOComponentEnum::UNKNOWNCOMPONENTTYPE;
  };
  template <typename TPixel>
  void
  SetPixelTypeInfo(const TPixel *)
  {
    this->SetNumberOfComponents(1);
    this->SetPixelType(IOPixelEnum::SCALAR);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TPixel>
  void
  SetPixelTypeInfo(const RGBPixel<TPixel> *)
  {
    this->SetNumberOfComponents(3);
    this->SetPixelType(IOPixelEnum::RGB);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TPixel>
  void
  SetPixelTypeInfo(const RGBAPixel<TPixel> *)
  {
    this->SetNumberOfComponents(4);
    this->SetPixelType(IOPixelEnum::RGBA);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <unsigned int VLength>
  void
  SetPixelTypeInfo(const Offset<VLength> *)
  {
    this->SetNumberOfComponents(VLength);
    this->SetPixelType(IOPixelEnum::OFFSET);
    this->SetComponentType(IOComponentEnum::LONG);
  }
  template <typename TPixel, unsigned int VLength>
  void
  SetPixelTypeInfo(const Vector<TPixel, VLength> *)
  {
    this->SetNumberOfComponents(VLength);
    this->SetPixelType(IOPixelEnum::VECTOR);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TCoordinate, unsigned int VPointDimension>
  void
  SetPixelTypeInfo(const Point<TCoordinate, VPointDimension> *)
  {
    this->SetNumberOfComponents(VPointDimension);
    this->SetPixelType(IOPixelEnum::POINT);
    this->SetComponentType(MapPixelType<TCoordinate>::CType);
  }
  template <typename TPixel, unsigned int VLength>
  void
  SetPixelTypeInfo(const CovariantVector<TPixel, VLength> *)
  {
    this->SetNumberOfComponents(VLength);
    this->SetPixelType(IOPixelEnum::COVARIANTVECTOR);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TPixel, unsigned int VLength>
  void
  SetPixelTypeInfo(const SymmetricSecondRankTensor<TPixel, VLength> *)
  {
    this->SetNumberOfComponents(VLength * (VLength + 1) / 2);
    this->SetPixelType(IOPixelEnum::SYMMETRICSECONDRANKTENSOR);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TPixel>
  void
  SetPixelTypeInfo(const DiffusionTensor3D<TPixel> *)
  {
    this->SetNumberOfComponents(6);
    this->SetPixelType(IOPixelEnum::DIFFUSIONTENSOR3D);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TPixel>
  void
  SetPixelTypeInfo(const std::complex<TPixel> *)
  {
    this->SetNumberOfComponents(2);
    this->SetPixelType(IOPixelEnum::COMPLEX);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TPixel, unsigned int VLength>
  void
  SetPixelTypeInfo(const FixedArray<TPixel, VLength> *)
  {
    this->SetNumberOfComponents(VLength);
    this->SetPixelType(IOPixelEnum::FIXEDARRAY);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TPixel>
  void
  SetPixelTypeInfo(const VariableLengthVector<TPixel> *)
  {
    this->SetNumberOfComponents(1);
    this->SetPixelType(IOPixelEnum::VARIABLELENGTHVECTOR);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TValue>
  void
  SetPixelTypeInfo(const Array<TValue> *)
  {
    this->SetNumberOfComponents(1);
    this->SetPixelType(IOPixelEnum::ARRAY);
    this->SetComponentType(MapPixelType<TValue>::CType);
  }
  template <typename TPixel, unsigned int VLength>
  void
  SetPixelTypeInfo(const Matrix<TPixel, VLength, VLength> *)
  {
    this->SetNumberOfComponents(VLength * VLength);
    this->SetPixelType(IOPixelEnum::MATRIX);
    this->SetComponentType(MapPixelType<TPixel>::CType);
  }
  template <typename TValue>
  void
  SetPixelTypeInfo(const VariableSizeMatrix<TValue> *)
  {
    this->SetNumberOfComponents(1);
    this->SetPixelType(IOPixelEnum::VARIABLESIZEMATRIX);
    this->SetComponentType(MapPixelType<TValue>::CType);
  }

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

  IOPixelEnum m_PixelType{ IOPixelEnum::SCALAR };

  IOComponentEnum m_ComponentType{ IOComponentEnum::UNKNOWNCOMPONENTTYPE };

  IOByteOrderEnum m_ByteOrder{ IOByteOrderEnum::OrderNotApplicable };
 
  IOFileEnum m_FileType{ IOFileEnum::TypeNotApplicable };

  bool m_Initialized{};

  std::string m_FileName{};

  unsigned int m_NumberOfComponents{};

  unsigned int m_NumberOfDimensions{ 0 };

  bool m_UseCompression{ false };
 
 
  int         m_CompressionLevel{ 30 };
  int         m_MaximumCompressionLevel{ 100 };
  std::string m_Compressor{ "uninitialized" };

  virtual void
  SetMaximumCompressionLevel(int);
  itkGetConstMacro(MaximumCompressionLevel, int);

  virtual void
  InternalSetCompressor(const std::string & _compressor);

  bool m_UseStreamedReading{};

  bool m_UseStreamedWriting{};

  bool m_ExpandRGBPalette{};

  bool m_IsReadAsScalarPlusPalette{};

  bool m_WritePalette{};

  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, IOComponentEnum ctype, SizeType numComp);

  virtual void
  ReadBufferAsASCII(std::istream & is, void * buffer, IOComponentEnum ctype, SizeType numComp);

  bool
  ReadBufferAsBinary(std::istream & is, void * buffer, SizeType num);

  void
  AddSupportedReadExtension(const char * extension);

  void
  AddSupportedWriteExtension(const char * extension);
 
 
  void
  SetSupportedReadExtensions(const ArrayOfExtensionsType &);
  void
  SetSupportedWriteExtensions(const ArrayOfExtensionsType &);

  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 ignoreCase = true);
 
  ArrayOfExtensionsType m_SupportedReadExtensions{};
  ArrayOfExtensionsType m_SupportedWriteExtensions{};
};

extern ITKIOImageBase_EXPORT void
WriteRawBytesAfterSwapping(IOComponentEnum componentType,
                           const void *    buffer,
                           std::ofstream & file,
                           IOByteOrderEnum byteOrder,
                           SizeValueType   numberOfBytes,
                           SizeValueType   numberOfComponents);

extern ITKIOImageBase_EXPORT void
ReadRawBytesAfterSwapping(IOComponentEnum componentType,
                          void *          buffer,
                          IOByteOrderEnum byteOrder,
                          SizeValueType   numberOfComponents);
 
#define IMAGEIOBASE_TYPEMAP(type, ctype)            \
  template <>                                       \
  struct ImageIOBase::MapPixelType<type>            \
  {                                                 \
    static constexpr IOComponentEnum CType = ctype; \
  }
 
// the following typemaps are not platform independent
IMAGEIOBASE_TYPEMAP(signed char, IOComponentEnum::CHAR);
IMAGEIOBASE_TYPEMAP(char, std::numeric_limits<char>::is_signed ? IOComponentEnum::CHAR : IOComponentEnum::UCHAR);
IMAGEIOBASE_TYPEMAP(unsigned char, IOComponentEnum::UCHAR);
IMAGEIOBASE_TYPEMAP(short, IOComponentEnum::SHORT);
IMAGEIOBASE_TYPEMAP(unsigned short, IOComponentEnum::USHORT);
IMAGEIOBASE_TYPEMAP(int, IOComponentEnum::INT);
IMAGEIOBASE_TYPEMAP(unsigned int, IOComponentEnum::UINT);
IMAGEIOBASE_TYPEMAP(long, IOComponentEnum::LONG);
IMAGEIOBASE_TYPEMAP(unsigned long, IOComponentEnum::ULONG);
IMAGEIOBASE_TYPEMAP(long long, IOComponentEnum::LONGLONG);
IMAGEIOBASE_TYPEMAP(unsigned long long, IOComponentEnum::ULONGLONG);
IMAGEIOBASE_TYPEMAP(float, IOComponentEnum::FLOAT);
IMAGEIOBASE_TYPEMAP(double, IOComponentEnum::DOUBLE);
#undef IMAGIOBASE_TYPEMAP
 
} // end namespace itk
 
#endif // itkImageIOBase_h