SDK/ToolBoxReference/mlImageFormatTools_8h_source.html

/*************************************************************************************

**

** Copyright 2007, MeVis Medical Solutions AG

**

** The user may use this file in accordance with the license agreement provided with

** the Software or, alternatively, in accordance with the terms contained in a

** written agreement between the user and MeVis Medical Solutions AG.

**

** For further information use the contact form at https://www.mevislab.de/contact

**

**************************************************************************************/


#ifndef ML_IMAGE_FORMAT_TOOLS_H

#define ML_IMAGE_FORMAT_TOOLS_H


// Resolve platform independencies.

#include "MLImageFormatBaseSystem.h"


#include "mlModuleIncludes.h"

#include "mlImageFormatTagList.h"

#include <mlTimeCounter.h>


// Implement everything in ML namespace.

ML_START_NAMESPACE


  class MLImageFormatInfos;

  class DataCompressor;

  class MLImageFormatIdxTable;


  //----------------------------------------------------------------------

  //----------------------------------------------------------------------


  class MLIMAGEFORMATBASE_EXPORT MLImageFormatTools {


  public:

    friend class MLImageFormatSaveHandler;


    enum SaveModeBits {

      DefaultSaveMode      = 0,

      AllowPartialPages    = 1,

      SaveOnlyDefaultValue = 2

    };


    //--------------------------------------------------------------------------------

    //--------------------------------------------------------------------------------

    typedef void  MLImageFormatNotifyCB(double      progress,

                                        void        *usrData

                                       );


    //--------------------------------------------------------------------------------

    //--------------------------------------------------------------------------------

    static const std::string  ML_FILE_VERSION_STRING;


    //--------------------------------------------------------------------------------

    //--------------------------------------------------------------------------------

    static const std::string  ML_FILE_VERSION_STRING_EXT;


    //--------------------------------------------------------------------------------

    //--------------------------------------------------------------------------------

    static const size_t       ML_MAX_VERSION_AND_FIRST_PAIR_SIZE;


    //----------------------------------------------------------------------

    //

    //

    //----------------------------------------------------------------------


    static MLErrorCode         open(MLImageFormatInfos        *&infos,

                                    const std::string          &fileName,

                                    bool                       truncate                  = false,

                                    const std::string          &compressorName           = "",

                                    const MLImageFormatTagList &compressionTagList       = MLImageFormatTagList::getDefaultEmptyTagList(),

                                    const MLImageFormatTagList &userTagList              = MLImageFormatTagList::getDefaultEmptyTagList(),

                                    const MLImageFormatTagList &privateTagList           = MLImageFormatTagList::getDefaultEmptyTagList(),

                                    const std::string          &defaultVoxelValue        = "0",

                                    bool                       rewritable                = true,

                                    bool                       suppressReadCheckSumTests = false);


    static MLErrorCode         open(MLImageFormatInfos        *&infos,

                                    MLImageFormatAbstractFileHandle* fileHandle,

                                    bool                       truncate = false,

                                    const std::string          &compressorName = "",

                                    const MLImageFormatTagList &compressionTagList = MLImageFormatTagList::getDefaultEmptyTagList(),

                                    const MLImageFormatTagList &userTagList = MLImageFormatTagList::getDefaultEmptyTagList(),

                                    const MLImageFormatTagList &privateTagList = MLImageFormatTagList::getDefaultEmptyTagList(),

                                    const std::string          &defaultVoxelValue = "0",

                                    bool                       rewritable = true,

                                    bool                       suppressReadCheckSumTests = false);


    static MLErrorCode         close(MLImageFormatInfos *&infos);


    static MLErrorCode         save(MLImageFormatInfos             &infos,

                                    PagedImage                     &inputPagedImg,

                                    const SubImageBox              &box            = SubImageBox(),

                                    MLImageFormatNotifyCB          *callback       = nullptr,

                                    void                           *userData       = nullptr,

                                    const ScaleShiftData           &scaleShiftData = ScaleShiftData(),

                                    MLuint32                       saveModeBits    = DefaultSaveMode,

                                    MLdouble                       *saveTime       = nullptr ,

                                    MLdouble                       *prepTime       = nullptr);


    static MLErrorCode overwriteHeaderAndPageList(const MLImageFormatInfos &infos,

                                                  MLuint32                  saveModeBits);


    static MLErrorCode         overwrite(MLImageFormatInfos         &infos         ,

                                         PagedImage                 &inputPagedImg ,

                                         const SubImageBox          &box           ,

                                         MLImageFormatNotifyCB      *callback      ,

                                         void                       *userData      ,

                                         const ScaleShiftData       &scaleShiftData,

                                         MLuint32                   saveModeBits = DefaultSaveMode,

                                         MLdouble                   *saveTime    = nullptr ,

                                         MLdouble                   *prepTime    = nullptr);


    static MLErrorCode         overwrite(MLImageFormatInfos         &infos         ,

                                         const SubImage             &inputSubImg   ,

                                         MLImageFormatNotifyCB      *callback      ,

                                         void                       *userData      ,

                                         const ScaleShiftData       &scaleShiftData,

                                         MLuint32                   saveModeBits = DefaultSaveMode,

                                         MLdouble                   *saveTime    = nullptr ,

                                         MLdouble                   *prepTime    = nullptr);


    static MLErrorCode         getTile(const MLImageFormatInfos &infos,

                                       SubImage                 &subImgToFill,

                                       bool                      useFileDataType,

                                       bool                      useFileRegion,

                                       const ScaleShiftData     &scaleShiftData);


    static MLuint32            calcCheckSum(const void *dataPtr, size_t numBytes, size_t voxSize);


    static void                setDICOMTreeSourceFileName(PagedImage &outImg,

                                                          const std::string &fileName);


  protected:


    static MLErrorCode  _loadFileProperties(MLImageFormatInfos &infos);


    static MLErrorCode  _destroyFileProperties(MLImageFormatInfos *&infos);


    static MLErrorCode  _loadPage(const MLImageFormatInfos &infos,

                                  MLint                    pageId,

                                  SubImage                 &pageBuf);


    static MLErrorCode _decompressPageData(const MLImageFormatInfos  &infos,

                                           const size_t              savedPageSizeInBytes,

                                           const size_t              expectedSizeInBytes,

                                           MLuint8                  *&loadedPage,

                                           bool                      &isLossy);


    static MLErrorCode _saveIndexTableAndPages(MLImageFormatInfos    &infos,

                                               const SubImageBox     &box,

                                               PagedImage            *inputPagedImg,

                                               const SubImage        *inputSubImg,

                                               MLImageFormatNotifyCB *callback,

                                               void                  *userData,

                                               const ScaleShiftData  &scaleShiftData,

                                               bool                  replaceAreaToSave,

                                               MLuint32              saveModeBits,

                                               MLdouble              *saveTime=nullptr,

                                               MLdouble              *prepTime=nullptr);


    static MLErrorCode _savePage(MLImageFormatInfos    &infos,

                                 const MLint           pageId,

                                 const bool            isOutsideAreaToSave,

                                 const MLTypeData      *defaultVoxelPtr,

                                 const SubImage        &subImgToSave,

                                 const bool            replaceOnlyWrittenPageIds,

                                 const MLuint32        saveModeBits,

                                 TimeCounter           &saveTimer,

                                 MLdouble              &saveTime,

                                 TimeCounter           &calcTimer,

                                 MLdouble              &calcTime);


    static MLErrorCode _compressPageData(DataCompressor *compressor,

                                         SubImage       &dataSubImg,

                                         MLint          &dstBufSize);


  };


