Main interface class to access functional groups from DICOM Enhanced objects. More...

Classes
struct	ThreadedFGReader
	Threaded functional group reader, used to read per-frame functional groups in parallel. More...

struct	ThreadedFGWriter
	Threaded functional group writer, used to write per-frame functional groups in parallel. More...

Public Types
typedef OFMap< Uint32, FunctionalGroups * >	PerFrameGroups
	Type representing per-frame functional groups, i.e. a number of functional groups assigned to each frame.

typedef FunctionalGroups::iterator	iterator
	Iterator type for iterating over functional groups.

typedef FunctionalGroups::const_iterator	const_iterator
	Const iterator type for iterating over functional groups.

Public Member Functions
	FGInterface ()
	Constructor, constructs empty sets of per-frame and shared functional groups.

virtual	~FGInterface ()
	Virtual destructor, frees memory.

virtual void	clear ()
	Delete all functional groups (shared and per-frame)

virtual OFBool	check ()
	Checks the functional groups for consistency. More...

virtual size_t	getNumberOfFrames ()
	Returns number of frames. More...

virtual OFCondition	read (DcmItem &dataset)
	Read enhanced multi-frame information from DICOM item, usually DcmDataset, i.e. must contain Shared and Per-frame Functional Group Sequences. More...

virtual OFCondition	write (DcmItem &dataset)
	Write enhanced multi-frame information to DICOM item, usually DcmDataset, i.e. writes Shared and Per-frame Functional Group Sequences. More...

virtual FGBase *	get (const Uint32 frameNo, const DcmFGTypes::E_FGType fgType)
	Get specific functional group for a frame, no matter whether it is stored per frame or shared. More...

virtual FGBase *	get (const Uint32 frameNo, const DcmFGTypes::E_FGType fgType, OFBool &isPerFrame)
	Get specific functional group for a frame, no matter whether it is stored per frame or shared. More...

const FunctionalGroups *	getPerFrame (const Uint32 frameNo) const
	Return all per-frame functional groups, e.g. to iterate over them. More...

const FunctionalGroups *	getShared () const
	Return all shared functional groups, e.g. to iterate over them. More...

virtual OFCondition	addShared (const FGBase &group)
	Add functional group that should be shared for all frames. More...

virtual OFCondition	addPerFrame (const Uint32 frameNo, const FGBase &group)
	Add functional group for given frame. More...

virtual OFBool	deleteShared (const DcmFGTypes::E_FGType fgType)
	Deletes a shared functional group of the given type. More...

virtual OFBool	deletePerFrame (const Uint32 frameNo, const DcmFGTypes::E_FGType fgType)
	Deletes per-frame functional group of the given type for a specific frame. More...

size_t	deletePerFrame (const DcmFGTypes::E_FGType fgType)
	Deletes per-frame functional group for all frames. More...

size_t	deleteFrame (const Uint32 frameNo)
	Deletes all functional groups for a specific frame. More...

virtual void	setCheckOnWrite (const OFBool doCheck)
	If enabled, functional group structure is checked before actual writing is performed in the write() method. More...

virtual OFBool	getCheckOnWrite ()
	Returns whether functional group structure is checked before actual writing is performed in the write() method. More...

virtual void	setUseThreads (const Uint32 numThreads)
	Sets the maximum number of threads to be used for reading and writing per-frame functional groups. More...

virtual Uint32	getUseThreads () const
	Returns the number of threads to be used for writing per-frame functional groups. More...

Protected Member Functions
virtual FGBase *	getShared (const DcmFGTypes::E_FGType fgType)
	Get shared functional group based on its type. More...

virtual OFCondition	insertShared (FGBase *group, const OFBool replaceExisting=OFTrue)
	Insert shared functional group. More...

virtual FGBase *	getPerFrame (const Uint32 frameNo, const DcmFGTypes::E_FGType fgType)
	Get per-frame functional group. More...

virtual OFCondition	insertPerFrame (const Uint32 frameNo, FGBase *group, const OFBool replaceExisting=OFTrue)
	Insert per-frame functional group. More...

