Like SubImageBox , only with Vector6 corners. Manages a rectangular 6D box given by two Vector6. Permits intersections etc. See mlSubImgBoxf in project ML.

The ML includes some frequently used types.

A detailed explanation of the following helper classes will be given in later editions of this document. Please refer to later versions of this document or to the header files:

2.6.3.2.1. MLDataType

The MLDataType is an enumerator describing all voxel data types currently available in the ML. This includes built-in data types like MLint8Type, MLuint8Type, MLint16Type, MLuint16Type, MLint32Type, MLuint32Type, MLint64Type, MLuint64Type, MLfloatType and MLdoubleType as well as (pre)registered types like Vector2, Vector3, Vector4, Vector6, Vector8, Vector10, Vector16, Vector32, complexf, etc.

Values of this type are often used to request or to determine image data or voxels of a certain type.

Since the number of MLDataTypes can change during runtime, it is implemented as an integer, and the function MLNumDataTypes() returns the current number of available voxel data types. MLDataTypeNames() returns a pointer to the table of data type names corresponding to the MLDataType values.

	Note
	An MLDataType value may also be invalid or out of range. This should be taken into consideration when using such values. MLIsValidType(MLDataType) can be used to check a type's validity. The number of data types may grow during runtime. MLNumDataTypes() can be used to retrieve the current number.

A number of other useful functions is available to query information about MLDataTypes:

1. const char *MLNameFromDataType(MLDataType dt)

   Returns the C string name of data type dt if dt is a valid type. Otherwise "" is returned.

2. MLDataType MLDataTypeFromName(const char * const name)

   Returns the MLDataType value of the data type with the name name. If name is not valid, -1 is returned.

3. double MLDataTypeMax(MLDataType dt)

   Returns the maximum value of data type dt; if dt is invalid, 0 is returned.

4. double MLDataTypeMin(MLDataType dt)

   Returns the minimum value of data type dt if dt is invalid, 0 is returned.

5. size_t MLSizeOf(MLDataType dt)

   Returns the size of the data type dt in bytes. 0 is returned for invalid types.

6. int MLIsValidType(MLDataType dt)

   Returns true(=1) if data type dt is valid. Otherwise false(=0) is returned.

7. int MLIsSigned(MLDataType dt)

   Returns true(=1) if data type dt is signed. Otherwise false(=0) is returned.

8. int MLIsIntType(MLDataType dt)

   returns true(=1) if data type dt is an integer data type. Otherwise false(=0) is returned.

9. int MLIsFloatType(MLDataType dt)

   Returns true(=1) if data type dt is a floating point data type. Otherwise false(=0) is returned.

10. int MLIsScalarType(MLDataType dt)

    Returns true(=1) if data type dt is a scalar (i.e., a built-in) type. Otherwise false(=0) is returned.

There are some more functions for the definition of features and properties related to data types. See the documentation in the file mlDataTypes.h for more information. A modern version to get compile-time information on MLDataType is to use the TypeTraits template class. See the documentation in the file mlTypeTraits.h for more information.

• int MLRangeOrder (MLDataType dt)

• int MLHolds (MLDataType dt1, MLDataType dt2)

• MLDataType MLGetPromotedType (MLDataType d1, MLDataType d2)

• MLDataType MLGetDataTypeForRange (double *min, double *max, int preferUnsigned)

• MLDataType MLGetDataTypeForUncorrectedRange (double min, double max, int preferUnsigned)

• MLDataType MLGetRangeAndPrecisionEquivalent (MLDataType dt)

• MLDataType MLGetPromotedPrecision (MLDataType dt1, MLDataType dt2)

Follow these steps to implement your own compressor (see MLDataCompressorDoc.h and other header files in project MLDataCompressor for details and code fragments):

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

The following example shows a complete header file implementation of a data compressor that packs 16 bit words by removing bit 12 to 15. It is a potentially lossy compressor, because highest bits are removed. It, however, could be useful for CT data, for example, which do not use those bits, or for cases where other compressors do not reach high compression ratios, because data is too noisy:

#ifndef __mlCTPackDataCompressor_H
#define __mlCTPackDataCompressor_H

