MeVisLab Toolbox Reference
ml::MLImageFormat Class Reference

File format class to store, load, and modify a PagedImage in a file. More...

#include <mlImageFormat.h>

Public Member Functions

Construction/Destruction
 MLImageFormat (const std::string &fileName="")
 Constructor which stores the name of the file without opening the file. More...
 
 MLImageFormat (MLImageFormatAbstractFileHandle *fileHandle)
 Constructor which takes a virtual file handle of an already opened file. More...
 
virtual ~MLImageFormat ()
 Destructor, closes an eventually open file. More...
 
Properties
const std::string & getFileName () const
 Returns the fileName. More...
 
bool isOpen () const
 Returns true if file is open, false otherwise. More...
 
const PagedImagegetImageProperties () const
 Returns the current image properties if available or NULL otherwise. More...
 
const MLImageFormatInfosgetInternalInfos () const
 Returns a pointer to the private internal information of the managed file; it is subject to change. More...
 
MLImageFormatTagListgetTagList ()
 Returns the current tag list if available or an empty list otherwise. More...
 
const MLImageFormatTagListgetConstTagList () const
 Returns the current tag list if available or an empty list otherwise. More...
 
const MLImageFormatTagListgetConstUserTagList () const
 Returns the current user tags if available or an empty list otherwise. More...
 
const MLImageFormatTagListgetConstPrivateTagList () const
 Returns the current private tags or an empty list otherwise. More...
 
const MLImageFormatTagListgetConstCompressionTagList () const
 Returns the current compression properties if available or en empty list otherwise. More...
 
bool arePartialPagesEnabled () const
 Returns true if saving of partial pages is allowed, otherwise it returns false. More...
 
void enablePartialPages (bool enable)
 Enables saving with partial pages if true is passed, otherwise it is set to false (which then maintains readability by older readers of version 000.000.000). More...
 
Operations on file
MLErrorCode open (bool truncate=false, const std::string &compressorName="", const MLImageFormatTagList &compressionArgs=MLImageFormatTagList::getDefaultEmptyTagList(), const MLImageFormatTagList &userTagList=MLImageFormatTagList::getDefaultEmptyTagList(), const MLImageFormatTagList &privateTagList=MLImageFormatTagList::getDefaultEmptyTagList(), const std::string &defaultVoxelVal="0", bool rewritable=true, bool suppressReadCheckSumTests=false)
 Opens the file for reading and writing. More...
 
MLErrorCode openForReading (bool suppressReadCheckSumTests=false)
 Convenience method to opens files only for reading. More...
 
MLErrorCode save (PagedImage &inImg, const SubImageBox &box=SubImageBox(), const ScaleShiftData &scaleShiftData=ScaleShiftData(), bool onlyCreate=false)
 Save the specified region of the paged image in the file and fill all other regions with the value given by ML_DEFAULT_VOXEL_TAG. More...
 
MLErrorCode overwrite (PagedImage &inImg, const SubImageBox &box=SubImageBox(), const ScaleShiftData &scaleShiftData=ScaleShiftData())
 Save the specified region of the paged image in the file and leave all regions outside box unchanged. More...
 
MLErrorCode overwrite (const SubImage &inputSubImg, const ScaleShiftData &scaleShiftData=ScaleShiftData())
 Save the specified region of the paged image in the file and leave all regions outside box unchanged. More...
 
MLErrorCode updateMinMaxTagValuesInOpenFile (MLdouble newMinVoxelValue, MLdouble newMaxVoxelValue, std::string *errorDescription=nullptr)
 Save the file header information a second time over the already written file and replace the min/max voxel value tags by the values given in newMinVoxelValue and newMaxVoxelValue. More...
 
MLErrorCode close ()
 Closes an open file, closing a non open file causes the return of an error. More...
 
MLErrorCode remove ()
 Closes the file if still not done and removes it from disk. More...
 
MLErrorCode getTile (SubImage &subImgToFill, bool useFileDataType=false, bool useFileRegion=false, const ScaleShiftData &scaleShiftData=ScaleShiftData())
 Loads a subimage from the specified file and returns an MLErrorCode describing success or failure. More...
 
void setCallback (MLImageFormatTools::MLImageFormatNotifyCB *callback=nullptr, void *userData=nullptr)
 Sets a callback function to be called before/after each save of a page. More...
 
MLImageFormatTools::MLImageFormatNotifyCBgetCallbackFunction () const
 Returns the currently set callback function, default is NULL. More...
 
