DSRDocument Class Reference

Interface class for 'dcmsr' (DICOM Structured Reporting Documents). More...

Inheritance diagram for DSRDocument:

List of all members.

Public Member Functions
	DSRDocument (const E_DocumentType documentType=DT_BasicTextSR)
	(default) constructor.
virtual	~DSRDocument ()
	destructor
void	clear ()
	clear all internal member variables
OFBool	isValid ()
	check whether the current internal state is valid.
OFBool	isFinalized () const
	check whether the document is finalized.
void	setLogStream (OFConsole *stream)
	set the log stream.
OFCondition	print (ostream &stream, const size_t flags=0)
	print current SR document to specified output stream.
OFCondition	read (DcmItem &dataset, const size_t flags=0)
	read SR document from DICOM dataset.
OFCondition	write (DcmItem &dataset, DcmStack *markedItems=NULL)
	write current SR document to DICOM dataset.
OFCondition	readXML (const OFString &filename, const size_t flags=0)
	read SR document from XML file.
OFCondition	writeXML (ostream &stream, const size_t flags=0)
	write current SR document in XML format.
OFCondition	renderHTML (ostream &stream, const size_t flags=0, const char *styleSheet=NULL)
	render current SR document in HTML format.
virtual OFBool	containsExtendedCharacters ()
	check if this document contains non-ASCII characters in one of the strings affected by SpecificCharacterSet in DICOM
E_DocumentType	getDocumentType () const
	get the current SR document type
DSRDocumentTree &	getTree ()
	get document tree
E_CharacterSet	getSpecificCharacterSetType () const
	get specific character set type.
OFCondition	setSpecificCharacterSetType (const E_CharacterSet characterSet)
	set specific character set type.
E_CompletionFlag	getCompletionFlag () const
	get document completion flag.
const char *	getCompletionFlagDescription () const
	get document completion flag description.
const OFString &	getCompletionFlagDescription (OFString &description) const
	get document completion flag description.
E_VerificationFlag	getVerificationFlag () const
	get document verification flag.
size_t	getNumberOfVerifyingObservers ()
	get number of verifying observers.
OFCondition	getVerifyingObserver (const size_t idx, OFString &dateTime, OFString &observerName, OFString &organization)
	get information about a verifying observer.
OFCondition	getVerifyingObserver (const size_t idx, OFString &dateTime, OFString &observerName, DSRCodedEntryValue &observerCode, OFString &organization)
	get information about a verifying observer.
DSRSOPInstanceReferenceList &	getPredecessorDocuments ()
	get list of predecessor documents.
DSRSOPInstanceReferenceList &	getIdenticalDocuments ()
	get list of identical documents.
DSRSOPInstanceReferenceList &	getCurrentRequestedProcedureEvidence ()
	get list of referenced SOP instances (Current Requested Procedure Evidence).
DSRSOPInstanceReferenceList &	getPertinentOtherEvidence ()
	get list of referenced SOP instances (Pertinent Other Evidence).
DSRCodingSchemeIdentificationList &	getCodingSchemeIdentification ()
	get list of coding schemes used (Coding Scheme Identification).
const char *	getModality () const
	get modality
const char *	getSOPClassUID () const
	get SOP class UID
const char *	getStudyInstanceUID () const
	get study instance UID
const char *	getSeriesInstanceUID () const
	get series instance UID
const char *	getSOPInstanceUID () const
	get SOP instance UID
const char *	getInstanceCreatorUID () const
	get instance creator UID
const char *	getSpecificCharacterSet () const
	get specific character set
const char *	getPatientsName () const
	get patient's name
const char *	getPatientsBirthDate () const
	get patient's birth date
const char *	getPatientsSex () const
	get patient's sex
const char *	getReferringPhysiciansName () const
	get referring physicians name
const char *	getStudyDescription () const
	get study description
const char *	getSeriesDescription () const
	get series description
const char *	getManufacturer () const
	get manufacturer
const char *	getStudyDate () const
	get study date
const char *	getStudyTime () const
	get study time
const char *	getInstanceCreationDate () const
	get instance creation date
const char *	getInstanceCreationTime () const
	get instance creation time
const char *	getContentDate () const
	get content date
const char *	getContentTime () const
	get content time
const char *	getStudyID () const
	get study ID
const char *	getPatientID () const
	get patient ID
const char *	getSeriesNumber () const
	get series number
const char *	getInstanceNumber () const
	get instance number
const char *	getAccessionNumber () const
	get accession number
const OFString &	getModality (OFString &value) const
	get modality
const OFString &	getSOPClassUID (OFString &value) const
	get SOP class UID
const OFString &	getStudyInstanceUID (OFString &value) const
	get study instance UID
const OFString &	getSeriesInstanceUID (OFString &value) const
	get series instance UID
const OFString &	getSOPInstanceUID (OFString &value) const
	get SOP instance UID
const OFString &	getInstanceCreatorUID (OFString &value) const
	get instance creator UID
const OFString &	getSpecificCharacterSet (OFString &value) const
	get specific character set
const OFString &	getPatientsName (OFString &value) const
	get patient's name
const OFString &	getPatientsBirthDate (OFString &value) const
	get patient's birth date
const OFString &	getPatientsSex (OFString &value) const
	get patient's sex
const OFString &	getReferringPhysiciansName (OFString &value) const
	get referring physicians name
const OFString &	getStudyDescription (OFString &value) const
	get study description
const OFString &	getSeriesDescription (OFString &value) const
	get series description
const OFString &	getManufacturer (OFString &value) const
	get manufacturer
const OFString &	getStudyDate (OFString &value) const
	get study date
const OFString &	getStudyTime (OFString &value) const
	get study time
const OFString &	getInstanceCreationDate (OFString &value) const
	get instance creation date
const OFString &	getInstanceCreationTime (OFString &value) const
	get instance creation time
const OFString &	getContentDate (OFString &value) const
	get content date
const OFString &	getContentTime (OFString &value) const
	get content time
const OFString &	getStudyID (OFString &value) const
	get study ID
const OFString &	getPatientID (OFString &value) const
	get patient ID
const OFString &	getSeriesNumber (OFString &value) const
	get series number
const OFString &	getInstanceNumber (OFString &value) const
	get instance number
const OFString &	getAccessionNumber (OFString &value) const
	get accession number
OFCondition	setSpecificCharacterSet (const OFString &value)
	set specific character set.
OFCondition	setCompletionFlagDescription (const OFString &value)
	set document completion flag description.
OFCondition	setPatientsName (const OFString &value)
	set patient's name.
OFCondition	setPatientsBirthDate (const OFString &value)
	set patient's birth date.
OFCondition	setPatientsSex (const OFString &value)
	set patient's sex.
OFCondition	setReferringPhysiciansName (const OFString &value)
	set referring physicians name.
OFCondition	setStudyDescription (const OFString &value)
	set study description.
OFCondition	setSeriesDescription (const OFString &value)
	set series description.
OFCondition	setManufacturer (const OFString &value)
	set manufacturer.
OFCondition	setContentDate (const OFString &value)
	set content date.
OFCondition	setContentTime (const OFString &value)
	set content time.
OFCondition	setStudyID (const OFString &value)
	set study ID.
OFCondition	setPatientID (const OFString &value)
	set patient ID.
OFCondition	setSeriesNumber (const OFString &value)
	set series number.
OFCondition	setInstanceNumber (const OFString &value)
	set instance number.
OFCondition	setAccessionNumber (const OFString &value)
	set accession number.
void	createNewStudy ()
	create new study.
void	createNewSeries ()
	create a new series.
OFCondition	createNewSeriesInStudy (const OFString &studyUID)
	create a new series within a given study.
void	createNewSOPInstance ()
	create a new SOP instance.
OFCondition	createNewDocument ()
	create a new document.
OFCondition	createNewDocument (const E_DocumentType documentType)
	create a new document of the specified type.
OFCondition	createRevisedVersion (const OFBool clearList=OFTrue)
	create a revised version of the current document.
OFCondition	completeDocument ()
	complete the current document.
OFCondition	completeDocument (const OFString &description)
	complete the current document and set a completion description.
OFCondition	verifyDocument (const OFString &observerName, const OFString &organization)
	verify the current document by a specific observer.
OFCondition	verifyDocument (const OFString &observerName, const OFString &organization, const OFString &dateTime)
	verify the current document by a specific observer.
OFCondition	verifyDocument (const OFString &observerName, const DSRCodedEntryValue &observerCode, const OFString &organization)
	verify the current document by a specific observer.
OFCondition	verifyDocument (const OFString &observerName, const DSRCodedEntryValue &observerCode, const OFString &organization, const OFString &dateTime)
	verify the current document by a specific observer.
void	removeVerification ()
	remove verification information.
OFCondition	finalizeDocument ()
	finalize the current state of the document.
Protected Member Functions
OFCondition	readXMLDocumentHeader (DSRXMLDocument &doc, DSRXMLCursor cursor, const size_t flags)
	read XML document header
OFCondition	readXMLPatientData (const DSRXMLDocument &doc, DSRXMLCursor cursor, const size_t flags)
	read XML "patient" data
OFCondition	readXMLStudyData (const DSRXMLDocument &doc, DSRXMLCursor cursor, const size_t flags)
	read XML "study" data
OFCondition	readXMLSeriesData (const DSRXMLDocument &doc, DSRXMLCursor cursor, const size_t flags)
	read XML "series" data
OFCondition	readXMLInstanceData (const DSRXMLDocument &doc, DSRXMLCursor cursor, const size_t flags)
	read XML "instance" data
OFCondition	readXMLDocumentData (const DSRXMLDocument &doc, DSRXMLCursor cursor, const size_t flags)
	read XML "document" data
OFCondition	readXMLVerifyingObserverData (const DSRXMLDocument &doc, DSRXMLCursor cursor, const size_t flags)
	read XML verifying observer data
void	renderHTMLPatientData (ostream &stream, const size_t flags)
	render patient name, sex, birthdate and ID in HTML format
void	renderHTMLReferenceList (ostream &stream, DSRSOPInstanceReferenceList &refList, const size_t flags)
	render list of referenced SOP instances in HTML format
OFCondition	checkDatasetForReading (DcmItem &dataset, E_DocumentType &documentType)
	check the given dataset before reading.
void	updateAttributes (const OFBool updateAll=OFTrue)
	update several DICOM attributes.
Private Member Functions
	DSRDocument (const DSRDocument &)
DSRDocument &	operator= (const DSRDocument &)
Private Attributes
DSRDocumentTree	DocumentTree
	SR document tree.
OFConsole *	LogStream
	output stream for error messages, NULL for no messages
OFBool	FinalizedFlag
	flag indicating whether is document is finalized or not
E_CompletionFlag	CompletionFlagEnum
	enumerated value: partial, complete
E_VerificationFlag	VerificationFlagEnum
	enumerated value: unverified, verified
E_CharacterSet	SpecificCharacterSetEnum
	defined term: see class DSRTypes
DcmUniqueIdentifier	SOPClassUID
	SOP Class UID: (UI, 1, 1).
DcmUniqueIdentifier	SOPInstanceUID
	SOP Instance UID: (UI, 1, 1).
DcmCodeString	SpecificCharacterSet
	Specific Character Set: (CS, 1-n, 1C).
DcmDate	InstanceCreationDate
	Instance Creation Date: (DA, 1, 3).
DcmTime	InstanceCreationTime
	Instance Creation Time: (TM, 1, 3).
DcmUniqueIdentifier	InstanceCreatorUID
	Instance Creator UID: (UI, 1, 3).
DSRCodingSchemeIdentificationList	CodingSchemeIdentification
	Coding Scheme Identification Sequence: (SQ, 1, 3).
DcmUniqueIdentifier	StudyInstanceUID
	Study Instance UID: (UI, 1, 1).
DcmDate	StudyDate
	Study Date: (DA, 1, 2).
DcmTime	StudyTime
	StudyTime: (TM, 1, 2).
DcmPersonName	ReferringPhysiciansName
	ReferringPhysiciansName: (PN, 1, 2).
DcmShortString	StudyID
	Study ID: (SH, 1, 2).
DcmShortString	AccessionNumber
	Accession Number: (SH, 1, 2).
DcmLongString	StudyDescription
	Study Description: (LO, 1, 3).
DcmLongString	SeriesDescription
	Series Description: (LO, 1, 3).
DcmPersonName	PatientsName
	Person Name: (PN, 1, 2).
DcmLongString	PatientID
	Patient ID: (LO, 1, 2).
DcmDate	PatientsBirthDate
	Patient Birth Date: (DA, 1, 2).
DcmCodeString	PatientsSex
	Patient Sex: (CS, 1, 2).
DcmLongString	Manufacturer
	Manufacturer: (LO, 1, 2).
DcmCodeString	Modality
	Modality: (CS, 1, 1).
DcmUniqueIdentifier	SeriesInstanceUID
	Series Instance Number: (UI, 1, 1).
DcmIntegerString	SeriesNumber
	Series Number: (IS, 1, 1).
DcmSequenceOfItems	ReferencedPerformedProcedureStepSequence
	Referenced Performed Procedure Step Sequence: (SQ, 1, 2).
DcmIntegerString	InstanceNumber
	Instance Number: (IS, 1, 1).
DcmCodeString	CompletionFlag
	Completion Flag: (CS, 1, 1).
DcmLongString	CompletionFlagDescription
	Completion Flag Description: (LO, 1, 3).
DcmCodeString	VerificationFlag
	Verification Flag: (CS, 1, 1).
DcmDate	ContentDate
	Content Date: (DA, 1, 1).
DcmTime	ContentTime
	Content Time: (TM, 1, 1).
DcmSequenceOfItems	VerifyingObserver
	Verifying Observer Sequence: (SQ, 1, 1C).
DSRSOPInstanceReferenceList	PredecessorDocuments
	Predecessor Documents Sequence: (SQ, 1, 1C).
DSRSOPInstanceReferenceList	IdenticalDocuments
	Identical Documents Sequence: (SQ, 1, 1C).
DcmSequenceOfItems	PerformedProcedureCode
	Performed Procedure Code Sequence: (SQ, 1, 2).
DSRSOPInstanceReferenceList	CurrentRequestedProcedureEvidence
	Current Requested Procedure Evidence Sequence: (SQ, 1, 1C).
DSRSOPInstanceReferenceList	PertinentOtherEvidence
	Pertinent Other Evidence Sequence: (SQ, 1, 1C).

---

Detailed Description

Interface class for 'dcmsr' (DICOM Structured Reporting Documents).

This class supports reading, writing, creation, printing and rendering of DICOM SR documents (according to DICOM PS 3.x-2004, formerly known as Supplement 23). The list of supported SOP classes is available in file "dsrtypes.h".

Definition at line 56 of file dsrdoc.h.

---

Constructor & Destructor Documentation

DSRDocument::DSRDocument (  const E_DocumentType  documentType = DT_BasicTextSR  )

(default) constructor. The parameter 'documentType' is optional and has a default value. Parameters: documentType  type of the SR document (see DSRTypes::E_DocumentType)

---

Member Function Documentation

OFCondition DSRDocument::checkDatasetForReading (  DcmItem &  dataset, E_DocumentType &  documentType )  [protected]

check the given dataset before reading. This methods checks whether the dataset contains at least the DICOM attributes SOP class UID and modality. Any incorrectness regarding these two attributes is reported to the log stream (if valid). Currently unsupported SOP classes are also reported as an error. Parameters: dataset  DICOM dataset to be checked documentType  SR document type retrieved from the SOP class UID Returns: status, EC_Normal if successful, an error code otherwise

OFCondition DSRDocument::completeDocument (  const OFString &  description  )

complete the current document and set a completion description. Sets the completion flag to COMPLETE if not already done (fails otherwise). The completion flag description can be modified independently from the flag by means of the method setCompletionFlagDescription() - see above. Not applicable to Key Object Selection Documents. Parameters: description  explanation of the value set for completion flag. (optional, see previous method, VR=LO) Returns: status, EC_Normal if successful, an error code otherwise

OFCondition DSRDocument::completeDocument (   )

complete the current document. Sets the completion flag to COMPLETE if not already done (fails otherwise). The completion flag description is set to an empty string (i.e. absent in DICOM dataset). Not applicable to Key Object Selection Documents. Returns: status, EC_Normal if successful, an error code otherwise

virtual OFBool DSRDocument::containsExtendedCharacters (   )  [virtual]

check if this document contains non-ASCII characters in one of the strings affected by SpecificCharacterSet in DICOM Returns: true if node contains non-ASCII characters, false otherwise

OFCondition DSRDocument::createNewDocument (  const E_DocumentType  documentType  )

create a new document of the specified type. A new SOP instance is only created if the current document type was valid/supported. Please note that the current document is deleted by this method. Parameters: documentType  type of the SR document (see DSRTypes::E_DocumentType) Returns: status, EC_Normal if successful, an error code otherwise

OFCondition DSRDocument::createNewDocument (   )

create a new document. A new SOP instance is only created if the current document type was valid/supported. Please note that the current document is deleted (cleared). Returns: status, EC_Normal if successful, an error code otherwise

void DSRDocument::createNewSeries (   )

create a new series. After generating a new series instance UID the method createNewSOPInstance() is called, i.e. also a SOP instance UID is generated. This is a requirement of the DICOM standard.

OFCondition DSRDocument::createNewSeriesInStudy (  const OFString &  studyUID  )

create a new series within a given study. After generating a new series instance UID within the given study the method createNewSOPInstance() is called, i.e. also a SOP instance UID is generated. This is a requirement of the DICOM standard. Parameters: studyUID  study instance UID to be set (should be a valid UID) Returns: status, EC_Normal if successful, an error code otherwise

void DSRDocument::createNewSOPInstance (   )

create a new SOP instance. Generate a new SOP instance UID, set the instance creation date/time and reset the finalized flag (OFFalse). This method is used internally for createNewDocument(), createRevisedVersion() and during object initialization. It could also be used explicitly from the calling application if a new UID should be created (this is the case if the study instance UID or series instance UID has changed as well as any other attribute within the SR Document General Module or SR Document Content Module, see DICOM standard for details). This method also updates the other DICOM header attributes (calling updateAttributes()).

void DSRDocument::createNewStudy (   )

create new study. After generating a new study instance UID the method createNewSeries() is called, i.e. also a new series instance UID and SOP instance UID are generated. This is a requirement of the DICOM standard.

OFCondition DSRDocument::createRevisedVersion (  const OFBool  clearList = OFTrue  )

create a revised version of the current document. A revised version can only be created if the current document is already completed (see completion flag). If so, a reference to the current document is added to the predecessor documents sequence. If all revised versions of a SR document are stored (written to datasets/files) it is possible to trace back the full chain of previous versions. A new SOP instance is created and the content date/time are set automatically. Furthermore, the verifying observer and identical documents sequence are deleted, the verification flag is set to UNVERIFIED, the completion flag is set to PARTIAL (i.e. not complete), the completion flag description is deleted, all digital signatures contained in the document tree are deleted and the finalized flag is reset (OFFalse). Not applicable to Key Object Selection Documents. Parameters: clearList  clear list of predecessor documents before adding the current document if OFTrue. Append current document to existing list otherwise. Returns: status, EC_Normal if successful, an error code otherwise

OFCondition DSRDocument::finalizeDocument (   )

finalize the current state of the document. A new document is originally not finalized but can be finalized using this method. This internal flag is e.g. used to indicate whether the entire document is digitally signed and, therefore, each newly added verifying observer would corrupt all previous signatures. NB: A document needs to be completed first in order to be finalized. Some of the above document management functions do reset the flag (i.e. set the FinalizedFlag to OFFalse), other methods (e.g. setXXX) do not change the flag though the state of the document is not finalized any more after they have been called. Not applicable to Key Object Selection Documents since there's no Completion Flag in this type of SR document. Returns: status, EC_Normal if successful, an error code otherwise

const OFString& DSRDocument::getAccessionNumber (  OFString &  value  )  const

get accession number Parameters: value  reference to character string in which the value should be stored Returns: character string (might empty)

const char* DSRDocument::getAccessionNumber (   )  const

get accession number Returns: pointer to string value (might be NULL)

DSRCodingSchemeIdentificationList& DSRDocument::getCodingSchemeIdentification (   )

get list of coding schemes used (Coding Scheme Identification). The Coding Scheme Identification Sequence maps Coding Scheme Designators to an external coding system registration, or to a private or local coding scheme. See DICOM standard for details. Returns: reference to list object

E_CompletionFlag DSRDocument::getCompletionFlag (   )  const

get document completion flag. Not applicable to Key Object Selection Documents. Returns: completion flag (might be CF_invalid if read from dataset)

const OFString& DSRDocument::getCompletionFlagDescription (  OFString &  description  )  const

get document completion flag description. Not applicable to Key Object Selection Documents. Parameters: description  reference to character string in which the value should be stored Returns: character string (might be empty)

const char* DSRDocument::getCompletionFlagDescription (   )  const

get document completion flag description. Not applicable to Key Object Selection Documents. Returns: pointer to string value (might be NULL)

const OFString& DSRDocument::getContentDate (  OFString &  value  )  const

get content date Parameters: value  reference to character string in which the value should be stored Returns: character string (might empty)

const char* DSRDocument::getContentDate (   )  const

get content date Returns: pointer to string value (might be NULL)

const OFString& DSRDocument::getContentTime (  OFString &  value  )  const

get content time Parameters: value  reference to character string in which the value should be stored Returns: character string (might empty)

const char* DSRDocument::getContentTime (   )  const

get content time Returns: pointer to string value (might be NULL)

DSRSOPInstanceReferenceList& DSRDocument::getCurrentRequestedProcedureEvidence (   )

get list of referenced SOP instances (Current Requested Procedure Evidence). PS 3.3-2004 states: "The intent of the Current Requested Procedure Evidence Sequence is to reference all evidence created in order to satisfy the current Requested Procedure(s) for this SR Document. This shall include, but is not limited to, all current evidence referenced in the content tree." and "In the context of the Key Object Selection, the current evidence is considered to be only the set of instances referenced within the Key Object Selection." Supplement 66 (FT) adds: "For a completed SR Document satisfying (i.e., being the final report for) the current Requested Procedure(s), this sequence shall list the full set of Composite SOP Instances created for the current Requested Procedure(s). For other SOP Instances that include the SR Document General Module, this sequence shall contain at minimum the set of Composite SOP Instances from the current Requested Procedure(s) that are referenced in the content tree." Returns: reference to list object

E_DocumentType DSRDocument::getDocumentType (   )  const

get the current SR document type Returns: document type (might be DT_invalid if read from dataset)

DSRSOPInstanceReferenceList& DSRDocument::getIdenticalDocuments (   )

get list of identical documents. Please note that currently the user is responsible for filling and modifying the content of this list. However, the list is automatically cleared when a new instance is created (incl. a revised version of the current document). Possibly, there will be a createDuplicate() method or the like in the future which creates an identical copy of the current document in a new study/series. PS 3.3-2004 states: "If identical copies of an SR Document are to be included in multiple Studies then the entire SR Document shall be duplicated with appropriate changes for inclusion into the different Studies (i.e. Study Instance UID, Series Instance UID, SOP Instance UID, Identical Documents Sequence etc.). The Identical Documents Sequence Attribute in each SOP Instance shall contain references to all other duplicate SOP Instances." Returns: reference to list object

const OFString& DSRDocument::getInstanceCreationDate (  OFString &  value  )  const

get instance creation date Parameters: value  reference to character string in which the value should be stored Returns: character string (might empty)

const char* DSRDocument::getInstanceCreationDate (   )  const

get instance creation date Returns: pointer to string value (might be NULL)

const OFString& DSRDocument::getInstanceCreationTime (  OFString &  value  )  const

get instance creation time Parameters: value  reference to character string in which the value should be stored Returns: character string (might empty)

const char* DSRDocument::getInstanceCreationTime (   )  const

get instance creation time Returns: pointer to string value (might be NULL)

const OFString& DSRDocument::getInstanceCreatorUID (  OFString &  value  )  const

get instance creator UID Parameters: value  reference to character string in which the value should be stored Returns: character string (might empty)

const char* DSRDocument::getInstanceCreatorUID (