1 /* 2 * 3 * Copyright (C) 2000-2020, OFFIS e.V. 4 * All rights reserved. See COPYRIGHT file for details. 5 * 6 * This software and supporting documentation were developed by 7 * 8 * OFFIS e.V. 9 * R&D Division Health 10 * Escherweg 2 11 * D-26121 Oldenburg, Germany 12 * 13 * 14 * Module: dcmsr 15 * 16 * Author: Joerg Riesmeier 17 * 18 * Purpose: 19 * classes: DSRDocument 20 * 21 */ 22 23 24 #ifndef DSRDOC_H 25 #define DSRDOC_H 26 27 #include "dcmtk/config/osconfig.h" /* make sure OS specific configuration is included first */ 28 29 #include "dcmtk/dcmsr/dsrdoctr.h" 30 #include "dcmtk/dcmsr/dsrrtpl.h" 31 #include "dcmtk/dcmsr/dsrsoprf.h" 32 #include "dcmtk/dcmsr/dsrrefin.h" 33 #include "dcmtk/dcmsr/dsrcsidl.h" 34 35 #include "dcmtk/dcmdata/dcvrcs.h" 36 #include "dcmtk/dcmdata/dcvrda.h" 37 #include "dcmtk/dcmdata/dcvris.h" 38 #include "dcmtk/dcmdata/dcvrlo.h" 39 #include "dcmtk/dcmdata/dcvrpn.h" 40 #include "dcmtk/dcmdata/dcvrsh.h" 41 #include "dcmtk/dcmdata/dcvrtm.h" 42 #include "dcmtk/dcmdata/dcvrui.h" 43 44 #include "dcmtk/ofstd/ofstream.h" 45 46 47 /*---------------------* 48 * class declaration * 49 *---------------------*/ 50 51 /** Interface class for 'dcmsr' (DICOM Structured Reporting Documents). 52 * This class supports reading, writing, creation, printing and rendering of DICOM 53 * Structured Reporting (SR) documents. 54 * The list of supported SOP classes is available in file "dsrtypes.h". Also see 55 * DSRTypes::E_DocumentType. 56 */ 57 class DCMTK_DCMSR_EXPORT DSRDocument 58 : protected DSRTypes 59 { 60 61 public: 62 63 // --- constructors and destructor --- 64 65 /** (default) constructor. 66 * The parameter 'documentType' is optional and has a default value. 67 ** @param documentType type of the SR document (see DSRTypes::E_DocumentType) 68 */ 69 DSRDocument(const E_DocumentType documentType = DT_BasicTextSR); 70 71 /** destructor 72 */ 73 virtual ~DSRDocument(); 74 75 76 // --- misc routines --- 77 78 /** clear all internal member variables 79 */ 80 virtual void clear(); 81 82 /** check whether the current internal state is valid. 83 * The SR document is valid if the corresponding document tree is valid and 84 * the SOP instance UID as well as the SOP class UID are not "empty". 85 ** @return OFTrue if valid, OFFalse otherwise 86 */ 87 virtual OFBool isValid(); 88 89 /** check whether the document is finalized. 90 * A new document is originally not finalized but can be finalized using the method 91 * finalizeDocument(). This flag is e.g. used to indicate whether the entire document 92 * is digitally signed and, therefore, each newly added verifying observer would corrupt 93 * all previous signatures. 94 ** @return OFTrue if finalized, OFFalse otherwise 95 */ 96 virtual OFBool isFinalized() const; 97 98 99 // --- input and output --- 100 101 /** print current SR document to specified output stream. 102 * The output format is identical to that of the dsrdump command line tool. 103 ** @param stream output stream (e.g.\ COUT from "ofconsol.h") 104 * @param flags optional flag used to customize the output (see DSRTypes::PF_xxx) 105 ** @return status, EC_Normal if successful, an error code otherwise 106 */ 107 virtual OFCondition print(STD_NAMESPACE ostream &stream, 108 const size_t flags = 0); 109 110 /** read SR document from DICOM dataset. 111 * Please note that the current document is also deleted if the reading process fails. 112 * If logging is enabled, the reason for any error might be obtained from the log output. 113 * Also warning and debug messages are reported if the respective logger is enabled. 114 ** @param dataset reference to DICOM dataset from which the document should be read 115 * @param flags optional flag used to customize the reading process (see 116 * DSRTypes::RF_xxx). E.g. DSRTypes::RF_readDigitalSignatures indicates 117 * whether to read the digital signatures from the dataset or not. If set, 118 * the MACParametersSequence and the DigitalSignaturesSequence are read for 119 * the general document header (equivalent to top-level content item) and 120 * each content item of the document tree. 121 * If not removed manually (with DSRDocumentTree::removeSignatures()), 122 * the signatures are written back to the dataset when the write() method 123 * is called. 124 * Please note that the two signature sequences for any other sequence 125 * (e.g. VerifyingObserver or PredecessorDocuments) are never read. 126 ** @return status, EC_Normal if successful, an error code otherwise 127 */ 128 virtual OFCondition read(DcmItem &dataset, 129 const size_t flags = 0); 130 131 /** read patient data from DICOM dataset. 132 * The list of data elements that are read can be found under "Patient Module" in the 133 * member variable section of this class. Other data is not changed, so be careful 134 * when using this method. 135 * @param dataset reference to DICOM dataset from which the data should be read 136 * @param flags optional flag used to customize the reading process (see DSRTypes::RF_xxx) 137 ** @return status, EC_Normal if successful, an error code otherwise 138 */ 139 virtual OFCondition readPatientData(DcmItem &dataset, 140 const size_t flags = 0); 141 142 /** read study data from DICOM dataset. Also reads patient data. 143 * The list of data elements that are read can be found under "Patient Module" and 144 * "General Study Module" in the member variable section of this class. Other data 145 * is not changed, so be careful when using this method. 146 * @param dataset reference to DICOM dataset from which the data should be read 147 * @param flags optional flag used to customize the reading process (see DSRTypes::RF_xxx) 148 ** @return status, EC_Normal if successful, an error code otherwise 149 */ 150 virtual OFCondition readStudyData(DcmItem &dataset, 151 const size_t flags = 0); 152 153 /** write current SR document to DICOM dataset. 154 * Please note that the ContentTemplateSequence for the root content item is not written 155 * automatically for particular SOP Classes (e.g. Key Object Selection Document). 156 * Instead, the template identification has to be set manually for the root CONTAINER 157 * (see DSRDocumentTreeNode::setTemplateIdentification()). This is because the template 158 * constraints cannot be checked yet. 159 * If logging is enabled, warning and debug messages are reported to the log output. 160 ** @param dataset reference to DICOM dataset to which the current document should be 161 * written. The 'dataset' is not cleared before writing to it! 162 * @param markedItems optional stack where pointers to all 'marked' content items 163 * (DICOM datasets/items) are added to during the write process. 164 * Can be used to digitally sign parts of the document tree. 165 ** @return status, EC_Normal if successful, an error code otherwise 166 */ 167 virtual OFCondition write(DcmItem &dataset, 168 DcmStack *markedItems = NULL); 169 170 /** read SR document from XML file. 171 * The format (Schema) of the XML document is expected to conform to the output format 172 * of the writeXML() method. In addition, the document can be validated against an XML 173 * Schema by setting the flag DSRTypes::XF_validateSchema. 174 * Digital signatures in the XML document are not yet supported. 175 * Please note that the current document is also deleted if the parsing process fails. 176 ** @param filename name of the file from which the XML document is read ("-" for stdin) 177 * @param flags optional flag used to customize the reading process (see DSRTypes::XF_xxx) 178 ** @return status, EC_Normal if successful, an error code otherwise 179 */ 180 virtual OFCondition readXML(const OFString &filename, 181 const size_t flags = 0); 182 183 /** write current SR document in XML format. 184 * The output format is identical to that of the dsr2xml command line tool. Digital 185 * signatures in the XML document are not yet supported. 186 ** @param stream output stream to which the XML document is written 187 * @param flags optional flag used to customize the output (see DSRTypes::XF_xxx) 188 ** @return status, EC_Normal if successful, an error code otherwise 189 */ 190 virtual OFCondition writeXML(STD_NAMESPACE ostream &stream, 191 const size_t flags = 0); 192 193 /** render current SR document in HTML/XHTML format. 194 * The output format is identical to that of the dsr2html command line tool. 195 ** @param stream output stream to which the HTML/XHTML document is written 196 * @param flags optional flag used to customize the output (see DSRTypes::HF_xxx) 197 * @param styleSheet optional filename/URL of a Cascading Style Sheet (CSS) 198 ** @return status, EC_Normal if successful, an error code otherwise 199 */ 200 virtual OFCondition renderHTML(STD_NAMESPACE ostream &stream, 201 const size_t flags = 0, 202 const char *styleSheet = NULL); 203 204 205 // --- get/set misc attributes --- 206 207 /** get the current SR document type 208 ** @return document type (might be DSRTypes::DT_invalid if read from dataset) 209 */ 210 virtual E_DocumentType getDocumentType() const; 211 212 /** get document tree 213 ** @return reference to the document tree 214 */ getTree()215 inline DSRDocumentTree &getTree() 216 { 217 return DocumentTree; 218 } 219 220 /** set document tree. 221 * Replace the currently stored document tree with the given one. Please note that the 222 * given 'tree' is checked before setting it, i.e. only a valid document tree is accepted. 223 * However, a new SOP instance is never created. If needed, this has to be done with 224 * createNewSOPInstance() in addition to or with createNewDocument() before this method 225 * is called. 226 ** @param tree document tree to be set (content will be copied) 227 ** @return status, EC_Normal if successful, an error code otherwise 228 */ 229 virtual OFCondition setTree(const DSRDocumentTree &tree); 230 231 /** set document tree from root template. 232 * Replace the currently stored document tree with the one from the given root template. 233 * By default, this method expands the tree, i.e. instances of DSRIncludedTemplateTreeNode 234 * that were added to the tree with DSRDocumentSubTree::includeTemplate() are replaced by 235 * their content, i.e. by the internally managed subtree. 236 * Please note that the additional comments on the above setTree() method also apply. 237 ** @param rootTemplate template specifying the document tree to be set (content will be 238 * copied). This parameter cannot be "const" because of 239 * DSRRootTemplate::getTree(), which is called internally and which 240 * modifies the tree. 241 * @param expandTree optional flag that allows for disabling the expanding of the 242 * document tree before setting it. Please note that various 243 * output methods like write() or renderHTML() do not yet work on 244 * such trees. 245 ** @return status, EC_Normal if successful, an error code otherwise 246 */ 247 virtual OFCondition setTreeFromRootTemplate(DSRRootTemplate &rootTemplate, 248 const OFBool expandTree = OFTrue); 249 250 /** get specific character set type. 251 * If the type is unknown, the original DICOM defined term can be retrieved 252 * with the method getSpecificCharacterSet(). 253 ** @return character set type (might be DSRTypes::CS_invalid or DSRTypes::CS_unknown) 254 */ 255 virtual E_CharacterSet getSpecificCharacterSetType() const; 256 257 /** set specific character set type. 258 * The DICOM defined term (see member variable SpecificCharacterSet) is set accordingly. 259 ** @param characterSet specific character set to be set (use DSRTypes::CS_invalid to reset 260 * to the default value, which is "unspecified") 261 ** @return status, EC_Normal if successful, an error code otherwise 262 */ 263 virtual OFCondition setSpecificCharacterSetType(const E_CharacterSet characterSet); 264 265 /** get document preliminary flag. 266 * @note Not applicable to document types that use the Key Object Document Module. 267 ** @return preliminary flag (might be DSRTypes::PF_invalid if not specified) 268 */ 269 virtual E_PreliminaryFlag getPreliminaryFlag() const; 270 271 /** set document preliminary flag. 272 * According to the DICOM standard, the concept of "completeness" is independent of the 273 * concept of "preliminary" or "final". Therefore, this flag can be specified separately. 274 * @note Not applicable to document types that use the Key Object Document Module. 275 ** @param flag preliminary flag to be set (use DSRTypes::PF_invalid to omit this optional 276 * value) 277 ** @return status, EC_Normal if successful, an error code otherwise 278 */ 279 virtual OFCondition setPreliminaryFlag(const E_PreliminaryFlag flag); 280 281 /** get document completion flag. 282 * According to the DICOM standard, this flag describes the estimated degree of completeness 283 * of an SR Document. See DICOM standard for details. 284 * @note Not applicable to document types that use the Key Object Document Module. 285 ** @return completion flag (might be DSRTypes::CF_invalid if read from dataset) 286 */ 287 virtual E_CompletionFlag getCompletionFlag() const; 288 289 /** get document verification flag. 290 * @note Not applicable to document types that use the Key Object Document Module. 291 ** @return verification flag (might be DSRTypes::VF_invalid if read from dataset) 292 */ 293 virtual E_VerificationFlag getVerificationFlag() const; 294 295 /** check whether there are one or more verifying observers. 296 * @note Not applicable to document types that use the Key Object Document Module. 297 ** @return OFTrue if there is at least one verifying observer, OFFalse otherwise 298 */ 299 virtual OFBool hasVerifyingObservers() const; 300 301 /** get number of verifying observers. 302 * A document can be verified more than once. The verification flag should be VERIFIED 303 * if any verifying observer is specified. The details on the observer can be retrieved 304 * using the getVerifyingObserver() methods. 305 * @note Not applicable to document types that use the Key Object Document Module. 306 ** @return number of verifying observers (if any), 0 otherwise 307 */ 308 virtual size_t getNumberOfVerifyingObservers() const; 309 310 /** get information about a verifying observer. 311 * All reference variables are cleared before the information is retrieved, i.e. if an error 312 * occurs (return value != EC_Normal) non-empty variables do contain valid (empty) data. 313 * @note Not applicable to document types that use the Key Object Document Module. 314 ** @param idx index of the verifying observer to be retrieved (starting with 1). 315 * Use getNumberOfVerifyingObservers() to get the maximum value. 316 * @param dateTime reference to variable where the date and time when this document 317 * has been verified should be stored (required) 318 * @param observerName reference to variable where the name of the person who has verified 319 * this document should be stored (required) 320 * @param organization reference to variable where the name of the organization to which 321 * the observer belongs should be stored (required) 322 ** @return status, EC_Normal if successful, an error code otherwise 323 */ 324 virtual OFCondition getVerifyingObserver(const size_t idx, 325 OFString &dateTime, 326 OFString &observerName, 327 OFString &organization); 328 329 /** get information about a verifying observer. 330 * All reference variables are cleared before the information is retrieved, i.e. if an error 331 * occurs (return value != EC_Normal) non-empty variables do contain valid (empty) data. 332 * @note Not applicable to document types that use the Key Object Document Module. 333 ** @param idx index of the verifying observer to be retrieved (starting with 1). 334 * Use getNumberOfVerifyingObservers() to get the maximum value. 335 * @param dateTime reference to variable where the date and time when this document 336 * has been verified should be stored (required) 337 * @param observerName reference to variable where the name of the person who has verified 338 * this document should be stored (required) 339 * @param observerCode reference to variable where the observer code should be stored. 340 * code identifying the verifying observer (optional, see previous method) 341 * @param organization reference to variable where the name of the organization to which 342 * the observer belongs should be stored (required) 343 ** @return status, EC_Normal if successful, an error code otherwise 344 */ 345 virtual OFCondition getVerifyingObserver(const size_t idx, 346 OFString &dateTime, 347 OFString &observerName, 348 DSRCodedEntryValue &observerCode, 349 OFString &organization); 350 351 /** get list of predecessor documents. 352 * A document can have more than one (direct) predecessor document. This is e.g. the case 353 * when two or more documents have been merged to create it. The corresponding method 354 * createRevisedVersion() automatically adds a reference to the current document. 355 * The DICOM standard states: "[The Predecessor Documents Sequence] Shall refer to SR SOP 356 * Instances (e.g. prior or provisional reports) whose content has been wholly or partially 357 * included in this document with or without modification." and "[...] the use of the 358 * Predecessor Document Sequence allows tracing back to the input SR Document, which in this 359 * case is the previous version." 360 * @note Not applicable to document types that use the Key Object Document Module. 361 ** @return reference to list object 362 */ 363 virtual DSRSOPInstanceReferenceList &getPredecessorDocuments(); 364 365 /** get list of identical documents. 366 * Please note that currently the user is responsible for filling and modifying the content of 367 * this list. However, the list is automatically cleared when a new instance is created (incl. 368 * a revised version of the current document). Possibly, there will be a createDuplicate() 369 * method or the like in the future which creates an identical copy of the current document in 370 * a new study/series. 371 * The DICOM standard states: "If identical copies of an SR Document are to be included in 372 * multiple Studies then the entire SR Document shall be duplicated with appropriate changes 373 * for inclusion into the different Studies (i.e. Study Instance UID, Series Instance UID, SOP 374 * Instance UID, Identical Documents Sequence etc.). The Identical Documents Sequence Attribute 375 * in each SOP Instance shall contain references to all other duplicate SOP Instances." 376 ** @return reference to list object 377 */ 378 virtual DSRSOPInstanceReferenceList &getIdenticalDocuments(); 379 380 /** get list of referenced SOP instances (Current Requested Procedure Evidence). 381 * The DICOM standard states: "The intent of the Current Requested Procedure Evidence Sequence 382 * is to reference all evidence created in order to satisfy the current Requested Procedure(s) 383 * for this SR Document. This shall include, but is not limited to, all current evidence 384 * referenced in the content tree." and "For a completed SR Document satisfying (i.e., being 385 * the final report for) the current Requested Procedure(s), this sequence shall list the full 386 * set of Composite SOP Instances created for the current Requested Procedure(s). For other 387 * SOP Instances that include the SR Document General Module, this sequence shall contain at 388 * minimum the set of Composite SOP Instances from the current Requested Procedure(s) that are 389 * referenced in the content tree." and "In the context of the Key Object Selection, the 390 * current evidence is considered to be only the set of instances referenced within the Key 391 * Object Selection." 392 ** @return reference to list object 393 */ 394 virtual DSRSOPInstanceReferenceList &getCurrentRequestedProcedureEvidence(); 395 396 /** get list of referenced SOP instances (Pertinent Other Evidence). 397 * The DICOM standard states: "The Pertinent Other Evidence Sequence attribute is used to 398 * reference all other evidence considered pertinent for this SR Document that is not listed 399 * in the Current Requested Procedure Evidence Sequence. This requires that the same SOP 400 * Instance shall not be referenced in both of these Sequences." 401 * @note Not applicable to document types that use the Key Object Document Module. 402 ** @return reference to list object 403 */ 404 virtual DSRSOPInstanceReferenceList &getPertinentOtherEvidence(); 405 406 /** get list of referenced SOP instances significantly related to the current SOP instance. 407 * The DICOM standard states: "Such referenced Instances may include equivalent documents or 408 * renderings of this document. [...] Required if the identity of a CDA Document equivalent 409 * to the current SOP Instance is known at the time of creation of this SOP instance. May be 410 * present otherwise." The Purpose of Reference Code should be taken from Defined Context 411 * Group 7006 (SR Document Purposes of Reference). 412 * Note: An equivalent rendering of the document might be provided as an "Encapsulated PDF" 413 * DICOM object. 414 * @note Not applicable to document types that use the Key Object Document Module. 415 ** @return reference to list object 416 */ 417 virtual DSRReferencedInstanceList &getReferencedInstances(); 418 419 /** get list of coding schemes used (Coding Scheme Identification). 420 * The Coding Scheme Identification Sequence maps Coding Scheme Designators to an external coding 421 * system registration, or to a private or local coding scheme. See DICOM standard for details. 422 ** @return reference to list object 423 */ 424 virtual DSRCodingSchemeIdentificationList &getCodingSchemeIdentification(); 425 426 427 // --- get DICOM string attributes --- 428 429 /** get specific character set 430 ** @param value reference to variable in which the value should be stored 431 * @param pos index of the value to get (0..vm-1), -1 for all components 432 ** @return status, EC_Normal if successful, an error code otherwise 433 */ 434 virtual OFCondition getSpecificCharacterSet(OFString &value, 435 const signed long pos = 0) const; 436 437 /** get completion flag description. 438 * @note Not applicable to document types that use the Key Object Document Module. 439 ** @param value reference to variable in which the value should be stored 440 * @param pos index of the value to get (0..vm-1), -1 for all components 441 ** @return status, EC_Normal if successful, an error code otherwise 442 */ 443 virtual OFCondition getCompletionFlagDescription(OFString &value, 444 const signed long pos = 0) const; 445 446 /** get modality 447 ** @param value reference to variable in which the value should be stored 448 * @param pos index of the value to get (0..vm-1), -1 for all components 449 ** @return status, EC_Normal if successful, an error code otherwise 450 */ 451 virtual OFCondition getModality(OFString &value, 452 const signed long pos = 0) const; 453 454 /** get SOP class UID 455 ** @param value reference to variable in which the value should be stored 456 * @param pos index of the value to get (0..vm-1), -1 for all components 457 ** @return status, EC_Normal if successful, an error code otherwise 458 */ 459 virtual OFCondition getSOPClassUID(OFString &value, 460 const signed long pos = 0) const; 461 462 /** get study instance UID 463 ** @param value reference to variable in which the value should be stored 464 * @param pos index of the value to get (0..vm-1), -1 for all components 465 ** @return status, EC_Normal if successful, an error code otherwise 466 */ 467 virtual OFCondition getStudyInstanceUID(OFString &value, 468 const signed long pos = 0) const; 469 470 /** get series instance UID 471 ** @param value reference to variable in which the value should be stored 472 * @param pos index of the value to get (0..vm-1), -1 for all components 473 ** @return status, EC_Normal if successful, an error code otherwise 474 */ 475 virtual OFCondition getSeriesInstanceUID(OFString &value, 476 const signed long pos = 0) const; 477 478 /** get SOP instance UID 479 ** @param value reference to variable in which the value should be stored 480 * @param pos index of the value to get (0..vm-1), -1 for all components 481 ** @return status, EC_Normal if successful, an error code otherwise 482 */ 483 virtual OFCondition getSOPInstanceUID(OFString &value, 484 const signed long pos = 0) const; 485 486 /** get instance creator UID 487 ** @param value reference to variable in which the value should be stored 488 * @param pos index of the value to get (0..vm-1), -1 for all components 489 ** @return status, EC_Normal if successful, an error code otherwise 490 */ 491 virtual OFCondition getInstanceCreatorUID(OFString &value, 492 const signed long pos = 0) const; 493 494 /** get timezone offset from UTC 495 ** @param value reference to variable in which the value should be stored 496 * @param pos index of the value to get (0..vm-1), -1 for all components 497 ** @return status, EC_Normal if successful, an error code otherwise 498 */ 499 virtual OFCondition getTimezoneOffsetFromUTC(OFString &value, 500 const signed long pos = 0) const; 501 502 /** get patient's name 503 ** @param value reference to variable in which the value should be stored 504 * @param pos index of the value to get (0..vm-1), -1 for all components 505 ** @return status, EC_Normal if successful, an error code otherwise 506 */ 507 virtual OFCondition getPatientName(OFString &value, 508 const signed long pos = 0) const; 509 510 /** get patient's birth date 511 ** @param value reference to variable in which the value should be stored 512 * @param pos index of the value to get (0..vm-1), -1 for all components 513 ** @return status, EC_Normal if successful, an error code otherwise 514 */ 515 virtual OFCondition getPatientBirthDate(OFString &value, 516 const signed long pos = 0) const; 517 518 /** get patient's sex 519 ** @param value reference to variable in which the value should be stored 520 * @param pos index of the value to get (0..vm-1), -1 for all components 521 ** @return status, EC_Normal if successful, an error code otherwise 522 */ 523 virtual OFCondition getPatientSex(OFString &value, 524 const signed long pos = 0) const; 525 526 /** get referring physician's name 527 ** @param value reference to variable in which the value should be stored 528 * @param pos index of the value to get (0..vm-1), -1 for all components 529 ** @return status, EC_Normal if successful, an error code otherwise 530 */ 531 virtual OFCondition getReferringPhysicianName(OFString &value, 532 const signed long pos = 0) const; 533 534 /** get study description 535 ** @param value reference to variable in which the value should be stored 536 * @param pos index of the value to get (0..vm-1), -1 for all components 537 ** @return status, EC_Normal if successful, an error code otherwise 538 */ 539 virtual OFCondition getStudyDescription(OFString &value, 540 const signed long pos = 0) const; 541 542 /** get series description 543 ** @param value reference to variable in which the value should be stored 544 * @param pos index of the value to get (0..vm-1), -1 for all components 545 ** @return status, EC_Normal if successful, an error code otherwise 546 */ 547 virtual OFCondition getSeriesDescription(OFString &value, 548 const signed long pos = 0) const; 549 550 /** get protocol name 551 ** @param value reference to variable in which the value should be stored 552 * @param pos index of the value to get (0..vm-1), -1 for all components 553 ** @return status, EC_Normal if successful, an error code otherwise 554 */ 555 virtual OFCondition getProtocolName(OFString &value, 556 const signed long pos = 0) const; 557 558 /** get manufacturer 559 ** @param value reference to variable in which the value should be stored 560 * @param pos index of the value to get (0..vm-1), -1 for all components 561 ** @return status, EC_Normal if successful, an error code otherwise 562 */ 563 virtual OFCondition getManufacturer(OFString &value, 564 const signed long pos = 0) const; 565 566 /** get manufacturer's model name 567 ** @param value reference to variable in which the value should be stored 568 * @param pos index of the value to get (0..vm-1), -1 for all components 569 ** @return status, EC_Normal if successful, an error code otherwise 570 */ 571 virtual OFCondition getManufacturerModelName(OFString &value, 572 const signed long pos = 0) const; 573 574 /** get device serial number 575 ** @param value reference to variable in which the value should be stored 576 * @param pos index of the value to get (0..vm-1), -1 for all components 577 ** @return status, EC_Normal if successful, an error code otherwise 578 */ 579 virtual OFCondition getDeviceSerialNumber(OFString &value, 580 const signed long pos = 0) const; 581 582 /** get software version(s) 583 ** @param value reference to variable in which the value should be stored 584 * @param pos index of the value to get (0..vm-1), -1 for all components 585 ** @return status, EC_Normal if successful, an error code otherwise 586 */ 587 virtual OFCondition getSoftwareVersions(OFString &value, 588 const signed long pos = 0) const; 589 590 /** get synchronization frame of reference UID 591 ** @param value reference to variable in which the value should be stored 592 * @param pos index of the value to get (0..vm-1), -1 for all components 593 ** @return status, EC_Normal if successful, an error code otherwise 594 */ 595 virtual OFCondition getSynchronizationFrameOfReferenceUID(OFString &value, 596 const signed long pos = 0) const; 597 598 /** get synchronization trigger 599 ** @param value reference to variable in which the value should be stored 600 * @param pos index of the value to get (0..vm-1), -1 for all components 601 ** @return status, EC_Normal if successful, an error code otherwise 602 */ 603 virtual OFCondition getSynchronizationTrigger(OFString &value, 604 const signed long pos = 0) const; 605 606 /** get acquisition time synchronized 607 ** @param value reference to variable in which the value should be stored 608 * @param pos index of the value to get (0..vm-1), -1 for all components 609 ** @return status, EC_Normal if successful, an error code otherwise 610 */ 611 virtual OFCondition getAcquisitionTimeSynchronized(OFString &value, 612 const signed long pos = 0) const; 613 614 /** get study date 615 ** @param value reference to variable in which the value should be stored 616 * @param pos index of the value to get (0..vm-1), -1 for all components 617 ** @return status, EC_Normal if successful, an error code otherwise 618 */ 619 virtual OFCondition getStudyDate(OFString &value, 620 const signed long pos = 0) const; 621 622 /** get study time 623 ** @param value reference to variable in which the value should be stored 624 * @param pos index of the value to get (0..vm-1), -1 for all components 625 ** @return status, EC_Normal if successful, an error code otherwise 626 */ 627 virtual OFCondition getStudyTime(OFString &value, 628 const signed long pos = 0) const; 629 630 /** get series date 631 ** @param value reference to variable in which the value should be stored 632 * @param pos index of the value to get (0..vm-1), -1 for all components 633 ** @return status, EC_Normal if successful, an error code otherwise 634 */ 635 virtual OFCondition getSeriesDate(OFString &value, 636 const signed long pos = 0) const; 637 638 /** get series time 639 ** @param value reference to variable in which the value should be stored 640 * @param pos index of the value to get (0..vm-1), -1 for all components 641 ** @return status, EC_Normal if successful, an error code otherwise 642 */ 643 virtual OFCondition getSeriesTime(OFString &value, 644 const signed long pos = 0) const; 645 646 /** get instance creation date 647 ** @param value reference to variable in which the value should be stored 648 * @param pos index of the value to get (0..vm-1), -1 for all components 649 ** @return status, EC_Normal if successful, an error code otherwise 650 */ 651 virtual OFCondition getInstanceCreationDate(OFString &value, 652 const signed long pos = 0) const; 653 654 /** get instance creation time 655 ** @param value reference to variable in which the value should be stored 656 * @param pos index of the value to get (0..vm-1), -1 for all components 657 ** @return status, EC_Normal if successful, an error code otherwise 658 */ 659 virtual OFCondition getInstanceCreationTime(OFString &value, 660 const signed long pos = 0) const; 661 662 /** get content date 663 ** @param value reference to variable in which the value should be stored 664 * @param pos index of the value to get (0..vm-1), -1 for all components 665 ** @return status, EC_Normal if successful, an error code otherwise 666 */ 667 virtual OFCondition getContentDate(OFString &value, 668 const signed long pos = 0) const; 669 670 /** get content time 671 ** @param value reference to variable in which the value should be stored 672 * @param pos index of the value to get (0..vm-1), -1 for all components 673 ** @return status, EC_Normal if successful, an error code otherwise 674 */ 675 virtual OFCondition getContentTime(OFString &value, 676 const signed long pos = 0) const; 677 678 /** get study ID 679 ** @param value reference to variable in which the value should be stored 680 * @param pos index of the value to get (0..vm-1), -1 for all components 681 ** @return status, EC_Normal if successful, an error code otherwise 682 */ 683 virtual OFCondition getStudyID(OFString &value, 684 const signed long pos = 0) const; 685 686 /** get patient ID 687 ** @param value reference to variable in which the value should be stored 688 * @param pos index of the value to get (0..vm-1), -1 for all components 689 ** @return status, EC_Normal if successful, an error code otherwise 690 */ 691 virtual OFCondition getPatientID(OFString &value, 692 const signed long pos = 0) const; 693 694 /** get issuer of patient ID 695 ** @param value reference to variable in which the value should be stored 696 * @param pos index of the value to get (0..vm-1), -1 for all components 697 ** @return status, EC_Normal if successful, an error code otherwise 698 */ 699 virtual OFCondition getIssuerOfPatientID(OFString &value, 700 const signed long pos = 0) const; 701 702 /** get series number 703 ** @param value reference to variable in which the value should be stored 704 * @param pos index of the value to get (0..vm-1), -1 for all components 705 ** @return status, EC_Normal if successful, an error code otherwise 706 */ 707 virtual OFCondition getSeriesNumber(OFString &value, 708 const signed long pos = 0) const; 709 710 /** get instance number 711 ** @param value reference to variable in which the value should be stored 712 * @param pos index of the value to get (0..vm-1), -1 for all components 713 ** @return status, EC_Normal if successful, an error code otherwise 714 */ 715 virtual OFCondition getInstanceNumber(OFString &value, 716 const signed long pos = 0) const; 717 718 /** get accession number 719 ** @param value reference to variable in which the value should be stored 720 * @param pos index of the value to get (0..vm-1), -1 for all components 721 ** @return status, EC_Normal if successful, an error code otherwise 722 */ 723 virtual OFCondition getAccessionNumber(OFString &value, 724 const signed long pos = 0) const; 725 726 727 // --- set DICOM string attributes --- 728 729 /** set specific character set. The internal enumerated value is set accordingly. 730 * Please note that this method does not return an error if the given 'value' is not 731 * defined by the DICOM standard or not supported by this class, e.g. when no mapping 732 * to the character set names needed for HTML/XHTML or XML output is defined. 733 * If needed, check the return value of the method getSpecificCharacterSetType() for 734 * DSRTypes::CS_invalid or DSRTypes::CS_unknown after calling this method. 735 ** @param value value to be set (single or multiple values) or "" for no value 736 * @param check check 'value' for conformance with VR (CS) and VM (1-n) if enabled 737 ** @return status, EC_Normal if successful, an error code otherwise 738 */ 739 virtual OFCondition setSpecificCharacterSet(const OFString &value, 740 const OFBool check = OFTrue); 741 742 /** set completion flag description. 743 * @note Not applicable to document types that use the Key Object Document Module. 744 ** @param value explanation of the value that is set for completion flag. If an empty 745 * string is passed, the description is removed from the dataset (type 3). 746 * @param check check 'value' for conformance with VR (LO) and VM (1) if enabled 747 ** @return status, EC_Normal if successful, an error code otherwise 748 */ 749 virtual OFCondition setCompletionFlagDescription(const OFString &value, 750 const OFBool check = OFTrue); 751 752 /** set timezone offset from UTC 753 ** @param value value to be set (single value only) or "" for no value 754 * @param check check 'value' for conformance with VR (SH) and VM (1) if enabled. 755 * Please note that it is not checked whether the 'value' conforms 756 * to the requirements of a valid timezone offset (see DICOM PS3.3). 757 ** @return status, EC_Normal if successful, an error code otherwise 758 */ 759 virtual OFCondition setTimezoneOffsetFromUTC(const OFString &value, 760 const OFBool check = OFTrue); 761 762 /** set patient's name 763 ** @param value value to be set (single value only) or "" for no value 764 * @param check check 'value' for conformance with VR (PN) and VM (1) if enabled 765 ** @return status, EC_Normal if successful, an error code otherwise 766 */ 767 virtual OFCondition setPatientName(const OFString &value, 768 const OFBool check = OFTrue); 769 770 /** set patient's birth date 771 ** @param value value to be set (single value only) or "" for no value 772 * @param check check 'value' for conformance with VR (DA) and VM (1) if enabled 773 ** @return status, EC_Normal if successful, an error code otherwise 774 */ 775 virtual OFCondition setPatientBirthDate(const OFString &value, 776 const OFBool check = OFTrue); 777 778 /** set patient's sex 779 ** @param value value to be set (single value only) or "" for no value 780 * @param check check 'value' for conformance with VR (CS) and VM (1) if enabled 781 ** @return status, EC_Normal if successful, an error code otherwise 782 */ 783 virtual OFCondition setPatientSex(const OFString &value, 784 const OFBool check = OFTrue); 785 786 /** set referring physician's name 787 ** @param value value to be set (single value only) or "" for no value 788 * @param check check 'value' for conformance with VR (PN) and VM (1) if enabled 789 ** @return status, EC_Normal if successful, an error code otherwise 790 */ 791 virtual OFCondition setReferringPhysicianName(const OFString &value, 792 const OFBool check = OFTrue); 793 794 /** set study description 795 ** @param value value to be set (single value only) or "" for no value 796 * @param check check 'value' for conformance with VR (LO) and VM (1) if enabled 797 ** @return status, EC_Normal if successful, an error code otherwise 798 */ 799 virtual OFCondition setStudyDescription(const OFString &value, 800 const OFBool check = OFTrue); 801 802 /** set series description 803 ** @param value value to be set (single value only) or "" for no value 804 * @param check check 'value' for conformance with VR (LO) and VM (1) if enabled 805 ** @return status, EC_Normal if successful, an error code otherwise 806 */ 807 virtual OFCondition setSeriesDescription(const OFString &value, 808 const OFBool check = OFTrue); 809 810 /** set protocol name 811 ** @param value value to be set (single value only) or "" for no value 812 * @param check check 'value' for conformance with VR (LO) and VM (1) if enabled 813 ** @return status, EC_Normal if successful, an error code otherwise 814 */ 815 virtual OFCondition setProtocolName(const OFString &value, 816 const OFBool check = OFTrue); 817 818 /** set manufacturer 819 ** @param value value to be set (single value only) or "" for no value 820 * @param check check 'value' for conformance with VR (LO) and VM (1) if enabled 821 ** @return status, EC_Normal if successful, an error code otherwise 822 */ 823 virtual OFCondition setManufacturer(const OFString &value, 824 const OFBool check = OFTrue); 825 826 /** set manufacturer's model name 827 ** @param value value to be set (single value only) or "" for no value 828 * @param check check 'value' for conformance with VR (LO) and VM (1) if enabled 829 ** @return status, EC_Normal if successful, an error code otherwise 830 */ 831 virtual OFCondition setManufacturerModelName(const OFString &value, 832 const OFBool check = OFTrue); 833 834 /** set device serial number 835 ** @param value value to be set (single value only) or "" for no value 836 * @param check check 'value' for conformance with VR (LO) and VM (1) if enabled 837 ** @return status, EC_Normal if successful, an error code otherwise 838 */ 839 virtual OFCondition setDeviceSerialNumber(const OFString &value, 840 const OFBool check = OFTrue); 841 842 /** set software version(s) 843 ** @param value value to be set (possibly multi-valued) or "" for no value 844 * @param check check 'value' for conformance with VR (LO) and VM (1-n) if enabled 845 ** @return status, EC_Normal if successful, an error code otherwise 846 */ 847 virtual OFCondition setSoftwareVersions(const OFString &value, 848 const OFBool check = OFTrue); 849 850 /** set synchronization frame of reference UID 851 ** @param value value to be set (single value only) or "" for no value 852 * @param check check 'value' for conformance with VR (UI) and VM (1) if enabled 853 ** @return status, EC_Normal if successful, an error code otherwise 854 */ 855 virtual OFCondition setSynchronizationFrameOfReferenceUID(const OFString &value, 856 const OFBool check = OFTrue); 857 /** set synchronization trigger 858 ** @param value value to be set (single value only) or "" for no value 859 * @param check check 'value' for conformance with VR (CS) and VM (1) if enabled 860 ** @return status, EC_Normal if successful, an error code otherwise 861 */ 862 virtual OFCondition setSynchronizationTrigger(const OFString &value, 863 const OFBool check = OFTrue); 864 865 /** set acquisition time synchronized 866 ** @param value value to be set (single value only) or "" for no value 867 * @param check check 'value' for conformance with VR (CS) and VM (1) if enabled 868 ** @return status, EC_Normal if successful, an error code otherwise 869 */ 870 virtual OFCondition setAcquisitionTimeSynchronized(const OFString &value, 871 const OFBool check = OFTrue); 872 873 /** set content date 874 ** @param value value to be set (single value only). If an empty string is passed, 875 * the current date is set when displaying or writing the document since 876 * the corresponding DICOM attribute is mandatory. 877 * @param check check 'value' for conformance with VR (DA) and VM (1) if enabled 878 ** @return status, EC_Normal if successful, an error code otherwise 879 */ 880 virtual OFCondition setContentDate(const OFString &value, 881 const OFBool check = OFTrue); 882 883 /** set content time 884 ** @param value value to be set (single value only). If an empty string is passed, 885 * the current time is set when displaying or writing the document since 886 * the corresponding DICOM attribute is mandatory. 887 * @param check check 'value' for conformance with VR (TM) and VM (1) if enabled 888 ** @return status, EC_Normal if successful, an error code otherwise 889 */ 890 virtual OFCondition setContentTime(const OFString &value, 891 const OFBool check = OFTrue); 892 893 /** set study date 894 ** @param value value to be set (single value only) or "" for no value 895 * @param check check 'value' for conformance with VR (DA) and VM (1) if enabled 896 ** @return status, EC_Normal if successful, an error code otherwise 897 */ 898 virtual OFCondition setStudyDate(const OFString &value, 899 const OFBool check = OFTrue); 900 901 /** set study time 902 ** @param value value to be set (single value only) or "" for no value 903 * @param check check 'value' for conformance with VR (TM) and VM (1) if enabled 904 ** @return status, EC_Normal if successful, an error code otherwise 905 */ 906 virtual OFCondition setStudyTime(const OFString &value, 907 const OFBool check = OFTrue); 908 909 /** set series date 910 ** @param value value to be set (single value only) or "" for no value 911 * @param check check 'value' for conformance with VR (DA) and VM (1) if enabled 912 ** @return status, EC_Normal if successful, an error code otherwise 913 */ 914 virtual OFCondition setSeriesDate(const OFString &value, 915 const OFBool check = OFTrue); 916 917 /** set series time 918 ** @param value value to be set (single value only) or "" for no value 919 * @param check check 'value' for conformance with VR (TM) and VM (1) if enabled 920 ** @return status, EC_Normal if successful, an error code otherwise 921 */ 922 virtual OFCondition setSeriesTime(const OFString &value, 923 const OFBool check = OFTrue); 924 925 /** set study ID 926 ** @param value value to be set (single value only) or "" for no value 927 * @param check check 'value' for conformance with VR (SH) and VM (1) if enabled 928 ** @return status, EC_Normal if successful, an error code otherwise 929 */ 930 virtual OFCondition setStudyID(const OFString &value, 931 const OFBool check = OFTrue); 932 933 /** set patient ID 934 ** @param value value to be set (single value only) or "" for no value 935 * @param check check 'value' for conformance with VR (LO) and VM (1) if enabled 936 ** @return status, EC_Normal if successful, an error code otherwise 937 */ 938 virtual OFCondition setPatientID(const OFString &value, 939 const OFBool check = OFTrue); 940 941 /** set issuer of patient ID 942 ** @param value value to be set (single value only) or "" for no value 943 * @param check check 'value' for conformance with VR (LO) and VM (1) if enabled 944 ** @return status, EC_Normal if successful, an error code otherwise 945 */ 946 virtual OFCondition setIssuerOfPatientID(const OFString &value, 947 const OFBool check = OFTrue); 948 949 /** set series number 950 ** @param value value to be set (single value only). If an empty string is passed, 951 * the value "1" is set when displaying or writing the document since 952 * the corresponding DICOM attribute is mandatory. 953 * @param check check 'value' for conformance with VR (IS) and VM (1) if enabled 954 ** @return status, EC_Normal if successful, an error code otherwise 955 */ 956 virtual OFCondition setSeriesNumber(const OFString &value, 957 const OFBool check = OFTrue); 958 959 /** set instance number 960 ** @param value value to be set (single value only). If an empty string is passed, 961 * the value "1" is set when displaying or writing the document since 962 * the corresponding DICOM attribute is mandatory. 963 * @param check check 'value' for conformance with VR (IS) and VM (1) if enabled 964 ** @return status, EC_Normal if successful, an error code otherwise 965 */ 966 virtual OFCondition setInstanceNumber(const OFString &value, 967 const OFBool check = OFTrue); 968 969 /** set accession number 970 ** @param value value to be set (single value only) or "" for no value 971 * @param check check 'value' for conformance with VR (SH) and VM (1) if enabled 972 ** @return status, EC_Normal if successful, an error code otherwise 973 */ 974 virtual OFCondition setAccessionNumber(const OFString &value, 975 const OFBool check = OFTrue); 976 977 978 // --- document management functions --- 979 980 /** create new study. 981 * After generating a new study instance UID the method createNewSeries() is called, 982 * i.e. also a new series instance UID and SOP instance UID are generated. This is 983 * a requirement of the DICOM standard. All other study-related attributes are 984 * cleared. 985 */ 986 virtual void createNewStudy(); 987 988 /** create a new series. 989 * After generating a new series instance UID the method createNewSOPInstance() is 990 * called, i.e. also a new SOP instance UID is generated. This is a requirement of 991 * the DICOM standard. All other series-related attributes are cleared. 992 */ 993 virtual void createNewSeries(); 994 995 /** create a new series within a given study. 996 * After generating a new series instance UID within the given study the method 997 * createNewSOPInstance() is called, i.e. also a SOP instance UID is generated. 998 * This is a requirement of the DICOM standard. 999 * NB: There is no mechanism that makes sure that the study-related attributes are 1000 * consistent for all series of a study. This either has to be done manually 1001 * or readStudyData() should be used in combination with createNewSeries(). 1002 ** @param studyUID study instance UID to be set (should be a valid UID) 1003 * @param check check 'studyUID' for conformance with VR and VM if enabled 1004 ** @return status, EC_Normal if successful, an error code otherwise 1005 */ 1006 virtual OFCondition createNewSeriesInStudy(const OFString &studyUID, 1007 const OFBool check = OFTrue); 1008 1009 /** create a new SOP instance. 1010 * Generate a new SOP instance UID, set the instance creation date/time and reset the 1011 * finalized flag (OFFalse). 1012 * This method is used internally for createNewDocument(), createRevisedVersion() 1013 * and during object initialization. 1014 * It could also be used explicitly from the calling application if a new UID should 1015 * be created (this is the case if the study instance UID or series instance UID has 1016 * changed as well as any other attribute within the SR Document General Module or 1017 * SR Document Content Module, see DICOM standard for details). 1018 * This method also updates other DICOM header attributes (by calling updateAttributes()). 1019 * However, instance-level attributes other than the SOP instance UID are usually not 1020 * changed (if already set), e.g. the current instance number or content date/time. 1021 */ 1022 virtual void createNewSOPInstance(); 1023 1024 /** create a new document. 1025 * A new SOP instance is only created if the current document type was valid/supported. 1026 * Please note that the current document is deleted (cleared). 1027 ** @return status, EC_Normal if successful, an error code otherwise 1028 */ 1029 virtual OFCondition createNewDocument(); 1030 1031 /** create a new document of the specified type. 1032 * A new SOP instance is only created if the current document type was valid/supported. 1033 * Please note that the current document is deleted by this method. 1034 ** @param documentType type of the new SR document (see DSRTypes::E_DocumentType) 1035 ** @return status, EC_Normal if successful, an error code otherwise 1036 */ 1037 virtual OFCondition createNewDocument(const E_DocumentType documentType); 1038 1039 /** change the type of the current document. 1040 * Please note that only the type of the SR document is changed (if possible) but no new 1041 * SOP instance is created. If needed, this has to be done with createNewSOPInstance() 1042 * in addition to this method or by calling createNewDocument() instead of this method. 1043 * Before changing the document type, it is checked whether the currently stored document 1044 * tree complies with the relationship content constraints of the new SR IOD. 1045 ** @param documentType new type of the SR document (see DSRTypes::E_DocumentType) 1046 ** @return status, EC_Normal if successful, an error code otherwise 1047 */ 1048 virtual OFCondition changeDocumentType(const E_DocumentType documentType); 1049 1050 /** create a revised version of the current document. 1051 * A revised version can only be created if the current document is already completed 1052 * (see completion flag). If so, a reference to the current document is added to the 1053 * predecessor documents sequence. If all revised versions of a SR document are 1054 * stored (written to datasets/files) it is possible to trace back the full chain of 1055 * previous versions. 1056 * A new SOP instance is created and the content date/time are set automatically. 1057 * Furthermore, the verifying observer and identical documents sequence are deleted, 1058 * the verification flag is set to UNVERIFIED, the completion flag is set to PARTIAL 1059 * (i.e. not complete), the completion flag description is deleted, all digital 1060 * signatures contained in the document tree are deleted and the finalized flag is 1061 * reset (OFFalse). The preliminary flag is not modified by this method. Also the 1062 * various lists of referenced instances remain unchanged, i.e. they have to be 1063 * adapted manually if needed. 1064 * @note Not applicable to document types that use the Key Object Document Module. 1065 * @param clearList clear list of predecessor documents before adding the current 1066 * document if OFTrue. Append current document to existing list 1067 * otherwise. 1068 ** @return status, EC_Normal if successful, an error code otherwise 1069 */ 1070 virtual OFCondition createRevisedVersion(const OFBool clearList = OFTrue); 1071 1072 /** complete the current document. 1073 * Sets the completion flag to COMPLETE if not already done (fails otherwise). This flag 1074 * describes the estimated degree of completeness of an SR Document (see DICOM standard 1075 * for details). The completion flag description is set to an empty string (i.e. absent 1076 * in DICOM dataset). 1077 * @note Not applicable to document types that use the Key Object Document Module. 1078 ** @return status, EC_Normal if successful, an error code otherwise 1079 */ 1080 virtual OFCondition completeDocument(); 1081 1082 /** complete the current document and set a completion description. 1083 * Sets the completion flag to COMPLETE if not already done (fails otherwise). This flag 1084 * describes the estimated degree of completeness of an SR Document (see DICOM standard 1085 * for details). The completion flag description can be modified independently from the 1086 * flag by means of the method setCompletionFlagDescription() - see above. 1087 * @note Not applicable to document types that use the Key Object Document Module. 1088 ** @param description explanation of the value set for completion flag. 1089 * (optional, see previous method, VR=LO) 1090 * @param check check 'description' for conformance with VR and VM if enabled 1091 ** @return status, EC_Normal if successful, an error code otherwise 1092 */ 1093 virtual OFCondition completeDocument(const OFString &description, 1094 const OFBool check = OFTrue); 1095 1096 /** verify the current document by a specific observer. 1097 * A document can be verified more than once. The observer information is added to a 1098 * sequence stored in the dataset. The verification flag is automatically set to 1099 * VERIFIED (if not already done) and the finalized flag is reset (set to OFFalse). 1100 * Please note that only completed documents (see completion flag) can be verified and that 1101 * a new SOP instance UID has to be generated (manually) according to the DICOM standard when 1102 * creating a dataset/file from this document. 1103 * @note Not applicable to document types that use the Key Object Document Module. 1104 ** @param observerName name of the person who has verified this document (required, VR=PN) 1105 * @param organization name of the organization to which the observer belongs (required, VR=LO) 1106 * @param dateTime verification date time (optional). If empty/absent the current date and 1107 * time are used. 1108 * @param check check 'observerName', 'organization' and 'dateTime' for conformance with 1109 * VR and VM if enabled 1110 ** @return status, EC_Normal if successful, an error code otherwise 1111 */ 1112 virtual OFCondition verifyDocument(const OFString &observerName, 1113 const OFString &organization, 1114 const OFString &dateTime = "", 1115 const OFBool check = OFTrue); 1116 1117 /** verify the current document by a specific observer. 1118 * A document can be verified more than once. The observer information is added to a 1119 * sequence stored in the dataset. The verification flag is automatically set to 1120 * VERIFIED (if not already done) and the finalized flag is reset (set to OFFalse). 1121 * Please note that only completed documents (see completion flag) can be verified and that 1122 * a new SOP instance UID has to be generated (manually) according to the DICOM standard when 1123 * creating a dataset/file from this document. 1124 * @note Not applicable to document types that use the Key Object Document Module. 1125 ** @param observerName name of the person who has verified this document (required, VR=PN) 1126 * @param observerCode code identifying the verifying observer (optional, see previous method) 1127 * @param organization name of the organization to which the observer belongs (required, VR=LO) 1128 * @param dateTime verification date time (optional). If empty/absent the current date and 1129 * time are used. 1130 * @param check check 'observerName', 'observerCode', 'organization' and 'dateTime' for 1131 * conformance with VR and VM if enabled 1132 ** @return status, EC_Normal if successful, an error code otherwise 1133 */ 1134 virtual OFCondition verifyDocument(const OFString &observerName, 1135 const DSRCodedEntryValue &observerCode, 1136 const OFString &organization, 1137 const OFString &dateTime = "", 1138 const OFBool check = OFTrue); 1139 1140 /** remove verification information. 1141 * The list of verifying observers is cleared, the verification flag is set to UNVERIFIED and 1142 * the finalized flag is reset (set to OFFalse). 1143 * Normally, there should be no need to call this method. On the other hand, it is useful to 1144 * guarantee a consistent state when processing documents which have not been created with this 1145 * module/toolkit. 1146 */ 1147 virtual void removeVerification(); 1148 1149 /** finalize the current state of the document. 1150 * A new document is originally not finalized but can be finalized using this method. 1151 * This internal flag is e.g. used to indicate whether the entire document is digitally signed 1152 * and, therefore, each newly added verifying observer would corrupt all previous signatures. 1153 * NB: A document needs to be completed first in order to be finalized. Some of the above 1154 * document management functions do reset the flag (i.e. set the FinalizedFlag to OFFalse), 1155 * other methods (e.g. setXXX) do not change the flag though the state of the document is 1156 * not finalized any more after they have been called. 1157 * @note Not applicable to document types that use the Key Object Document Module since there 1158 * is no completion flag attribute in this module. Please note that this method has 1159 * nothing to do with the preliminary flag. 1160 ** @return status, EC_Normal if successful, an error code otherwise 1161 */ 1162 virtual OFCondition finalizeDocument(); 1163 1164 1165 protected: 1166 1167 /** read XML document header 1168 ** @param doc document containing the XML file content 1169 * @param cursor cursor pointing to the starting node 1170 * @param flags flag used to customize the reading process (see DSRTypes::XF_xxx) 1171 ** @return status, EC_Normal if successful, an error code otherwise 1172 */ 1173 OFCondition readXMLDocumentHeader(DSRXMLDocument &doc, 1174 DSRXMLCursor cursor, 1175 const size_t flags); 1176 1177 /** read XML "patient" data 1178 ** @param doc document containing the XML file content 1179 * @param cursor cursor pointing to the starting node 1180 * @param flags flag used to customize the reading process (see DSRTypes::XF_xxx) 1181 ** @return status, EC_Normal if successful, an error code otherwise 1182 */ 1183 OFCondition readXMLPatientData(const DSRXMLDocument &doc, 1184 DSRXMLCursor cursor, 1185 const size_t flags); 1186 1187 /** read XML "study" data 1188 ** @param doc document containing the XML file content 1189 * @param cursor cursor pointing to the starting node 1190 * @param flags flag used to customize the reading process (see DSRTypes::XF_xxx) 1191 ** @return status, EC_Normal if successful, an error code otherwise 1192 */ 1193 OFCondition readXMLStudyData(const DSRXMLDocument &doc, 1194 DSRXMLCursor cursor, 1195 const size_t flags); 1196 1197 /** read XML "series" data 1198 ** @param doc document containing the XML file content 1199 * @param cursor cursor pointing to the starting node 1200 * @param flags flag used to customize the reading process (see DSRTypes::XF_xxx) 1201 ** @return status, EC_Normal if successful, an error code otherwise 1202 */ 1203 OFCondition readXMLSeriesData(const DSRXMLDocument &doc, 1204 DSRXMLCursor cursor, 1205 const size_t flags); 1206 1207 /** read XML "instance" data 1208 ** @param doc document containing the XML file content 1209 * @param cursor cursor pointing to the starting node 1210 * @param flags flag used to customize the reading process (see DSRTypes::XF_xxx) 1211 ** @return status, EC_Normal if successful, an error code otherwise 1212 */ 1213 OFCondition readXMLInstanceData(const DSRXMLDocument &doc, 1214 DSRXMLCursor cursor, 1215 const size_t flags); 1216 1217 /** read XML "document" data 1218 ** @param doc document containing the XML file content 1219 * @param cursor cursor pointing to the starting node 1220 * @param flags flag used to customize the reading process (see DSRTypes::XF_xxx) 1221 ** @return status, EC_Normal if successful, an error code otherwise 1222 */ 1223 OFCondition readXMLDocumentData(const DSRXMLDocument &doc, 1224 DSRXMLCursor cursor, 1225 const size_t flags); 1226 1227 /** read XML verifying observer data 1228 ** @param doc document containing the XML file content 1229 * @param cursor cursor pointing to the starting node 1230 * @param flags flag used to customize the reading process (see DSRTypes::XF_xxx) 1231 ** @return status, EC_Normal if successful, an error code otherwise 1232 */ 1233 OFCondition readXMLVerifyingObserverData(const DSRXMLDocument &doc, 1234 DSRXMLCursor cursor, 1235 const size_t flags); 1236 1237 /** render patient name, sex, birthdate and ID in HTML/XHTML format 1238 ** @param stream output stream to which the HTML/XHTML document is written 1239 * @param flags flag used to customize the output (see DSRTypes::HF_xxx) 1240 */ 1241 void renderHTMLPatientData(STD_NAMESPACE ostream &stream, 1242 const size_t flags); 1243 1244 /** render list of referenced SOP instances in HTML/XHTML format 1245 ** @param stream output stream to which the HTML/XHTML document is written 1246 * @param refList list of referenced SOP instances to be rendered 1247 * @param flags flag used to customize the output (see DSRTypes::HF_xxx) 1248 */ 1249 void renderHTMLReferenceList(STD_NAMESPACE ostream &stream, 1250 DSRSOPInstanceReferenceList &refList, 1251 const size_t flags); 1252 1253 /** render list of referenced SOP instances in HTML/XHTML format 1254 ** @param stream output stream to which the HTML/XHTML document is written 1255 * @param refList list of referenced SOP instances to be rendered 1256 * @param flags flag used to customize the output (see DSRTypes::HF_xxx) 1257 */ 1258 void renderHTMLReferenceList(STD_NAMESPACE ostream &stream, 1259 DSRReferencedInstanceList &refList, 1260 const size_t flags); 1261 1262 /** check the given dataset before reading. 1263 * This methods checks whether the dataset contains at least the DICOM attributes SOP class UID 1264 * and modality. Any incorrectness regarding these two attributes is reported to the logger. 1265 * Currently unsupported SOP classes are also reported as an error. 1266 ** @param dataset DICOM dataset to be checked 1267 * @param documentType SR document type retrieved from the SOP class UID 1268 ** @return status, EC_Normal if successful, an error code otherwise 1269 */ 1270 OFCondition checkDatasetForReading(DcmItem &dataset, 1271 E_DocumentType &documentType); 1272 1273 /** get current value of specific character set 1274 ** @return pointer to character string (never NULL) 1275 */ 1276 const char *getSpecificCharacterSet() const; 1277 1278 /** update various DICOM attributes. 1279 * (e.g. set the modality and SOP class UID, generate a new Study, Series and SOP instance UID 1280 * if required, set date/time values, etc.) 1281 ** @param updateAll flag indicating whether all DICOM attributes should be updated or only 1282 * the IOD-specific ones. (e.g. set DICOM defined terms from enum values) 1283 * @param verboseMode report (more) processing details to the logger if enabled (default) 1284 */ 1285 void updateAttributes(const OFBool updateAll = OFTrue, 1286 const OFBool verboseMode = OFTrue); 1287 1288 1289 private: 1290 1291 /// SR document tree 1292 DSRDocumentTree DocumentTree; 1293 1294 /// flag indicating whether this document is finalized or not 1295 OFBool FinalizedFlag; 1296 /// enumerated value: preliminary, final 1297 E_PreliminaryFlag PreliminaryFlagEnum; 1298 /// enumerated value: partial, complete 1299 E_CompletionFlag CompletionFlagEnum; 1300 /// enumerated value: unverified, verified 1301 E_VerificationFlag VerificationFlagEnum; 1302 /// defined term: see class DSRTypes 1303 E_CharacterSet SpecificCharacterSetEnum; 1304 1305 // DICOM attributes are listed ordered by Module. 1306 // The comments for each attribute describe "Name: (VR, VM, Type)". 1307 // Please note that for particular SR documents (e.g. Key Object Selection) 1308 // other rules might apply. See DICOM standard for further reference. 1309 1310 // --- SOP Common Module (M) --- 1311 // (see SR Document General Module) 1312 1313 /// SOP Class UID: (UI, 1, 1) 1314 DcmUniqueIdentifier SOPClassUID; 1315 /// SOP Instance UID: (UI, 1, 1) 1316 DcmUniqueIdentifier SOPInstanceUID; 1317 /// Specific Character Set: (CS, 1-n, 1C) 1318 DcmCodeString SpecificCharacterSet; 1319 /// Instance Creation Date: (DA, 1, 3) 1320 DcmDate InstanceCreationDate; 1321 /// Instance Creation Time: (TM, 1, 3) 1322 DcmTime InstanceCreationTime; 1323 /// Instance Creator UID: (UI, 1, 3) 1324 DcmUniqueIdentifier InstanceCreatorUID; 1325 /// Coding Scheme Identification Sequence: (SQ, 1-n, 3) 1326 DSRCodingSchemeIdentificationList CodingSchemeIdentification; 1327 /// Context Group Identification Sequence: (SQ, 1-n, 3) 1328 // - tbd: optional attribute not yet supported 1329 /// Mapping Resource Identification Sequence: (SQ, 1-n, 3) 1330 // - tbd: optional attribute not yet supported 1331 /// Timezone Offset from UTC: (SH, 1, 3) 1332 DcmShortString TimezoneOffsetFromUTC; 1333 1334 // --- General Study Module (M) --- 1335 1336 /// Study Instance UID: (UI, 1, 1) 1337 DcmUniqueIdentifier StudyInstanceUID; 1338 /// Study Date: (DA, 1, 2) 1339 DcmDate StudyDate; 1340 /// Study Time: (TM, 1, 2) 1341 DcmTime StudyTime; 1342 /// Referring Physician's Name: (PN, 1, 2) 1343 DcmPersonName ReferringPhysicianName; 1344 /// Study ID: (SH, 1, 2) 1345 DcmShortString StudyID; 1346 /// Accession Number: (SH, 1, 2) 1347 DcmShortString AccessionNumber; 1348 /// Study Description: (LO, 1, 3) 1349 DcmLongString StudyDescription; 1350 1351 // --- Patient Module (M) --- 1352 1353 /// Patient's Name: (PN, 1, 2) 1354 DcmPersonName PatientName; 1355 /// Patient ID: (LO, 1, 2) 1356 DcmLongString PatientID; 1357 /// Issuer of Patient ID: (LO, 1, 3) 1358 DcmLongString IssuerOfPatientID; 1359 /// Patient's Birth Date: (DA, 1, 2) 1360 DcmDate PatientBirthDate; 1361 /// Patient's Sex: (CS, 1, 2) 1362 DcmCodeString PatientSex; 1363 1364 // --- General Equipment Module (M) --- 1365 1366 /// Manufacturer: (LO, 1, 2) 1367 DcmLongString Manufacturer; 1368 /// Manufacturer's Model Name: (LO, 1, 3) 1369 DcmLongString ManufacturerModelName; 1370 /// Device Serial Number: (LO, 1, 3) 1371 DcmLongString DeviceSerialNumber; 1372 /// Software Version(s): (LO, 1-n, 3) 1373 DcmLongString SoftwareVersions; 1374 1375 // --- Enhanced General Equipment Module (M - for some IODs) --- 1376 1377 // Manufacturer: (LO, 1, 1) 1378 // - see 'General Equipment Module' 1379 // Manufacturer's Model Name: (LO, 1, 1) 1380 // - see 'General Equipment Module' 1381 // Device Serial Number: (LO, 1, 1) 1382 // - see 'General Equipment Module' 1383 // Software Version(s): (LO, 1-n, 1) 1384 // - see 'General Equipment Module' 1385 1386 // --- Synchronization Module (M/C/U - for some IODs) --- 1387 1388 /// Synchronization Frame of Reference UID: (UI, 1, 1) 1389 DcmUniqueIdentifier SynchronizationFrameOfReferenceUID; 1390 /// Synchronization Trigger: (CS, 1, 1) 1391 DcmCodeString SynchronizationTrigger; 1392 /// Acquisition Time Synchronized: (CS, 1, 1) 1393 DcmCodeString AcquisitionTimeSynchronized; 1394 1395 // --- SR Document Series / Key Object Document Series Module (M) --- 1396 1397 /// Modality: (CS, 1, 1) 1398 DcmCodeString Modality; 1399 /// Series Instance Number: (UI, 1, 1) 1400 DcmUniqueIdentifier SeriesInstanceUID; 1401 /// Series Number: (IS, 1, 1) 1402 DcmIntegerString SeriesNumber; 1403 /// Series Date: (DA, 1, 3) 1404 DcmDate SeriesDate; 1405 /// Series Time: (TM, 1, 3) 1406 DcmTime SeriesTime; 1407 /// Protocol Name: (LO, 1, 3) 1408 DcmLongString ProtocolName; 1409 /// Series Description: (LO, 1, 3) 1410 DcmLongString SeriesDescription; 1411 /// Series Description Code Sequence: (SQ, 1, 3) 1412 // - tbd: optional attribute not yet supported 1413 /// Referenced Performed Procedure Step Sequence: (SQ, 1, 2) 1414 DcmSequenceOfItems ReferencedPerformedProcedureStep; 1415 1416 // --- SR Document General Module (M) --- 1417 1418 /// Instance Number: (IS, 1, 1) 1419 DcmIntegerString InstanceNumber; 1420 /// Preliminary Flag: (CS, 1, 3) 1421 DcmCodeString PreliminaryFlag; 1422 /// Completion Flag: (CS, 1, 1) 1423 DcmCodeString CompletionFlag; 1424 /// Completion Flag Description: (LO, 1, 3) 1425 DcmLongString CompletionFlagDescription; 1426 /// Verification Flag: (CS, 1, 1) 1427 DcmCodeString VerificationFlag; 1428 /// Content Date: (DA, 1, 1) 1429 DcmDate ContentDate; 1430 /// Content Time: (TM, 1, 1) 1431 DcmTime ContentTime; 1432 /// Verifying Observer Sequence: (SQ, 1-n, 1C) 1433 DcmSequenceOfItems VerifyingObserver; 1434 /// Author Observer Sequence: (SQ, 1-n, 3) 1435 // - tbd: optional attribute not yet supported 1436 /// Participant Sequence: (SQ, 1-n, 3) 1437 // - tbd: optional attribute not yet supported 1438 /// Custodial Organization Sequence: (SQ, 1, 3) 1439 // - tbd: optional attribute not yet supported 1440 /// Predecessor Documents Sequence: (SQ, 1-n, 1C) 1441 DSRSOPInstanceReferenceList PredecessorDocuments; 1442 /// Identical Documents Sequence: (SQ, 1-n, 1C) 1443 DSRSOPInstanceReferenceList IdenticalDocuments; 1444 // Referenced Request Sequence: (SQ, 1-n, 1C) 1445 // - tbd: conditional attribute not yet supported 1446 /// Performed Procedure Code Sequence: (SQ, 1-n, 2) 1447 DcmSequenceOfItems PerformedProcedureCode; 1448 /// Current Requested Procedure Evidence Sequence: (SQ, 1-n, 1C) 1449 DSRSOPInstanceReferenceList CurrentRequestedProcedureEvidence; 1450 /// Pertinent Other Evidence Sequence: (SQ, 1-n, 1C) 1451 DSRSOPInstanceReferenceList PertinentOtherEvidence; 1452 /// Referenced Instance Sequence: (SQ, 1-n, 1C) 1453 DSRReferencedInstanceList ReferencedInstances; 1454 1455 // --- Timezone Module (M - for some IODs) --- 1456 1457 // Timezone Offset from UTC: (SH, 1, 1) 1458 // - see 'SOP Common Module' 1459 1460 // --- declaration of copy constructor and assignment operator --- 1461 1462 DSRDocument(const DSRDocument &); 1463 DSRDocument &operator=(const DSRDocument &); 1464 }; 1465 1466 1467 #endif 1468