A collection of some tool functions loading files with modules or other backends. More...

#include <mlModuleLoaderBackendsInterface.h>

Public Member Functions
virtual	~CoreModuleLoaderBackendInterface ()
	Virtual destructor to make derived versions correctly deleted.

virtual MLErrorCode	loadWithMLImageFormat (const std::string &pageFileName, SubImage &outSubImg, const ImageVector &corrOffset, MLImageFormat **loader, bool loadFullImage=false)=0
	Reads overlapping regions of the file pageFileName into outSubImg with the MLImageFileFormat.

virtual MLErrorCode	saveAsMLImageFormat (PagedImage &imgToSave, const std::string &outFileName, const std::string &mliCompress, bool updateMinMaxAfterSave)=0
	Save the ML PagedImage given by the output of the ddiOutput as .mlimage file with the compression given in mliCompress in a file with a name composed from outFileName + ".mlimage".

virtual void	getDCMTreeFromMLImageFile (const std::string &mlImageFileName, DCMTree::Const_TreePtr &treePtr, size_t &numVols, MLErrorCode &fileLoadError, MLErrorCode &treeExtractError)=0
	Loads a Const_TreePtr from a valid .mlimage file given by the absolute file path fileName if possible.

virtual MLErrorCode	loadWithImgFileLoader (const std::string &pageFileName, SubImage &outSubImg, const ImageVector &corrOffset, MLint dcmTiffExtZ, const bool isDCMTiff, bool loadFullImage=false)=0
	Reads overlapping regions of the file pageFileName into outSubImg with the MFL interface.

virtual MLErrorCode	saveSubImgInFile (const SubImage &srcSubImg, const std::string &outFileName)=0
	Write first 2D slice from srcSubImg in the file with name outFileName.

virtual MLErrorCode	createAndSaveThumbNail (PagedImage &srcImg, const std::string &outFile, MLint ext, bool useMiddleSlice=true, bool buildNoPreviewImageOnInvalidImage=false)=0
	Create a thumbnail with extent of extX * extY pixels from the ML image given with srcImg and writes it as file with name given by outFile.

virtual MLErrorCode	loadWithMLItkImageFileReader (const std::string &pageFileName, SubImage &outSubImg, const ImageVector &corrOffset, MLDataType fileDataType, Module *loader, DCMTree::Const_TreePtr constTreePtr, bool dstIsRGB, std::string metaDataDump=nullptr, bool loadFullImage=false, size_t itkLoadDim=3, bool hideErrorPosts=false, const SubImageBox &expectedImageExtent=SubImageBox())=0
	Reads overlapping regions of the file pageFileName into outSubImg with the ML itkImageFileReader.

virtual MLErrorCode	checkOrCreateReusableModule (const std::string &dllName, const std::string &moduleName, const std::vector< std::string > &expectedFields, Module module, Module moduleToUse)=0
	If module is non nullptr then it is checked for the name moduleName and whether it contains all fields whose names are given in expectedFields.

virtual std::string	getPreferredLoader (const std::string &fileName)=0
	If it is possible to derive a preferred loader from the given fileName then the name of the loader is returned as string, otherwise an empty string is returned.

virtual MLErrorCode	loadWithHistoLoad (const std::string &fileName, SubImage &outSubImg, const ImageVector &corrOffset, Module *loaderToCreate, bool loadFullImage, PagedImage pagedImg=nullptr, MLint level=0)=0
	Reads overlapping regions of the file pageFileName into outSubImg with the ML itkImageFileReader.

virtual void	destroyMLImageFormatFileReaderInstance (MLImageFormat *&instance)=0
	No-operation call if instance is nullptr, otherwise the MLImageFormat instance will be deleted and reset to nullptr; if no backend is available which can perform the deletion then an ML_PROGRAMMING_ERROR is posted and the allocated instance will remain as memory leak.

virtual std::string	getImagePropertiesWithImgFileReader (const std::string &fileName, PagedImage &pImgProps, std::string &fileFormat)=0
	If possible then retrieve pImgProps from file fileName by using ImgFileReader::open_ImageFile and ImgFileReader::read_ImageProperties() and an empty string is returned on success, otherwise a non-empty descriptive error string is returned; note that PagedImage is not validated on successfull call, because no image data is requested.

