DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Classes | Public Types | Public Member Functions | Protected Member Functions | Static Protected Member Functions | Private Attributes | List of all members
FGInterface Class Reference

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:

1. Check that every frame has a FrameContent functional group.
2. Check that any per-frame group is not shared at the same time.
3. Check for each per-frame group, that it is allowed to be per-frame.
4. 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 | ) |
| protected virtual

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
| ) |  |
| protected virtual

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 | ) |
| protected virtual

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
| ) |  |
| protected virtual

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 | ) |
| protected virtual

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`
| ) |  |
| protected virtual

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`
| ) |  |
| protected virtual

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 | ) |
| protected virtual

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 | ) |
| protected virtual

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
| ) |  |
| static protected

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 | ) |
| protected virtual

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
| ) |  |
| protected virtual

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 | ) |
| protected virtual

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 | ) |
| protected virtual

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

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1