#include "MLCTPackDataCompressorSystem.h"
#include "mlDataCompressor.h"

ML_UTILS_START_NAMESPACE

//! CTPackDataCompressor example for the ML.
class MLCTPackDATA_COMPRESSOR_EXPORT CTPackDataCompressor : public DataCompressor
{

public:

  //! Constructor (no destructor needed).
  CTPackDataCompressor() : DataCompressor() { }

  //! Returns name of compression scheme, used e.g., "RLE", or "LZW".
  virtual std::string     getTypeName()     const { return "CTPack";    }

  //! Returns the version string, e.g., "1.1.4" or "1.1"; compatibility
  //! check needs to be done in isSupportedVersion().
  virtual std::string     getVersion()      const { return "1.0";       }

  //! Returns true if the passed version ver is supported by the
  //! implemented compressor class and false otherwise.
  virtual bool            isSupportedVersion(const std::string &ver) const
  { return ver == getVersion(); }

  //! Return the name of the vendor providing the compressor code
  //! or algorithm, something like "MeVis", the author or the
  //! company selling the algorithm.
  virtual std::string     getVendor()       const { return "ML Guide";  }

  //! Returns the suffix describing the compression scheme, for
  //! example "rle" or "lzw".
  virtual std::string     getSuffix()       const { return "cpk";       }

  //! Returns true if compression is lossy, false if not, base class
  //! default is false.
  //! We have to enable lossy, because we throw away highest nibble
  //! which could cause check sum errors in file formats if not denoted.
  virtual bool            isLossy()         const { return true;        }

  //! Number of hints used by the derived compressor class (defaults
  //! to 0 in base class).
  virtual MLuint8         numUsedHints()    const { return 0;           }

  //! Compresses a chunk of memory to be decompressed later with decompress().
  //! \param  srcMem  is the pointer of data to be compressed.
  //! \param  srcSize is the size of the data pointed to by srcMem in bytes.
  //! \param  dstMem  the pointer to the compressed data.
  //!                 The compressor will allocate the required memory and
  //!                 overwrites the dstMem pointer which then must be freed
  //!                 by the caller with MLFree() or Memory::freeMemory().
  //! \param  dstNum  returns size of compressed data chunk in bytes or 0 on error.
  //! \return         ML_RESULT_OK on successful compression or an error code
  //!                 describing the error.
  virtual MLErrorCode compress(const  void  *srcMem,
                               size_t        srcSize,
                               void        *&dstMem,
                               MLint        &dstNum) const
  {
    MLErrorCode errCode = ML_NO_MEMORY;
    dstMem = NULL;
    dstNum = 0;

    if (srcMem && (srcSize>0)){

      // Determine size of destination buffer, it requires 4 byte at begin to
      // store original data size and in worst case 1 bit more per CTPack more
      // if no CTPack can be compressed. Add four bytes for rounding securely.

      const size_t packedSize =
        static_cast<size_t>(sizeof(MLint64) + (srcSize * 3) / 4 + 4);

      dstMem = Memory::allocateMemory(packedSize, ML_RETURN_NULL);

      if (dstMem != NULL) {

        // Get byte pointer to output memory and clear data.
        unsigned char *targetData = static_cast<unsigned char *>(dstMem);
        memset(targetData, 0, packedSize);

        // Store size of source data in little endian format at buffer start.
        (static_cast<MLint64*>(dstMem))[0] = static_cast<MLint64>(srcSize);

        if (!MLIsLittleEndian()) {
          MLSwapBytes(targetData, sizeof(MLint64), sizeof(MLint64));
        }

        // Traverse all nibbles/half bytes.
        srcSize *= 2;
        size_t oNibble = 16; // Set start to first nibble after stored startDstSize.
        for (size_t n = 0; n < srcSize; ++n) {

          // Get nibble from source data.
          const unsigned char nib =
            (static_cast<const unsigned char*>(srcMem)[n>>1] >>
             ((n & 1)*4)) & 0xf;

          // Add nibble to output data.
          if ((n & 3) != 3) {
            targetData[oNibble>>1] |= (oNibble & 1 ? (nib << 4) : nib);
            ++oNibble;
          }
        }

        // Calculate number of really used bytes in destination buffer and add 1
        // byte as buffer zone for check of buffer overrun during decompression.
        dstNum = (oNibble >> 1) + (oNibble & 1 ? 1 : 0);

        // Return success.
        errCode = ML_RESULT_OK;
      }
    }
    return errCode;
  }

