DicomIoAlgorithm Class Reference

#include <ImFusion/Dicom/DicomIOAlgorithm.h>

IoAlgorithm for reading and writing DICOM files. More...

Inheritance diagram for DicomIoAlgorithm:

Detailed Description

IoAlgorithm for reading and writing DICOM files.

The specified location can be either a file/folder path or a URI of the following syntax:

• Local file system: file://path/to/file/or/folder
• PACS instance: pacs://<Hostname>:<Port>/<HostAE>?<seriesUID>
• DicomWeb instance: https://<Hostname>:<Port>/<dicomweb-endpoint>/studies/<studyUID>/series/<seriesUID>

Depending on the mode passed during construction, this algorithm operate in the following fashion:

• IoMode::Read: The algorithm will use the DicomLoader class to read DICOM data from the specified location. Multiple input locations are supported by separating each item by '##'. Furthermore, an optional filter query ?<seriesUID> can be appended in order to only load a specific series from a folder. Thus, a valid input location has the following format: <path> [?<seriesUID>] [##<path> [?<seriesUID>] ]* Alternatively, the query can also be a key-value pair with the following format: <path> [?series=<seriesUID>[&key=<value>]* ] [##<path> [?series=<seriesUID>[&key=<value>]* ] ]* Only the keys 'series', 'study', 'ignoreNonDicom' and 'recursive' are recognised. All other keys are ignored. The optional 'ignoreNonDicom' key specifies whether files without a DICOM header are ignored (defaults to true). The optional 'recursive' key determines if a <path> to a folder should be loaded recursively.
• IoMode::Write: The algorithm will use the function defined in DicomExport.h to store the SharedImageSet passed during construction to the specified location. Depending on the image type it can be stored as set of DICOM frame or (if supported) as a single Enhanced DICOM file.

This class automatically uses the DicomPlugin::defaultAuthorizationProvider for the internal DatasetCache. The provider can be changed (or removed).

Public Types
enum class	GroupingType { None = 0 , PatientId = 1 , StudyId = 2 }
Public Types inherited from IoAlgorithm
enum	IoMode { Read = 0 , Write = 1 }
enum	LocationType {   File = 1 , Folder = 2 , URI = 4 , OpenIGTLink = 8 ,   Device = 16 }
Public Types inherited from Algorithm
enum	Status {   Unknown = -1 , Success = 0 , Error = 1 , InvalidInput ,   IncompleteInput , OutOfMemoryHost , OutOfMemoryGPU , UnsupportedGPU ,   UnknownAction , AbortedByUser , User = 1000 }
	Status codes. More...

Public Member Functions
	DicomIoAlgorithm ()
	Instantiates a new DicomIOAlgorithm for reading.
	DicomIoAlgorithm (SharedImageSet *image, IoMode mode, bool writeFolder=false)
	Instantiates a new DicomIOAlgorithm with the given parameters.
	DicomIoAlgorithm (SharedImageSet *image, const std::vector< SharedImageSet * > &references, IoMode mode, bool writeFolder=false)
	Instantiates a new DicomIOAlgorithm with the given parameters.
	DicomIoAlgorithm (const std::vector< PointCloud * > rtStructs)
	DicomIoAlgorithm (const std::vector< SharedImageSet * > &images, const std::vector< SharedImageSet * > &references, IoMode mode, bool writeFolder=false)
	Instantiates a new DicomIOAlgorithm with the given parameters.
	DicomIoAlgorithm (const DataList &input, const std::vector< SharedImageSet * > &references, IoMode mode, bool writeFolder=false, std::unique_ptr< Dicom::IOD_Registry > registry=nullptr)
	~DicomIoAlgorithm () override
	Default destructor.
void	compute () override
	Executes the algorithm.
OwningDataList	takeOutput () override
	Returns the loaded DICOM data.
void	setCache (std::shared_ptr< Dicom::DatasetCache > datasetCache)
	Sets the internal dataset cache (must not be null)
std::shared_ptr< Dicom::DatasetCache >	cache () const
	Returns the internal dataset cache (never nullptr)
SharedImageSet *	inputImage () const
	The image that is getting written (nullptr if mode is Read)
void	setReferencedImages (const std::vector< SharedImageSet * > &images)
	Sets a list of images the exported DICOM files should reference.
const std::vector< SharedImageSet * > &	referencedImages () const
	Returns a list of images the exported DICOM files will reference.
void	setReferencedFiles (const std::vector< std::string > &files)
	Sets a list of DICOM files the exported DICOM files should reference.
const std::vector< std::string > &	referencedFiles () const
	Returns a list of DICOM files the exported DICOM files will reference.
Dicom::IOD_Registry &	registry ()
	Returns the registry instance used for reading and writing.
const Dicom::IOD_Registry &	registry () const
	Returns the registry instance used for reading and writing.
bool	ignoreTransform () const
	Returns the flag whether to ignore the transformation matrix during loading.
void	setIgnoreTransform (bool value)
	Sets the flag whether to ignore the transformation matrix during loading.
bool	isAutoCropSegmentationsEnabled () const
	Returns whether segmentations will be cropped during writing.
void	setAutoCropSegmentations (bool value)
	Sets whether segmentations will be cropped during writing.
Dicom::Compression	compression () const
	Sets the compression used when saving.
void	setCompression (Dicom::Compression compression)
	Returns the compression used when saving.
int	compressionQuality () const
	Sets the quality setting of lossy compressions.
void	setCompressionQuality (int quality)
	Returns the quality setting of lossy compressions.
void	setFilenameFormat (const std::string &format)
	Sets the filename format that will be used for exporting files to a folder.
const std::string &	filenameFormat () const
	Returns the current filename format.
const std::vector< std::shared_ptr< DcmDataset > > &	createDatasetsToWrite ()
void	clearDatasetsToWrite ()
void	configure (const Properties *p) override
	Configure this object instance by de-serializing the given Properties.
void	configuration (Properties *p) const override
	Serialize the current object configuration into the given Properties object.
void	registerErrorHandler (std::function< void(const Dicom::Error &)> handler)
std::vector< Dicom::Error >	caughtErrors () const
int	status () const override
	Unlike other IoAlgorithms, this algorithm can report a more detailed status.
Public Member Functions inherited from IoAlgorithm
	IoAlgorithm (IoMode ioMode, int locationType)
	Constructor for initializing IO algorithm.
virtual IoMode	ioMode () const
	Return IO mode.
virtual std::vector< std::string >	supportedFileExtensions () const
	Return supported file extensions (for file based IO)
virtual std::string	suggestedSaveFileName () const
	Return a file name suggestion typically used by IoController to prefill the file name in the save file dialog (for file based write)
virtual bool	canLoad (const Filesystem::Path &filepath) const
	Returns whether the algorithm is suitable for loading the indicated file.
virtual bool	fail (int *errorCode=nullptr) const
int	status () const override
	Indicates the status of the last call to compute().
virtual int	supportedLocations () const
	Return combination of supported location types from LocationType enum.
virtual void	setLocation (const std::string &location)
	Set location for subsequent loading/saving.
virtual std::string	location () const
	Get location for loading/saving.
void	configure (const Properties *p) override
	Set one or multiple properties.
void	configuration (Properties *p) const override
	Retrieve the properties of this object.
std::unique_ptr< Properties >	userOptions (bool includeReadOptions, bool includeWriteOptions) const
	Convenience method to retrieve all properties from this IoAlgorithm that are tagged as user options to be configured during load/save.
void	configureFromGlobalSettings ()
	Convenience method to configure the algorithm's user options with the values stored in the global settings.
Public Member Functions inherited from Algorithm
	Algorithm ()
	Default constructor will registers a single "compute" action that calls compute() and returns status().
virtual void	setProgress (Progress *progress)
	Sets a Progress interface the algorithm can use to notify observers about its computing progress.
Progress *	progress () const
	Returns the progress interface if set.
virtual bool	survivesDataDeletion (const Data *) const
	Indicates whether the algorithm can handle (partial) deletion of the specified data, by default this checks whether the data is in the input list.
const FactoryInfo &	factoryInfo () const
	Returns the record describing how this Algorithm was instantiated by the AlgorithmFactory.
void	setFactoryInfo (const FactoryInfo &value)
	Sets the record describing how this Algorithm was instantiated by the AlgorithmFactory.
Status	runAction (const std::string &id)
	Run the action with name id if it exists.
const std::vector< Action > &	actions ()
	Get a mapping from Action id to Action as registered in this algorithm.
Public Member Functions inherited from Configurable
virtual void	configureDefaults ()
	Retrieve the properties of this object, replaces values with their defaults and sets it again.
void	registerParameter (ParameterBase *param)
	Register the given Parameter or SubProperty, so that it will be configured during configure()/configuration().
void	unregisterParameter (const ParameterBase *param)
	Remove the given Parameter or SubProperty from the list of registered parameters.
	Configurable (const Configurable &rhs)
	Configurable (Configurable &&rhs) noexcept
Configurable &	operator= (const Configurable &)
Configurable &	operator= (Configurable &&) noexcept

Protected Attributes
std::unique_ptr< Impl >	m_pimpl
DataList	m_input
std::vector< SharedImageSet * >	m_referencedImages
std::vector< std::string >	m_referencedFiles
OwningDataList	m_output
const bool	m_writeFolder
std::vector< std::shared_ptr< DcmDataset > >	m_datasetsToWrite
std::shared_ptr< Dicom::DatasetCache >	m_cache
	Caches datasets between the writer and the controller.
std::shared_ptr< Dicom::IOD_Registry >	m_registry
std::unordered_map< std::string, std::unique_ptr< Dicom::DatasetHandler > >	m_datasetHandlers
Dicom::ErrorRecorder	m_errorRecorder
std::function< void(const Dicom::Error &)>	m_errorHandler
	Optional error handler.
void *	m_cacheErrorRecorderHandler = nullptr
bool	m_wasCanceled
bool	m_ignoreTransform
	Flag whether to ignore the transformation matrix during loading.
bool	m_reconstructVolume
	Flag corresponding to DicomLoader::reconstructVolumes()
bool	m_ignoreDuplicateFrames
	Flag corresponding to DicomLoader::ignoreDuplicateFrames()
Dicom::Compression	m_compression = Dicom::Compression::LittleEndianImplicit
int	m_compressionQuality = 90
std::string	m_filenameFormat = ""
bool	m_dicomSegCrop = false
	Flag whether DicomSeg drops frames without segmented data (like e.g. Slicer does)
GroupingType	m_groupIdType = GroupingType::None
Protected Attributes inherited from IoAlgorithm
std::string	m_location
IoMode	m_ioMode
int	m_locationType
bool	m_fail
Protected Attributes inherited from Algorithm
std::string	m_name
	Algorithm name.
Progress *	m_progress = nullptr
	Non-owing pointer to a progress interface. May be a nullptr.
FactoryInfo	m_factoryInfo = {}
	Record describing how this algorithm was instantiated by the AlgorithmFactory.
int	m_status = Status::Unknown
	Algorithm status after last call to compute()
std::vector< Action >	m_actions
	Map of key given by the id of the action, of the available actions of this algorithm.
Protected Attributes inherited from Configurable
std::vector< Param >	m_params
	List of all registered Parameter and SubProperty instances.

Additional Inherited Members
Static Public Member Functions inherited from IoAlgorithm
static std::unique_ptr< IoAlgorithm >	createFromLastDataSource (const DataSourceComponent &dsc)
	Virtual constructor that creates the IoAlgorithm recorded last in the DataSourceComponent.
Static Public Member Functions inherited from Algorithm
static bool	createCompatible (const DataList &data, Algorithm **a=nullptr)
	Factory function to check algorithm compatibility with input data and optionally instantiate it.
Public Attributes inherited from Algorithm
Signal	signalOutputChanged
	Signal should be emitted by Algorithms when their output/result has changed.
Signal	signalParametersChanged
	Signal should be emitted by Algorithms when their parameter configuration has changed.
Public Attributes inherited from Configurable
Signal	signalParametersChanged
	Emitted whenever one of the registered Parameters' or SubPropertys' signalValueChanged signal was emitted.
Protected Member Functions inherited from IoAlgorithm
void	recordToDataSourceComponent (Data &data, int indexInFile)
	Append the current configuration of the IoAlgorithm to the DataSourceComponent of a data.
Protected Member Functions inherited from Algorithm
void	loadDefaults ()
void	registerAction (const std::string &id, const std::string &guiName, const std::function< Algorithm::Status(void)> &action)
	Register an action to be run via runAction.
template<typename D>
void	registerAction (const std::string &id, const std::string &guiName, Algorithm::Status(D::*action)(void))
	Template version of runAction that can be used with a pointer to a member function.
void	registerAction (const Action &action)
	Register an action.

Constructor & Destructor Documentation

DicomIoAlgorithm() [1/3]

DicomIoAlgorithm	(	SharedImageSet *	image,
		IoMode	mode,
		bool	writeFolder = false )

Instantiates a new DicomIOAlgorithm with the given parameters.

Parameters

image	Image to write as DICOM. Must be 0 if mode is Read, must not be 0 if mode is Write.
mode	General mode of operation of the instantiated (read/write).
writeFolder	Only used in Write mode: Flag whether to store 3D images the image as folder with multiple files or as single enhanced DICOM file.

DicomIoAlgorithm() [2/3]

DicomIoAlgorithm	(	SharedImageSet *	image,
		const std::vector< SharedImageSet * > &	references,
		IoMode	mode,
		bool	writeFolder = false )

Instantiates a new DicomIOAlgorithm with the given parameters.

Parameters

image	Image to write as DICOM. Must be 0 if mode is Read, must not be 0 if mode is Write.
references	Images the exported DICOMs should reference after export. See Dicom::addReference for details.
mode	General mode of operation of the instantiated (read/write).
writeFolder	Only used in Write mode: Flag whether to store 3D images the image as folder with multiple files or as single enhanced DICOM file.

DicomIoAlgorithm() [3/3]

DicomIoAlgorithm	(	const std::vector< SharedImageSet * > &	images,
		const std::vector< SharedImageSet * > &	references,
		IoMode	mode,
		bool	writeFolder = false )

Instantiates a new DicomIOAlgorithm with the given parameters.

Parameters

images	Images to write as a single DICOM. Must be 0 if mode is Read, must not be 0 if mode is Write. Multiple images are only supported if all of them are of type LABEL! Otherwise only the first image is used.
references	Images the exported DICOMs should reference after export. See Dicom::addReference for details.
mode	General mode of operation of the instantiated (read/write).
writeFolder	Only used in Write mode: Flag whether to store 3D images the image as folder with multiple files or as single enhanced DICOM file.

Member Function Documentation

compute()

void compute ( )

overridevirtual

Executes the algorithm.

Implements Algorithm.

takeOutput()

OwningDataList takeOutput ( )

overridevirtual

Returns the loaded DICOM data.

Reimplemented from Algorithm.

setReferencedImages()

void setReferencedImages

(

const std::vector< SharedImageSet * > &

images

)

Sets a list of images the exported DICOM files should reference.

See Dicom::addReference for details.

setReferencedFiles()

void setReferencedFiles

(

const std::vector< std::string > &

files

)

Sets a list of DICOM files the exported DICOM files should reference.

See Dicom::addReference for details.

setAutoCropSegmentations()

void setAutoCropSegmentations

(

bool

value

)

Sets whether segmentations will be cropped during writing.

Only works in Write mode

compression()

Dicom::Compression compression

(

)

const

Sets the compression used when saving.

The default is LittleEndianImplicit (uncompressed). The compression will only be used during saving.

compressionQuality()

int compressionQuality

(

)

const

Sets the quality setting of lossy compressions.

The quality goes from 1 to 100, with 1 being the lowest quality and highest compression and 100 being the highest quality and the lowest compression. Values will be clamped to 1 and 100. Has no effect on lossless compressions.

setFilenameFormat()

void setFilenameFormat

(

const std::string &

format

)

Sets the filename format that will be used for exporting files to a folder.

See saveDatasets for details.

configure()

void configure ( const Properties * p )

overridevirtual

Configure this object instance by de-serializing the given Properties.

The default implementation will do so automatically for all registered Parameter and SubProperty instances.

See also

configuration() for the inverse functionality

Reimplemented from Configurable.

Reimplemented in DicomIOAlgorithmBrowser, and DicomIOAlgorithmFolder.

configuration()

void configuration ( Properties * p ) const

overridevirtual

Serialize the current object configuration into the given Properties object.

The default implementation will do so automatically for all registered Parameter and SubProperty instances.

See also

configure() for the inverse functionality

Reimplemented from Configurable.

Reimplemented in DicomIOAlgorithmBrowser, and DicomIOAlgorithmFolder.

status()

int status ( ) const

overridevirtual

Unlike other IoAlgorithms, this algorithm can report a more detailed status.

Reimplemented from Algorithm.

---

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

• ImFusion/Dicom/DicomIOAlgorithm.h