virtual MLErrorCode	getImagePropertiesWithMLImageFormatReader (const std::string &fileName, PagedImage &pImgProps)=0
	If possible then retrieve pImgProps from file fileName by using an MLImageFormat and ML_RESULT_OK is returned on success, otherwise another MLErrorCode is returned; pImgProps is validated on successfull call.

	ML_ABSTRACT_ROOT_CLASS_HEADER (CoreModuleLoaderBackendInterface)
	Registration in the ML runtime type system, ML_ABSTRACT_ROOT_CLASS_SOURCE is in ModuleLoadersBackendsInit.cpp.

Detailed Description

A collection of some tool functions loading files with modules or other backends.

Pure virtual interface class which must be implemented to fulfill by an implementation.

Definition at line 33 of file mlModuleLoaderBackendsInterface.h.

Constructor & Destructor Documentation

◆ ~CoreModuleLoaderBackendInterface()

virtual ml::CoreModuleLoaderBackendInterface::~CoreModuleLoaderBackendInterface ( )

virtual

Virtual destructor to make derived versions correctly deleted.

Member Function Documentation

◆ checkOrCreateReusableModule()

virtual MLErrorCode ml::CoreModuleLoaderBackendInterface::checkOrCreateReusableModule	(	const std::string &	dllName,
		const std::string &	moduleName,
		const std::vector< std::string > &	expectedFields,
		Module **	module,
		Module **	moduleToUse )

pure virtual

If module is non nullptr then it is checked for the name moduleName and whether it contains all fields whose names are given in expectedFields.

If *module is nullptr then the dll given with dllName is loaded and module with moduleName is created; then it is checked checks whether the module contains fields with names specified in expectedFields. In any case a valid *module or a successfully created and checked module are returned in **moduleToUse for further use.

Parameters

dllName	Needed if module is nullptr and a module shall be created, otherwise ignored; in creation case its specifies the name of the dll to be loaded which implements containing with the module to create.
moduleName	Needed if module is nullptr and a module shall be created, otherwise ignored; in creation case its specifies the name of the module to create.
expectedFields	Fields expected in passed or created module, otherwise ML_BAD_FIELD_TYPE is returned.
module	If passed nullptr then a module is created from dll dllName and with module name moduleName; otherwise *module must be non nullptr and module must have name moduleName; if not then an error is returned.
moduleToUse	moduleToUse must be passed non-nullptr, *moduleToUse must be nullptr. A passed and/or created module instance will be created if checked for correct name and expected fields. Then module must be removed by the caller after use with MLDeleteModule from mlAPI.h to avoid memory and open file leaks. ML_RESULT_OK if a module has been passed via module or created and if all expectedFields are found in it, ML_LIBRARY_LOAD_ERROR if no backend implementation is available, and otherwise another error code.

◆ createAndSaveThumbNail()

virtual MLErrorCode ml::CoreModuleLoaderBackendInterface::createAndSaveThumbNail	(	PagedImage &	srcImg,
		const std::string &	outFile,
		MLint	ext,
		bool	useMiddleSlice = true,
		bool	buildNoPreviewImageOnInvalidImage = false )

pure virtual

Create a thumbnail with extent of extX * extY pixels from the ML image given with srcImg and writes it as file with name given by outFile.

Parameters

srcImg	The ML image providing the image the thumbnail is generated from.
outFile	The name of output file to be generated including suffix.
ext	The maximum extent of the output image to be generated.
useMiddleSlice	If true (the default) then the middle slice of the srcImg is taken to build the snapshot, otherwise the first slice is taken.
buildNoPreviewImageOnInvalidImage	If true then a "No Preview" is generated if the image is invalid, if false then no file is written and an errorCode is returned.

Returns: ML_RESULT_OK on success, ML_LIBRARY_LOAD_ERROR if no backend implementation is available, and otherwise an MLErrorCode describing the error.

