DCMTK Version 3.7.0 OFFIS DICOM Toolkit

dcmsr: a structured reporting library and utility apps

This module contains classes to read, write, create, modify, access, print and render DICOM Structured Reporting (SR) documents. The list of supported SOP classes is provided in DSRTypes::E_DocumentType.

The main interface classes are:

- DSRDocument
- DSRDocumentTree
- DSRDocumentSubTree
- DSRDocumentTreeNode
- DSRContentItem
- DSRCodedEntryValue

Here are some further classes that are useful when implementing SR templates:

- DSRBasicCodedEntry
- DSRContextGroup
- DSRRootTemplate
- DSRSubTemplate

Currently, the following SR templates are implemented (see notes for details):

- TID300_Measurement
- TID1001_ObservationContext
- TID1204_LanguageOfContentItemAndDescendants
- TID1411_VolumetricROIMeasurements
- TID1419_ROIMeasurements_Measurement
- TID1500_MeasurementReport
- TID1501_MeasurementGroup
- TID1600_ImageLibrary
- TID4019_AlgorithmIdentification

# Tools

This module contains the following command line tools:

- dsr2html: Render DICOM SR file and data set to HTML/XHTML
- dsr2xml: Convert DICOM SR file and data set to XML
- dsrdump: Dump DICOM SR file and data set
- xml2dsr: Convert XML document to DICOM SR file

# Examples

The following example shows how to load a DICOM Structured Report and render its content in HTML format:

DcmFileFormat fileformat;
OFCondition status = fileformat.loadFile("test.dcm");
if (status.good())
{
DSRDocument document;
status = document.read(*fileformat.getDataset());
if (status.good())
{
status = document.renderHTML(cout);
if (status.bad())
cerr << "Error: cannot render SR document (" << status.text() << ")" << endl;
} else
cerr << "Error: cannot read SR document (" << status.text() << ")" << endl;
} else
cerr << "Error: cannot load DICOM file (" << status.text() << ")" << endl;
DSRDocument
Interface class for 'dcmsr' (DICOM Structured Reporting Documents).
Definition: dsrdoc.h:61
DSRDocument::renderHTML
virtual OFCondition renderHTML(STD_NAMESPACE ostream &stream, const size_t flags=0, const char *styleSheet=NULL, const char *urlPrefix=NULL)
render current SR document in HTML/XHTML format.
DSRDocument::read
virtual OFCondition read(DcmItem &dataset, const size_t flags=0)
read SR document from DICOM dataset.
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
OFCondition
General purpose class for condition codes.
Definition: ofcond.h:177
OFCondition::bad
OFBool bad() const
check if the status is not OK, i.e. error or failure.
Definition: ofcond.h:322
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

The following example shows how to create a DICOM Structured Report and save it to a file (further details can be found in the mkreport source file):

