A utility class to load and save data from/to the local file system. More...

#include <mitkIOUtil.h>

Inheritance diagram for mitk::IOUtil:

Classes
struct	LoadInfo
	Contains information about the current loading process. More...

struct	ReaderOptionsFunctorBase
	Base class for option callbacks used in load operations. More...

struct	SaveInfo
	Contains information about a save operation for a BaseData object. More...

struct	WriterOptionsFunctorBase
	Base class for option callbacks used in save operations. More...

Public Types
enum class	AppBundlePath { Parent , Self }

Static Public Member Functions
static std::string	GetProgramPath ()

static fs::path	GetAppBundlePath (AppBundlePath path=AppBundlePath::Parent)

static std::string	GetTempPath ()

static char	GetDirectorySeparator ()

static std::string	CreateTemporaryFile (std::ofstream &tmpStream, const std::string &templateName="XXXXXX", const std::string &path=std::string())

static std::string	CreateTemporaryFile (std::ofstream &tmpStream, std::ios_base::openmode mode, const std::string &templateName="XXXXXX", std::string path=std::string())

static std::string	CreateTemporaryFile (const std::string &templateName="XXXXXX", const std::string &path=std::string())

static std::string	CreateTemporaryDirectory (const std::string &templateName="XXXXXX", std::string path=std::string())

static DataStorage::SetOfObjects::Pointer	Load (const std::string &path, DataStorage &storage, const ReaderOptionsFunctorBase *optionsCallback=nullptr)
	Load a file into the given DataStorage. More...

static DataStorage::SetOfObjects::Pointer	Load (const std::string &path, const IFileReader::Options &options, DataStorage &storage)
	Load a file into the given DataStorage given user defined IFileReader::Options. More...

static std::vector< BaseData::Pointer >	Load (const std::string &path, const ReaderOptionsFunctorBase *optionsCallback=nullptr)
	Load a file and return the loaded data. More...

template<typename T >
static T::Pointer	Load (const std::string &path, const ReaderOptionsFunctorBase *optionsCallback=nullptr)
	Load a file, cast the first result to type T and return it. More...

static std::vector< BaseData::Pointer >	Load (const std::string &path, const IFileReader::Options &options)
	Load a file and return the loaded data. More...

template<typename T >
static T::Pointer	Load (const std::string &path, const IFileReader::Options &options)
	Load a file with options, cast the first result to type T and return it. More...

static DataStorage::SetOfObjects::Pointer	Load (const std::vector< std::string > &paths, DataStorage &storage, const ReaderOptionsFunctorBase *optionsCallback=nullptr)
	Loads a list of file paths into the given DataStorage. More...

static std::vector< BaseData::Pointer >	Load (const std::vector< std::string > &paths, const ReaderOptionsFunctorBase *optionsCallback=nullptr)
	Load a list of file paths and return the loaded data. More...

static std::vector< BaseData::Pointer >	Load (const us::ModuleResource &usResource, std::ios_base::openmode mode=std::ios_base::in)
	Loads the contents of a us::ModuleResource and returns the corresponding mitk::BaseData. More...

template<typename T >
static T::Pointer	Load (const us::ModuleResource &usResource, std::ios_base::openmode mode=std::ios_base::in)
	Load a module resource, cast the first result to type T and return it. More...

static BaseData::Pointer	Load (const std::string &path, const PropertyList *properties)
	Load a file with additional properties for the reader. More...

static void	Save (const mitk::BaseData *data, const std::string &path, bool setPathProperty=false)
	Save a mitk::BaseData instance. More...

static void	Save (const mitk::BaseData *data, const std::string &path, const IFileWriter::Options &options, bool setPathProperty=false)
	Save a mitk::BaseData instance. More...

static void	Save (const mitk::BaseData *data, const std::string &mimeType, const std::string &path, bool addExtension=true, bool setPathProperty=false)
	Save a mitk::BaseData instance. More...

static void	Save (const mitk::BaseData *data, const std::string &mimeType, const std::string &path, const mitk::IFileWriter::Options &options, bool addExtension=true, bool setPathProperty=false)
	Save a mitk::BaseData instance. More...

static void	Save (std::vector< SaveInfo > &saveInfos, bool setPathProperty=false)
	Use SaveInfo objects to save BaseData instances. More...

Static Protected Member Functions
static std::string	Load (std::vector< LoadInfo > &loadInfos, DataStorage::SetOfObjects nodeResult, DataStorage ds, const ReaderOptionsFunctorBase *optionsCallback)
	Internal load implementation that processes LoadInfo objects. More...

