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:70

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:818

mlImageFormatTagList.h

mlModuleIncludes.h

mlTimeCounter.h

MLuint32
unsigned int MLuint32
Definition: mlTypeDefs.h:191

MLuint8
unsigned char MLuint8
Definition: mlTypeDefs.h:115

MLdouble
double MLdouble
Definition: mlTypeDefs.h:223

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

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:578

ml::ScaleShiftData
TScaleShiftData< MLdouble > ScaleShiftData
Double version of TScaleShiftData for maximum reasonable precision.
Definition: mlScaleShiftData.h:326

ml::SubImageBox
TSubImageBox< MLint > SubImageBox
Define the standard SubImageBox type used in the ML. Its size varies with the size of the MLint type.
Definition: mlSubImageBox.h:285