MeVisLab Toolbox Reference
mlImageFormatTools.h
Go to the documentation of this file.
1 /*************************************************************************************
2 **
3 ** Copyright 2007, MeVis Medical Solutions AG
4 **
5 ** The user may use this file in accordance with the license agreement provided with
6 ** the Software or, alternatively, in accordance with the terms contained in a
7 ** written agreement between the user and MeVis Medical Solutions AG.
8 **
9 ** For further information use the contact form at https://www.mevislab.de/contact
10 **
11 **************************************************************************************/
12 
13 #ifndef ML_IMAGE_FORMAT_TOOLS_H
14 #define ML_IMAGE_FORMAT_TOOLS_H
15 
19 
20 // Resolve platform independencies.
21 #include "MLImageFormatBaseSystem.h"
22 
23 #include "mlModuleIncludes.h"
24 #include "mlImageFormatTagList.h"
25 #include <mlTimeCounter.h>
26 
27 // Implement everything in ML namespace.
28 ML_START_NAMESPACE
29 
31  class MLImageFormatInfos;
32  class DataCompressor;
33  class MLImageFormatIdxTable;
34 
35  //----------------------------------------------------------------------
38  //----------------------------------------------------------------------
39  class MLIMAGEFORMATBASE_EXPORT MLImageFormatTools {
40 
41  public:
42  friend class MLImageFormatSaveHandler;
43 
45  enum SaveModeBits {
46  DefaultSaveMode = 0,
47  AllowPartialPages = 1,
49  SaveOnlyDefaultValue = 2
52  };
53 
54  //--------------------------------------------------------------------------------
57  //--------------------------------------------------------------------------------
58  typedef void MLImageFormatNotifyCB(double progress,
59  void *usrData
60  );
61 
62 
63  //--------------------------------------------------------------------------------
68  //--------------------------------------------------------------------------------
69  static const std::string ML_FILE_VERSION_STRING;
70 
71  //--------------------------------------------------------------------------------
75  //--------------------------------------------------------------------------------
76  static const std::string ML_FILE_VERSION_STRING_EXT;
77 
78  //--------------------------------------------------------------------------------
81  //--------------------------------------------------------------------------------
82  static const size_t ML_MAX_VERSION_AND_FIRST_PAIR_SIZE;
83 
84  //----------------------------------------------------------------------
85  //
88  //
89  //----------------------------------------------------------------------
90 
126  static MLErrorCode open(MLImageFormatInfos *&infos,
127  const std::string &fileName,
128  bool truncate = false,
129  const std::string &compressorName = "",
130  const MLImageFormatTagList &compressionTagList = MLImageFormatTagList::getDefaultEmptyTagList(),
131  const MLImageFormatTagList &userTagList = MLImageFormatTagList::getDefaultEmptyTagList(),
132  const MLImageFormatTagList &privateTagList = MLImageFormatTagList::getDefaultEmptyTagList(),
133  const std::string &defaultVoxelValue = "0",
134  bool rewritable = true,
135  bool suppressReadCheckSumTests = false);
136 
140  static MLErrorCode open(MLImageFormatInfos *&infos,
141  MLImageFormatAbstractFileHandle* fileHandle,
142  bool truncate = false,
143  const std::string &compressorName = "",
144  const MLImageFormatTagList &compressionTagList = MLImageFormatTagList::getDefaultEmptyTagList(),
145  const MLImageFormatTagList &userTagList = MLImageFormatTagList::getDefaultEmptyTagList(),
146  const MLImageFormatTagList &privateTagList = MLImageFormatTagList::getDefaultEmptyTagList(),
147  const std::string &defaultVoxelValue = "0",
148  bool rewritable = true,
149  bool suppressReadCheckSumTests = false);
150 
156  static MLErrorCode close(MLImageFormatInfos *&infos);
157 
185  static MLErrorCode save(MLImageFormatInfos &infos,
186  PagedImage &inputPagedImg,
187  const SubImageBox &box = SubImageBox(),
188  MLImageFormatNotifyCB *callback = nullptr,
189  void *userData = nullptr,
190  const ScaleShiftData &scaleShiftData = ScaleShiftData(),
191  MLuint32 saveModeBits = DefaultSaveMode,
192  MLdouble *saveTime = nullptr ,
193  MLdouble *prepTime = nullptr);
194 
195 
211  static MLErrorCode overwriteHeaderAndPageList(const MLImageFormatInfos &infos,
212  MLuint32 saveModeBits);
213 
214 
240  static MLErrorCode overwrite(MLImageFormatInfos &infos ,
241  PagedImage &inputPagedImg ,
242  const SubImageBox &box ,
243  MLImageFormatNotifyCB *callback ,
244  void *userData ,
245  const ScaleShiftData &scaleShiftData,
246  MLuint32 saveModeBits = DefaultSaveMode,
247  MLdouble *saveTime = nullptr ,
248  MLdouble *prepTime = nullptr);
249 
272  static MLErrorCode overwrite(MLImageFormatInfos &infos ,
273  const SubImage &inputSubImg ,
274  MLImageFormatNotifyCB *callback ,
275  void *userData ,
276  const ScaleShiftData &scaleShiftData,
277  MLuint32 saveModeBits = DefaultSaveMode,
278  MLdouble *saveTime = nullptr ,
279  MLdouble *prepTime = nullptr);
280 
313  static MLErrorCode getTile(const MLImageFormatInfos &infos,
314  SubImage &subImgToFill,
315  bool useFileDataType,
316  bool useFileRegion,
317  const ScaleShiftData &scaleShiftData);
319 
320 
331  static MLuint32 calcCheckSum(const void *dataPtr, size_t numBytes, size_t voxSize);
332 
342  static void setDICOMTreeSourceFileName(PagedImage &outImg,
343  const std::string &fileName);
344 
345 
346  protected:
347 
354  static MLErrorCode _loadFileProperties(MLImageFormatInfos &infos);
355 
359  static MLErrorCode _destroyFileProperties(MLImageFormatInfos *&infos);
360 
371  static MLErrorCode _loadPage(const MLImageFormatInfos &infos,
372  MLint pageId,
373  SubImage &pageBuf);
374 
384  static MLErrorCode _decompressPageData(const MLImageFormatInfos &infos,
385  const size_t savedPageSizeInBytes,
386  const size_t expectedSizeInBytes,
387  MLuint8 *&loadedPage,
388  bool &isLossy);
389 
432  static MLErrorCode _saveIndexTableAndPages(MLImageFormatInfos &infos,
433  const SubImageBox &box,
434  PagedImage *inputPagedImg,
435  const SubImage *inputSubImg,
436  MLImageFormatNotifyCB *callback,
437  void *userData,
438  const ScaleShiftData &scaleShiftData,
439  bool replaceAreaToSave,
440  MLuint32 saveModeBits,
441  MLdouble *saveTime=nullptr,
442  MLdouble *prepTime=nullptr);
443 
471  static MLErrorCode _savePage(MLImageFormatInfos &infos,
472  const MLint pageId,
473  const bool isOutsideAreaToSave,
474  const MLTypeData *defaultVoxelPtr,
475  const SubImage &subImgToSave,
476  const bool replaceOnlyWrittenPageIds,
477  const MLuint32 saveModeBits,
478  TimeCounter &saveTimer,
479  MLdouble &saveTime,
480  TimeCounter &calcTimer,
481  MLdouble &calcTime);
482 
496  static MLErrorCode _compressPageData(DataCompressor *compressor,
497  SubImage &dataSubImg,
498  MLint &dstBufSize);
499 
500  };
501 
502 ML_END_NAMESPACE
503 
504 #endif // of __mlImageFormatTools_H
505 
506 
MLIMAGEFORMATBASE_EXPORT
#define MLIMAGEFORMATBASE_EXPORT
Definition: MLImageFormatBaseSystem.h:19
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.
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)
Decompresses and replaces 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 that 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 that 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 checksum 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.
Definition: mlImageFormatTools.h:76
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 that can be registered in save and overwrite functions to interrupt processing and to g...
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 that will not be exceeded by version string and first tag pair.
Definition: mlImageFormatTools.h:82
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)
Saves or overwrites pages overlapping areaToSave of inputPagedImg.
ml::MLImageFormatTools::_loadPage
static MLErrorCode _loadPage(const MLImageFormatInfos &infos, MLint pageId, SubImage &pageBuf)
Reads 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)
Saves 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)
Stores the page subImgToSave in file given by infos and updates the corresponding entry in the index ...
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 in the returned inform...
ml::PagedImage
The class PagedImage, representing a fragmented image that manages properties and data of an image lo...
Definition: mlPagedImage.h:66
ml::SubImage
This class manages/represents a rectangular 6D image region that is organized linearly in memory.
Definition: mlSubImage.h:75
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
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
ml::ScaleShiftData
TScaleShiftData< MLdouble > ScaleShiftData
Double version of TScaleShiftData for maximum reasonable precision.
Definition: mlScaleShiftData.h:326
ml::SubImageBox
TSubImageBox< MLint > SubImageBox
Defines the standard SubImageBox type used in the ML. Its size varies with the size of the MLint type...
Definition: mlSubImageBox.h:255