static std::string	Save (const BaseData data, const std::string &mimeType, const std::string &path, WriterOptionsFunctorBase optionsCallback, bool addExtension, bool setPathProperty)
	Internal save implementation with writer options callback. More...

static std::string	Save (std::vector< SaveInfo > &saveInfos, WriterOptionsFunctorBase *optionsCallback, bool setPathProperty)
	Internal save implementation that processes SaveInfo objects. More...

Detailed Description

A utility class to load and save data from/to the local file system.

See also: QmitkIOUtil

Definition at line 50 of file mitkIOUtil.h.

Member Enumeration Documentation

◆ AppBundlePath

enum mitk::IOUtil::AppBundlePath

strong

Enumerator
Parent
Self

Definition at line 141 of file mitkIOUtil.h.

Member Function Documentation

◆ CreateTemporaryDirectory()

static std::string mitk::IOUtil::CreateTemporaryDirectory	(	const std::string &	templateName = `"XXXXXX"`,
		std::string	path = `std::string()`
	)

static

Create a temporary directory.

This method generates a uniquely named temporary directory from templateName. The last set of six consecutive 'X' characters in templateName is replaced with a string that makes the directory name unique.

The directory is created with read, write and executable permissions for owner only.

Parameters

templateName	An optional template for the directory name.
path	An optional path where the temporary directory should be created. Defaults to the default temp path as returned by GetTempPath().

Returns: The filename of the created temporary file.

Exceptions

mitk::Exception if the temporary directory could not be created.

◆ CreateTemporaryFile() [1/3]

static std::string mitk::IOUtil::CreateTemporaryFile	(	const std::string &	templateName = `"XXXXXX"`,
		const std::string &	path = `std::string()`
	)

static

Creates an empty temporary file.

This method generates a unique temporary filename from templateName and creates this file.

The file is created with read and write permissions for owner only.

This version is potentially unsafe because the created temporary file is not kept open and could be used by another process between calling this method and opening the returned

file path for reading or writing.

Returns: The filename of the created temporary file.

Parameters

templateName	An optional template for the filename.
path	An optional path where the temporary file should be created. Defaults to the default temp path as returned by GetTempPath().

Exceptions

mitk::Exception if the temporary file could not be created.

◆ CreateTemporaryFile() [2/3]

static std::string mitk::IOUtil::CreateTemporaryFile	(	std::ofstream &	tmpStream,
		const std::string &	templateName = `"XXXXXX"`,
		const std::string &	path = `std::string()`
	)

static

Create and open a temporary file.

This method generates a unique temporary filename from templateName, creates and opens the file using the output stream tmpStream and returns the name of the newly create file.

The templateName argument must contain six consecutive 'X' characters ("XXXXXX") and these are replaced with a string that makes the filename unique.

The file is created with read and write permissions for owner only.

Parameters

tmpStream	The output stream for writing to the temporary file.
templateName	An optional template for the filename.
path	An optional path where the temporary file should be created. Defaults to the default temp path as returned by GetTempPath().

Returns: The filename of the created temporary file.

Exceptions

mitk::Exception if the temporary file could not be created.

◆ CreateTemporaryFile() [3/3]

static std::string mitk::IOUtil::CreateTemporaryFile	(	std::ofstream &	tmpStream,
		std::ios_base::openmode	mode,
		const std::string &	templateName = `"XXXXXX"`,
		std::string	path = `std::string()`
	)

static

Create and open a temporary file.

This method generates a unique temporary filename from templateName, creates and opens the file using the output stream tmpStream and the specified open mode mode and returns the name of the newly create file. The open mode is always OR'd with std::ios_base::out | std::ios_base::trunc.

The templateName argument must contain six consecutive 'X' characters ("XXXXXX") and these are replaced with a string that makes the filename unique.

The file is created with read and write permissions for owner only.

Parameters

tmpStream	The output stream for writing to the temporary file.
mode	The open mode for the temporary file stream.
templateName	An optional template for the filename.
path	An optional path where the temporary file should be created. Defaults to the default temp path as returned by GetTempPath().

Returns: The filename of the created temporary file.

Exceptions

mitk::Exception if the temporary file could not be created.

◆ GetAppBundlePath()

static fs::path mitk::IOUtil::GetAppBundlePath ( AppBundlePath path = AppBundlePath::Parent )

