dcmsr/include/dcmtk/dcmsr/dsrdoc.h

/*
 *
 *  Copyright (C) 2000-2010, OFFIS e.V.
 *  All rights reserved.  See COPYRIGHT file for details.
 *
 *  This software and supporting documentation were developed by
 *
 *    OFFIS e.V.
 *    R&D Division Health
 *    Escherweg 2
 *    D-26121 Oldenburg, Germany
 *
 *
 *  Module: dcmsr
 *
 *  Author: Joerg Riesmeier
 *
 *  Purpose:
 *    classes: DSRDocument
 *
 *  Last Update:      $Author: joergr $
 *  Update Date:      $Date: 2010-10-14 13:16:32 $
 *  CVS/RCS Revision: $Revision: 1.53 $
 *  Status:           $State: Exp $
 *
 *  CVS/RCS Log at end of file
 *
 */


#ifndef DSRDOC_H
#define DSRDOC_H

#include "dcmtk/config/osconfig.h"   /* make sure OS specific configuration is included first */

#include "dcmtk/dcmsr/dsrdoctr.h"
#include "dcmtk/dcmsr/dsrsoprf.h"
#include "dcmtk/dcmsr/dsrcsidl.h"

#include "dcmtk/ofstd/ofstream.h"


/*---------------------*
 *  class declaration  *
 *---------------------*/

