DCMTK: MdfDatasetManager Class Reference

DCMTK Version 3.6.9 OFFIS DICOM Toolkit

Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | Private Member Functions | Private Attributes | List of all members
MdfDatasetManager Class Reference

This class encapsulates data structures and operations for modifying DICOM files. More...

## Public Member Functions
| MdfDatasetManager ()
| Constructor, initializes member-variables.
| ~MdfDatasetManager ()
| Destructor.
OFCondition | loadFile (const char *file_name, const E_FileReadMode readMode=ERM_autoDetect, const E_TransferSyntax xfer=EXS_Unknown, const OFBool createIfNecessary=OFFalse)
| Loads a file into dataset manager.
OFCondition | modifyOrInsertPath (OFString tag_path, const OFString &value, const OFBool only_modify, const OFBool update_metaheader=OFTrue, const OFBool ignore_missing_tags=OFFalse, const OFBool no_reservation_checks=OFFalse)
| Modifies/Inserts a path (with a specific value if desired).
OFCondition | modifyOrInsertFromFile (OFString tag_path, const OFString &filename, const OFBool only_modify, const OFBool update_metaheader=OFTrue, const OFBool ignore_missing_tags=OFFalse, const OFBool no_reservation_checks=OFFalse)
| Modifies/Inserts a path with a specific value read from file.
OFCondition | modifyAllTags (OFString tag_path, const OFString &value, const OFBool update_metaheader, int &count, const OFBool ignore_missing_tags=OFFalse)
| Modifies all matching tags in dataset to a new value.
OFCondition | deleteTag (OFString tag_path, const OFBool all_tags, const OFBool ignore_missing_tags)
| Deletes tag in dataset.
OFCondition | deletePrivateData ()
| Deletes all private data from file,\ i.e.
OFCondition | generateAndInsertUID (const DcmTagKey &uidKey)
| Inserts new Study, Series or SOP Instance UID.
OFCondition | saveFile (const char *file_name, E_TransferSyntax opt_xfer=EXS_Unknown, E_EncodingType opt_enctype=EET_UndefinedLength, E_GrpLenEncoding opt_glenc=EGL_recalcGL, E_PaddingEncoding opt_padenc=EPD_noChange, OFCmdUnsignedInt opt_filepad=0, OFCmdUnsignedInt opt_itempad=0, OFBool opt_dataset=OFFalse)
| Saves current dataset back to a file.
OFCondition | saveFile ()
| Saves current dataset back to file using original filename and original parameters like transfer syntax, padding etc.
DcmDataset * | getDataset ()
| Returns the dataset that this MdfDatasetManager handles.
DcmFileFormat * | getFileFormat ()
| Returns the DcmFileFormat that this MdfDatasetManager handles.
OFString | getFilename () const
| Returns filename of the file that is currently loaded.
void | setModifyUNValues (OFBool modifyUNValues)
| Sets whether attributes with VR of UN should be modified or left alone.

## Protected Member Functions
OFCondition | findOrCreateValidPath (DcmPathProcessor &proc, OFString tag_path, const OFString &value_or_filename, const OFBool only_modify, const OFBool ignore_missing_tags, const OFBool no_reservation_checks)
| Finds or inserts a path and performs some basic checks on the path:
OFCondition | startModify (DcmElement *elem, const OFString &value)
| modifies element to a specific value
void | deleteRelatedMetaheaderTag (const DcmTagKey &key)
| If key is the tag for SOPInstanceUID or SOPClassUID, then this function removes the related MediaStorage UIDs from the metaheader.
OFBool | isTagInDictionary (const DcmTagKey &search_key)
| Returns true, if given tag key can be found in dictionary.
OFCondition | checkPixelDataInsertion (DcmElement *elem)
| Make user user is not trying to replace encapsulated Pixel Data element value.

## Private Member Functions
MdfDatasetManager & | operator= (const MdfDatasetManager &)
| private undefined assignment operator
| MdfDatasetManager (const MdfDatasetManager &)
| private undefined copy constructor

## Private Attributes
OFString | current_file
| name of file that is currently loaded
DcmFileFormat * | dfile
| will hold file to modify
DcmDataset * | dset
| will hold the dataset that should be modified
OFBool | ignore_un_modifies
| if enabled, no value modifications on attributes having VR of UN are not executed

## Detailed Description

This class encapsulates data structures and operations for modifying DICOM files.

Therefore it allows the process of load->modify->save to provide this service.

## Member Function Documentation

## ◆ checkPixelDataInsertion()

OFCondition MdfDatasetManager::checkPixelDataInsertion | ( | DcmElement * | elem | ) |
| protected

Make user user is not trying to replace encapsulated Pixel Data element value.

This is currently not implemented since there is no direct / obvious way to insert raw data into the pixel sequence structure managed by the DcmPixelData class.

Parameters

  elem | The potential Pixel Data element to be checked

Returns
  EC_Normal if modification is possible, error code otherwise

## ◆ deletePrivateData()

