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 that stores the name of the file without opening the file. More...

	MLImageFormat (MLImageFormatAbstractFileHandle *fileHandle)
	Constructor that 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 PagedImage *	getImageProperties () const
	Returns the current image properties if available or NULL otherwise. More...

const MLImageFormatInfos *	getInternalInfos () const
	Returns a pointer to the private internal information of the managed file. More...

MLImageFormatTagList &	getTagList ()
	Returns the current tag list if available or an empty list otherwise. More...

const MLImageFormatTagList &	getConstTagList () const
	Returns the current tag list if available or an empty list otherwise. More...

const MLImageFormatTagList &	getConstUserTagList () const
	Returns the current user tags if available or an empty list otherwise. More...

const MLImageFormatTagList &	getConstPrivateTagList () const
	Returns the current private tags or an empty list otherwise. More...

const MLImageFormatTagList &	getConstCompressionTagList () 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`. 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 open files only for reading. More...

MLErrorCode	save (PagedImage &inImg, const SubImageBox &box=SubImageBox(), const ScaleShiftData &scaleShiftData=ScaleShiftData(), bool onlyCreate=false)
	Saves the specified region of the paged image in the file and fills 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())
	Saves the specified region of the paged image in the file and leaves all regions outside box unchanged. More...

MLErrorCode	overwrite (const SubImage &inputSubImg, const ScaleShiftData &scaleShiftData=ScaleShiftData())
	Saves the specified region of the paged image in the file and leaves all regions outside box unchanged. More...

MLErrorCode	updateMinMaxTagValuesInOpenFile (MLdouble newMinVoxelValue, MLdouble newMaxVoxelValue, std::string *errorDescription=nullptr)
	Saves the file header information a second time over the already written file and replaces the minimum/maximum 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::MLImageFormatNotifyCB *	getCallbackFunction () 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 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 ()
	Saves 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 that stores the name of the file without opening the file.

◆ MLImageFormat() [2/2]

ml::MLImageFormat::MLImageFormat ( MLImageFormatAbstractFileHandle * fileHandle )

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

The ownership of the fileHandle is passed to the MLImageFormat; this way, 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

Saves 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. 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.

It 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 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, as consistency with the written data must not be compromised.

◆ 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 sufficient. Be sure that eventually set subimage data was also allocated with subImgToFill.allocate() or MLAllocateMemory, and not with new or similar methods, 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, as 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 open 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, as 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()`
	)

Saves the specified region of the paged image in the file and leaves all regions outside box unchanged.

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

Parameters

inputSubImg	The ML subimage that 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()`
	)

Saves the specified region of the paged image in the file and leaves all regions outside box unchanged.

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

Parameters

inImg	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`
	)

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

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

Parameters

inImg	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; if `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, as 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 that will be called during the file write process, and potentially other processing steps in the future. May be NULL if not used.
userData	Pointer passed to each call of callback that provides application data, typically an object pointer. May be NULL if not needed.

◆ updateMinMaxTagValuesInOpenFile()

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

Saves the file header information a second time over the already written file and replaces the minimum/maximum 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 minimum/maximum voxel values change. If the tag is not available or too small to compensate tag list size changes, an error is returned and the tag list is not overwritten.

Parameters

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ MLImageFormat() [1/2]

◆ MLImageFormat() [2/2]

◆ ~MLImageFormat()

Member Function Documentation

◆ _overwriteHeaderAndPageList()

◆ arePartialPagesEnabled()

◆ buildFileNameWithExtension()

◆ close()

◆ enablePartialPages()

◆ getCallbackFunction()

◆ getCallbackFunctionData()

◆ getConstCompressionTagList()

◆ getConstPrivateTagList()

◆ getConstTagList()

◆ getConstUserTagList()

◆ getDataPreparationTime()

◆ getFileName()

◆ getImageProperties()

◆ getInternalInfos()

◆ getPureSaveTime()

◆ getTagList()

◆ getTile()

◆ isOpen()

◆ open()

◆ openForReading()

◆ overwrite() [1/2]

◆ overwrite() [2/2]

◆ remove()

◆ resetTimeMeasurements()

◆ save()

◆ setCallback()

◆ updateMinMaxTagValuesInOpenFile()