static

Get the file system path where the app bundle of the running executable is located on macOS.

When AppBundlePath::Self is passed, the path of the app bundle is returned instead.

On other operating systems, always the result of GetProgramPath() is returned instead.

◆ GetDirectorySeparator()

static char mitk::IOUtil::GetDirectorySeparator ( )

static

Returns the Directory Separator for the current OS.

Returns: the Directory Separator for the current OS, i.e. "\\" for Windows and "/" otherwise.

◆ GetProgramPath()

static std::string mitk::IOUtil::GetProgramPath ( )

static

Get the file system path where the running executable is located.

Returns: The location of the currently running executable, without the filename.

Referenced by mitk::RenderingTestHelper::ArgcHelperClass::ArgcHelperClass().

◆ GetTempPath()

static std::string mitk::IOUtil::GetTempPath ( )

static

Get the default temporary path without a trailing path separator.

Returns: The default path for temporary data.

◆ Load() [1/12]

static std::vector<BaseData::Pointer> mitk::IOUtil::Load	(	const std::string &	path,
		const IFileReader::Options &	options
	)

static

Load a file and return the loaded data.

This method calls Load(const std::vector<std::string>&) with a one-element vector.

Parameters

path	The absolute file name including the file extension.
options	IFileReader option instance that should be used if selected reader has options.

Returns: The set of loaded BaseData objects.

Exceptions

mitk::Exception if path could not be loaded.

See also: Load(const std::vector<std::string>&, DataStorage&)

◆ Load() [2/12]

template<typename T >

static T::Pointer mitk::IOUtil::Load	(	const std::string &	path,
		const IFileReader::Options &	options
	)

inlinestatic

Load a file with options, cast the first result to type T and return it.

Template Parameters

T	The target BaseData subclass type.

Returns: Smart pointer to the loaded object, or nullptr if the cast fails.

Definition at line 355 of file mitkIOUtil.h.

◆ Load() [3/12]

static DataStorage::SetOfObjects::Pointer mitk::IOUtil::Load	(	const std::string &	path,
		const IFileReader::Options &	options,
		DataStorage &	storage
	)

static

Load a file into the given DataStorage given user defined IFileReader::Options.

This method calls Load(const std::vector<std::string>&, DataStorage&) with a one-element vector.

Parameters

path	The absolute file name including the file extension.
options	IFileReader option instance that should be used if selected reader has options.
storage	A DataStorage object to which the loaded data will be added.

Returns: The set of added DataNode objects.

Exceptions

mitk::Exception if path could not be loaded.

See also: Load(const std::vector<std::string>&, DataStorage&)

◆ Load() [4/12]

static BaseData::Pointer mitk::IOUtil::Load	(	const std::string &	path,
		const PropertyList *	properties
	)

static

Load a file with additional properties for the reader.

Parameters

path	The absolute file name including the file extension.
properties	Properties to pass to the file reader.

Returns: The loaded BaseData object.

◆ Load() [5/12]

static std::vector<BaseData::Pointer> mitk::IOUtil::Load	(	const std::string &	path,
		const ReaderOptionsFunctorBase *	optionsCallback = `nullptr`
	)

static

Load a file and return the loaded data.

This method calls Load(const std::vector<std::string>&) with a one-element vector.

Parameters

path	The absolute file name including the file extension.
optionsCallback	Pointer to a callback instance. The callback is used by the load operation if more the suitable reader was found or the reader has options that can be set.

Returns: The set of added DataNode objects.

Exceptions

mitk::Exception if path could not be loaded.

See also: Load(const std::vector<std::string>&, DataStorage&)

◆ Load() [6/12]

template<typename T >

static T::Pointer mitk::IOUtil::Load	(	const std::string &	path,
		const ReaderOptionsFunctorBase *	optionsCallback = `nullptr`
	)

inlinestatic

Load a file, cast the first result to type T and return it.

Convenience template that calls Load(path, optionsCallback) and casts the first element of the result to the specified type.

Template Parameters

T	The target BaseData subclass type.

Returns: Smart pointer to the loaded object, or nullptr if the cast fails.

Definition at line 328 of file mitkIOUtil.h.

◆ Load() [7/12]

static DataStorage::SetOfObjects::Pointer mitk::IOUtil::Load	(	const std::string &	path,
		DataStorage &	storage,
		const ReaderOptionsFunctorBase *	optionsCallback = `nullptr`
	)

static