◆ destroyMLImageFormatFileReaderInstance()

virtual void ml::CoreModuleLoaderBackendInterface::destroyMLImageFormatFileReaderInstance ( MLImageFormat *& instance )

pure virtual

No-operation call if instance is nullptr, otherwise the MLImageFormat instance will be deleted and reset to nullptr; if no backend is available which can perform the deletion then an ML_PROGRAMMING_ERROR is posted and the allocated instance will remain as memory leak.

◆ getDCMTreeFromMLImageFile()

virtual void ml::CoreModuleLoaderBackendInterface::getDCMTreeFromMLImageFile	(	const std::string &	mlImageFileName,
		DCMTree::Const_TreePtr &	treePtr,
		size_t &	numVols,
		MLErrorCode &	fileLoadError,
		MLErrorCode &	treeExtractError )

pure virtual

Loads a Const_TreePtr from a valid .mlimage file given by the absolute file path fileName if possible.

Parameters

mlImageFileName	The absolute file name path to the .mlimage file from which the DCMTree shall be loaded.
treePtr	Returns the loaded DCMTree on success, nullptr on failure.
numVols	Will return 1 on successful DCMTree load, otherwise 0.
fileLoadError	Return code of loading the .mlimage file.
treeExtractError	Return code from extracting the DICOM tree from .mlimage file; same code as fileLoadError if that one is not ML_RESULT_OK, ML_RESULT_OK if a tree is found, ML_ELEMENT_NOT_FOUND if noDCMTree is in it, ML_LIBRARY_LOAD_ERROR if no backend implementation is available, or otherwise an error code describing the problem.

◆ getImagePropertiesWithImgFileReader()

virtual std::string ml::CoreModuleLoaderBackendInterface::getImagePropertiesWithImgFileReader	(	const std::string &	fileName,
		PagedImage &	pImgProps,
		std::string &	fileFormat )

pure virtual

If possible then retrieve pImgProps from file fileName by using ImgFileReader::open_ImageFile and ImgFileReader::read_ImageProperties() and an empty string is returned on success, otherwise a non-empty descriptive error string is returned; note that PagedImage is not validated on successfull call, because no image data is requested.

◆ getImagePropertiesWithMLImageFormatReader()

virtual MLErrorCode ml::CoreModuleLoaderBackendInterface::getImagePropertiesWithMLImageFormatReader	(	const std::string &	fileName,
		PagedImage &	pImgProps )

pure virtual

If possible then retrieve pImgProps from file fileName by using an MLImageFormat and ML_RESULT_OK is returned on success, otherwise another MLErrorCode is returned; pImgProps is validated on successfull call.

◆ getPreferredLoader()

virtual std::string ml::CoreModuleLoaderBackendInterface::getPreferredLoader ( const std::string & fileName )

pure virtual

If it is possible to derive a preferred loader from the given fileName then the name of the loader is returned as string, otherwise an empty string is returned.

Currently only "ImgFileReader" is returned in some cases.

◆ loadWithHistoLoad()

virtual MLErrorCode ml::CoreModuleLoaderBackendInterface::loadWithHistoLoad	(	const std::string &	fileName,
		SubImage &	outSubImg,
		const ImageVector &	corrOffset,
		Module **	loaderToCreate,
		bool	loadFullImage,
		PagedImage *	pagedImg = nullptr,
		MLint	level = 0 )

pure virtual

Reads overlapping regions of the file pageFileName into outSubImg with the ML itkImageFileReader.

Parameters