class DSRDocument
  : protected DSRTypes
{

  public:

  // --- constructors and destructor ---

    DSRDocument(const E_DocumentType documentType = DT_BasicTextSR);

    virtual ~DSRDocument();


  // --- misc routines ---

    void clear();

    OFBool isValid();

    OFBool isFinalized() const;


  // --- input and output ---

    OFCondition print(STD_NAMESPACE ostream &stream,
                      const size_t flags = 0);

    OFCondition read(DcmItem &dataset,
                     const size_t flags = 0);

    OFCondition write(DcmItem &dataset,
                      DcmStack *markedItems = NULL);

    OFCondition readXML(const OFString &filename,
                        const size_t flags = 0);

    OFCondition writeXML(STD_NAMESPACE ostream &stream,
                         const size_t flags = 0);

    OFCondition renderHTML(STD_NAMESPACE ostream &stream,
                           const size_t flags = 0,
                           const char *styleSheet = NULL);


  // --- get/set misc attributes ---

    E_DocumentType getDocumentType() const;

    inline DSRDocumentTree &getTree()
    {
        return DocumentTree;
    }

    E_CharacterSet getSpecificCharacterSetType() const;

    OFCondition setSpecificCharacterSetType(const E_CharacterSet characterSet);

    E_PreliminaryFlag getPreliminaryFlag() const;

    E_CompletionFlag getCompletionFlag() const;

    const char *getCompletionFlagDescription() const;

    const OFString &getCompletionFlagDescription(OFString &description) const;

    E_VerificationFlag getVerificationFlag() const;

    size_t getNumberOfVerifyingObservers();

    OFCondition getVerifyingObserver(const size_t idx,
                                     OFString &dateTime,
                                     OFString &observerName,
                                     OFString &organization);

    OFCondition getVerifyingObserver(const size_t idx,
                                     OFString &dateTime,
                                     OFString &observerName,
                                     DSRCodedEntryValue &observerCode,
                                     OFString &organization);

    DSRSOPInstanceReferenceList &getPredecessorDocuments();

    DSRSOPInstanceReferenceList &getIdenticalDocuments();

    DSRSOPInstanceReferenceList &getCurrentRequestedProcedureEvidence();

    DSRSOPInstanceReferenceList &getPertinentOtherEvidence();

    DSRCodingSchemeIdentificationList &getCodingSchemeIdentification();


  // --- get DICOM string attributes (C string) ---
  // --- (these functions return the whole string value,
  // ---  i.e. all components of multi-valued attributes)

    const char *getModality() const;

    const char *getSOPClassUID() const;

    const char *getStudyInstanceUID() const;

    const char *getSeriesInstanceUID() const;

    const char *getSOPInstanceUID() const;

    const char *getInstanceCreatorUID() const;

    const char *getSpecificCharacterSet() const;

    const char *getPatientName() const;

    const char *getPatientBirthDate() const;

    const char *getPatientSex() const;

    const char *getReferringPhysicianName() const;

    const char *getStudyDescription() const;

    const char *getSeriesDescription() const;

    const char *getManufacturer() const;

    const char *getManufacturerModelName() const;

    const char *getDeviceSerialNumber() const;

    const char *getSoftwareVersions() const;

    const char *getStudyDate() const;

    const char *getStudyTime() const;

    const char *getInstanceCreationDate() const;

    const char *getInstanceCreationTime() const;

    const char *getContentDate() const;

    const char *getContentTime() const;

    const char *getStudyID() const;

    const char *getPatientID() const;

    const char *getSeriesNumber() const;

    const char *getInstanceNumber() const;

    const char *getAccessionNumber() const;


  // --- get DICOM string attributes (C++ string) ---
  // --- (these functions return only the first
  // ---  component of multi-valued attributes)

    const OFString &getModality(OFString &value) const;

    const OFString &getSOPClassUID(OFString &value) const;

    const OFString &getStudyInstanceUID(OFString &value) const;

    const OFString &getSeriesInstanceUID(OFString &value) const;

    const OFString &getSOPInstanceUID(OFString &value) const;

    const OFString &getInstanceCreatorUID(OFString &value) const;

    const OFString &getSpecificCharacterSet(OFString &value) const;

    const OFString &getPatientName(OFString &value) const;

    const OFString &getPatientBirthDate(OFString &value) const;

    const OFString &getPatientSex(OFString &value) const;

    const OFString &getReferringPhysicianName(OFString &value) const;

    const OFString &getStudyDescription(OFString &value) const;

    const OFString &getSeriesDescription(OFString &value) const;

    const OFString &getManufacturer(OFString &value) const;

    const OFString &getManufacturerModelName(OFString &value) const;

    const OFString &getDeviceSerialNumber(OFString &value) const;

    const OFString &getSoftwareVersions(OFString &value) const;

    const OFString &getStudyDate(OFString &value) const;

    const OFString &getStudyTime(OFString &value) const;

    const OFString &getInstanceCreationDate(OFString &value) const;

    const OFString &getInstanceCreationTime(OFString &value) const;

    const OFString &getContentDate(OFString &value) const;

    const OFString &getContentTime(OFString &value) const;

    const OFString &getStudyID(OFString &value) const;

    const OFString &getPatientID(OFString &value) const;

    const OFString &getSeriesNumber(OFString &value) const;

    const OFString &getInstanceNumber(OFString &value) const;

    const OFString &getAccessionNumber(OFString &value) const;


  // --- set DICOM string attributes ---

    OFCondition setSpecificCharacterSet(const OFString &value);

    OFCondition setPreliminaryFlag(const E_PreliminaryFlag flag);

    OFCondition setCompletionFlagDescription(const OFString &value);

    OFCondition setPatientName(const OFString &value);

    OFCondition setPatientBirthDate(const OFString &value);

    OFCondition setPatientSex(const OFString &value);

    OFCondition setReferringPhysicianName(const OFString &value);

    OFCondition setStudyDescription(const OFString &value);

    OFCondition setSeriesDescription(const OFString &value);

    OFCondition setManufacturer(const OFString &value);

    OFCondition setManufacturerModelName(const OFString &value);

    OFCondition setDeviceSerialNumber(const OFString &value);

    OFCondition setSoftwareVersions(const OFString &value);

    OFCondition setContentDate(const OFString &value);

    OFCondition setContentTime(const OFString &value);

    OFCondition setStudyID(const OFString &value);

    OFCondition setPatientID(const OFString &value);

    OFCondition setSeriesNumber(const OFString &value);

    OFCondition setInstanceNumber(const OFString &value);

    OFCondition setAccessionNumber(const OFString &value);


  // --- document management functions ---

    void createNewStudy();

    void createNewSeries();

    OFCondition createNewSeriesInStudy(const OFString &studyUID);

    void createNewSOPInstance();

    OFCondition createNewDocument();

    OFCondition createNewDocument(const E_DocumentType documentType);

    OFCondition createRevisedVersion(const OFBool clearList = OFTrue);

    OFCondition completeDocument();

    OFCondition completeDocument(const OFString &description);

    OFCondition verifyDocument(const OFString &observerName,
                               const OFString &organization);

    OFCondition verifyDocument(const OFString &observerName,
                               const OFString &organization,
                               const OFString &dateTime /*= ""*/);

    OFCondition verifyDocument(const OFString &observerName,
                               const DSRCodedEntryValue &observerCode,
                               const OFString &organization);

    OFCondition verifyDocument(const OFString &observerName,
                               const DSRCodedEntryValue &observerCode,
                               const OFString &organization,
                               const OFString &dateTime /*= ""*/);

    void removeVerification();

    OFCondition finalizeDocument();


  protected:

    OFCondition readXMLDocumentHeader(DSRXMLDocument &doc,
                                      DSRXMLCursor cursor,
                                      const size_t flags);

    OFCondition readXMLPatientData(const DSRXMLDocument &doc,
                                   DSRXMLCursor cursor,
                                   const size_t flags);

    OFCondition readXMLStudyData(const DSRXMLDocument &doc,
                                 DSRXMLCursor cursor,
                                 const size_t flags);

    OFCondition readXMLSeriesData(const DSRXMLDocument &doc,
                                  DSRXMLCursor cursor,
                                  const size_t flags);

    OFCondition readXMLInstanceData(const DSRXMLDocument &doc,
                                    DSRXMLCursor cursor,
                                    const size_t flags);

    OFCondition readXMLDocumentData(const DSRXMLDocument &doc,
                                    DSRXMLCursor cursor,
                                    const size_t flags);

    OFCondition readXMLVerifyingObserverData(const DSRXMLDocument &doc,
                                             DSRXMLCursor cursor,
                                             const size_t flags);

    void renderHTMLPatientData(STD_NAMESPACE ostream &stream,
                               const size_t flags);

    void renderHTMLReferenceList(STD_NAMESPACE ostream &stream,
                                 DSRSOPInstanceReferenceList &refList,
                                 const size_t flags);

    OFCondition checkDatasetForReading(DcmItem &dataset,
                                       E_DocumentType &documentType);

    void updateAttributes(const OFBool updateAll = OFTrue);


  private:

    DSRDocumentTree DocumentTree;

    OFBool             FinalizedFlag;
    E_PreliminaryFlag  PreliminaryFlagEnum;
    E_CompletionFlag   CompletionFlagEnum;
    E_VerificationFlag VerificationFlagEnum;
    E_CharacterSet     SpecificCharacterSetEnum;

    // DICOM attributes are listed ordered by module.
    // The comments for each attribute describe "Name: (VR, VM, Type)".
    // Please note that for particular SR documents (e.g. Key Object Selection)
    // other rules might apply.  See DICOM standard for further reference.

    // --- SOP Common Module (M) ---
    // (see SR Document General Module)

    DcmUniqueIdentifier SOPClassUID;
    DcmUniqueIdentifier SOPInstanceUID;
    DcmCodeString       SpecificCharacterSet;
    DcmDate             InstanceCreationDate;
    DcmTime             InstanceCreationTime;
    DcmUniqueIdentifier InstanceCreatorUID;
    DSRCodingSchemeIdentificationList CodingSchemeIdentification;

    // --- General Study Module (M) ---

    DcmUniqueIdentifier StudyInstanceUID;
    DcmDate             StudyDate;
    DcmTime             StudyTime;
    DcmPersonName       ReferringPhysicianName;
    DcmShortString      StudyID;
    DcmShortString      AccessionNumber;
    DcmLongString       StudyDescription;

    // --- Patient Module (M) ---

    DcmPersonName       PatientName;
    DcmLongString       PatientID;
    DcmDate             PatientBirthDate;
    DcmCodeString       PatientSex;

    // --- General Equipment Module (M) ---

    DcmLongString       Manufacturer;
    DcmLongString       ManufacturerModelName;
    DcmLongString       DeviceSerialNumber;
    DcmLongString       SoftwareVersions;

    // --- Enhanced General Equipment Module (M - for some IODs) ---

    //  Manufacturer: (LO, 1, 1)
        //  - see 'General Equipment Module'
        //  - see 'General Equipment Module'
        //  - see 'General Equipment Module'
        //  - see 'General Equipment Module'

    // --- Frame of Reference (C) ---

    // tbd: conditional module for X-Ray Radiation Dose SR not yet supported

    // --- SR Document Series Module (M) ---

    DcmCodeString       Modality;
    DcmUniqueIdentifier SeriesInstanceUID;
    DcmIntegerString    SeriesNumber;
    DcmLongString       SeriesDescription;
    DcmSequenceOfItems  ReferencedPerformedProcedureStep;

    // --- SR Document General Module (M) ---

    DcmIntegerString    InstanceNumber;
    DcmCodeString       PreliminaryFlag;
    DcmCodeString       CompletionFlag;
    DcmLongString       CompletionFlagDescription;
    DcmCodeString       VerificationFlag;
    DcmDate             ContentDate;
    DcmTime             ContentTime;
    DcmSequenceOfItems  VerifyingObserver;
    DSRSOPInstanceReferenceList PredecessorDocuments;
    DSRSOPInstanceReferenceList IdenticalDocuments;
    //  Referenced Request Sequence: (SQ, 1, 1C)
        // -- not yet supported --
    DcmSequenceOfItems  PerformedProcedureCode;
    DSRSOPInstanceReferenceList CurrentRequestedProcedureEvidence;
    DSRSOPInstanceReferenceList PertinentOtherEvidence;

 // --- declaration of copy constructor and assignment operator ---

    DSRDocument(const DSRDocument &);
    DSRDocument &operator=(const DSRDocument &);
};