Load a file into the given DataStorage.

This method calls Load(const std::vector<std::string>&, DataStorage&) with a one-element vector.

Parameters

path	The absolute file name including the file extension.
storage	A DataStorage object to which the loaded data will be added.
optionsCallback	Pointer to a callback instance. The callback is used by the load operation if more the suitable reader was found or the reader has options that can be set.

Returns: The set of added DataNode objects.

Exceptions

mitk::Exception if path could not be loaded.

See also: Load(const std::vector<std::string>&, DataStorage&)

◆ Load() [8/12]

static std::vector<BaseData::Pointer> mitk::IOUtil::Load	(	const std::vector< std::string > &	paths,
		const ReaderOptionsFunctorBase *	optionsCallback = `nullptr`
	)

static

Load a list of file paths and return the loaded data.

Parameters

paths	A list of absolute file names including the file extension.
optionsCallback	Pointer to a callback instance for reader selection and options.

Returns: A vector of loaded BaseData objects.

Exceptions

mitk::Exception if an entry in paths could not be loaded.

◆ Load() [9/12]

static DataStorage::SetOfObjects::Pointer mitk::IOUtil::Load	(	const std::vector< std::string > &	paths,
		DataStorage &	storage,
		const ReaderOptionsFunctorBase *	optionsCallback = `nullptr`
	)

static

Loads a list of file paths into the given DataStorage.

If an entry in paths cannot be loaded, this method will continue to load the remaining entries into storage and throw an exception afterwards.

Parameters

paths	A list of absolute file names including the file extension.
storage	A DataStorage object to which the loaded data will be added.
optionsCallback	Pointer to a callback instance. The callback is used by the load operation if more the suitable reader was found or the reader has options that can be set.

Returns: The set of added DataNode objects.

Exceptions

mitk::Exception if an entry in paths could not be loaded.

◆ Load() [10/12]

static std::vector<BaseData::Pointer> mitk::IOUtil::Load	(	const us::ModuleResource &	usResource,
		std::ios_base::openmode	mode = `std::ios_base::in`
	)

static

Loads the contents of a us::ModuleResource and returns the corresponding mitk::BaseData.

Parameters

usResource	a ModuleResource, representing a BaseData object
mode	Optional parameter to set the openmode of the stream

Returns: The set of loaded BaseData objects. Should contain either one or zero elements, since a resource stream represents one object.

Exceptions

mitk::Exception if no reader was found for the stream.

◆ Load() [11/12]

template<typename T >

static T::Pointer mitk::IOUtil::Load	(	const us::ModuleResource &	usResource,
		std::ios_base::openmode	mode = `std::ios_base::in`
	)

inlinestatic

Load a module resource, cast the first result to type T and return it.

Template Parameters

T	The target BaseData subclass type.

Returns: Smart pointer to the loaded object, or nullptr if the cast fails.

Definition at line 405 of file mitkIOUtil.h.

◆ Load() [12/12]

static std::string mitk::IOUtil::Load	(	std::vector< LoadInfo > &	loadInfos,
		DataStorage::SetOfObjects *	nodeResult,
		DataStorage *	ds,
		const ReaderOptionsFunctorBase *	optionsCallback
	)

staticprotected

Internal load implementation that processes LoadInfo objects.

Parameters

loadInfos	Vector of LoadInfo objects describing files to load.
nodeResult	Optional pointer to receive created DataNode objects.
ds	Optional DataStorage to add loaded data to.
optionsCallback	Optional callback for reader selection and options.

Returns: Error message string (empty on success).

◆ Save() [1/7]

static std::string mitk::IOUtil::Save	(	const BaseData *	data,
		const std::string &	mimeType,
		const std::string &	path,
		WriterOptionsFunctorBase *	optionsCallback,
		bool	addExtension,
		bool	setPathProperty
	)

staticprotected

Internal save implementation with writer options callback.

Parameters

data	The data to save.
mimeType	The MIME type to use for writing.
path	The file path to save to.
optionsCallback	Optional callback for writer selection and options.
addExtension	Whether to add a file extension based on MIME type.
setPathProperty	Whether to store the file path as a property on the data.

Returns: Error message string (empty on success).

◆ Save() [2/7]

static void mitk::IOUtil::Save	(	const mitk::BaseData *	data,
		const std::string &	mimeType,
		const std::string &	path,
		bool	addExtension = `true`,
		bool	setPathProperty = `false`
	)

static