void * getCallbackFunctionData () const
 Returns the currently set user data for the callback function, default is NULL. More...
 
Time measurements
MLdouble getDataPreparationTime () const
 Time needed for data preparation for the recent save or overwrite operation in seconds, that is for example data reordering and compression, but not for saving; default is 0. More...
 
MLdouble getPureSaveTime () const
 Time needed for the recent save or overwrite operation in seconds, however without data preparation; defaut is 0. More...
 
void resetTimeMeasurements ()
 Resets recent time measurements to 0. More...
 

Static Public Member Functions

static std::string buildFileNameWithExtension (std::string fileName)
 Assures that the passed filename has the extension ".mlimage" and appends it automatically if not. More...
 

Protected Member Functions

MLErrorCode _overwriteHeaderAndPageList ()
 Save the file header information a second time over the already written file. More...
 

Detailed Description

File format class to store, load, and modify a PagedImage in a file.

Definition at line 36 of file mlImageFormat.h.

Constructor & Destructor Documentation

◆ MLImageFormat() [1/2]

ml::MLImageFormat::MLImageFormat ( const std::string &  fileName = "")

Constructor which stores the name of the file without opening the file.

◆ MLImageFormat() [2/2]

ml::MLImageFormat::MLImageFormat ( MLImageFormatAbstractFileHandle fileHandle)

Constructor which takes a virtual file handle of an already opened file.

The ownership of the fileHandle is passed to the MLImageFormat, so it will be closed and deleted when MLImageFormat is closed or deleted.

◆ ~MLImageFormat()

virtual ml::MLImageFormat::~MLImageFormat ( )
virtual

Destructor, closes an eventually open file.

Member Function Documentation

◆ _overwriteHeaderAndPageList()

MLErrorCode ml::MLImageFormat::_overwriteHeaderAndPageList ( )
protected

Save the file header information a second time over the already written file.

It requires that the file is already written (for example with save()) and that the file is open. It allows an update of already written tags, for example after correcting the minimum or maximum voxel values or other image properties. WARNING, IMPORTANT: It is only possible to overwrite the tag list correctly if its binary size is unchanged and page properties and indexes remain consistent. It is left to the caller to guarantee this consistency. So use this method with care!

Returns
ML_RESULT_OK on success or another code in case of failure.

◆ arePartialPagesEnabled()

bool ml::MLImageFormat::arePartialPagesEnabled ( ) const

Returns true if saving of partial pages is allowed, otherwise it returns false.

◆ buildFileNameWithExtension()

static std::string ml::MLImageFormat::buildFileNameWithExtension ( std::string  fileName)
static

Assures that the passed filename has the extension ".mlimage" and appends it automatically if not.

Empty or invalid file names will return an empty string. (Note: Still supports legacy filename extension ".mif")

◆ close()

MLErrorCode ml::MLImageFormat::close ( )

Closes an open file, closing a non open file causes the return of an error.

Returns
ML_RESULT_OK on success or another code describing the nature of the error.

◆ enablePartialPages()

void ml::MLImageFormat::enablePartialPages ( bool  enable)

Enables saving with partial pages if true is passed, otherwise it is set to false (which then maintains readability by older readers of version 000.000.000).

◆ getCallbackFunction()

MLImageFormatTools::MLImageFormatNotifyCB* ml::MLImageFormat::getCallbackFunction ( ) const

Returns the currently set callback function, default is NULL.

◆ getCallbackFunctionData()

void* ml::MLImageFormat::getCallbackFunctionData ( ) const

Returns the currently set user data for the callback function, default is NULL.

◆ getConstCompressionTagList()

const MLImageFormatTagList& ml::MLImageFormat::getConstCompressionTagList ( ) const

Returns the current compression properties if available or en empty list otherwise.

◆ getConstPrivateTagList()

const MLImageFormatTagList& ml::MLImageFormat::getConstPrivateTagList ( ) const

Returns the current private tags or an empty list otherwise.

◆ getConstTagList()

const MLImageFormatTagList& ml::MLImageFormat::getConstTagList ( ) const

Returns the current tag list if available or an empty list otherwise.

◆ getConstUserTagList()

const MLImageFormatTagList& ml::MLImageFormat::getConstUserTagList ( ) const

Returns the current user tags if available or an empty list otherwise.

◆ getDataPreparationTime()

MLdouble ml::MLImageFormat::getDataPreparationTime ( ) const

Time needed for data preparation for the recent save or overwrite operation in seconds, that is for example data reordering and compression, but not for saving; default is 0.

◆ getFileName()