virtual FunctionalGroups *	getOrCreatePerFrameGroups (const Uint32 frameNo)
	Get existing per-frame group or create it for the given frame. More...

virtual OFCondition	readSharedFG (DcmItem &dataset)
	Read Shared Functional Group Sequence from given item. More...

virtual OFCondition	readPerFrameFG (DcmItem &dataset)
	Read Per-Frame Functional Group Sequence from given item. More...

virtual OFCondition	writeSharedFG (DcmItem &dataset)
	Write Shared Functional Group Sequence to given item. More...

virtual OFCondition	writePerFrameFG (DcmItem &dataset)
	Write Per-Frame Functional Group Sequence to given item. More...

virtual OFCondition	writePerFrameFGParallel (DcmItem &dataset, const Uint32 numThreads)
	Write Per-Frame Functional Group Sequence to given item in parallel. More...

virtual OFCondition	writePerFrameFGSequential (DcmItem &dataset)
	Write Per-Frame Functional Group Sequence to given item in sequential mode, i.e. no extra threads are used. More...

virtual OFCondition	convertSharedToPerFrame (const DcmFGTypes::E_FGType fgType)
	Convert a shared functional group to a per-frame one by copying the shared one into a per-frame one for each frame and deleting the shared one afterwards. More...

virtual Uint32	findAdequateNumberOfThreads (const Uint32 numFrames, const Uint32 userThreadSetting)
	Find an adequate number of threads to use for reading and writing per-frame functional groups. More...

Static Protected Member Functions
static OFCondition	readSingleFG (DcmItem &fgItem, FunctionalGroups &groups)
	Read single functional group into the item provided. More...

Private Attributes
FunctionalGroups	m_shared
	Shared functional groups.

PerFrameGroups	m_perFrame
	Link from frame number (map key) to the list of functional groups (value) relevant for the frame.

OFBool	m_checkOnWrite
	If enabled, functional group structure is checked on write(). More...

Uint32	m_numThreads
	Maximum number of threads to use for reading and writing per-frame functional groups, default is 1 thread (sequential writing). More...

Detailed Description

Main interface class to access functional groups from DICOM Enhanced objects.

Allows reading, modifying and writing functional groups back and forth from DICOM datasets.

Member Function Documentation

◆ addPerFrame()

virtual OFCondition FGInterface::addPerFrame	(	const Uint32	frameNo,
		const FGBase &	group
	)

virtual

Add functional group for given frame.

If there is already a shared functional group with identical values, the call returns without errors, too. If there is a shared group that differs, the shared group is converted to be "per-frame" for all frames and then the given group is inserted for the frame specified by the user. If a per-frame functional group of the same type already exists it is overwritten.

Parameters

frameNo	The frame number this group should be added for (starts from 0)
group	The group to be added. The group is copied when adding, so the ownership stays with the caller, no matter what the method returns.

Returns: EC_Normal, if adding was successful, error otherwise

◆ addShared()

virtual OFCondition FGInterface::addShared ( const FGBase & group )

virtual

Add functional group that should be shared for all frames.

This will delete all per-frame groups of the same type if existing.

Parameters

group The group to be added. The group is copied.

Returns: EC_Normal, if adding was successful, error otherwise

◆ check()

virtual OFBool FGInterface::check ( )

virtual

Checks the functional groups for consistency.

The following checks are performed:

Check that every frame has a FrameContent functional group.
Check that any per-frame group is not shared at the same time.
Check for each per-frame group, that it is allowed to be per-frame.
Check for each shared group, that it is allowed to be shared.
Returns
OFTrue, if check consistency is ok, error otherwise

◆ convertSharedToPerFrame()

virtual OFCondition FGInterface::convertSharedToPerFrame ( const DcmFGTypes::E_FGType fgType )

protectedvirtual

Convert a shared functional group to a per-frame one by copying the shared one into a per-frame one for each frame and deleting the shared one afterwards.

Parameters

fgType The type of functional group to convert

