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.
	MLImageFormat (MLImageFormatAbstractFileHandle *fileHandle)
	Constructor which takes a virtual file handle of an already opened file.
virtual	~MLImageFormat ()
	Destructor, closes an eventually open file.
Properties
const std::string &	getFileName () const
	Returns the fileName.
bool	isOpen () const
	Returns true if file is open, false otherwise.
const PagedImage *	getImageProperties () const
	Returns the current image properties if available or NULL otherwise.
const MLImageFormatInfos *	getInternalInfos () const
	Returns a pointer to the private internal information of the managed file; it is subject to change.
MLImageFormatTagList &	getTagList ()
	Returns the current tag list if available or an empty list otherwise.
const MLImageFormatTagList &	getConstTagList () const
	Returns the current tag list if available or an empty list otherwise.
const MLImageFormatTagList &	getConstUserTagList () const
	Returns the current user tags if available or an empty list otherwise.
const MLImageFormatTagList &	getConstPrivateTagList () const
	Returns the current private tags or an empty list otherwise.
const MLImageFormatTagList &	getConstCompressionTagList () const
	Returns the current compression properties if available or en empty list otherwise.
bool	arePartialPagesEnabled () const
	Returns true if saving of partial pages is allowed, otherwise it returns false.
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).
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.
MLErrorCode	openForReading (bool suppressReadCheckSumTests=false)
	Convenience method to opens files only for reading.
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.
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.
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.
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.
MLErrorCode	close ()
	Closes an open file, closing a non open file causes the return of an error.
MLErrorCode	remove ()
	Closes the file if still not done and removes it from disk.
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.
void	setCallback (MLImageFormatTools::MLImageFormatNotifyCB *callback=nullptr, void *userData=nullptr)
	Sets a callback function to be called before/after each save of a page.
MLImageFormatTools::MLImageFormatNotifyCB *	getCallbackFunction () const
	Returns the currently set callback function, default is NULL.
void *	getCallbackFunctionData () const
	Returns the currently set user data for the callback function, default is NULL.
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.
MLdouble	getPureSaveTime () const
	Time needed for the recent save or overwrite operation in seconds, however without data preparation; defaut is 0.
void	resetTimeMeasurements ()
	Resets recent time measurements to 0.

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.

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

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

subImgToFill	The subimage to manage the loaded data.
useFileDataType	If 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.
useFileRegion	If 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.
scaleShiftData	Specifies 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

truncate	if 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.
compressorName	name of DataCompressor used for data compression if not "" (the default).
compressionArgs	Parameters for the data compressor to be used for data compression in case of write operations and if truncate is true. Default is MLImageFormatTools::getDefaultEmptyTagList().
userTagList	Tags list with user defined tag values. Default is MLImageFormatTools::getDefaultEmptyTagList().
privateTagList	List of private tags. Default is MLImageFormatTools::getDefaultEmptyTagList().
defaultVoxelVal	The string representation of the voxel value used for regions which are not written in case of write operations and if truncate is true.
rewritable	If 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.
suppressReadCheckSumTests	If 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

suppressReadCheckSumTests

If 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

inputSubImg	is the ML subimage which shall overwrite the corresponding area in the file.
scaleShiftData	Specifies 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

inImg	is the paged image whose contents shall be stored in the file.
box	Only 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.
scaleShiftData	Specifies 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

inImg	is the paged image whose contents shall be stored in the file.
box	Only 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.
scaleShiftData	Specifies scale factor and offset for loaded data. If not passed the data will not be rescaled.
onlyCreate	If 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

callback	Pointer to the function to be called during the file write process, later possible also on other processing steps. May be NULL if not used.
userData	Pointer 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

newMinVoxelValue	The new minVoxelValue to be stored in the tag list which is written into the file.
newMaxVoxelValue	The new maxVoxelValue to be stored in the tag list which is written into the file.
errorDescription	If 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:

• MeVis/Foundation/Sources/MLImageFormatBase/mlImageFormat.h