OFCondition MdfDatasetManager::deletePrivateData | ( |  | ) |

Deletes all private data from file,\ i.e.

all tags having odd group numbers.

Returns
  EC_Normal, if deletion was successful; error code otherwise

## ◆ deleteRelatedMetaheaderTag()

void MdfDatasetManager::deleteRelatedMetaheaderTag | ( | const DcmTagKey & | key | ) |
| protected

If key is the tag for SOPInstanceUID or SOPClassUID, then this function removes the related MediaStorage UIDs from the metaheader.

The metaheader is then updated "automagically" when the file is saved back to disk.

Parameters

  key | tag to examine

## ◆ deleteTag()

OFCondition MdfDatasetManager::deleteTag | ( | OFString | tag_path,
|  | const OFBool | all_tags,
|  | const OFBool | ignore_missing_tags )

Deletes tag in dataset.

Parameters

  tag_path | holds complete path to tag
  all_tags | if true, tag is deleted at all levels of dataset, else only 1st level is accessed
  ignore_missing_tags | if true, tags that could not be found while modifying are handled as non-errors

Returns
  returns EC_Normal if everything is OK, else an error

## ◆ findOrCreateValidPath()

OFCondition MdfDatasetManager::findOrCreateValidPath | ( | DcmPathProcessor & | proc,
|  | OFString | tag_path,
|  | const OFString & | value_or_filename,
|  | const OFBool | only_modify,
|  | const OFBool | ignore_missing_tags,
|  | const OFBool | no_reservation_checks )
| protected

Finds or inserts a path and performs some basic checks on the path:

- If the path is a private tag, it is checked whether the private creator tag is present in the dataset. (disabled if no_reservation_checks is true).
- If the path contains tags with group numbers 0,1,2,3,5,7 or FF, an error is returned.
- If a value is defined (via file or non-empty string), it is ensured that the path does points to a leaf object (i.e. not a sequence or item).
- It is not possible to "only modify" a path that points to a non-leaf object If the path has been created or found, the path processor contains at least one valid path.

Parameters

  proc | path processor to be used
  tag_path | path to item/element
  value_or_filename | denotes new value of tag or filename to read value from. Only used to determine whether a value should be applied (not in this method) to the target element or not.
  only_modify | if true, only existing tags are processed. If false, any not existing tag is inserted
  ignore_missing_tags | if true, tags that could not be found while modifying (only_modify must be true) are handled as non-errors
  no_reservation_checks | if true, any missing private reservation tags are ignored when inserting private tags. Only makes sense w/o only_modify

Returns
  returns EC_Normal if everything is OK, else an error

## ◆ generateAndInsertUID()

OFCondition MdfDatasetManager::generateAndInsertUID | ( | const DcmTagKey & | uidKey | ) |

Inserts new Study, Series or SOP Instance UID.

If SOP Instance UID is generated, the related tag in the metaheader is deleted, too so that the new UID is also applied there when saving to disk later.

Parameters

  uidKey | [in] The Instance UID to insert (study, series or sop instance UID key permitted).

Returns
  EC_Normal, if insertion was successful, error otherwise

## ◆ getDataset()

DcmDataset * MdfDatasetManager::getDataset | ( |  | ) |

Returns the dataset that this MdfDatasetManager handles.

You should use the returned object with care to avoid side effects with other class methods that modify this object, too.

Returns
  returns the dataset, this MdfDatasetManager manages and NULL, if no dataset is loaded

## ◆ getFileFormat()

DcmFileFormat * MdfDatasetManager::getFileFormat | ( |  | ) |

Returns the DcmFileFormat that this MdfDatasetManager handles.

You should use the returned object with care to avoid side-effects with other class methods that modify this object, too.

Returns
  returns the DcmFileFormat, this MdfDatasetManager manages and NULL, if no file is loaded

## ◆ getFilename()

OFString MdfDatasetManager::getFilename | ( |  | ) | const

Returns filename of the file that is currently loaded.

Returns
  returns filename and "" if no file is loaded.

## ◆ isTagInDictionary()

OFBool MdfDatasetManager::isTagInDictionary | ( | const DcmTagKey & | search_key | ) |
| protected

Returns true, if given tag key can be found in dictionary.

Parameters

  search_key | tag to lookup

Returns
  OFTrue if tag could be found, else OFFalse

## ◆ loadFile()

OFCondition MdfDatasetManager::loadFile | ( | const char * | file_name,
|  | const E_FileReadMode | readMode = ERM_autoDetect,
|  | const E_TransferSyntax | xfer = EXS_Unknown,
|  | const OFBool | createIfNecessary = OFFalse )

Loads a file into dataset manager.

Parameters

  file_name | file to be loaded
  readMode | read file with or without metaheader. Default=autodetect
  xfer | try to read with this transfer syntax. Default=autodetect
  createIfNecessary | If true, the file is created if it does not exist

Returns
  returns EC_Normal if everything is OK, else an error

References ERM_autoDetect, and EXS_Unknown.

## ◆ modifyAllTags()