Returns: EC_Normal if conversion worked out, FG_EC_NoSuchGroup if such a group does not exist and other error otherwise. In the last case the functional groups may be left in invalid state, but that should only happen for fatal errors like exhausted memory.

◆ deleteFrame()

size_t FGInterface::deleteFrame ( const Uint32 frameNo )

Deletes all functional groups for a specific frame.

Parameters

frameNo The frame number whose functional groups should be deleted. First frame is frame 0.

Returns: Number of per-frame groups deleted for this frame

◆ deletePerFrame() [1/2]

size_t FGInterface::deletePerFrame ( const DcmFGTypes::E_FGType fgType )

Deletes per-frame functional group for all frames.

Parameters

fgType The type of functional group to delete

Returns: Number of per-frame groups deleted (usually equal to number of frames)

◆ deletePerFrame() [2/2]

virtual OFBool FGInterface::deletePerFrame	(	const Uint32	frameNo,
		const DcmFGTypes::E_FGType	fgType
	)

virtual

Deletes per-frame functional group of the given type for a specific frame.

Parameters

frameNo	The frame number for the functional group of interest. First frame is frame 0.
fgType	The type of functional group to delete

Returns: OFTrue if group existed and could be deleted, OFFalse (group did not exist) otherwise

◆ deleteShared()

virtual OFBool FGInterface::deleteShared ( const DcmFGTypes::E_FGType fgType )

virtual

Deletes a shared functional group of the given type.

Parameters

fgType The type of functional group to delete

Returns: OFTrue if group existed and could be deleted, OFFalse (group did not exist) otherwise

◆ findAdequateNumberOfThreads()

virtual Uint32 FGInterface::findAdequateNumberOfThreads	(	const Uint32	numFrames,
		const Uint32	userThreadSetting
	)

protectedvirtual

Find an adequate number of threads to use for reading and writing per-frame functional groups.

The number is adjusted to the number of frames, i.e. there will be no more threads used than one fifth the number of frames (so that each thread must at least handle 5 frames, since otherwise the overhead of starting threads would be too high).

Parameters

numFrames	The number of frames to read/write
userThreadSetting	The user-defined number of threads to use

Returns: The adjusted number of threads to use

◆ get() [1/2]

virtual FGBase* FGInterface::get	(	const Uint32	frameNo,
		const DcmFGTypes::E_FGType	fgType
	)

virtual

Get specific functional group for a frame, no matter whether it is stored per frame or shared.

Parameters

frameNo	The frame number the functional group should apply to (starts with 0)
fgType	The type of functional group to look for

Returns: The functional group if found, NULL otherwise

◆ get() [2/2]

virtual FGBase* FGInterface::get	(	const Uint32	frameNo,
		const DcmFGTypes::E_FGType	fgType,
		OFBool &	isPerFrame
	)

virtual

Get specific functional group for a frame, no matter whether it is stored per frame or shared.

Parameters

frameNo	The frame number of group of interest (starts from 0)
fgType	The type of functional group to look for
isPerFrame	If OFTrue, the group found was found as per-frame, otherwise it is a shared functional group

Returns: The functional group if found, error otherwise

◆ getCheckOnWrite()

virtual OFBool FGInterface::getCheckOnWrite ( )

virtual

Returns whether functional group structure is checked before actual writing is performed in the write() method.

Returns: OFTrue if checking is performed, OFFalse otherwise

◆ getNumberOfFrames()

virtual size_t FGInterface::getNumberOfFrames ( )

virtual

Returns number of frames.

Computed by number of per-frame functional group items (i.e. the Number of Frames attribute is not taken into account).

Returns: Number of frames

Referenced by FrameSorterIdentity::sort(), and FrameSorterIPP::sort().

◆ getOrCreatePerFrameGroups()

virtual FunctionalGroups* FGInterface::getOrCreatePerFrameGroups ( const Uint32 frameNo )

protectedvirtual

Get existing per-frame group or create it for the given frame.

Note that the per-frame groups do not have to be created "in order", i.e. one could add groups in order 3,5,1 ,... .