ML_END_NAMESPACE


#endif // of __mlImageFormatTools_H


MLImageFormatBaseSystem.h

MLIMAGEFORMATBASE_EXPORT
#define MLIMAGEFORMATBASE_EXPORT
Global and OS specific declarations for the MLImageFormatBase project.
Definition MLImageFormatBaseSystem.h:24

ml::DataCompressor
Abstract base class for ML data compression algorithms.
Definition mlDataCompressor.h:37

ml::MLImageFormatAbstractFileHandle
A base class for abstract read/write access of the MLImageFileFormat.
Definition mlImageFormatFileAccess.h:27

ml::MLImageFormatInfos
A internal structure containing information about an opened file, not to be used, because it is subje...
Definition mlImageFormatInfos.h:45

ml::MLImageFormatTagList
Class defining a list of tags used in the MLImageFormat class.
Definition mlImageFormatTagList.h:39

ml::MLImageFormatTools
Basic tool functions used to store, load, and modify a PagedImage in a file, used by the MLImageForma...
Definition mlImageFormatTools.h:39

ml::MLImageFormatTools::_decompressPageData
static MLErrorCode _decompressPageData(const MLImageFormatInfos &infos, const size_t savedPageSizeInBytes, const size_t expectedSizeInBytes, MLuint8 *&loadedPage, bool &isLossy)
Decompress and replace data given as pointer in loadedPage.