outSubImg	The subimage to be filled with data from file fileName. If loadFullImage is false and outSubImage has an empty box then the file is only opened but no data is requested.
fileName	The file used as source of the data to write into outSubImg.
corrOffset	is a vector subtracted from the page location loaded the file, e.g. if multiple files are composed into the time dimension then the file position in time could be subtracted with ImageVector(0,0,0,0,tPos,0).
loaderToCreate	If non nullptr and a loader is needed for operation then it is (re)used (if necessary recreated) for loading the data, otherwise a temporary local loader is created and destroyed (which might be significantly slower when many accesses take place). If loaderToCreate is non nullptr is target will return new or potentially (re)created instances of HistoLoad which might also reference non closed files after use. Created instances must be removed by the caller after use with MLDeleteModule from mlAPI.h to avoid memory and open file leaks. If a loaderToCreate is passed which is not an ML HistoLoad then an error code is returned.
loadFullImage	If true then outSubImg.free() is called and the SubImage is reinitialized with the extents and data type of the input image and data is allocated with allocateAsMemoryBlockHandle(). If false (the default) outSubImg must be a valid subimage with correctly set data type, box, sourceImageExtent and allocated data.
pagedImg	If non-nullptr then *pagedImg will be updated to the image properties of the possibly opened image. Will only be valid if return value is ML_RESULT_OK.
level	If 0 then then the image is loaded with its normal (and exact) extents, the extent in zhe u-dimension will be 1. If -1 then at u=0 the image with its original extents is located, at u=1 with half extent, .... for all sensible down-scaled extents. If a value > 0 is specified a specific down-scaled resolution is passed to the output and u will be 0.

Returns: ML_RESULT_OK on success, ML_LIBRARY_LOAD_ERROR if no backend implementation is available, and or another error code otherwise. Empty file names are answered with ML_BAD_PARAMETER.

◆ loadWithImgFileLoader()

virtual MLErrorCode ml::CoreModuleLoaderBackendInterface::loadWithImgFileLoader	(	const std::string &	pageFileName,
		SubImage &	outSubImg,
		const ImageVector &	corrOffset,
		MLint	dcmTiffExtZ,
		const bool	isDCMTiff,
		bool	loadFullImage = false )

pure virtual

Reads overlapping regions of the file pageFileName into outSubImg with the MFL interface.

In cases of DCM/Tif files the name of the .tif file must be used, because the .dcm file does not contain image data.

Parameters

outSubImg	The subimage to be filled with data from file pageFileName.
pageFileName	The file used as source of the data to write into outSubImg.
corrOffset	is a vector subtracted from the page location loaded the file, e.g. if multiple files are composed into the time dimension then the file position in time could be subtracted with ImageVector(0,0,0,0,tPos,0).
dcmTiffExtZ	Z-Extent of the DCM/Tif-image from which the subimage is loaded; only needed for the DCM/Tiff file formats. This extent is needed to access time points in the data correctly and must be derived from private DICOM tags stored in the .dcm file corresponding to the .tif file. If a value < 1 is passed then it will be taken from the image properties of the file, however, in that case all time points will be unrolled into the z-dimension and accesses to time points > 0 will be invalid.
isDCMTiff	Must be passed as true if the file is a DCM/Tiff pair. For correct time point access dcmTiffExtZ must also be known.
loadFullImage	If true then outSubImg.free() is called and the SubImage is reinitialized with the extents and data type of the input image and data is allocated with allocateAsMemoryBlockHandle(). If false (the default) outSubImg must be a valid subimage with correctly set data type, box, sourceImageExtent and allocated data.

Returns: ML_RESULT_OK on success. ML_COULD_NOT_OPEN_FILE on opening of property reading problems, ML_LIBRARY_LOAD_ERROR if no backend implementation is available, and ML_FILE_IO_ERROR or ML_NO_MEMORY on other errors.

◆ loadWithMLImageFormat()

virtual MLErrorCode ml::CoreModuleLoaderBackendInterface::loadWithMLImageFormat	(	const std::string &	pageFileName,
		SubImage &	outSubImg,
		const ImageVector &	corrOffset,
		MLImageFormat **	loader,
		bool	loadFullImage = false )

pure virtual

Reads overlapping regions of the file pageFileName into outSubImg with the MLImageFileFormat.

Parameters