const std::string& ml::MLImageFormat::getFileName ( ) const

Returns the fileName.

Returns an empty string if only a file handle was given to the constructor.

◆ getImageProperties()

const PagedImage* ml::MLImageFormat::getImageProperties ( ) const

Returns the current image properties if available or NULL otherwise.

◆ getInternalInfos()

const MLImageFormatInfos* ml::MLImageFormat::getInternalInfos ( ) const

Returns a pointer to the private internal information of the managed file; it is subject to change.

◆ getPureSaveTime()

MLdouble ml::MLImageFormat::getPureSaveTime ( ) const

Time needed for the recent save or overwrite operation in seconds, however without data preparation; defaut is 0.

◆ getTagList()

MLImageFormatTagList& ml::MLImageFormat::getTagList ( )

Returns the current tag list if available or an empty list otherwise.

Take care when modifying the tag list, because the consistency with the written data must not be endangered.

◆ getTile()

MLErrorCode ml::MLImageFormat::getTile ( SubImage subImgToFill,
bool  useFileDataType = false,
bool  useFileRegion = false,
const ScaleShiftData scaleShiftData = ScaleShiftData() 
)

Loads a subimage from the specified file and returns an MLErrorCode describing success or failure.

Previous settings or contents of the subimage are overwritten. Subimage memory will be (re)allocated if its pointer is NULL or if memory denoted by box and data type is too small, otherwise memory will be reused.

Parameters
subImgToFillThe subimage to manage the loaded data.
useFileDataTypeIf true then the data type of the stored file is used; if false the data type of subImgToFill is used. Default is to use the data type of the subimage.
useFileRegionIf true then the extent of the file is loaded as tile and the subImgToFill box is overwritten; if false the region of subImgToFill is used. Default is to use the region of the subimage.
scaleShiftDataSpecifies scale factor and offset for loaded data. If not passed the data will not be rescaled.
Returns
An MLErrorCode describing the success or failure of the operation and ML_RESULT_OK on success.

Note that this routine will use subImgToFill.free() and subImgToFill.allocate() to (re)allocate the data if its size is not enough. Be sure that eventually set subimage data was also allocated with subImgToFill.allocate() or MLAllocateMemory (and not with new or so) to avoid collisions of memory managers.

◆ isOpen()

bool ml::MLImageFormat::isOpen ( ) const

Returns true if file is open, false otherwise.

◆ open()

MLErrorCode ml::MLImageFormat::open ( bool  truncate = false,
const std::string &  compressorName = "",
const MLImageFormatTagList compressionArgs = MLImageFormatTagList::getDefaultEmptyTagList(),
const MLImageFormatTagList userTagList = MLImageFormatTagList::getDefaultEmptyTagList(),
const MLImageFormatTagList privateTagList = MLImageFormatTagList::getDefaultEmptyTagList(),
const std::string &  defaultVoxelVal = "0",
bool  rewritable = true,
bool  suppressReadCheckSumTests = false 
)

Opens the file for reading and writing.

Parameters
truncateif true the file is truncated or newly created when opened, that means an existing file will emptied and a non existing one will be created. If false the file will be opened and all file information will be read from header.
compressorNamename of DataCompressor used for data compression if not "" (the default).
compressionArgsParameters for the data compressor to be used for data compression in case of write operations and if truncate is true. Default is MLImageFormatTools::getDefaultEmptyTagList().
userTagListTags list with user defined tag values. Default is MLImageFormatTools::getDefaultEmptyTagList().
privateTagListList of private tags. Default is MLImageFormatTools::getDefaultEmptyTagList().
defaultVoxelValThe string representation of the voxel value used for regions which are not written in case of write operations and if truncate is true.
rewritableIf truncate is false then this flag decides whether the file is opened as read only or as a rewritable file. Default is true which means that opening is done in read-write mode. This flag is ignored if truncate is true.
suppressReadCheckSumTestsIf true then checksum tests are disabled while reading page data to gain maximum load performance; the default is off, because this is not recommended. Not allowed if the file is created or modified.
Returns
ML_RESULT_OK on success or another code in case of failure. If the file is already open the call does nothing.

◆ openForReading()

MLErrorCode ml::MLImageFormat::openForReading ( bool  suppressReadCheckSumTests = false)

Convenience method to opens files only for reading.

If the file is already open the call does nothing. This function does the same as open with default parameters and rewritable = false.

Parameters
suppressReadCheckSumTestsIf true then checksum tests are disabled while reading page data to gain maximum load performance; the default is off, because this is not recommended.
Returns
ML_RESULT_OK on success or another code in case of failure.