DSRDocument document;
document.setPatientName("Doe^John");
/* ... */
DSRDocumentTree &tree = document.getTree();
tree.addContentItem(DSRTypes::RT_isRoot, DSRTypes::VT_Container);
tree.getCurrentContentItem().setConceptName(DSRCodedEntryValue(/* some code */));
tree.addChildContentItem(DSRTypes::RT_hasObsContext, DSRTypes::VT_Code, CODE_DCM_ObserverType);
tree.getCurrentContentItem().setCodeValue(CODE_DCM_Person);
/* ... */
DcmFileFormat fileformat;
OFCondition status = document.write(*fileformat.getDataset())
if (status.good())
{
status = fileformat.saveFile("test.dcm", EXS_LittleEndianExplicit);
if (status.bad())
cerr << "Error: cannot save DICOM file (" << status.text() << ")" << endl;
} else
cerr << "Error: cannot write SR document (" << status.text() << ")" << endl;
DSRCodedEntryValue
Class for handling coded entry values, i.e. unambiguous machine-readable codes.
Definition: dsrcodvl.h:120
DSRContentItem::setConceptName
OFCondition setConceptName(const DSRCodedEntryValue &conceptName, const OFBool check=OFTrue)
set concept name.
DSRContentItem::setCodeValue
OFCondition setCodeValue(const DSRCodedEntryValue &codeValue, const OFBool check=OFTrue)
set code value.
DSRDocumentSubTree::getCurrentContentItem
virtual DSRContentItem & getCurrentContentItem()
get reference to current content item.
DSRDocumentSubTree::addContentItem
virtual size_t addContentItem(const E_RelationshipType relationshipType, const E_ValueType valueType, const E_AddMode addMode=AM_afterCurrent)
add specified content item to the current one.
DSRDocumentSubTree::addChildContentItem
virtual OFCondition addChildContentItem(const E_RelationshipType relationshipType, const E_ValueType valueType, const DSRCodedEntryValue &conceptName, const OFBool check=OFTrue)
add specified content item below the current one.
DSRDocumentTree
Class managing the SR document tree.
Definition: dsrdoctr.h:45
DSRDocument::write
virtual OFCondition write(DcmItem &dataset, DcmStack *markedItems=NULL)
write current SR document to DICOM dataset.
DSRDocument::setPatientName
virtual OFCondition setPatientName(const OFString &value, const OFBool check=OFTrue)
set patient's name
DSRDocument::getTree
DSRDocumentTree & getTree()
get document tree
Definition: dsrdoc.h:226
DSRTypes::VT_Code
@ VT_Code
DICOM Value Type: CODE.
Definition: dsrtypes.h:593
DSRTypes::VT_Container
@ VT_Container
DICOM Value Type: CONTAINER.
Definition: dsrtypes.h:619
DSRTypes::RT_isRoot
@ RT_isRoot
internal type used for the document root
Definition: dsrtypes.h:565
DSRTypes::RT_hasObsContext
@ RT_hasObsContext
DICOM Relationship Type: HAS OBS CONTEXT.
Definition: dsrtypes.h:569
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.
EXS_LittleEndianExplicit
@ EXS_LittleEndianExplicit
Explicit VR Little Endian.
Definition: dcxfer.h:46

Alternatively, many properties of the document tree can be accessed and modified directly as the following example shows:

DSRDocument document(DSRTypes::DT_KeyObjectSelectionDocument);
/* ... */
DSRDocumentTree &tree = document.getTree();
tree.addContentItem(DSRTypes::RT_isRoot, DSRTypes::VT_Container);
DSRCodedEntryValue *codePtr = tree.getCurrentContentItem().getConceptNamePtr();
if (codePtr != NULL)
codePtr->setCode("113000", "DCM", "Of Interest");
/* ... */
tree.addContentItem(DSRTypes::RT_contains, DSRTypes::VT_Image);
DSRImageReferenceValue *imagePtr = tree.getCurrentContentItem().getImageReferencePtr();
if (imagePtr != NULL)
{
imagePtr->setValue(DSRImageReferenceValue(UID_UltrasoundMultiframeImageStorage, /* image UID */));
imagePtr->setPresentationState(DSRCompositeReferenceValue(UID_GrayscaleSoftcopyPresentationStateStorage, /* GSPS UID */));
imagePtr->getFrameList().addItem(2);
imagePtr->getFrameList().addItem(5);
}
/* ... */
DSRCodedEntryValue::setCode
OFCondition setCode(const DSRBasicCodedEntry &basicCodedEntry, const OFBool check=OFFalse)
set code.
DSRCompositeReferenceValue
Class for composite reference values.
Definition: dsrcomvl.h:46
DSRContentItem::getImageReferencePtr
DSRImageReferenceValue * getImageReferencePtr()
get pointer to image reference.
DSRContentItem::getConceptNamePtr
DSRCodedEntryValue * getConceptNamePtr()
get pointer to concept name.
DSRImageReferenceValue
Class for image reference values.
Definition: dsrimgvl.h:57
DSRImageReferenceValue::setPresentationState
OFCondition setPresentationState(const DSRCompositeReferenceValue &pstateValue, const OFBool check=OFTrue)
set reference to presentation state object.
DSRImageReferenceValue::getFrameList
DSRImageFrameList & getFrameList()
get reference to list of referenced frame numbers.
Definition: dsrimgvl.h:382
DSRImageReferenceValue::setValue
OFCondition setValue(const DSRImageReferenceValue &referenceValue, const OFBool check=OFTrue)
set image reference value.
DSRListOfItems::addItem
void addItem(const T &item)
add item to the list
Definition: dsrtlist.h:242
DSRTypes::VT_Image
@ VT_Image
DICOM Value Type: IMAGE.
Definition: dsrtypes.h:615
DSRTypes::DT_KeyObjectSelectionDocument
@ DT_KeyObjectSelectionDocument
DICOM IOD: Key Object Selection Document.
Definition: dsrtypes.h:513
DSRTypes::RT_contains
@ RT_contains
DICOM Relationship Type: CONTAINS.
Definition: dsrtypes.h:567