OFCondition MdfDatasetManager::modifyAllTags | ( | OFString | tag_path,
|  | const OFString & | value,
|  | const OFBool | update_metaheader,
|  | int & | count,
|  | const OFBool | ignore_missing_tags = OFFalse )

Modifies all matching tags in dataset to a new value.

Parameters

  tag_path | denotes, which tag to modify
  value | denotes new value of tag
  update_metaheader | if true, metaheader UIDs are updated, if related dataset UIDs are changed, (default=true)
  count | returns the number of tags that were affected
  ignore_missing_tags | if true, tags that could not be found while modifying are handled as non-errors

Returns
  returns EC_Normal if everything is OK, else an error

## ◆ modifyOrInsertFromFile()

OFCondition MdfDatasetManager::modifyOrInsertFromFile | ( | OFString | tag_path,
|  | const OFString & | filename,
|  | const OFBool | only_modify,
|  | const OFBool | update_metaheader = OFTrue,
|  | const OFBool | ignore_missing_tags = OFFalse,
|  | const OFBool | no_reservation_checks = OFFalse )

Modifies/Inserts a path with a specific value read from file.

Parameters

  tag_path | path to item/element
  filename | name of the file from which the value should be read
  only_modify | if true, only existing tags are processed. If false, any not existing tag is inserted
  update_metaheader | updates metaheader UIDs, if related UIDs in dataset are changed (default=true)
  ignore_missing_tags | if true, tags that could not be found while modifying (only_modify must be true) are handled as non-errors
  no_reservation_checks | if true, any missing private reservation tags are ignored when inserting private tags. Only makes sense w/o only_modify

Returns
  returns EC_Normal if everything is OK, else an error

## ◆ modifyOrInsertPath()

OFCondition MdfDatasetManager::modifyOrInsertPath | ( | OFString | tag_path,
|  | const OFString & | value,
|  | const OFBool | only_modify,
|  | const OFBool | update_metaheader = OFTrue,
|  | const OFBool | ignore_missing_tags = OFFalse,
|  | const OFBool | no_reservation_checks = OFFalse )

Modifies/Inserts a path (with a specific value if desired).

Parameters

  tag_path | path to item/element
  value | denotes new value of tag
  only_modify | if true, only existing tags are processed. If false, any not existing tag is inserted
  update_metaheader | updates metaheader UIDs, if related UIDs in dataset are changed (default=true)
  ignore_missing_tags | if true, tags that could not be found while modifying (only_modify must be true) are handled as non-errors
  no_reservation_checks | if true, any missing private reservation tags are ignored when inserting private tags. Only makes sense w/o only_modify

Returns
  returns EC_Normal if everything is OK, else an error

## ◆ saveFile() [1/2]

OFCondition MdfDatasetManager::saveFile | ( |  | ) |

Saves current dataset back to file using original filename and original parameters like transfer syntax, padding etc.

Returns
  returns EC_Normal if everything is OK, else an error

## ◆ saveFile() [2/2]

OFCondition MdfDatasetManager::saveFile | ( | const char * | file_name,
|  | E_TransferSyntax | opt_xfer = EXS_Unknown,
|  | E_EncodingType | opt_enctype = EET_UndefinedLength,
|  | E_GrpLenEncoding | opt_glenc = EGL_recalcGL,
|  | E_PaddingEncoding | opt_padenc = EPD_noChange,
|  | OFCmdUnsignedInt | opt_filepad = 0,
|  | OFCmdUnsignedInt | opt_itempad = 0,
|  | OFBool | opt_dataset = OFFalse )

Saves current dataset back to a file.

Caution: After saving MdfDatasetManager keeps working on old filename.

Parameters

  file_name | filename to save to
  opt_xfer | transfer syntax to save to (EXS_Unknown: don't change)
  opt_enctype | write with explicit or implicit length encoding
  opt_glenc | option to set group length calculation mode
  opt_padenc | sets padding option
  opt_filepad | pad file to a multiple of this options value
  opt_itempad | pad item to a multiple of this options value
  opt_dataset | if true, write only dataset, else write fileformat

Returns
  returns EC_Normal if everything is OK, else an error

References EET_UndefinedLength, EGL_recalcGL, EPD_noChange, and EXS_Unknown.

## ◆ setModifyUNValues()

void MdfDatasetManager::setModifyUNValues | ( | OFBool | modifyUNValues | ) |

Sets whether attributes with VR of UN should be modified or left alone.

Parameters

  modifyUNValues | [in] If set, UN values will be modified (default)

## ◆ startModify()

OFCondition MdfDatasetManager::startModify | ( | DcmElement * | elem,
|  | const OFString & | value )
| protected

modifies element to a specific value

Parameters

  elem | element that should be changed
  value | the value, the element should be changed to

Returns
  OFCondition, which returns an error code if an error occurs

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

- dcmdata/apps/mdfdsman.h

Generated on Wed Apr 30 2025 for DCMTK Version 3.6.9 by Doxygen 1.13.2