  //! Decompresses a chunk of memory created with compress().
  //! \param  srcMem  is the pointer to the compressed data to be decompressed.
  //! \param  srcSize is the size of the data pointed to by srcMem in bytes.
  //! \param  dstMem  returns the pointer to the decompressed data; it is
  //!                 overwritten with the pointer to the allocated and
  //!                 uncompressed data which must be freed by the caller
  //!                 with MLFree() or Memory::freeMemory().
  //! \param  resSize returns the size of the decompressed data
  //!                 memory in bytes or -1 on error.
  //! \return         ML_RESULT_OK on successful decompression or
  //!                 an error code describing the error.
  virtual MLErrorCode decompress(const  void  *srcMem,
                                 size_t        srcSize,
                                 void        *&dstMem,
                                 MLint64      &resSize) const
  {
    // Pointer to working and result buffers.
    dstMem              = NULL;
    resSize             = -1;
    MLErrorCode errCode = ML_BAD_POINTER_OR_0;

    // Check uncompressed size for at least the four size bytes at start.
    if (srcSize <= sizeof(MLint64)) {
      errCode = ML_FILE_OR_DATA_STRUCTURE_CORRUPTED;
    } else {

      // Get size of decompression data from start of compressed data.
      MLint64 uncompressedSize = (static_cast<const MLint64*>(srcMem))[0];

      if (!MLIsLittleEndian()) {

        // Swap data to local endian format, the data is always stored
        // in little endian.
        MLSwapBytes(reinterpret_cast<unsigned char*>(&uncompressedSize),
                    sizeof(MLint64),
                    sizeof(MLint64));
      }

      if (uncompressedSize < 0) {

        // Should not happen, data is probably corrupted.
        errCode = ML_FILE_OR_DATA_STRUCTURE_CORRUPTED;
      } else {

       // Size seems to be valid, allocate return buffer.
        dstMem = Memory::allocateMemory(static_cast<size_t>(uncompressedSize),
                                        ML_RETURN_NULL);
        if (!dstMem) {
          errCode = ML_NO_MEMORY;
        } else {

          // Unpack all packed nibbles from source data into cleaned result buffer.
          memset(dstMem, 0, uncompressedSize);
          MLint64 oNibble = 0;
          for (size_t n = 16; n < srcSize*2; ++n) {
            // Get nibble from packed data.
            const unsigned char nib =
              (static_cast<const unsigned char*>(srcMem)[n>>1] >>
               ((n & 1)*4)) & 0xf;

            // After unpacking 3 nibbles add a fourth empty one.
            if ((oNibble & 3) == 3) { ++oNibble; }

            // Add nibble to output, shifted by 4 bits if necessary.
            static_cast<unsigned char*>(dstMem)[oNibble >> 1] |=
             (oNibble & 1) ? (nib << 4) : nib;

            ++oNibble;
          }

          // Return success and number of uncompressed bytes.
          errCode = ML_RESULT_OK;
          resSize = uncompressedSize;
        } // else ML_NO_MEMORY;
      } // else if ((uncompressedSize < 0))
    } // else if (srcSize <= sizeof(MLint64) + 1)

    // Clean up on error.
    if (ML_RESULT_OK != errCode) {
      MLFree(dstMem);
      dstMem  = NULL;
      resSize = -1;
    }
    return errCode;
  }


private:

  //! Implements interface for the runtime type system of the ML.
  ML_CLASS_HEADER(CTPackDataCompressor)
};

ML_UTILS_END_NAMESPACE
#endif // __mlCTPackDataCompressor_H

Do not forget to implement the registration code in the ML runtime type system with the typical ML_CLASS_SOURCE macro in the .cpp file:

ML_CLASS_SOURCE(CTPackDataCompressor, DataCompressor);

Also, the registration of the classes in the runtime type system and in the factory for ML data compressors need to be called before using them for the first time (normally in the initialization code while loading the module code):

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