In addition, there are specific DSRDocumentTree::addContentItem() and DSRDocumentTree::addChildContentItem() methods that expect a pointer to a newly created DSRDocumentTreeNode instance.

Iterating over a document tree and searching for content items that meet certain criteria can be achieved in various ways. Here are two of them:

DSRDocument document;
/* ... */
DSRDocumentTree &tree = document.getTree();
/* #1: search for content items with a certain concept name */
if (tree.gotoNamedNode(CODE_DCM_ProcedureReported))
{
do {
const DSRDocumentTreeNode *node = tree.getNode();
/* and check for expected value type */
if ((node != NULL) && (node->getValueType() == DSRTypes::VT_Code))
{
/* do something useful with the CODE content item */
}
} while (tree.gotoNextNamedNode(CODE_DCM_ProcedureReported, OFFalse /*searchIntoSub*/));
}
/* #2: search for content items using a more complex filter */
DSRDocumentTreeNodeAndFilter filter;
filter.addFilter(new DSRDocumentTreeNodeValueTypeFilter(DSRTypes::VT_Code));
filter.addFilter(new DSRDocumentTreeNodeRelationshipTypeFilter(DSRTypes::RT_hasConceptMod));
filter.addFilter(new DSRDocumentTreeNodeHasChildrenFilter());
if (tree.gotoMatchingNode(filter))
{
/* found first "has concept mod CODE" content item that has children */
}
DSRDocumentSubTree::getNode
virtual DSRDocumentTreeNode * getNode() const
get pointer to current node.
DSRDocumentSubTree::gotoNextNamedNode
virtual size_t gotoNextNamedNode(const DSRCodedEntryValue &conceptName, const OFBool searchIntoSub=OFTrue)
set internal cursor to the next named node.
DSRDocumentSubTree::gotoNamedNode
virtual size_t gotoNamedNode(const DSRCodedEntryValue &conceptName, const OFBool startFromRoot=OFTrue, const OFBool searchIntoSub=OFTrue)
set internal cursor to a named node.
DSRDocumentSubTree::gotoMatchingNode
virtual size_t gotoMatchingNode(const DSRDocumentTreeNodeFilter &filter, const OFBool startFromRoot=OFTrue, const OFBool searchIntoSub=OFTrue)
set internal cursor to a matching node.
DSRDocumentTreeNodeAndFilter
Class implementing a list of document tree node filters that are combined with AND (conjunction)
Definition: dsrdnflt.h:120
DSRDocumentTreeNodeFilterList::addFilter
OFCondition addFilter(DSRDocumentTreeNodeFilter *filter)
add a document tree node filter to the list
DSRDocumentTreeNodeHasChildrenFilter
Class implementing a document tree node filter that checks for the presence (or absence) of child nod...
Definition: dsrdnflt.h:162
DSRDocumentTreeNodeRelationshipTypeFilter
Class implementing a document tree node filter that checks for a given relationship type.
Definition: dsrdnflt.h:326
DSRDocumentTreeNodeValueTypeFilter
Class implementing a document tree node filter that checks for a given value type.
Definition: dsrdnflt.h:294
DSRDocumentTreeNode
Base class for content items.
Definition: dsrdoctn.h:55
DSRDocumentTreeNode::getValueType
E_ValueType getValueType() const
get value type of the current content item
Definition: dsrdoctn.h:337
DSRTypes::RT_hasConceptMod
@ RT_hasConceptMod
DICOM Relationship Type: HAS CONCEPT MOD.
Definition: dsrtypes.h:573

The final example shows how to deal with SR templates, e.g. when creating a DICOM Structured Report that is based on TID 1500 (Measurement Report):