ml::MLImageFormatTools::ML_FILE_VERSION_STRING
static const std::string ML_FILE_VERSION_STRING
Basic file version string used for MeVisLab release 1.5.
Definition mlImageFormatTools.h:69

ml::MLImageFormatTools::open
static MLErrorCode open(MLImageFormatInfos *&infos, const std::string &fileName, bool truncate=false, const std::string &compressorName="", const MLImageFormatTagList &compressionTagList=MLImageFormatTagList::getDefaultEmptyTagList(), const MLImageFormatTagList &userTagList=MLImageFormatTagList::getDefaultEmptyTagList(), const MLImageFormatTagList &privateTagList=MLImageFormatTagList::getDefaultEmptyTagList(), const std::string &defaultVoxelValue="0", bool rewritable=true, bool suppressReadCheckSumTests=false)
Opens a file in binary mode returning a descriptor for the opened file.

ml::MLImageFormatTools::overwrite
static MLErrorCode overwrite(MLImageFormatInfos &infos, const SubImage &inputSubImg, MLImageFormatNotifyCB *callback, void *userData, const ScaleShiftData &scaleShiftData, MLuint32 saveModeBits=DefaultSaveMode, MLdouble *saveTime=nullptr, MLdouble *prepTime=nullptr)
Overwrites a region in a file which has been written before (with save).

ml::MLImageFormatTools::close
static MLErrorCode close(MLImageFormatInfos *&infos)
Closes an open file.

ml::MLImageFormatTools::overwrite
static MLErrorCode overwrite(MLImageFormatInfos &infos, PagedImage &inputPagedImg, const SubImageBox &box, MLImageFormatNotifyCB *callback, void *userData, const ScaleShiftData &scaleShiftData, MLuint32 saveModeBits=DefaultSaveMode, MLdouble *saveTime=nullptr, MLdouble *prepTime=nullptr)
Overwrites a region in a file which has been written before (with save).

ml::MLImageFormatTools::calcCheckSum
static MLuint32 calcCheckSum(const void *dataPtr, size_t numBytes, size_t voxSize)
Calculates a 24 bit check sum for the data given by dataPtr.

ml::MLImageFormatTools::ML_FILE_VERSION_STRING_EXT
static const std::string ML_FILE_VERSION_STRING_EXT
Basic file version string used for MeVisLab release 1.5 plus addOns which endanger backward compatibi...
Definition mlImageFormatTools.h:75

ml::MLImageFormatTools::save
static MLErrorCode save(MLImageFormatInfos &infos, PagedImage &inputPagedImg, const SubImageBox &box=SubImageBox(), MLImageFormatNotifyCB *callback=nullptr, void *userData=nullptr, const ScaleShiftData &scaleShiftData=ScaleShiftData(), MLuint32 saveModeBits=DefaultSaveMode, MLdouble *saveTime=nullptr, MLdouble *prepTime=nullptr)
Saves the data of the paged image inputPagedImg from the region given by box in the file.

ml::MLImageFormatTools::MLImageFormatNotifyCB
void MLImageFormatNotifyCB(double progress, void *usrData)
Callback type which can be registered in save and overwrite functions to interrupt processing and to ...
Definition mlImageFormatTools.h:58

ml::MLImageFormatTools::_destroyFileProperties
static MLErrorCode _destroyFileProperties(MLImageFormatInfos *&infos)
Destroys the MLImageFileInfo object and resets the pointer to NULL.