Parameters

frameNo The frame number to get/create per-frame groups for

Returns: The functional groups if found/created, NULL in case of error

◆ getPerFrame() [1/2]

const FunctionalGroups* FGInterface::getPerFrame ( const Uint32 frameNo ) const

Return all per-frame functional groups, e.g. to iterate over them.

Parameters

frameNo The frame number of the groups of interest (starts from 0)

Returns: The per-frame functional groups for the given frame

◆ getPerFrame() [2/2]

virtual FGBase* FGInterface::getPerFrame	(	const Uint32	frameNo,
		const DcmFGTypes::E_FGType	fgType
	)

protectedvirtual

Get per-frame functional group.

Parameters

frameNo	The frame number of the group
fgType	The type of the group

Returns: The functional group or NULL if not existent

◆ getShared() [1/2]

const FunctionalGroups* FGInterface::getShared ( ) const

Return all shared functional groups, e.g. to iterate over them.

Returns: The shared functional groups

◆ getShared() [2/2]

virtual FGBase* FGInterface::getShared ( const DcmFGTypes::E_FGType fgType )

protectedvirtual

Get shared functional group based on its type.

Parameters

fgType The type of functional group

Returns: The functional group or NULL if not existent

◆ getUseThreads()

virtual Uint32 FGInterface::getUseThreads ( ) const

virtual

Returns the number of threads to be used for writing per-frame functional groups.

Returns: The number of threads to use

◆ insertPerFrame()

virtual OFCondition FGInterface::insertPerFrame	(	const Uint32	frameNo,
		FGBase *	group,
		const OFBool	replaceExisting = `OFTrue`
	)

protectedvirtual

Insert per-frame functional group.

Parameters

frameNo	The frame number the group should be added for
group	The functional group to be inserted
replaceExisting	If OFTrue, an existing per-frame functional group will be deleted, otherwise the old group is not overwritten

Returns: EC_Normal if insertion worked, FG_EC_DoubledFG if group exists and is not overwritten, other error code for other cases

◆ insertShared()

virtual OFCondition FGInterface::insertShared	(	FGBase *	group,
		const OFBool	replaceExisting = `OFTrue`
	)

protectedvirtual

Insert shared functional group.

Parameters

group	The functional group to be inserted
replaceExisting	If OFTrue, an existing shared functional group will be deleted, otherwise the old group is not overwritten

Returns: EC_Normal if insertion worked, FG_EC_DoubledFG if group exists and is not overwritten, other error code for other cases

◆ read()

virtual OFCondition FGInterface::read ( DcmItem & dataset )

virtual

Read enhanced multi-frame information from DICOM item, usually DcmDataset, i.e. must contain Shared and Per-frame Functional Group Sequences.

Parameters

dataset The item to read from

Returns: EC_Normal if reading was successful, error otherwise

◆ readPerFrameFG()

virtual OFCondition FGInterface::readPerFrameFG ( DcmItem & dataset )

protectedvirtual

Read Per-Frame Functional Group Sequence from given item.

Parameters

dataset The item to read from

Returns: EC_Normal if reading was successful, error otherwise

◆ readSharedFG()

virtual OFCondition FGInterface::readSharedFG ( DcmItem & dataset )

protectedvirtual

Read Shared Functional Group Sequence from given item.

Parameters

dataset The item to read from

Returns: EC_Normal if reading was successful, error otherwise

◆ readSingleFG()

static OFCondition FGInterface::readSingleFG	(	DcmItem &	fgItem,
		FunctionalGroups &	groups
	)

staticprotected

Read single functional group into the item provided.

Parameters

fgItem	The item to read from
groups	The resulting group after reading

Returns: EC_Normal if reading was successful, error otherwise

◆ setCheckOnWrite()

virtual void FGInterface::setCheckOnWrite ( const OFBool doCheck )

virtual

If enabled, functional group structure is checked before actual writing is performed in the write() method.