◆ overwrite() [1/2]

MLErrorCode ml::MLImageFormat::overwrite ( const SubImage inputSubImg,
const ScaleShiftData scaleShiftData = ScaleShiftData() 
)

Save the specified region of the paged image in the file and leave all regions outside box unchanged.

May be called only on files already written with save(). Requires that the has been opened with open().

Parameters
inputSubImgis the ML subimage which shall overwrite the corresponding area in the file.
scaleShiftDataSpecifies scale factor and offset for loaded data. If not passed the data will not be rescaled.
Returns
ML_RESULT_OK on success or another code in case of failure.

◆ overwrite() [2/2]

MLErrorCode ml::MLImageFormat::overwrite ( PagedImage inImg,
const SubImageBox box = SubImageBox(),
const ScaleShiftData scaleShiftData = ScaleShiftData() 
)

Save the specified region of the paged image in the file and leave all regions outside box unchanged.

May be called only on files already written with save(). Requires that the has been opened with open().

Parameters
inImgis the paged image whose contents shall be stored in the file.
boxOnly regions overlapping with box are written into the file. It defaults to the empty box. An empty box means that the whole image is to be stored.
scaleShiftDataSpecifies scale factor and offset for loaded data. If not passed the data will not be rescaled.
Returns
ML_RESULT_OK on success or another code in case of failure.

◆ remove()

MLErrorCode ml::MLImageFormat::remove ( )

Closes the file if still not done and removes it from disk.

Only works if a fileName was given in the constructor.

Returns
ML_RESULT_OK on success or another code describing the nature of the error.

◆ resetTimeMeasurements()

void ml::MLImageFormat::resetTimeMeasurements ( )

Resets recent time measurements to 0.

◆ save()

MLErrorCode ml::MLImageFormat::save ( PagedImage inImg,
const SubImageBox box = SubImageBox(),
const ScaleShiftData scaleShiftData = ScaleShiftData(),
bool  onlyCreate = false 
)

Save the specified region of the paged image in the file and fill all other regions with the value given by ML_DEFAULT_VOXEL_TAG.

Requires that the has been opened with open() and with rewritable=true.

Parameters
inImgis the paged image whose contents shall be stored in the file.
boxOnly pages overlapping with box are written into the file. It defaults to the empty box. An empty box means that the whole image is to be stored.
scaleShiftDataSpecifies scale factor and offset for loaded data. If not passed the data will not be rescaled.
onlyCreateIf false then the input data is saved normally, it true then the voxel value at position (0,0,0,0,0,0) is taken as default background value for the entire volume.
Returns
ML_RESULT_OK on success or another code in case of failure. Notes: Pages and areas not written to the file, because they do not overlap or are not inside box, are reloaded with the value given by the tag value ML_DEFAULT_VOXEL_TAG.

◆ setCallback()

void ml::MLImageFormat::setCallback ( MLImageFormatTools::MLImageFormatNotifyCB callback = nullptr,
void *  userData = nullptr 
)

Sets a callback function to be called before/after each save of a page.

Only one callback can be set; if callback is NULL the callback is reset. Default is NULL for both arguments.

Parameters
callbackPointer to the function to be called during the file write process, later possible also on other processing steps. May be NULL if not used.
userDataPointer passed to each call of callback which provides application data, typically an object pointer or so. May be NULL if not needed.

◆ updateMinMaxTagValuesInOpenFile()

MLErrorCode ml::MLImageFormat::updateMinMaxTagValuesInOpenFile ( MLdouble  newMinVoxelValue,
MLdouble  newMaxVoxelValue,
std::string *  errorDescription = nullptr 
)

Save the file header information a second time over the already written file and replace the min/max voxel value tags by the values given in newMinVoxelValue and newMaxVoxelValue.

This call requires that the file is already written, that the file is open for writing and that a size compensation tag is somewhere in the tag list whose size can be changed if tags of the min/max voxel values change. If the tag is not available or too small to compensate tag list size changed an error is returned and the tag list is not overwritten.

Parameters
newMinVoxelValueThe new minVoxelValue to be stored in the tag list which is written into the file.
newMaxVoxelValueThe new maxVoxelValue to be stored in the tag list which is written into the file.
errorDescriptionIf passed as NULL pointer then the argument is ignored, otherwise it is set to a string describing the result state of the function; default is NULL.
Returns
ML_RESULT_OK on success or an error code describing the nature of the error.

The documentation for this class was generated from the following file: