DCMTK: dcmsr: a structured reporting library and utility apps

DCMTK Version 3.6.9 OFFIS DICOM Toolkit

Loading...
Searching...
No Matches
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:60
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:44
DcmFileFormat::getDataset
DcmDataset * getDataset()
get dataset part of the fileformat
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.
OFCondition
General purpose class for condition codes.
Definition ofcond.h:176
OFCondition::bad
OFBool bad() const
check if the status is not OK, i.e. error or failure.
Definition ofcond.h:321
OFCondition::text
const char * text() const
get a human readable text representation of this error code.
Definition ofcond.h:296
OFCondition::good
OFBool good() const
check if the status is OK.
Definition ofcond.h:312

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::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.
DSRDocumentSubTree::getCurrentContentItem
virtual DSRContentItem & getCurrentContentItem()
get reference to current content item.
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::getTree
DSRDocumentTree & getTree()
get document tree
Definition dsrdoc.h:221
DSRDocument::setPatientName
virtual OFCondition setPatientName(const OFString &value, const OFBool check=OFTrue)
set patient's name
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::getConceptNamePtr
DSRCodedEntryValue * getConceptNamePtr()
get pointer to concept name.
DSRContentItem::getImageReferencePtr
DSRImageReferenceValue * getImageReferencePtr()
get pointer to image reference.
DSRImageReferenceValue
Class for image reference values.
Definition dsrimgvl.h:57
DSRImageReferenceValue::getFrameList
DSRImageFrameList & getFrameList()
get reference to list of referenced frame numbers.
Definition dsrimgvl.h:371
DSRImageReferenceValue::setPresentationState
OFCondition setPresentationState(const DSRCompositeReferenceValue &pstateValue, const OFBool check=OFTrue)
set reference to presentation state object.
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:333
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
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::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::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 Wed Apr 30 2025 for DCMTK Version 3.6.9 by Doxygen 1.13.2