Checking might be time consuming on functional groups with many frames, though disabling might result in invalid functional group structures. Disabling should only be done if the user knows that the functional groups are valid, wants to to adapt the functional groups manually after calling write() or knows what he's doing otherwise.
Per default, checking is enabled.

Parameters

doCheck If OFTrue, checking will be performed. If OFFalse, no checks are performed.

◆ setUseThreads()

virtual void FGInterface::setUseThreads ( const Uint32 numThreads )

virtual

Sets the maximum number of threads to be used for reading and writing per-frame functional groups.

Parameters

numThreads The maximum number of threads to use The number of threads will be adjusted to the number of frames, i.e. there will be no more threads used than one fifth the number of frames (so that each thread must at least handle 10 frames, since otherwise the overhead of starting threads would be too high). The number is adjusted on the fly.

◆ write()

virtual OFCondition FGInterface::write ( DcmItem & dataset )

virtual

Write enhanced multi-frame information to DICOM item, usually DcmDataset, i.e. writes Shared and Per-frame Functional Group Sequences.

Parameters

dataset The item to write to

Returns: EC_Normal if successful, error otherwise

◆ writePerFrameFG()

virtual OFCondition FGInterface::writePerFrameFG ( DcmItem & dataset )

protectedvirtual

Write Per-Frame Functional Group Sequence to given item.

Parameters

dataset The item to write to

Returns: EC_Normal if writing was successful, error otherwise

◆ writePerFrameFGParallel()

virtual OFCondition FGInterface::writePerFrameFGParallel	(	DcmItem &	dataset,
		const Uint32	numThreads
	)

protectedvirtual

Write Per-Frame Functional Group Sequence to given item in parallel.

Parameters

dataset	The item to write to
numThreads	The maximum number of threads to use

Returns: EC_Normal if writing was successful, error otherwise

◆ writePerFrameFGSequential()

virtual OFCondition FGInterface::writePerFrameFGSequential ( DcmItem & dataset )

protectedvirtual

Write Per-Frame Functional Group Sequence to given item in sequential mode, i.e. no extra threads are used.

Parameters

dataset The item to write to

Returns: EC_Normal if writing was successful, error otherwise

◆ writeSharedFG()

virtual OFCondition FGInterface::writeSharedFG ( DcmItem & dataset )

protectedvirtual

Write Shared Functional Group Sequence to given item.

Parameters

dataset The item to write to

Returns: EC_Normal if writing was successful, error otherwise

Member Data Documentation

◆ m_checkOnWrite

OFBool FGInterface::m_checkOnWrite

private

If enabled, functional group structure is checked on write().

Otherwise, checks are skipped.

◆ m_numThreads

Uint32 FGInterface::m_numThreads

private

Maximum number of threads to use for reading and writing per-frame functional groups, default is 1 thread (sequential writing).

The number provided by the user will be adjusted to the number of frames, i.e. there will be not more threads used than one fifth the number of frames (so that each thread must at least handle number is adjusted on the fly.

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

dcmfg/include/dcmtk/dcmfg/fginterface.h

Classes

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ addPerFrame()

◆ addShared()

◆ check()

◆ convertSharedToPerFrame()

◆ deleteFrame()

◆ deletePerFrame() [1/2]

◆ deletePerFrame() [2/2]

◆ deleteShared()

◆ findAdequateNumberOfThreads()

◆ get() [1/2]

◆ get() [2/2]

◆ getCheckOnWrite()

◆ getNumberOfFrames()

◆ getOrCreatePerFrameGroups()

◆ getPerFrame() [1/2]

◆ getPerFrame() [2/2]

◆ getShared() [1/2]

◆ getShared() [2/2]

◆ getUseThreads()

◆ insertPerFrame()

◆ insertShared()

◆ read()

◆ readPerFrameFG()

◆ readSharedFG()

◆ readSingleFG()

◆ setCheckOnWrite()

◆ setUseThreads()

◆ write()

◆ writePerFrameFG()

◆ writePerFrameFGParallel()

◆ writePerFrameFGSequential()

◆ writeSharedFG()

Member Data Documentation

◆ m_checkOnWrite

◆ m_numThreads