TID1500_MeasurementReport report(CMR_CID7021::ImagingMeasurementReport);
report.setLanguage(CID5000_Language::English);
report.getObservationContext().addPersonObserver("Doe^Jane", "Some Organization");
/* ... */
CMR_TID1411_in_TID1500 &volumetric = report.getVolumetricROIMeasurements();
volumetric.setActivitySession("1");
volumetric.setTrackingIdentifier("aorta reference region");
/* ... */
CMR_TID1419_in_TID1411_in_TID1500 &measurement = volumetric.getMeasurement();
measurement.createNewMeasurement(CMR_CID7469::Volume, CMR_TID1419_in_TID1411_in_TID1500::MeasurementValue("15", CMR_CID7181::CubicMillimeter));
measurement.setDerivation(CMR_CID7464::StandardDeviation);
/* ... */
DSRDocument document;
document.setPatientName("Last Name^First Name");
/* ... */
if (document.setTreeFromRootTemplate(report).good())
document.print(cout, DSRTypes::PF_printTemplateIdentification);
else
cerr << "Error: cannot set template content as document tree" << endl;
CID5000_Language::English
@ English
(eng,RFC5646,"English")
Definition: cid5000.h:44
CID7021_MeasurementReportDocumentTitle::ImagingMeasurementReport
@ ImagingMeasurementReport
(126000,DCM,"Imaging Measurement Report")
Definition: cid7021.h:44
CID7181_AbstractMultiDimensionalImageModelComponentUnit::CubicMillimeter
@ CubicMillimeter
(mm3,UCUM,"cubic millimeter"), included from CID 7462
Definition: cid7181.h:76
CID7464_GeneralRegionOfInterestMeasurementModifier::StandardDeviation
@ StandardDeviation
(386136009,SCT,"Standard Deviation")
Definition: cid7464.h:50
CID7469_GenericIntensityAndSizeMeasurement::Volume
@ Volume
(118565006,SCT,"Volume"), included from CID 7472
Definition: cid7469.h:406
CMR_SRNumericMeasurementValueWithUnits
Class for SR numeric values and measurements (extended version with additional support of the DICOM C...
Definition: srnumvlu.h:39
DSRDocument::setTreeFromRootTemplate
virtual OFCondition setTreeFromRootTemplate(DSRRootTemplate &rootTemplate, const OFBool expandTree=OFTrue)
set document tree from root template.
DSRDocument::print
virtual OFCondition print(STD_NAMESPACE ostream &stream, const size_t flags=0)
print current SR document to specified output stream.
DSRTypes::PF_printTemplateIdentification
static const size_t PF_printTemplateIdentification
print template identification (TID and mapping resource)
Definition: dsrtypes.h:429
TID1411_VolumetricROIMeasurements
Implementation of DCMR Template: TID 1411 - Volumetric ROI Measurements (and included templates 1502 ...
Definition: tid1411.h:57
TID1411_VolumetricROIMeasurements::setTrackingIdentifier
OFCondition setTrackingIdentifier(const OFString &trackingID, const OFBool check=OFTrue)
set the value of the 'Tracking Identifier' content item (TID 1411 - Row 2).
TID1411_VolumetricROIMeasurements::setActivitySession
OFCondition setActivitySession(const OFString &session, const OFBool check=OFTrue)
set the value of the 'Activity Session' content item (TID 1411 - Row 1b).
TID1411_VolumetricROIMeasurements::getMeasurement
TID1419_Measurement & getMeasurement() const
get current measurement value of this measurement group as defined by TID 1419 (ROI Measurements),...
Definition: tid1411.h:148
TID1419_ROIMeasurements_Measurement
Implementation of the DCMR Template: TID 1419 - ROI Measurements (only the "Measurement" content item...
Definition: tid1419m.h:54
TID1419_ROIMeasurements_Measurement::setDerivation
OFCondition setDerivation(const T_Derivation &derivation, const OFBool check=OFTrue)
set the value of the 'Derivation' content item (TID 1419 - Row 8).
TID1419_ROIMeasurements_Measurement::createNewMeasurement
OFCondition createNewMeasurement(const T_Measurement &conceptName, const MeasurementValue &numericValue, const OFBool check=OFTrue)
create a new measurement.
TID1500_MeasurementReport
Implementation of DCMR Template: TID 1500 - Measurement Report (and included templates 1204,...
Definition: tid1500.h:75

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