#endif


/*
 *  CVS/RCS Log:
 *  $Log: dsrdoc.h,v $
 *  Revision 1.53  2010-10-14 13:16:32  joergr
 *  Updated copyright header. Added reference to COPYRIGHT file.
 *
 *  Revision 1.52  2010-09-30 08:49:40  joergr
 *  Fixed incomplete comment.
 *
 *  Revision 1.51  2010-09-29 15:07:06  joergr
 *  Enhanced comments on attributes from Enhanced General Equipment Module.
 *
 *  Revision 1.50  2010-09-29 10:07:12  joergr
 *  Added support for the recently introduced, optional PreliminaryFlag.
 *
 *  Revision 1.49  2010-09-28 16:26:43  joergr
 *  Added support for Enhanced General Equipment Module which is required for
 *  both X-Ray Radiation Dose SR and Colon CAD SR.
 *
 *  Revision 1.48  2010-08-09 13:26:25  joergr
 *  Updated data dictionary to 2009 edition of the DICOM standard. From now on,
 *  the official "keyword" is used for the attribute name which results in a
 *  number of minor changes (e.g. "PatientsName" is now called "PatientName").
 *
 *  Revision 1.47  2010-07-01 13:40:33  joergr
 *  Moved SeriesDescription (0008,103E) from General Series to SR Document Series
 *  Module (according to CP 703).
 *
 *  Revision 1.46  2009-10-13 14:57:50  uli
 *  Switched to logging mechanism provided by the "new" oflog module.
 *
 *  Revision 1.45  2009-04-21 08:32:38  joergr
 *  Fixed typo.
 *
 *  Revision 1.44  2007/11/15 16:33:30  joergr
 *  Added support for output in XHTML 1.1 format.
 *
 *  Revision 1.43  2006/12/06 11:50:42  joergr
 *  Updated various citations according to the latest version of the DICOM
 *  standard (incl. CP 584). Removed references to a particular edition of the
 *  standard.
 *
 *  Revision 1.42  2006/08/15 16:40:03  meichel
 *  Updated the code in module dcmsr to correctly compile when
 *    all standard C++ classes remain in namespace std.
 *
 *  Revision 1.41  2006/07/25 13:19:53  joergr
 *  Renamed member variable "ReferencedPerformedProcedureStepSequence" to
 *  "ReferencedPerformedProcedureStep" for consistency reasons.
 *
 *  Revision 1.40  2006/06/01 15:23:14  joergr
 *  Removed explicit reference to a particular edition of the DICOM standard.
 *
 *  Revision 1.39  2006/05/11 09:18:21  joergr
 *  Moved containsExtendedCharacters() from dcmsr to dcmdata module.
 *
 *  Revision 1.38  2005/12/08 16:04:59  meichel
 *  Changed include path schema for all DCMTK header files
 *
 *  Revision 1.37  2005/11/30 12:00:24  joergr
 *  Added support for X-Ray Radiation Dose SR documents.
 *
 *  Revision 1.36  2005/07/27 16:41:55  joergr
 *  Updated reference to DICOM standard edition.
 *
 *  Revision 1.35  2004/11/22 16:39:09  meichel
 *  Added method that checks if the SR document contains non-ASCII characters
 *  in any of the strings affected by SpecificCharacterSet.
 *
 *  Revision 1.34  2004/04/16 13:24:07  joergr
 *  Restructured code to avoid default parameter values for "complex types" like
 *  OFString. Required for Sun CC 2.0.1.
 *
 *  Revision 1.33  2004/01/05 14:36:02  joergr
 *  Removed acknowledgements with e-mail addresses from CVS log.
 *
 *  Revision 1.32  2003/10/30 17:53:23  joergr
 *  Added full support for the ContentTemplateSequence (read/write, get/set
 *  template identification). Template constraints are not checked yet.
 *
 *  Revision 1.31  2003/10/09 13:18:16  joergr
 *  Added text from Supplement 66 to getCurrentRequestedProcedureEvidence() API
 *  comment.
 *
 *  Revision 1.30  2003/09/10 13:16:13  joergr
 *  Replaced PrivateCodingSchemeUID by new CodingSchemeIdentificationSequence as
 *  required by CP 324.
 *
 *  Revision 1.29  2003/08/07 18:01:42  joergr
 *  Removed libxml dependency from header files.
 *
 *  Revision 1.28  2003/08/07 12:31:46  joergr
 *  Added readXML functionality.
 *  Updated documentation to get rid of doxygen warnings.
 *  Made method isFinalized() const.
 *  Added new option to createRevisedVersion() which allows to keep the current
 *  list of predecessor documents.
 *  Changed interface to access the list of predecessor documents. Now using the
 *  existing class DSRSOPInstanceReferenceList.
 *  Added preliminary support for the Identical Documents Sequence.
 *  Renamed parameters/variables "string" to avoid name clash with STL class.
 *
 *  Revision 1.27  2002/05/14 08:15:24  joergr
 *  Updated comments.
 *
 *  Revision 1.26  2002/05/07 12:49:31  joergr
 *  Added support for the Current Requested Procedure Evidence Sequence and the
 *  Pertinent Other Evidence Sequence to the dcmsr module.
 *
 *  Revision 1.25  2002/04/16 13:50:52  joergr
 *  Added configurable support for C++ ANSI standard includes (e.g. streams).
 *
 *  Revision 1.24  2001/11/09 16:10:48  joergr
 *  Added preliminary support for Mammography CAD SR.
 *
 *  Revision 1.23  2001/09/26 13:04:06  meichel
 *  Adapted dcmsr to class OFCondition
 *
 *  Revision 1.22  2001/04/03 08:24:01  joergr
 *  Added new command line option: ignore relationship content constraints
 *  specified for each SR document class.
 *
 *  Revision 1.21  2001/01/29 17:37:14  joergr
 *  Added methods to support a new state of finalized and unfinalized documents.
 *
 *  Revision 1.20  2001/01/25 11:48:43  joergr
 *  Corrected typos / enhanced comments.
 *
 *  Revision 1.19  2001/01/18 15:53:33  joergr
 *  Added support for digital signatures.
 *
 *  Revision 1.18  2000/12/08 13:42:40  joergr
 *  Renamed createNewSeries(studyUID) to createNewSeriesInStudy(studyUID).
 *
 *  Revision 1.17  2000/11/16 13:31:27  joergr
 *  Corrected behaviour of updateDicomAttributes().
 *
 *  Revision 1.16  2000/11/14 17:27:25  joergr
 *  Added method to remove verification information.
 *
 *  Revision 1.15  2000/11/14 16:36:21  joergr
 *  Added methods to set the content date/time.
 *
 *  Revision 1.14  2000/11/14 11:45:50  joergr
 *  Corrected behaviour of method createRevisedVersion().
 *
 *  Revision 1.13  2000/11/13 14:19:06  joergr
 *  Updated comments.
 *
 *  Revision 1.12  2000/11/13 10:26:21  joergr
 *  Added output of optional observation datetime to rendered HTML page.
 *
 *  Revision 1.11  2000/11/10 18:10:20  joergr
 *  Corrected behaviour of createNewSOPInstance() and createRevisedDocument().
 *
 *  Revision 1.10  2000/11/10 17:44:49  joergr
 *  Added new methods to set the completion flag description, create new study/
 *  series UIDs. Added missing type 2 sequence to dataset. Corrected wrong format
 *  of predecessor documents sequence. Changed behaviour of completion/verification
 *  flags. Improved HTML and print/dump output.
 *
 *  Revision 1.9  2000/11/09 20:32:07  joergr
 *  Added support for non-ASCII characters in HTML 3.2 (use numeric value).
 *
 *  Revision 1.8  2000/11/07 18:12:25  joergr
 *  Enhanced rendered HTML output of date, time, datetime and pname.
 *
 *  Revision 1.7  2000/11/01 16:16:33  joergr
 *  Added support for conversion to XML.
 *  Added support for Cascading Style Sheet (CSS) used optionally for HTML
 *  rendering.
 *  Enhanced support for specific character sets.
 *
 *  Revision 1.6  2000/10/26 14:17:06  joergr
 *  Added support for "Comprehensive SR".
 *
 *  Revision 1.5  2000/10/18 17:01:47  joergr
 *  Made some functions inline.
 *
 *  Revision 1.4  2000/10/17 12:35:05  joergr
 *  Added methods to retrieve information on predecessor documents and
 *  verifying observers.
 *
 *  Revision 1.3  2000/10/16 16:30:23  joergr
 *  Added missing get/setSeriesDescription() methods.
 *  Updated comments.
 *
 *  Revision 1.2  2000/10/16 11:59:04  joergr
 *  Made method creating a new SOP instance public. Added check for correct SOP
 *  instance UID and SOP class UID to validity check.
 *
 *  Revision 1.1  2000/10/13 07:49:25  joergr
 *  Added new module 'dcmsr' providing access to DICOM structured reporting
 *  documents (supplement 23).  Doc++ documentation not yet completed.
 *
 *
 */

---

Generated on 6 Jan 2011 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.5.1