MLDataCompressor Overview

Overview documentation of the ML DataCompressor project.

MLDataCompressor Class Library

This library contains the base class DataCompressor which allows for implementing new data compression algorithms and a factory class DataCompressorFactory allowing for registration of user derived classes. In this way any number of new compression classes can be implemented which are automatically detected by classes using compression algorithms.

How to implement your own DataCompressor class?

• Be sure to implement everything in the namespace ML_UTILS_NAMESPACE.
• Derive from the DataCompressor class and override the following methods:

  virtual const std::string     getTypeName()     const = 0;
  virtual const std::string     getVersion()      const = 0;
  virtual const bool            isSupportedVersion(const std::string &ver) const = 0;
  virtual MLErrorCode           compress(const  void *srcMem,
                                         size_t       srcSize,
                                         void       *&dstMem,
                                         MLint       &dstNum) const = 0;
  virtual MLErrorCode           decompress(const  void *srcMem,
                                           size_t       srcSize,
                                           void       *&dstMem,
                                           MLint64     &resSize) const = 0;

  It is also recommended to implement

  virtual std::string           getVendor()       const { return "";           }
  virtual std::string           getSuffix()       const { return "";           }
  virtual bool                  isLossy()         const { return false;        }

• Register your DataCompressor (for example during dll/so registration) first with YourDataCompressor::initClass() in the runtime type system of the ML and then in the DataCompressor factory:

  YourDataCompressor::initClass();
  DataCompressorFactory::registerCompressor(YourDataCompressor::getClassTypeId());

  This requires the usage of

  ML_CLASS_HEADER(YourDataCompressor)

  at the end of your class definition and

  ML_CLASS_SOURCE(YourDataCompressor, DataCompressor)

  in the implementation.
• Be sure that classes using the your data compressor will find it registered in the DataCompressorFactory BEFORE they are instantiated. In MeVisLab your can do this by specifying the PreloadDll flag in a .def file for your compressor.
• You may also want to override the numUsedHints() method and initialize the following members appropriately to specify parameters for your compressor which might be detected and passed by some applications to control the behavior of the compression:

  HintType    _hintType[MaxHints];
  MLdouble    _dblHints[MaxHints];
  MLint       _intHints[MaxHints];
  std::string _strHints[MaxHints];
  std::string _hintName[MaxHints];
  double      _rangeMin[MaxHints];
  double      _rangeMax[MaxHints];

  The parameters _hintType, _hintName, rangeMin, and _rangeMax should be set by your derived class, all other should be set to default values.

Then all classes using DataCompressors via the DataCompressorFactory (for example the MLImageFormat class) will automatically detect your compression algorithm and offer it as an option.