Save a mitk::BaseData instance.

Parameters

data	The data to save.
mimeType	The mime-type to use for writing `data`.
path	The path to the image including file name and an optional file extension.
addExtension	If `true`, an extension according to the given `mimeType` is added to `path` if it does not contain one. If `path` already contains a file name extension, it is not checked for compatibility with `mimeType`.
setPathProperty

Exceptions

mitk::Exception if no writer for the combination of data and mimeType is available or the writer is not able to write the image.

◆ Save() [3/7]

static void mitk::IOUtil::Save	(	const mitk::BaseData *	data,
		const std::string &	mimeType,
		const std::string &	path,
		const mitk::IFileWriter::Options &	options,
		bool	addExtension = `true`,
		bool	setPathProperty = `false`
	)

static

Save a mitk::BaseData instance.

Parameters

data	The data to save.
mimeType	The mime-type to use for writing `data`.
path	The path to the image including file name and an optional file extension.
options	Configuration data for the used IFileWriter instance.
addExtension	If `true`, an extension according to the given `mimeType` is added to `path` if it does not contain one. If `path` already contains a file name extension, it is not checked for compatibility with `mimeType`.
setPathProperty

Exceptions

mitk::Exception if no writer for the combination of data and mimeType is available or the writer is not able to write the image.

◆ Save() [4/7]

static void mitk::IOUtil::Save	(	const mitk::BaseData *	data,
		const std::string &	path,
		bool	setPathProperty = `false`
	)

static

Save a mitk::BaseData instance.

Parameters

data	The data to save.
path	The path to the image including file name and and optional file extension. If no extension is set, the default extension and mime-type for the BaseData type of `data` is used.
setPathProperty

Exceptions

mitk::Exception if no writer for data is available or the writer is not able to write the image.

◆ Save() [5/7]

static void mitk::IOUtil::Save	(	const mitk::BaseData *	data,
		const std::string &	path,
		const IFileWriter::Options &	options,
		bool	setPathProperty = `false`
	)

static

Save a mitk::BaseData instance.

Parameters

data	The data to save.
path	The path to the image including file name and an optional file extension. If no extension is set, the default extension and mime-type for the BaseData type of `data` is used.
options	The IFileWriter options to use for the selected writer.
setPathProperty

Exceptions

mitk::Exception if no writer for data is available or the writer is not able to write the image.

◆ Save() [6/7]

static void mitk::IOUtil::Save	(	std::vector< SaveInfo > &	saveInfos,
		bool	setPathProperty = `false`
	)

static

Use SaveInfo objects to save BaseData instances.

This is a low-level method for directly working with SaveInfo objects. Usually, the Save() methods taking a BaseData object as an argument are more appropriate.

Parameters

saveInfos	A list of SaveInfo objects for saving contained BaseData objects.
setPathProperty

See also: Save(const mitk::BaseData*, const std::string&)

◆ Save() [7/7]

static std::string mitk::IOUtil::Save	(	std::vector< SaveInfo > &	saveInfos,
		WriterOptionsFunctorBase *	optionsCallback,
		bool	setPathProperty
	)

staticprotected

Internal save implementation that processes SaveInfo objects.

Parameters

saveInfos	Vector of SaveInfo objects describing data to save.
optionsCallback	Optional callback for writer selection and options.
setPathProperty	Whether to store the file path as a property on the data.

Returns: Error message string (empty on success).

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

mitkIOUtil.h

Classes

Public Types

Static Public Member Functions

Static Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ AppBundlePath

Member Function Documentation

◆ CreateTemporaryDirectory()

◆ CreateTemporaryFile() [1/3]

file path for reading or writing.

◆ CreateTemporaryFile() [2/3]

◆ CreateTemporaryFile() [3/3]

◆ GetAppBundlePath()

◆ GetDirectorySeparator()

◆ GetProgramPath()

◆ GetTempPath()

◆ Load() [1/12]

◆ Load() [2/12]

◆ Load() [3/12]

◆ Load() [4/12]

◆ Load() [5/12]

◆ Load() [6/12]

◆ Load() [7/12]

◆ Load() [8/12]

◆ Load() [9/12]

◆ Load() [10/12]

◆ Load() [11/12]

◆ Load() [12/12]

◆ Save() [1/7]

◆ Save() [2/7]

◆ Save() [3/7]

◆ Save() [4/7]

◆ Save() [5/7]

◆ Save() [6/7]

◆ Save() [7/7]