DCMTK Version 3.7.0 OFFIS DICOM Toolkit

dcmdata: a data encoding/decoding library and utility apps

This module contains classes to manage DICOM data structures and files. It also provides support for DICOMDIR files as required for DICOM storage media.

The main interface classes are:

- DcmFileFormat
- DcmDataset
- DcmItem
- DcmElement

Here are some further classes that are of interest:

- DcmTag
- DcmTagKey
- DicomDirInterface

# Tools

This module contains the following command line tools:

- cda2dcm: Encapsulate CDA file into DICOM file format
- dcm2cda: Extract CDA file from DICOM encapsulated CDA
- dcm2json: Convert DICOM file and data set to JSON
- dcm2pdf: Extract PDF file from DICOM encapsulated PDF
- dcm2xml: Convert DICOM file and data set to XML
- dcmconv: Convert DICOM file encoding
- dcmcrle: Encode DICOM file to RLE transfer syntax
- dcmdecap: Extract encapsulated file from DICOM encapsulated storage object
- dcmdrle: Decode RLE-compressed DICOM file
- dcmdump: Dump DICOM file and data set
- dcmencap: Encapsulate document into DICOM format
- dcmftest: Test if file uses DICOM part 10 format
- dcmgpdir: Create a general purpose DICOMDIR
- dcmodify: Modify DICOM files
- dump2dcm: Convert ASCII dump to DICOM file
- img2dcm: Convert standard image formats into DICOM format
- json2dcm: Convert JSON document to DICOM file or data set
- pdf2dcm: Encapsulate PDF file into DICOM file format
- stl2dcm: Encapsulate STL file into DICOM file format
- xml2dcm: Convert XML document to DICOM file or data set

# Files

The following file provides further documentation:

- datadict.txt file

# Examples

The following example shows how to load a DICOM file and output the patient's name:

DcmFileFormat fileformat;
OFCondition status = fileformat.loadFile("test.dcm");
if (status.good())
{
OFString patientName;
if (fileformat.getDataset()->findAndGetOFString(DCM_PatientName, patientName).good())
{
cout << "Patient's Name: " << patientName << endl;
} else
cerr << "Error: cannot access Patient's Name!" << endl;
} else
cerr << "Error: cannot read DICOM file (" << status.text() << ")" << endl;
DcmFileFormat
a class handling the DICOM file format (with meta header)
Definition: dcfilefo.h:42
DcmFileFormat::loadFile
virtual OFCondition loadFile(const OFFilename &fileName, const E_TransferSyntax readXfer=EXS_Unknown, const E_GrpLenEncoding groupLength=EGL_noChange, const Uint32 maxReadLength=DCM_MaxReadLength, const E_FileReadMode readMode=ERM_autoDetect)
load object from a DICOM file.
DcmFileFormat::getDataset
DcmDataset * getDataset()
get dataset part of the fileformat
DcmItem::findAndGetOFString
OFCondition findAndGetOFString(const DcmTagKey &tagKey, OFString &value, const unsigned long pos=0, const OFBool searchIntoSub=OFFalse)
find element and get value as a C++ string (only one component).
OFCondition
General purpose class for condition codes.
Definition: ofcond.h:177
OFCondition::text
const char * text() const
get a human readable text representation of this error code.
Definition: ofcond.h:297
OFCondition::good
OFBool good() const
check if the status is OK.
Definition: ofcond.h:313
OFString
a simple string class that implements a subset of std::string.
Definition: ofstring.h:76

The following example shows how to create a DICOM dataset and save it to a file:

char uid[100];
DcmFileFormat fileformat;
DcmDataset *dataset = fileformat.getDataset();
dataset->putAndInsertString(DCM_SOPClassUID, UID_SecondaryCaptureImageStorage);
dataset->putAndInsertString(DCM_SOPInstanceUID, dcmGenerateUniqueIdentifier(uid, SITE_INSTANCE_UID_ROOT));
dataset->putAndInsertString(DCM_PatientName, "Doe^John");
/* ... */
dataset->putAndInsertUint8Array(DCM_PixelData, pixelData, pixelLength);
OFCondition status = fileformat.saveFile("test.dcm", EXS_LittleEndianExplicit);
if (status.bad())
cerr << "Error: cannot write DICOM file (" << status.text() << ")" << endl;
DcmDataset
a class handling the DICOM dataset format (files without meta header)
Definition: dcdatset.h:42
DcmFileFormat::saveFile
virtual OFCondition saveFile(const OFFilename &fileName, const E_TransferSyntax writeXfer=EXS_Unknown, const E_EncodingType encodingType=EET_UndefinedLength, const E_GrpLenEncoding groupLength=EGL_recalcGL, const E_PaddingEncoding padEncoding=EPD_noChange, const Uint32 padLength=0, const Uint32 subPadLength=0, const E_FileWriteMode writeMode=EWM_createNewMeta)
save object to a DICOM file.
DcmItem::putAndInsertUint8Array
OFCondition putAndInsertUint8Array(const DcmTag &tag, const Uint8 *value, const unsigned long count, const OFBool replaceOld=OFTrue)
create a new element, put specified value to it and insert the element into the dataset/item.
DcmItem::putAndInsertString
OFCondition putAndInsertString(const DcmTag &tag, const char *value, const OFBool replaceOld=OFTrue)
create a new element, put specified value to it and insert the element into the dataset/item.
OFCondition::bad
OFBool bad() const
check if the status is not OK, i.e. error or failure.
Definition: ofcond.h:322
dcmGenerateUniqueIdentifier
DCMTK_DCMDATA_EXPORT char * dcmGenerateUniqueIdentifier(char *uid, const char *prefix=NULL)
creates a Unique Identifier in uid and returns uid.
SITE_INSTANCE_UID_ROOT
#define SITE_INSTANCE_UID_ROOT
UID root for SOP Instance UIDs.
Definition: dcuid.h:415
EXS_LittleEndianExplicit
@ EXS_LittleEndianExplicit
Explicit VR Little Endian.
Definition: dcxfer.h:46

The following example shows how to create a general purpose DICOMDIR from multiple files:

DicomDirInterface dicomdir;
OFCondition status = dicomdir.createNewDicomDir();
if (status.good())
{
while ( /* there are files */ )
dicomdir.addDicomFile( /* current filename */ );
status = dicomdir.writeDicomDir();
if (status.bad())
cerr << "Error: cannot write DICOMDIR (" << status.text() << ")" << endl;
} else
cerr << "Error: cannot create DICOMDIR (" << status.text() << ")" << endl;
DicomDirInterface
An interface class for simplified creation of a DICOMDIR.
Definition: dcddirif.h:108
DicomDirInterface::createNewDicomDir
OFCondition createNewDicomDir(const E_ApplicationProfile profile=AP_GeneralPurpose, const OFFilename &filename=OFFilename(DEFAULT_DICOMDIR_NAME), const OFString &filesetID=DEFAULT_FILESETID)
create a new DICOMDIR object.
DicomDirInterface::addDicomFile
OFCondition addDicomFile(const OFFilename &filename, const OFFilename &directory=OFFilename())
add specified DICOM file to the current DICOMDIR.
DicomDirInterface::writeDicomDir
OFCondition writeDicomDir(const E_EncodingType encodingType=EET_UndefinedLength, const E_GrpLenEncoding groupLength=EGL_withoutGL)
write the current DICOMDIR object to file.

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