ml::MLImageFormatTools::open
static MLErrorCode open(MLImageFormatInfos *&infos, MLImageFormatAbstractFileHandle *fileHandle, bool truncate=false, const std::string &compressorName="", const MLImageFormatTagList &compressionTagList=MLImageFormatTagList::getDefaultEmptyTagList(), const MLImageFormatTagList &userTagList=MLImageFormatTagList::getDefaultEmptyTagList(), const MLImageFormatTagList &privateTagList=MLImageFormatTagList::getDefaultEmptyTagList(), const std::string &defaultVoxelValue="0", bool rewritable=true, bool suppressReadCheckSumTests=false)
Overload of open() with a virtual file handle, have a look at open(..., filename, ....

ml::MLImageFormatTools::SaveModeBits
SaveModeBits
Mode bits describing special save options.
Definition mlImageFormatTools.h:45

ml::MLImageFormatTools::ML_MAX_VERSION_AND_FIRST_PAIR_SIZE
static const size_t ML_MAX_VERSION_AND_FIRST_PAIR_SIZE
Number of characters which will not be exceeded by version string and first tag pair.
Definition mlImageFormatTools.h:81

ml::MLImageFormatTools::_saveIndexTableAndPages
static MLErrorCode _saveIndexTableAndPages(MLImageFormatInfos &infos, const SubImageBox &box, PagedImage *inputPagedImg, const SubImage *inputSubImg, MLImageFormatNotifyCB *callback, void *userData, const ScaleShiftData &scaleShiftData, bool replaceAreaToSave, MLuint32 saveModeBits, MLdouble *saveTime=nullptr, MLdouble *prepTime=nullptr)
Save or overwrite pages overlapping areaToSave of inputPagedImg.

ml::MLImageFormatTools::_loadPage
static MLErrorCode _loadPage(const MLImageFormatInfos &infos, MLint pageId, SubImage &pageBuf)
Read page given by id pageId into memory handled by pageBuf.

ml::MLImageFormatTools::setDICOMTreeSourceFileName
static void setDICOMTreeSourceFileName(PagedImage &outImg, const std::string &fileName)
If the paged image has DicomTreeImagePropertyExtensions then set their file names,...

ml::MLImageFormatTools::overwriteHeaderAndPageList
static MLErrorCode overwriteHeaderAndPageList(const MLImageFormatInfos &infos, MLuint32 saveModeBits)
Save the file header information a second time over the already written file.

ml::MLImageFormatTools::getTile
static MLErrorCode getTile(const MLImageFormatInfos &infos, SubImage &subImgToFill, bool useFileDataType, bool useFileRegion, const ScaleShiftData &scaleShiftData)
Loads a subimage from the specified file and returns an MLErrorCode describing success or failure.

ml::MLImageFormatTools::_savePage
static MLErrorCode _savePage(MLImageFormatInfos &infos, const MLint pageId, const bool isOutsideAreaToSave, const MLTypeData *defaultVoxelPtr, const SubImage &subImgToSave, const bool replaceOnlyWrittenPageIds, const MLuint32 saveModeBits, TimeCounter &saveTimer, MLdouble &saveTime, TimeCounter &calcTimer, MLdouble &calcTime)
Store the page subImgToSave in file given by infos and update the corresponding entry in the index ta...

ml::MLImageFormatTools::_compressPageData
static MLErrorCode _compressPageData(DataCompressor *compressor, SubImage &dataSubImg, MLint &dstBufSize)
Compresses data of a subimage.

ml::MLImageFormatTools::_loadFileProperties
static MLErrorCode _loadFileProperties(MLImageFormatInfos &infos)
Reads all information from the file given by fileHandle in infos and stores it the returned informati...

ml::PagedImage
Class which represents an image, which manages properties of an image and image data which is located...
Definition mlPagedImage.h:66

ml::SubImage
This class manages/represents a rectangular 6d image region which is organized linearly in memory.
Definition mlSubImage.h:75

ml::TScaleShiftData< MLdouble >

ml::TSubImageBox< MLint >

ml::TimeCounter
Class to measure precise time intervals.
Definition mlTimeCounter.h:26

MLErrorCode
MLint32 MLErrorCode
Type of an ML Error code.
Definition mlTypeDefs.h:716

mlImageFormatTagList.h

mlModuleIncludes.h

mlrange_cast
Target mlrange_cast(Source arg)
Generic version of checked ML casts.
Definition mlRangeCasts.h:332

mlTimeCounter.h

MLuint32
unsigned int MLuint32
Definition mlTypeDefs.h:185

MLuint8
unsigned char MLuint8
Definition mlTypeDefs.h:109

MLdouble
double MLdouble
Definition mlTypeDefs.h:217

MLTypeData
unsigned char MLTypeData
This is the pointer type used to point to the data of MLType data instances.
Definition mlTypeDefs.h:1300

MLint
MLint64 MLint
A signed ML integer type with at least 64 bits used for index calculations on very large images even ...
Definition mlTypeDefs.h:490