outSubImg	The subimage to be filled with data from file pageFileName.
pageFileName	The file used as source of the data to write into outSubImg.
corrOffset	is a vector subtracted from the page location loaded the file, e.g. if multiple files are composed into the time dimension then the file position in time could be subtracted with ImageVector(0,0,0,0,tPos,0).
loader	If non nullptr then it is (re)used (if necessary recreated) for loading the data, otherwise a temporary local loader is created and destroyed (which might be significantly slower on when many accesses take place). If loader is non nullptr is target will return new or potentially (re)created instances of MLImageFormatLoaders which might also reference non closed files. Those instances must be removed by the caller after use with MLDeleteModule from mlAPI.h to avoid memory and open file leaks.
loadFullImage	If true then outSubImg.free() is called and the SubImage is reinitialized with the extents and data type of the input image and data is allocated with allocateAsMemoryBlockHandle(). If false (the default) outSubImg must be a valid subimage with correctly set data type, box, sourceImageExtent and allocated data.

Returns: ML_RESULT_OK on success. ML_COULD_NOT_OPEN_FILE on opening of property reading problems, ML_LIBRARY_LOAD_ERROR if no backend implementation is available, and ML_FILE_IO_ERROR on any other error.

◆ loadWithMLItkImageFileReader()

virtual MLErrorCode ml::CoreModuleLoaderBackendInterface::loadWithMLItkImageFileReader	(	const std::string &	pageFileName,
		SubImage &	outSubImg,
		const ImageVector &	corrOffset,
		MLDataType	fileDataType,
		Module **	loader,
		DCMTree::Const_TreePtr	constTreePtr,
		bool	dstIsRGB,
		std::string *	metaDataDump = nullptr,
		bool	loadFullImage = false,
		size_t	itkLoadDim = 3,
		bool	hideErrorPosts = false,
		const SubImageBox &	expectedImageExtent = SubImageBox() )

pure virtual

Reads overlapping regions of the file pageFileName into outSubImg with the ML itkImageFileReader.

Parameters

outSubImg	The subimage to be filled with data from file pageFileName.
pageFileName	The file used as source of the data to write into outSubImg.
corrOffset	is a vector subtracted from the page location loaded the file, e.g. if multiple files are composed into the time dimension then the file position in time could be subtracted with ImageVector(0,0,0,0,tPos,0).
fileDataType	The ML data type to be used for loading the image data. If an invalid type is passed then this function tries to determine the file type automatically according to the stored file type. On color images: integer color images will automatically choose the integer type, not Vector3f, which will lead to a single channel luminosity image where color channels are converted to single luminosity integer channel image. If a normal integer scalar type is passed then this function implicitly converts the color pixels with luminosity conversions to a scalar value in a single channel. If Vector3fType is passed then this function loads the color pixels into a single channel Vector3f image.
loader	If non nullptr then it is (re)used (if necessary recreated) for loading the data, otherwise a temporary local loader is created and destroyed (which might be significantly slower on when many accesses take place). If loader is non nullptr is target will return new or potentially (re)created instances of MLImageFormatLoaders which might also reference non closed files. Those instances must be removed by the caller after use with MLDeleteModule from mlAPI.h to avoid memory and open file leaks. If a loader is passed which is not an ML itkImageFileReader then a ML_BAD_PARAMETER error is returned.
constTreePtr	If a DCMTree is passed for pageFileName then rescaleSlope/Intercept tag values (if there are any) will be unset on loaded data, because the itk reader evaluates them, but the loaded data shall not have them applied.
dstIsRGB	If the image is an RGB color image with three c channels then dstIsRGB can be set to true to indicate that color data shall be read from file and that it shall be reordered from interleaved to separated RGB into the outSubImg, where fileDataType must either be an invalid data type for automatic initialization or an integer type; MLVector3fType as fileDataType is not allowed then. For dstIsRGB = false see documentation for fileDataType.
metaDataDump	If non nullptr then *metaDataDump will be set to the meta data dump of the file or to "" if not available. Ignored if nullptr.
loadFullImage	If true then outSubImg.free() is called and the SubImage is reinitialized with the extents and data type of the input image and data is allocated with allocateAsMemoryBlockHandle(). If false (the default) outSubImg must be a valid subimage with correctly set data type, box, sourceImageExtent and allocated data.
itkLoadDim	The dimension used by the itkImageFileReader to load the image data; allowed are only 2, 3, 4, and 6.
hideErrorPosts	If true then errors from the itkImageFileReader are suppressed as far as possible regarding the post to the ML error handler; the error code of the function or other results should not be influenced; if false (the default) then error diagnostic is posted normally to the ML error handler.
expectedImageExtent	If not empty then this is the extent of the full image within outSubImg resides; this actually may differ, e.g. if the itkImageFileReader does not unroll time points into time-extent of the image but into the z-extent; by comparing the extents of the image which shall be filled with data and the extent provided by itkImageFileReader, the backend routine may try to correct this on the fly; the default (an empty box) means that no such correction is performed.

Returns: ML_RESULT_OK on success. ML_COULD_NOT_OPEN_FILE on opening of property reading problems. ML_BAD_PARAMETER if a data type conversion is not allow or not possible, ML_LIBRARY_LOAD_ERROR if no backend implementation is available, and ML_FILE_IO_ERROR on file access problems and any other MLErrorCode otherwise.

◆ ML_ABSTRACT_ROOT_CLASS_HEADER()

ml::CoreModuleLoaderBackendInterface::ML_ABSTRACT_ROOT_CLASS_HEADER ( CoreModuleLoaderBackendInterface )

Registration in the ML runtime type system, ML_ABSTRACT_ROOT_CLASS_SOURCE is in ModuleLoadersBackendsInit.cpp.

◆ saveAsMLImageFormat()

virtual MLErrorCode ml::CoreModuleLoaderBackendInterface::saveAsMLImageFormat	(	PagedImage &	imgToSave,
		const std::string &	outFileName,
		const std::string &	mliCompress,
		bool	updateMinMaxAfterSave )

pure virtual

Save the ML PagedImage given by the output of the ddiOutput as .mlimage file with the compression given in mliCompress in a file with a name composed from outFileName + ".mlimage".

Parameters

imgToSave	The PagedImage whose content is to be saved.
outFileName	The name of the .mlimage file to be written (without extension). The suffix ".mlimage" is appended automatically.
mliCompress	is the name of the compressor to be used for saving; it is used with its default settings.
updateMinMaxAfterSave	If true then the writer will update the min/max values of the written file after saving with the values from pagedImageToSave. If false then the min/max values before saving are stored in the file.

Returns: ML_RESULT_OK on success, ML_LIBRARY_LOAD_ERROR if no backend implementation is available, and an MLErrorCode describing the problem otherwise.

◆ saveSubImgInFile()

virtual MLErrorCode ml::CoreModuleLoaderBackendInterface::saveSubImgInFile	(	const SubImage &	srcSubImg,
		const std::string &	outFileName )

pure virtual

Write first 2D slice from srcSubImg in the file with name outFileName.

The extents of srcSubImg must be in 32 bit range, the number of color channels must be 1 or 3, and the voxel type must MLuint8Type. The file format is retrieved from the suffix of the file name and must be able to store the given voxel and image configuration.

Parameters

srcSubImg	The subimage whose first slice shall be written.
outFileName	The name of the file to be written.

Returns: ML_RESULT_OK on success, ML_LIBRARY_LOAD_ERROR if no backend implementation is available, and otherwise an MLErrorCode describing the problem.

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

FMEstable/ReleaseMeVis/Projects/MLModuleLoaderBackends/Sources/mlModuleLoaderBackendsInterface.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~CoreModuleLoaderBackendInterface()

Member Function Documentation

◆ checkOrCreateReusableModule()

◆ createAndSaveThumbNail()

◆ destroyMLImageFormatFileReaderInstance()

◆ getDCMTreeFromMLImageFile()

◆ getImagePropertiesWithImgFileReader()

◆ getImagePropertiesWithMLImageFormatReader()

◆ getPreferredLoader()

◆ loadWithHistoLoad()

◆ loadWithImgFileLoader()

◆ loadWithMLImageFormat()

◆ loadWithMLItkImageFileReader()

◆ ML_ABSTRACT_ROOT_CLASS_HEADER()

◆ saveAsMLImageFormat()

◆ saveSubImgInFile()