Home

Merge DICOM Toolkit™ C/C++ User`s Manual v

1. 23 DICOM FIl8S arte 23 File 28 The ees 29 File Management Roles and 0 0 0 32 ereltelgnrige ee ES 33 Using Merge DICOM Toolkit nnnm 34 cci esd sys H 34 Initialization File ioci erc eL Etre tc aie 34 M RGE Fiealthcare Merge DICOM Toolkit User s Manual 91 9 35 Bullet nits co 36 MICS COMP ies 36 MICS CONV 37 11761 12 37 ges M 38 38 39 Developing DICOM Applications sss 41 Library InitiallZatlOri or Ert 41 Statically Linked Configuration esssssssssseseeneeeeeeen enne 42 Registering Your Application eese nennen 42 Association Management Network Only seen 43 Negotiated Transfer Syntaxes Network 46 Dynamic Service Lists 2 euenire cete
2. M RGE 65 Healthcare Merge DICOM Toolkit Performance Tuning 66 User s Manual Notice in this log file that all warnings and informational messages are also logged This is always the case although the first violation returned to the application was an error because Validation Levell was specified The message log agrees in that the first VE Validation Error logged is for the attribute Patient s Age 0010 1010 The log states that the message contains 41 as the value for this attribute Part 6 of DICOM clearly states that this attribute has a value representation of AS Age String and part 5 states that for this VR the value should have a leading zero and be represented as 041 There is also one other error flagged in this message The required attribute View Position 0018 5101 had no value Many more details relating to the usage and behavior of MC Validate Message and MC Get Next Validate Error canbe found in the Reference Manual DICOM message validation does involve processing overhead The most significant overhead is in the accessing of the message info files and significantly less overhead is involved in actually validating the contents of the message structure It is important to understand that depending on the way in which your message object was created this validation overhead can occur at different points in your application see Table 14 Table 14 Po
3. Network message exchange is discussed further one of the following sections Dynamic Service Lists Service lists In addition to defining service lists in the Application Profile Merge DICOM Toolkit defined at runtime has mechanisms to define service lists and transfer syntax lists at run time A number of functions exist to create transfer syntaxes and service lists in various formats The following example shows how to create two transfer syntax lists and a service list TRANSFER SYNTAX syntaxIds 3 char serviceList 3 syntaxlIds 0 JPEG BASELINE syntaxlIds 1 TRANSFER SYNTAX 0 status MC NewSyntaxList BASELINE syntaxIds if status MC NORMAL COMPLETION BadStatus status testSyntaxIds 0 EXPLICIT LITTLE ENDIAN testSyntaxIds 1 IMPLICIT LITTLE ENDIAN testSyntaxIds 2 TRANSFER SYNTAX O atus MC NewSyntaxList DEFAULT syntaxIds status MC NORMAL COMPLETION BadStatus status Fh ct status MC NewServiceFromName CT JPEG STANDARD CT BASELINE 0 1 if status MC NORMAL COMPLETION BadStatus status status MC NewServiceFromName CT DEFAULT STANDARD CT DEFAULT 0 1 48 M RGE Fiealthcare Merge DICOM Toolkit Objects are useful M RGE Fiealthcare User s Manual if
4. An excerpt from a Merge DICOM Toolkit message log file is included below that contains all three classes of messages errors warnings and informational Message Log Example 03 29 21 14 54 77 MC3 W 0010 1010 Value from stream had problem 03 29 21 14 54 78 MCS W Invalid value for this tag s VR 03 29 21 14 56 41 MC3 Read PDU Head E Error on Read Transport call 03 29 21 14 56 41 MC3 MCI nextPDUtype E Error on Read PDU Head call 35 Merge DICOM Toolkit Do a DICOM User s Manual 03 29 21 14 56 41 MC3 Transport Conn Closed Event E Transport unexpectedly closed K 03 29 21 14 56 41 MC3 MCI ReadNextPDV I DUL read pdvs error UL Provider aborted the association 03 29 21 14 56 41 MC3 E 0000 0000 Error during C Stream To Message 03 29 21 14 56 41 MC3 E Callback cannot comply 03 29 21 14 56 41 C3 MC Read Message E Network connection unexpectedly shut down On more DICOM Toolkit computing platforms additional information is logged such as process and thread id numbers identifying where the message was generated Utility Programs The Merge DICOM Toolkit supplies several useful utility programs These utilities can be used to help you validate your own implementations and better understand the standard All these utilities use the Merge DICOM Toolkit Library and require that you set your MERGE INI env
5. Next child expected to be the IMAGE item if nodeType SR NODE IMAGE status MC SRH Get IMAGE Data childID sopClassUid sizeof sopClassUid SopInstanceUid sizeof sopInstanceUid amp refFramesCount if status MC_NORMAL COMPLETION printf MC SRH Get IMAGE Data Eror code d status return printf Image SOP Class s Image SOP Instance s n sopClassUid sopInstanceUid Unicode Support Merge DICOM Toolkit supports DICOM character sets to Unicode conversion using a public domain library ICU4C The Unicode conversion libraries are optional and users that are not planning to use Unicode conversion don t need to deploy the extra two shared objects included in the distribution package The original copyright notice of the ICU4C software is below ICU License ICU 1 8 1 and later COPYRIGHT AND PERMISSION NOTICE Copyright c 1995 2012 International Business Machines Corporation and others All rights reserved Permission is hereby granted free of charge to any person obtaining a copy of this software and associated documentation files the Software to deal in the Software without restriction including without limitation the rights to use copy modify merge publish distribute and or sell copies of the Software and to permit persons to whom the Software is furnished to do so provided that the above copyright notice s and this permission notice appear in all copies of the Software
6. sse 111 Memory 444 044 115 Overview of the Merge DICOM Toolkit SR functions 117 Encoding SR Documents 0000000 118 Reading SR 4 2 4 1 enne 122 Deploying 124 Merge DICOM Toolkit Required Files sees 128 Configuration 129 Configuring Remote Nodes for SCU 130 UN VR 2 130 Appendix A Frequently Asked Questions 133 Appendix B Unique Identifiers UIDs 139 Summary of UID Composition 0 0 139 Sample UID Format 0 cccccceseseceecceeeeeeeeeceeeeeeeeaeeeeaaeeeeaaesaeeeseaeeeeaaeseeeaeseeaeees 140 Obtaining a UID ai eee 140 Obtaining UID From ANSI sse 140 Appendix C XML structure sse ener nennen nnne nens 141 V Merge DICOM Toolkit User s Manual vi M RGE Healthcare Merge DICOM Toolkit User s Manual Overview This User s Manual is intended for developers of medical imaging applications who are using t
7. If your application runs on a resource rich system you should set LARGE DATA STORE to the value MEM in the Service Profile and Merge DICOM Toolkit will keep the Pixel Data values in the message object stored in memory rather than using temporary files This should improve performance Also in this case you may want your callback function to supply the Pixel Data in fewer big blocks or one large block While MyPDSupplyFunction isacallback function in this example it is not what is being referred to when we discuss Callback Functions with a capital C and capital F in Merge DICOM Toolkit Callback Functions are another even more powerful way to handle large OB or OW data and are discussed later Parsing Messages When your AE receives a DICOM message it will most often need to examine the values contained in the message attributes to perform an action e g store an image print a film change state If your application is a server the message conveys the operation your server should perform and the data associated with the operation If your application is a client the message may be a response message from a server on the network resulting from a previous request message to that same server Once you have received a message object use the Get Value family of functions to parse your message This family of functions can be broken into five types based on their functionality as specified in Table 11
8. Specifies a function that is called repeatedly to get the value of an attribute of VR OB OW OF SL SS UL US AT FL FD UN or UT e g pixel data or fixed width value a chunk at a time These attributes tend to have very large values Note This callback function is different than the type of Callback Function registered using MC Register Callback Function See the later discussion of Callback Functions Both the MC Get Value and MC Get Next Value function types have several variants depending on the data type of the variable to which you are assigning the retrieved value see Table 12 These variants can be very helpful because they perform the necessary type conversion from any DICOM value representation to any compatible ANSI C data type If a type conversion is not reasonable e g from LT to short int then MC INCOMPATIBLE VR will be returned as MC STATUS code Also other error statuses will be returned if the conversion was reasonable but the value stored in the attribute of the message made the conversion impossible e g MC INVALID VALUE FOR VR MC VALUE OUT OF RANGE Table 12 Acceptable MC Get Value VR combinations MC Get function type Function may be used to retrieve values from attributes with these Value Representations Get Value To Int DS FD FL IS SL SS UL US SQ Get Value To Uint DS FD FL IS SL SS UL US SQ Get Value To ShortInt DS
9. mc3file Sample DICOM messages can be generated with the mc3file utility You specify the service command and transfer syntax and mc3file generates a reasonable sample message that is written to a binary file The contents of this file are generated in DICOM file format or in exactly the format as the message would be streamed over the network The program fills in default values for all the required attributes within the message You can also use this utility to generate its own configuration file which you can then modify to specify your own values for attributes in generated messages These generated messages are purely meant as useful examples that can be used to test message exchange or give the application developer a feel for the structure of DICOM messages They are not intended to represent real world medical data The messages generated be validated or listed with the mc31ist mc3valid utilities The command syntax for mc3 ile is the following mc3file serv cmd num g lt file gt c lt file gt 1 m q t lt syntax gt f lt file gt lt serv gt lt cmd gt These two options are always used together They specify the service name and command for the message to be generated These names can be either upper or lower case If the exact names for a service command pair are not known the 1 option can be used instead to specify the service name and command If th
10. An application entity is an SCU when it requests DICOM services over a network and an SCP when it provides DICOM services over a network We will more often refer to the SCU as a Client and the SCP as a Server A single DICOM application entity can act as both a client and a server This client server model is a powerful and omnipresent one in the world of distributed network computing 11 Healthcare Merge DICOM Toolkit 12 User s Manual Services and Meta Services DICOM is formed around the concepts of Services and Service Classes The DICOM Standard specifies a set of services that can be performed over a network Some of the services can also be stored to interchangeable media these are italicized in Table 1 As new services are introduced the standard will be further expanded The standard also groups related services into a service class Table 1 lists the DICOM standard service classes and their component services When a particular collection of services in a service class implies a higher level of service this collection is combined by the standard into a Meta Service Specifying that your application supports a specific meta service is a useful shorthand for explicitly listing out the collection of services that make up that meta service Table 1 DICOM Services Classes and their Component Services Service Class Services Description Verification Verification Verifies application level communication between DICOM
11. M RGE Fiealthcare User s Manual MC Free File amp fileID Fr the file object once written to media fileID is the handle to the file object being written 2 is the value given to the NumBytes parameter and means that the file will be padded if necessary to have a total length that is a multiple of 2 using the file padding attribute FFFC FFFC If this value is setto 0 no file padding will occur NULL specifies that you aren t passing any user information to FileToMedia FileToMedia is the file system interface callback function you must author to write from your media device described earlier as the Your ToMediaFunction The parameters for this callback function must agree with the following prototype static MC STATUS FileToMedia char filename void userInfo amt dataSize void dataBuffer ENE isFirst int isLast fileName identifies the file you should be writing e g PNR1 HDR3 AMR62 dataSize specifies the even number of bytes of data you should write and dataBuffer is address of the data isFirst indicates whether this is the first chunk of data being written e g you should open the file isLast is set to MTI TRUE by the library when it is requesting that you write the last block of data e g you can now close the file The library will callback FileToMedia until all data has been written The userInfo parameter can be used to pass application specific data between the sample applic
12. PRINT QUEUE FILM SESSION PRIVATE FILM SESSION FILM BOX PRIVATE FILM BOX BASIC IMAGE BOX PRIVATE BASIC IMAGE BOX PRIVATE PRIVATE PRIVATE STUDY COMPONENT PRIVATE Not applicable M RGE 31 Fiealthcare Merge DICOM Toolkit File Management Services File Management Roles 32 User s Manual File Management Roles and Services Part 10 of the DICOM Standard specifies a set of file management roles and services There are five DICOM File Services that describe the entire set of DICOM file operation primitives Table 7 DICOM File Services DICOM File Services Description M WRITE Create new files in a set and assign them file ID M READ Read existing files based on their file ID M DELETE Delete existing files based on their file ID M INQUIRE FILE SET Inquire free space available for creating new files within a file set M INQUIRE FILE Inquire date and time of file creation or last update if applicable for any file within a file set The Merge DICOM Toolkit supplies families of functions that perform the first two underlined file services The Toolkit also implements enhanced read and write functionality for the creation and maintenance of DICOMDIR files and its hierarchy of directory entities and directory records The remaining three file services are best implemented by the application entity through file system calls because they are file System dependent operations DICOM AE s that perf
13. Person name of the e g Recording person whose role is Observer described by the Concept Name COMPOSITE SR NODE COMPOSITE Purpose of A reference to one Reference Composite SOP Instance which is not an Image or Waveform IMAGE SR NODE IMAGE Purpose of A reference to one Image Reference IMAGE Content Item may convey a reference to a Softcopy Presentation State associated with the Image WAVEFORM SR NODE WAVEFORM Purpose of A reference to one Reference Waveform M RGE Healthcare Merge DICOM Toolkit Item Type Merge DICOM Toolkit Definition Concept Name Description M RGE Healthcare SCOORD SR_NODE_SCOORD Purpose of Reference Spatial coordinates of a geometric region of interest in the DICOM image coordinate system The IMAGE Content Item from which spatial coordinates are selected is denoted by a SELECTED FROM relationship TCOORD SR_NODE_TCOORD Purpose of Reference Temporal Coordinates i e time or event based coordinates of a region of interest in the DICOM waveform coordinate system The WAVEFORM or IMAGE or SCOORD Content Item from which Temporal Coordinates are selected is denoted by a SELECTED FROM relationship CONTAINER SR_NODE_CONTAINER Document Title or document section heading Concept Name conveys the Document Title if the ONTAINER is the Document Root Content Item or the category of observation CONTAINE
14. Structured Report Content Items are represented as a special SR objects in the memory Each object is represented by the integer object ID that is also called a Node ID The ID value for SR Objects is the same as the item ID or Message ID of the underlying message object SR objects are always mapped to the message objects and use them as attribute storage This allows you to use SR object ID in the basic toolkit functions like Set Value Deletion of the SR Object does not delete the underlying item object Figure 20 shows the relationship between SR tree and the message object 115 Merge DICOM Toolkit User s Manual R Object ID ject ID Message _ gt Object M 22 4 SR Content Ohiect Item node Attributes Content SR Content SR Content SR Content onten Item node Item node Item node fl Ohiect SR Content Item node Attribuy Ohiect Item Attributes Seni Content Seauence Figure 20 Relationship between SR object and the message object When a message or item object is mapped with the SR object it is marked with a special flag that prohibits some of the operations that can break the structured report hierarchy For example Duplicate Message will not work on the messages mapped with the SR object 116 M RGE Healthcare Merge DICOM Toolkit User s Manual Overview of the Merge DICOM Tool
15. the message info and data dictionary files are not referenced and an empty message object instance is opened This message object contains no attributes and the MC Set Service Command function must be called to set the service and command for this file before it can be written to the file set As in the case of networking this approach is more efficient but penalizes you in the area of run time error checking M RGE Healthcare Merge DICOM Toolkit User s Manual When your application is done using a file object the file object should be freed using the MC Free File call Reading Files To read in the contents of a DICOM file for analysis or parsing you must open the file Opening a DICOM file in the DICOM Toolkit API means that a complete file object is filled in from an existing physical file This means the entire DICOM file is read in on the open The following code reads a file into the file object Read in the DICOM file status MC Open File myApplicationID fileID NULL MediaToFile if status MC NORMAL COMPLETION PrintError Unable to read file from media status exit EXIT FAILURE myApplicationID is the handle to your application entity obtained when you registered your application with the Toolkit Library i1eID is the handle of a previously created file object and NULL specifies that you aren t passing any user information to MediaToFile MediaT
16. Cardiac Electrophysiology Waveform Storage General Audio Waveform Storage General ECG Waveform Storage Hemodynamic Waveform Storage Respiratory Waveform Storage Hanging Protocol Storage Ophthalmic 8 bit Photography Image Storage Ophthalmic 16 bit Photography Image Storage Ophthalmic Tomography Image Storage Stereometric Relationship Storage Detached Patient Management Detached Visit Management Detached Study Management Detached Study Component Management Detached Results Management Detached Interpretation Management Basic Film Session Command C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE N GET N GET N GET N GET N GET N GET N CREATE 27 Naming DICOM File Sets and File ID s 28 User s Manual Service Command Basic Film Box N CREATE Basic Grayscale Image Box N SET Basic Color Image Box N SET Autorefraction Measurements Storage C STORE Keratometry Measurements Storage C STORE Subjective Refraction Measurements Storage C STORE Ophthalmic Axial Measurements Storage C STORE Ophthalmic Visual Field Static Perimetry Measurements Storage C STORE Visual Acuity Measurements Storage C STORE Lensometry Measurements Storage C STORE Media Storage Directory Storage C STORE Merge DICOM Toolkit defines a
17. FD FL IS SL SS UL US SQ 55 Merge DICOM Toolkit 56 User s Manual MC Get function type Function may be used to retrieve values from attributes with these Value Representations DS FD FL IS SL SS UL US SQ AT DS FD FL IS SL SS UL US SQ AT DS FD FL IS SL SS UL US SQ DS FD FL IS SL SS UL US SQ DS FD FL IS SL SS UL US SQ AS AT CS DA DS DT FD FL IS LO LT PN SH SL SS ST TM UI UL US UT SQ OB OW OF SL SS UL US AT FL FD UN UT UNKNOWN VR OB OW Note The same table of acceptable conversions applies for the Get Next Value To MC Get pValue To and MC Get Next pValue To families of functions The user should be aware that while the toolkit makes reasonable efforts to ensure correct conversions between data representations the Value To functions should be used with caution in some circumstances For instance loss of precision is possible when Get Value To String is called to return the value of a float or a double attribute as a string Let s assume the value of the attribute of VR FL is 123 456789 Internally the toolkit converts the value to string using the g format specification The returned result is the 123 457 string the rounded value with the default precision A better approach in this case would be to retrieve the attribute in its native
18. For the sake of simplicity the remainder of this manual refers to the client as the SCU and the server as the SCP The association request proposal contains the set of services the client would like to perform and the transfer syntaxes it understands The server then responds to the client with a subset of the services and transfer syntaxes proposed by the client If this subset is empty the server has rejected the association If the subset is not empty the server has accepted the association and the agreed upon services may be performed The client is responsible for releasing the association when it is finished performing its network operations Either the client or the server can abort the association in the case of some catastrophic failure e g disk full out of memory 18 M RGE Healthcare Merge DICOM Toolkit Service Command Pair Attributes Values and Tags M RGE Fiealthcare User s Manual 1 o Association Requested e 2 Association Accepted o ASSOCIATION 3 4 Association Released Figure 5 A Successful DICOM Association Messages Once an association is established services are performed by AEs through the exchange of DICOM Messages A message is the combination of a DICOM command request or response and its associated object instance see Figure 6 Messages containing command requests will be referred to as request messages while messages containing command responses wil
19. Note The Media Storage Directory Service is not performed over a network and the single object specified in the Basic Directory Information Object Definition Part 3 is used Table 5 Service Command Pairs Specifying Object Instances that can be Stored in a DICOM File Service Basic Structured Display Storage Basic Text Structured Reporting Breast Tomosynthesis Image Storage Comprehensive Structured Reporting Computed Radiography Image Storage CT Image Storage Chest CAD SR Colon CAD SR Deformable Spatial Registration Storage Digital X Ray Image Storage For Presentation Digital X Ray Image Storage For Processing Digital Intra oral X Ray Image Storage For Presentation Digital Intra oral X Ray Image Storage For Processing Digital Mammography Image Storage For Presentation Digital Mammography Image Storage For Processing Encapsulated CDA Storage Encapsulated PDF Storage Enhanced CT Image Storage Enhanced MR Image Storage Enhanced MR Color Image Storage Enhanced PET Image Storage Enhanced US Volume Storage Enhanced XA Image Storage Enhanced XRF Image Storage Command C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE M RGE Healthcare Service Command Enhanced Structured Reporting C STOR
20. SOP Instances and spatial or temporal regions of interest within such SOP Instances Relationships by reference are enabled between Content Items There are more specific SR IODs defined in the DICOM like Key Object Selection Document and Mammography CAD SR Those IODs use the same way to encode data and the difference is in the constrains on the Content Item Types and their relationships Figure 17 illustrates the typical SR Document structure As you can see the top level header is very similar to the DICOM image IODs and consists of the same Patient Study and Series modules The main difference from other IODs is the SR Document Content Module The attributes in this Module convey the content of an SR Document 103 Merge DICOM Toolkit The SR Document hierarchy User s Manual Patient Module Patient Name Patient ID Patient Sex Patient Date Of Birth General Study Module Study Instance UID Accession Number SR Document Series Module Modality SR Document General Module Referenced Request Sequence gt Requested Procedure ID gt Requested Procedure Description SR Document Content Module Node 1 Contains Node 2 Has Obs Ctx Has Obs Ctx Contains Has Properties Node C1 Node C2 Node 3 Node 4 Figure 17 SR Document Structure example The Document Content Module has a tree structure and consists of a sin
21. Sample Encoding of Encapsulated Pixel Data in Table 13 Further examples of encapsulated pixel data encoding are contained in Part 5 of the DICOM standard 60 M RGE Healthcare Merge DICOM Toolkit M RGE User s Manual Icon Image Sequences The Icon Image Sequence can contain small thumbnail images This sequence also contains the Pixel Data Tag 7 0 0010 just like the main message Because this may or may not be compressed some special considerations are necessary Sending on the network writing a file or writing a stream 1 Message is uncompressed Icon is uncompressed There is no user intervention required An association will negotiate one of the unencapsulated transfer syntaxes and both the image and the icon_image will be sent as the negotiated unencapsulated transfer syntax 2 Message is compressed Icon is uncompressed There is no user intervention required An association will negotiate one of the encapsulated transfer syntaxes and the image will be sent in this encapsulated transfer syntax and the icon_image will be sent EXPLICIT_LITTLE_ENDIAN EXPLICIT LITTLE ENDIAN is the default syntax for the non pixel data portion of a message including nested pixel data when the main pixel data is encapsulated 3 Message is compressed Icon is compressed Minor intervention is required Special creation of icon The only difference is Set Message Transfer Syntax sqgID e
22. See the following sections for a further discussion of UN VR IMPLEMENTATION CLASS UID The Implementation Class UID is used to identify in a unique manner a specific class of implementation PS3 7 of DICOM states The Implementation Class UID is intended to provide respective each network node knows the other s implementation identity and non ambiguous identification in the event of communication problems encountered between two nodes M RGE 129 Healthcare Merge DICOM Toolkit Configuring remote nodes at run time UN VR interoperability problems 130 User s Manual Configuration Option Description PS3 7 of DICOM further defines how this UID should be defined different equipment of the same type or product line but having different serial numbers shall use the same Implementation Class UID if they share the same implementation environment i e software IMPLEMENTATION_VERSION The Implementation Version is intended to distinguish between software versions of an implementation It should be set to the version of the Merge DICOM Toolkit application Configuring Remote Nodes for SCU Applications Typical Merge DICOM Toolkit SCU applications use the mergecom app configuration file to configure SCP applications that it communicates with Using this configuration file requires that remote applications be configured before the library is initialized It may be desirable to config
23. the last time you are providing data for this attribute s value i e when you are providing the last block of data PROVIDING_DATA_LENGTH Callback is receiving OB OW OF data and the length of the entire value for this attribute is being supplied The length is passed in using CbdataSizePtr CodataBufferPtr is not used PROVIDING_MEDIA_DATA_LENGTH Callback is receiving the offset of the value of a DICOM file attribute of Value Representation OB OW or OF from the beginning of the file CbdataBufferPtr points to a unsigned long that contains this offset CbdataSizePtr is set to the length of the value contained at the offset This value for CBtype only occurs as a result of the MC Open File Bypass OBOW function call See later sections of this manual dealing with DICOM file access and the Reference Manual for more information PROVIDING OFFSET TABLE Callback is receiving offset table of encapsulated OB OW OF data Merge DICOM Toolkit has set CbdataSizePtr to the number of bytes of data it is providing at CbdataBufferPtr Merge DICOM Toolkit will set CbisFirstPtr to TRUE not zero and CbisLastPtr to TRUE not zero The entire offset table is passed in one call to the registered callback function Note that the callback can be repeatedly called 82 M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare User s Manual Value of Cbtype Required Callback Behavior PR
24. 1 Send Request Msg 2 J Send Response Msg 1 Read Request Msg 2 Read Response Msg 1 1 gt BE Process Request Msg 2 Send Regiest Msg 34 En Send Response Msg 2 Read Response Msg 2 Figure 14 Timing of Message Exchange During Asynchronous Transfers Asynchronous operations are implemented utilizing the standard Merge DICOM Toolkit network functions MC_Send_Request_Message MC Send Response Message MC Read Message MC Read Message To Tag MC Continue Read Message Tag and MC Continue Read Message To One additional requirement however is for the application to keep track of the Message ID 0000 0110 tag and the Message ID Being Responded To 0000 0120 tags Message ID contains an integer uniquely identifying a request message transferred over an association Merge DICOM Toolkit will automatically insert this tag when sending a request message over the network Message ID Being Responded To is contained in response messages and contains the Message ID that corresponds to the request message that a response is for During normal synchronous transfers Merge DICOM Toolkit keeps track of the Message ID of the last request message and automatically inserts this into the Message ID Being Responded Totag when sending a response For asynchronous operations to work properly the application is required to keep track of these tags and appropriately fill them in response messages For app
25. Acuity Measurements Storage Multi frame Grayscale Byte Secondary Capture Image Storage Multi frame Grayscale Word Secondary Capture Image storage Multi frame Single Bit Secondary Capture Image Storage Multi frame True Color Secondary Capture Image Storage Segmentation Storage Surface Segmentation Storage Basic Structured Display Storage Basic Text Structured Reporting Comprehensive Structured Reporting Enhanced Structured Reporting Key Object Selection Chest CAD SR Colon CAD SR Mammography CAD SR X Ray Radiation Dose SR Encapsulated CDA Storage Encapsulated PDF Storage Procedure Log Blending Softcopy Presentation State Storage Color Softcopy Presentation State Storage Grayscale Softcopy Presentation State Storage Pseudo Color Softcopy Presentation State Storage 12 lead ECG Waveform Storage Ambulatory ECG Waveform Storage Arterial Pulse Waveform Storage Basic Voice Audio Waveform Storage Cardiac Electrophysiology Waveform Storage General Audio Waveform Storage General ECG Waveform Storage Hemodynamic Waveform Storage Ophthalmic 8 bit Photography Image Storage Ophthalmic 16 bit Photography Image Storage Ophthalmic Tomography Image Storage Spectacle Prescription Report Storage Stereometric Relationship Storage Real World Value Mapping Storage M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare Service Class Storage Commitment Media Storage Query Retrieve Basi
26. DICOM file can be created a file object must be created The Create File call creates the file object whose type is specified by the supplied service command pair For example the following call creates an DICOM MR image file object Create new MR Image file object status MC_Create_File amp fileID fileName STANDARD_MR C_STORE_RQ if status MC NORMAL COMPLETION PrintError Unable to create file object status exit EXIT_FAILURE The filelD variable is used to return a handle to the new file object fileName is a string variable containing the DICOM file ID file name e g PNR1 HDRS AMR62 that will be given to the new object STANDARD is the service name and C STORE RQis the command name identifying the class of file object being created see Table 5 It is important to realize that Create File does not create the physical DICOM file out on the media the MC Write File calldescribed later does that Create File corresponds to the Open Message call used in networking it creates references to the proper message info file along with the data dictionary and builds an unpopulated file object instance for your application to fill in This file object contains empty attributes Just as there is an MC Open Empty Message available for networking there is also a MC Create Empty File available for media interchange In this case
27. Data Structures and Encoding Part 6 Data Dictionary Part 7 Message Exchange Part 8 Network Communication Support for Message Exchange Part 9 Point to Point Communication Support for Message Exchange retired Part 10 Common Media Storage Functions for Data Interchange Part 11 Media Storage Application Profiles NEMA Standards Publication No PS 3 5 1993 DICOM Part 5 Data Structures and Encoding p 4 M RGE 1 Fiealthcare Merge DICOM Toolkit A Quick Walk Through DICOM User s Manual Part 12 Media Formats and Physical Media for Data Interchange Part 13 Print Management Point to Point Communication Support retired Part 14 Grayscale Standard Display Function Part 15 Security Profiles Part 16 DICOM Content Mapping Resource Part 17 Explanatory Information Part 18 Web Access to DICOM Persistent Objects WADO Part 1 of the standard gives an overview of the standard Since this part was approved before most of the other parts were completed it is already somewhat outdated and can be confusing Part 2 describes DICOM conformance and how to write a conformance statement A conformance statement is important because it allows a network administrator to plan or coordinate a network of DICOM applications For an application to claim DICOM conformance it must have an accurate conformance statement Parts 3 and 4 define the types of services and information that can be exchanged using DICOM Parts 5 and 6
28. Free File Once open navigating a DICOMDIR usually involves calling MC DDH Get First Lower Record to get the first record of the root entity e g the first patient record From here MC DDH Get Next Record is used to sequentially obtain further records of the root entity while MC DDH Get First Lower Record is used to get lower level entity records M RGE Healthcare Merge DICOM Toolkit User s Manual e g study records MC_DDH_Get_Parent_Record canbe used to navigate up the record hierarchy The record identifiers obtained using the record navigation functions can be used with MC Get Value functions to obtain record attribute values These identifiers are valid until the associated record object is not freed Record objects are freed automatically when the DICOMDIR object is freed or manually when the application calls DDH Release Record Or MC DDH Delete Record Modifications to the content of existing records are not allowed The toolkit provides an easy and fast way for searching and collecting data from records through the Traverse Records function This function can be used for the traversal of the entire record hierarchy or just a branch of records by setting the proper starting point through the Root D argument The toolkit will call the provided callback for each record encountered during traversal The callback can dynamically control the traversal using various
29. ISO IR 100 ISO IR 101 ISO IR 109 ISO IR 110 ISO IR144 ISO IR 127 ISO IR 126 ISO IR 138 ISO IR 148 0008 0012 Instance Creation Date DA 3 0008 0013 Instance Creation Time T 3 0008 0014 Instance Creator UID UI 3 84 M RGE Healthcare Merge DICOM Toolkit Encoding items in a sequence User s Manual 0008 0016 SOP Class UID UI 3 0008 0018 SOP Instance UID UI 3 2000 0010 umber of Copies IS 3 2000 0020 Print Priority CS 3 Enumerated Values HIGH MED LOW 2000 0030 edium Type CS 3 Defined Terms PAPER CLEAR FILM BLUE FIL 2000 0040 Film Destination CS 3 Enumerated Values MAGAZINE PROCESSOR 2000 0050 Film Session Label LO 3 2000 0060 emory Allocation IS 3 2000 0500 Referenced Film Box Sequence 50 3 Item Name s REF_FILM_BOX Item Name REF FILM BOX 0008 1150 Referenced SOP Class UID UI 1 0008 1155 Referenced SOP Instance UID UI 1 To encode an item into an attribute of Value Representation SQ treat the attribute as a multi valued integer where each value is an ItemID This means using the MC_Set_Value_From_Int and MC Set Next Value From Int functions where the Value parameter is the ItemID Similarly to decode an item use the MC Get Value To Int andMC Get Next Value To Int functions where the value returned is the ItemID The following sample code fragment gives an example of encoding a Pre formatted Grayscale Image I
30. JPEG Lossless Supported Photometric Interpretations and Bit Depths JPEG Lossless Non Hierarchical Process 14 Photometric RGB Interpretation MONOCHROME2 Samples Per Pixel The JPEG_2000 transfer syntax is UID 1 2 840 10008 1 2 4 91 JPEG 2000 Image Compression and uses Pegasus libraries 6820 6920 for lossy or lossless Table 20 details the photometric interpretation and bit depths supported by the standard compressor and decompressor for this transfer syntax Table 20 JPEG 2000 Lossy Supported Photometric Interpretations and Bit Depths JPEG 2000 When used for Lossy Photometric MONOCHROME 1 YBR_ICT RGB Interpretation MONOCHROME2 esee s w e s s o we pe 9 M RGE Healthcare Merge DICOM Toolkit SPECIAL NOTES Merge DICOM Toolkit can update group 0x0028 for you M RGE Healthcare User s Manual The JPEG_2000_LOSSLESS_ONLY transfer syntax is UID 1 2 840 10008 1 2 4 90 JPEG 2000 Image Compression Lossless Only and uses Pegasus libraries 6820 6920 for lossless Table 21 details the photometric interpretation and bit depths supported by the standard compressor and decompressor for this transfer syntax Table 21 JPEG 2000 Lossless Supported Photometric Interpretations and Bit Depths JPEG 2000 Lossless Photometric MONOCHROME1 YBR_RC RGB Interpretation MONOCHROME2 T ese fe w e s s we pe 9 When using the standard compressor all d
31. Most of these functions have three parameters in common a MsgItemID to specify the message object a Tag to specify the attribute whose value is being fetched and a value variable to which the value stored in the attribute is assigned See the Reference Manual for detailed specifications of these functions The MC Get Value family of functions also operate on DICOM file objects and item objects since both of these objects are also constructed of DICOM attributes M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare Table 11 The MC_Get_Value Family of Functions Function Type Description MC Get Value Count Returns the number of values assigned to an attribute in a message object Multi valued attributes can have more than one value assigned to them MC Get Value Length Returns the length of attribute s value in bytes MC Get Value Gets the first and possibly only value of an attribute in a message object There are eleven functions of this type the one you use depends on the data type of the variable to which you are assigning to the attribute s value e g string short int long int float Get Next Value Gets the next value of a multi valued attribute in a message object There are eleven functions of this type the one you use can depend on the data type of the value you are assigning to the attribute e g string short int long int float MC Get Value To Function
32. RT Plan Storage RT Image Storage RT Structure Set Storage RT Treatment Summary Record Storage Secondary Capture Image Storage Segmentation Storage Surface Segmentation Storage Spatial Registration Storage Spatial Fiducials Storage Spectacle Prescription Report Storage Standalone Overlay Storage Standalone Curve Storage Standalone Modality LUT Storage Standalone VOI LUT Storage Ultrasound Image Storage Ultrasound Multi frame Image Storage Video Endoscopic Image Storage Video Microscopic Image Storage Video Photographic Image Storage VL Endoscopic Image Storage VL Microscopic Image Storage VL Photographic Image Storage VL Slide Coordinates Microscopic Image Storage Command C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE C STORE M RGE Healthcare M RGE Fiealthcare Service VL Whole Slide Microscopy Image Storage XA XRF Grayscale Softcopy Presentation State Storage X Ray Angiographic Image Storage X Ray Radiofluoroscopic Image Storage X Ray Radiation Dose SR Storage X Ray 3D Angiographic Image Storage X Ray 3D Craniofacial Image Storage 12 lead ECG Waveform Storage Ambulatory ECG Waveform Storage Arterial Pulse Waveform Storage Basic Voice Audio Waveform Storage
33. Send Response Message AssociationID ResponseStatus ResponseMessageID status MC Read Message AssociationID Timeout amp MessageID amp ServiceName amp Command The parameters to the Send Request Message and MC Send Response Message include an AssociationID identifying the open association over which the message is to be sent and a MessagerD identifying the message object to be sent The Send Response Message call includes one additional parameter ResponseStatus that must be set to a valid DICOM response status defined in mergecom h Example response status codes for the N GET RSP response message are summarized in Table 15 Response codes for other DICOM commands are described in the appropriate Applications Guides and in Part 4 of the DICOM Standard 69 Fiealthcare Merge DICOM Toolkit Receiving Messages Using select to handle asynchronous events 70 User s Manual Table 15 Valid Response Message Status Codes for an N GET Command N_GET_RSP Status Codes N_GET_SUCCESS N GET WARNING OPT ATTRIB UNSUPPORTED N GET ATTRIBUTE LIST ERROR N GET CLASS INSTANCE CONFLICT N GET DUPLICATE INVOCATION N GET MISTYPED ARGUMENT N GET NO SUCH SOP CLASS N GET NO SUCH SOP INSTANCE N GET PROCESSING FAILURE N GET RESOURCE LIMITATION N GET UNRECOGNIZED OPERATION When your application makes an MC Read Message call the AssociationID parameter specifies the a
34. an application to be DICOM conformant it must e meet the minimum general conformance requirements specified in Part 2 and service specific conformance requirements specified in Part 4 Network Services and or Parts 10 and 11 Media Services and e have a published DICOM conformance statement detailing the above conformance and any optional extensions Conformance also applies to aspects of the communications protocol that are managed by the DICOM Toolkit Most parameters are configurable by your application The conformance statement for the Merge DICOM Toolkit in the Reference Manual lists all these protocol parameters and how they can be configured Conformance Statement templates in each of the Sample Application Guides also provide guidance in preparing your conformance statement for your application Part 2 also deals with private extensions to the DICOM Standard by defining Standard Extended Services Standard Extended Services give your application a little more flexibility by allowing you to add private attributes as long as they are of value type 3 optional and are documented in the conformance statement DICOM also allows you to define your own Specialized and Private Services These should be avoided by most applications since they are non standard add complexity to your application and limit interoperability If you are significantly extending services or creating your own private services you may need the Merge DICOM
35. and that both the above copyright notice s and this permission notice appear in supporting documentation THE SOFTWARE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE DATA OR PROFITS WHETHER IN AN ACTION OF CONTRACT NEGLIGENCE OR OTHER TORTIOUS ACTION ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE Except as contained in this notice the name of a copyright holder shall not be used in advertising or otherwise to promote the sale use or other dealings in this Software without prior written authorization of the copyright holder APIs to perform Unicode conversion are listed below e MC Enable Unicode Conversion e MC Byte To Unicode 124 M RGE Healthcare Merge DICOM Toolkit User s Manual e MC Unicode To Byte e MC Get Value To UnicodeString e Get Next Value To UnicodeString e MC Set Value From UnicodeString e MC Set Next Value From UnicodeString A new type UChar is introduced to represent a Unicode character storage unit This storage unit inherited from the ICUAC library is implicitly defined as unsign
36. applications This value should also be slightly larger than the PDU MAXIMUM LENGTH to increase performance Setting this value to an even multiple of the MSS 1460 bytes will help increase performance on most platforms 135 Merge DICOM Toolkit 136 User s Manual TCPIP SEND BUFFER SIZE This option sets the TCP IP send buffer size Higher values for this buffer generally will increase the network performance of the toolkit for client SCU applications This value should also be slightly larger than the PDU MAXIMUM LENGTH to increase performance Setting this value to an even multiple of the MSS 1460 bytes will help increase performance on most platforms EXPORT UNDEFINED LENGTH SQ This option determines how Merge DICOM Toolkit encodes sequences within all non DICOMDIR messages and files When set to Yes the sequences are encoded as undefined length This eliminates the need for Merge DICOM Toolkit to determine the length of sequences and increases performance EXPORT GROUP LENGTHS TO NETWORK This option determines if Merge DICOM Toolkit encodes group length attributes when writing to the network if they are included in the message being sent Setting this option to No increases Merge DICOM Toolkit network performance This eliminates the need for Merge DICOM Toolkit to determine the length of groups when streaming to the network EXPORT GROUP LENGTHS TO MEDIA This option determines if Merge DICOM Toolkit encodes
37. are two utility functions Byte To Unicode and MC Unicode To Byte that convert DICOM character set to Unicode and back respectively These two functions perform conversion without requiring any message handle There are four functions MC Get Value To UnicodeString Get Next Value To UnicodeString Set Value From UnicodeString and Set Next Value From UnicodeString dealing with getting and setting an attribute value with Unicode character string The operations are similar to the regular MC Get Next Value To String and MC Set Next Value From String counterparts There are no equivalent functions to get set private attribute with UnicodeString To workaround user can call MC Unicode To Byte and then MC Set pValue to set an attribute value or call MC Get pValue and then Byte To Unicode to get an attribute value Finally if user prefers unloading the Unicode conversion library calling MC Enable Unicode Conversion with zero as argument will unload the ICUAC libraries Note that if user calls Release Library the ICUAC library will NOT be unloaded automatically Below is an example usage of the utililty functions M RGE 125 Fiealthcare Merge DICOM Toolkit User s Manual example to convert Unicode to Japanese character sets MC STATUS status char charsets 3 MC UChar uChars input input is defined externally a Unicode string int numberOfUnicodeCharact
38. be used to convert a DICOM object between various transfer syntaxes and formats The utility will read an input file and then write the Formats output file in the transfer syntax specified in the command line The utility can also convert between DICOM stream format and the DICOM file format Note that on platforms that supporting the Pegasus libraries for compression the utility can also compress and decompress images The syntax for the mc3conv utility is the following mc3conv input file output file t lt syntax gt m tag tag new value gt input file DICOM SOP Instance message fil output file Output DICOM SOP Instance message fil E Specify transfer syntax for output file where syntax il for implicit little endian default el for explicit little endian for explicit big endian rle for RLE m Specify format of output file to be DICOM 3 media Part 10 format tag Change value for this tag in output file where tag the tag that is to be changed in hex 0 new value the value for the tag in quotes multi values Separated as 11 12 h Show these options Example mc3conv in img out dcm t el m mc3echo Do a DICOM The mc3echo utility validates application level communication between two DICOM ping AE s An echo test is the equivalent of a network ping operation but at the DICOM application level rather than the TCP IP transport level A
39. describe how commands and data shall be encoded so that decoding devices can interpret them Part 7 describes the structure of the DICOM commands that along with related data make up a DICOM message This part also describes the association negotiation process where two DICOM applications mutually agree on the services they will perform over the network Part 8 describes how the DICOM messages are exchanged over the network using two prominent transport layer protocols TCP IP and OSI Note that IPv4 and 6 are supported by DICOM and by Merge DICOM Toolkit This is termed the DICOM Upper Layer Protocol DICOM UL Part 9 describes how DICOM messages shall be exchanged using the old 50 pin point to point connection originally specified in the predecessor to DICOM ACR NEMA Version 2 This part has been retired from the DICOM standard Part 10 describes the DICOM model for the storage of medical imaging information on removable media It specifies the contents of a DICOM File Set the format of a DICOM File and the policies associated with the maintenance of a DICOM Media Storage Directory DICOMDIR structure Part 11 specifies the Media Storage Application Profiles that standardize a number of choices related to a specific clinical need modality or application This includes the specification of a specific physical medium and media format e g CD ROM 3 5 high density floppy as well as the types of information obj
40. developed with Merge DICOM Toolkit When using the MC Wait For Association call you can specify a timeout in this call to indicate how long you wish to wait for a valid association request if you specify a timeout of 1 you wait forever If this call returns with a status of MC NORMAL COMPLETION an Application ID is returned that indicates the AE that has received the valid association request along with an Association ID for the new association This Association ID is used to refer to this particular association in future calls The server application must either MC Accept Association or MC Reject Association before DICOM messages can be exchanged over the association The server application detects when the client has released the association in the last message received from the client This will be discussed further in later sections dealing with DICOM message exchange You also have the option of using the MC Wait For Secure Association call Use that function if you will be supplying additional code that will maintain a secure connection using a protocol such as Secure Socket Layer SSL or Transport Layer Security TLS Refer to the Merge DICOM Toolkit Reference manual for more information about the MC Wait For Secure Association call Server Side Example of MC Wait For Association status MC Wait For Association Service List 1 1 amp calledApplicationID amp associationID if status MC NORMAL COMPLETION pri
41. different points in your application see Table 23 Table 23 Point of performance overhead associated with file validation File Object Creation Method Point at which file access overhead for validation occurs MC_Create_File MC Create File MC Create Empty File MC Validate File Note You must use Set Service Command before validating and or writing a file created in this manner Using MC Create File has an up front performance cost but provides additional validation as you set the value of attributes in the file object With the Create Empty File method the cost occurs on validation itself Many times the MC Validate File is selectively used in an application as a runtime option or conditionally compiled into the source code Validation might only be used during integration testing or in the field for diagnostic purposes Reasons for this include performance since the overhead associated with file validation may be an issue especially for larger files having many attributes or on lower end platforms M RGE Healthcare Merge DICOM Toolkit M RGE Fiealthcare User s Manual Also validation can clutter the message log with warnings and errors that may not be desirable in a production environment Converting Files to from Messages Two very useful and powerful functions are supplied for converting file objects to message objects and vice versa These functions
42. empty SR root object C_SRH_Add_Type_Child Adds a new child node where Type is a child Content Item Type for example TEXT C_SRH_Set_Type_Data Sets additional attributes for the Content Item node e C_SRH_Add_Reference Creates a reference to another Content Item node by reference C_SRH_Free_SR Releases all memory associated with SR object including the underlying message object Can be used for cleanup in case of failure M RGE 117 Fiealthcare Merge DICOM Toolkit User s Manual High Level functions for reading SR These functions quickly navigate the SR content tree and access Content Item s attributes The following functions are included C SRH Get First Child Retrieves the first child Content Item relationship and node type C_SRH_Get_Next_Child Retrieves the next child Content Item relationship and node type C_SRH_Get_Reference Retrieves the Content Item referenced by reference C_SRH_Get_Type_Data Retrieves attributes of the Content Item where Type is a child Content Item Type for example DATE e High Level utility functions Those functions are used internally by the other high level functions and exposed to provide greater flexibility to the user Following functions are included in that group MC SRH Create Type Node Creates a new Content Item node specified by Type The node is created as a
43. functionalit described in previous sections of this manual also applies to item objects The MC Get Value andMC Set Value families of functions work on item objects as well as message objects simply specify an ItemID in the first parameter to these functions rather than a MessagelD Four additional Merge DICOM Toolkit API functions are required for Items and are specific to items MC Open Item is used to create an Item with a given ItemName and returns an ItemID handle MC Free Item is used to release the items resources back to the operating system MC Empty Item is used to empty the values of all the attributes of an item and MC List Item lists the contents of an item object to an output stream ItemName s are strings used to identify each item and are listed in the message txt file for attributes in messages having a VR of SQ The contents of each item are also listed in the message txt file Below are two excerpts of message txt one showing a reference to the Referenced Film Box Item and the other the contents of that item at EH HH BASIC FILM SESSION N SET RQ aE EH HH aE aE EH EEE 0008 0005 Specific Character set cs 3 Defined Terms
44. large block and keep them in primary memory for rapid access Once again while MyPDStoreFunction is a callback function in this example it is not what is being referred to when we discuss Callback Functions with a capital C and capital F in Merge DICOM Toolkit Callback Functions are discussed later 8 bit Pixel Data For DICOM s Implicit VR Little Endian transfer syntax the pixel data attribute s 7 e0 0010 VRis specified as being OW independent of what the bits allocated and bits stored attributes are set to To reduce confusion Merge DICOM Toolkit sets the VR of pixel data for the other non encapsulated transfer syntaxes to OW When retrieving or setting pixel data with the Get Value To Function and MC Set Value From Function calls the toolkit assumes that the OW pixel data is encoded in the host system s native endian format as defined by DICOM Figure 9 describes how 8 bit pixel data is encoded in an OW buffer for both big and little endian formats 58 M RGE Healthcare Merge DICOM Toolkit M RGE Fiealthcare User s Manual Byte 0 MSb Pixel2 LSb Byte 0 MSb Pixel 1 Byte2 MSb 4 LSb Byte 2 Byte 3 MSb Piel3 Byte 3 MSb Pixel6 156 MSb MSb MSb Sb 0 i LSb i LSb i LSb i LSb LSb e Byte 4 Byte 4 Byte 5 MSp Pixel 5 LSb Byte 5 M Pixel 6 e e e e e Big Endian Machines Little Endian Machines Figure 9 Sample Pixel Data Byte Streams for 8 bit
45. last block of data The callback function must provide all of the compressed decompressed data when CBisLast is received CBoutdataLength should be set to the number of bytes of data the callback is providing at CBoutdataValue A call with CBrelease set to TRUE non zero should release all memory that the compressor decompressor has allocated The callback should return MC NORMAL COMPLETION to indicate success or MC CANNOT COMPLY for any failure When decompressing an image without an offset table the toolkit does not know if it has reached the end of a fragment or the end of a frame The decompressor MUST return data whenever it is available so the toolkit can keep track of the image data returned When the toolkit determines it has received an entire image and the image has been decompressed the isLast will be set and no data will be passed to the callback Merge DICOM Toolkit has two sets of built in compressors and decompressors The MC RLE Compressor and MC RLE Decompressor can be used to compress or decompress data encoded in the RLE transfer syntax These routines support data with photometric interpretation of MONOCHROME1 MONOCHROME2 RGB and YBR FULL The routines are supported on all Merge DICOM Toolkit platforms These callbacks should be registered as follows status MC Register Compression Callbacks msgID MC RLE Compressor MC RLE Decompressor The other Merge DICOM Toolkit built in
46. lossy compression is done the Lossy Image Compression Lossy Image Compression Ratio and Lossy Image Compression Method tags will be updated by Merge DICOM Toolkit 79 Merge DICOM Toolkit Server Callbacks Client Callbacks Other uses of Callbacks Use of empty messages require adding the pixel data taa 80 User s Manual Using Callback Functions The Callback Functions with a capital C capital F discussed in this section exhibit one significant difference from the callback functions used in the MC Get Value To From Function functions and stream handling functions described earlier Callback Functions throttle the data flow as the message object is communicated over the network Rather than storing attributes with large OB OW values within the message object itself your application is responsible for maintaining the value of these attributes This can be useful on Systems with limited resources or when dealing with very large pixel data elements such as large multi frame images MC Register Callback Function is used when performing DICOM interchangeable media operations when the Open File Bypass OBOW function is called to read in a DICOM file See further discussion of this function in the DICOM Files section later in this manual A server SCP application can call Register Callback Function to register a Callback Function that will be called repetitively as the at
47. message objects when your application is done with them You can keep an old message object around if you plan to reuse the message object often and have the available memory Send the Film Session Creation message y status MC Open Message amp messageID BASIC FILM SESSION N CREATE RQ if status MC NORMAL COMPLETION printf Unable to open request message Mn printf Nt sWMn MC Error Message status return 1 session sop 1 2 840 10008 5 1 1 1 status MC Set Value From String messageID 0x00000002 session sop if status MC NORMAL COMPLETION printf MC Set Value From String failed Nn printf Nt sWMn MC Error Message status MC Free Message amp messageID MC Abort Association amp associationID MC Release Application amp applicationID return 1 session uid 1 2 840 10008 75 89 status MC Set Value From String messageID 0x00001000 Ssession uid if status MC NORMAL COMPLETION printf MC Set Value From String failed n printf Nt sWMn MC Error Message status MC Free Message amp messageID MC Abort Association amp associationID MC Release Application amp applicationID return 1 status MC Set Value From String messageID NUMBER OF COPIES 71 if status MC NORMAL COMPLETION printf MC Set Value Fr
48. my MC3File The configuration file can be modified and reloaded into MC3File with the c option to generate a DICOM message This option reads in a configuration file previously generated by mc3file The service name and command for the message need not be specified on the command line because they are contained in filename Because multiple files generated with this option are identical mc3file assume only one file should be generated This assumption can be overridden by specifying a number on the command line This option lists all the service command pairs supported by mc3file When generating a message this option can be used instead of explicitly specifying the Service name and command on the command line When specified alone in the command line the complete list of pairs is printed out without pausing This option allows the user to generate a DICOM file When generating the file object mc3file encodes the File Meta Information This option prevents mc3file from prompting the user for correct service command pairs It is a useful option when running the program from a batch file This option specifies the transfer syntax the DICOM message generated is stored in The default transfer syntax is implicit little endian The possible values for syntax are il for implicit little endian el for explicit little endian and eb for explicit big endian f file This option all
49. on the SCU side A traditional SCP can effectively support asynchronous communications by simply enabling its negotiation over associations lt is possible however to do further optimization of SCP applications On operating systems that Merge DICOM Toolkit supports threading an SCP can be written to process messages in the background as it is reading request messages and to send response messages over the association when processing is completed In this scenario after reading a message the SCP would pass the received message to another thread for processing and freeing The main SCP thread would then go to reading the next message Once processing is complete for a message the background thread would signal the main thread to send a response message for the request This allows the network bandwidth to be more fully utilized by having the SCP reading data off the network as much as possible The SCP in this case must monitor the negotiated max operations so that it is not exceeded Figure 14 shows an example message exchange between an SCU and SCP when using asynchronous communications This example shows how the SCU spends less time reading the response messages and moves to sending the next request message to increase bandwidth utilization M RGE Healthcare Merge DICOM Toolkit Message ID must be set for asvnchronous M RGE Fiealthcare User s Manual SCU SCP Read Request Msg 1 Send Request Msg 1 Process Request Msg
50. rather than transmitted or received over a network Most Merge DICOM Toolkit API calls dealing with message objects can also operate on items and files these calls would be called polymorphic in object oriented parlance DICOM messages items and files will be described in much greater detail later in this document Sample Applications Included with the toolkit are sample applications in ANSI C source code form and a Makefile that compiles and links the sample applications with the toolkit library Sample client and server applications are supplied for Storage Query Retrieve and Print services Also a compression sample and DICOM File Service application are provided Before writing your own applications you should read the corresponding Sample Application Guides and look at the sample source The guides also include a DICOM conformance statement for the example application While these sample applications are primitive in features and user interface they illustrate how to use the DICOM Toolkit API to perform DICOM services over a network Merge DICOM Toolkit Extended Toolkit Merge Healthcare has a DICOM Database Management System in which the DICOM standard is maintained This database along with a few additional tools is used to generate the binary message info and dictionary files accessed by the DICOM Toolkit or compiled into your application As the DICOM standard is updated or extended by simply maintaining this database we ca
51. representation using MC_Get_Value_To_Float and then convert it to string outside of the toolkit using the desired precision A special purpose function exists in the Value family called MC Get Value To Buffer This function is only used to retrieve the value of a binary attribute or an attribute whose value representation is unknown Below is example of parsing attributes from a PATIENT STUDY ONLY QR FIND C FIND RQ message This example reads in attributes that may contain query values The application could use these values to query its own database and send a response message s with one or more matches See the Query Retrieve Sample Application Guides for further details Again your application should free the message object when done using it Example of parsing a C FIND RQ Messag First is Patient ID M RGE Fiealthcare Merge DICOM Toolkit User s Manual status MC Get Value To String FindMessageID PATIENT ID 64 PatientID Next is Patient name status MC Get Value To String FindMessageID MC PATIENTS NAME 64 szPatientName Next is patients birth day status MC Get Value To String FindMessageID MC PATIENTS BIRTH DATE 8 szPatientBday Finally patients sex status MC Get Value To String iMessageID MC PATIENTS SEX 16 szPatientSex Now you can per
52. requester of the association The client proposes settings for both of these fields and the server responds with values less than or equal to the proposed values that are then used for the association The term notifications refers to NCEVENT REPORT messages that are sent from an SCP to an SCU These messages are used by DICOM services such as Print Job and Storage Commitment The terms operations and sub operations refer to all other message types The term sub operations specifically refers to services such as Query Retrieve where multiple response messages are sent for a single request message For a client negotiating the SCU role the invoked field refers to the number of operations that could be sent without receiving a response message and the performed field would specify the maximum number of notifications received before the client is required to send a response message For a client negotiating the SCP role and an asynchronous window the invoked field would refer to the maximum notifications sent before receiving a response and the performed field would refer to the maximum operations received before the client is required to send a response Although asynchronous operations can be used for all DICOM service classes this feature is most useful with the Storage Service Class Asynchronous operations can be utilized to improve the network performance of transferring a large number of C STORE messages over an association D
53. return values Here is an example on how to use DDH Traverse Records tofinda specific series record Find Information Structure typedef struct RecordFind Struct char matchValue int matchRecordID char buff 256 RecordFind Find callback MC TRAVERSAL STATUS FindSeriesCbk int CrtRecID void CbkData C STATUS status DIR RECORD TYPE recType REC TYPE UNKNOWN RecordFind findInfo RecordFind CbkData Check for record type C DDH Get Record Type CrtRecID amp recType if recType REC TYPE SERIES return MC TS CONTINU CJ Em Check for matching Series Instance UID status MC Get Value To String CrtRecID MC SERIES INSTANCE UID 256 findInfo gt buff if status MC NORMAL COMPLETION if stremp findInfo matchValue findInfo gt buff 0 Found a match findInfo matchRecordID CrtRecID return MC TS STOP Continue the traversal with the next series record instead of lower level instance records return MC TS STOP LOWER void FindSeries RecordFind findInfo M RGE 95 Healthcare Merge DICOM Toolkit Automatic deletion of referenced items Make sure you are committed 96 User s Manual findInfo matchValue 1 2 3 4 5 6 7 8 9 findInfo matchRecordID 0 MC DDH Trav
54. smaller than the value for the WORK BUFFER SIZE the chunk will simply be stored If it is larger the data will be stored internally WORK BUFFER SIZE buffers By supporting a maximum PDU size and WORK BUFFER SIZE larger than 28K Merge DICOM Toolkit will store the buffers in memory allocated with the C function malloc This can be used to reduce Merge DICOM Toolkit s typical memory usage Note however that SCU systems do not necessarily size their PDUs according to the Maximum PDU size negotiated This solution does not guarantee that image data will be stored with malloc As is the case when assigning image data with Set Value From Function the LARGE DATA STORE and LARGE DATA SIZE configuration options can be used to store the data in temporary files Loading Messages from Disk This functionality shares the same characteristics as when data is being read from the network with MC Read Message MC Stream Message is used to read DICOM stream objects and Open File MC Open File Bypass OBOW Open File Upto and MC Open File Upto Tag Bypass Value are used to read DICOM Part 10 format files Whereas objects being read from the network determine memory usage by the PDU size these functions determine memory usage by the size buffers passed from their callback functions The WORK BUFFER SIZE configuration value has the same impact as when reading from the
55. standalone Message Item without SR object e MC SRH Add Child Adds newly created Content Item node to an existing Content Item node as a child Encoding SR Documents The creation of the SR document involves following steps 1 2 3 4 5 Creating a new SR object as a root node Adding Content Items nodes to the tree based on the templates definition Converting SR object to a message object Adding Patient Study Series and other attributes required by the IOD definition Saving the result message object to a file To create a new SR you need to know the IOD type you are creating and the templates that will be used to generate the SR Document Content 118 M RGE Healthcare Merge DICOM Toolkit User s Manual Key Object Selection Example The Key Object Selection document is constrained by a single template The following template is taken from the DICOM Part 16 TID 2010 KEY OBJECT SELECTION Type Non Extensible NL Rel with Parent VT Concept Name VM Condition Value Set Typ Constraint 1 CONTAI DCID 7010 Key Object NER Selection Document Titles E Root node 2 gt HAS CONCEPT MOD CODE EV 113011 DCM 1 n U Document Title Modifier 3 HAS CONCEPT MOD CODE EV 113011 DOM 1 UC Row 1 Concept DCID Document Title Name 113001 7011 Modifier DOM Rejected for Quality Reasons or 113010 DCM Quality Issue 4 HAS CONCEPT MOD
56. syntax and one of the proposed transfer syntaxes As previously discussed the abstract and transfer syntaxes supported by a server SCP are defined through a service list contained in the Merge DICOM Toolkit Application Profile When support within a server SCP is limited to the three non encapsulated DICOM transfer syntaxes the toolkit will transparently handle the use of M RGE Healthcare Merge DICOM Toolkit Transfer Syntax Lists for SCUs User s Manual multiple presentation contexts for a DICOM service However when encapsulated DICOM transfer syntaxes are used the server SCP must be able to determine the transfer syntax of messages it receives so that it can properly parse the pixel data contained in them When a single presentation context is negotiated for a DICOM service the Get First Acceptable Service and Get Next Acceptable Service functions can be used to determine the transfer syntax for a service When more than one presentation context is negotiated for a service the Message Transfer Syntax function must be used to retrieve this transfer syntax The following is a typical call to this function MC Status Get Message Transfer Syntax ImageMsgID amp transferSyntax Exchange of messages over the network is discussed further below The presentation contexts supported for client SCU applications using Merge DICOM Toolkit are also defined through the Merge DI
57. the application to start preparing the next message to be sent while data is still being transferred The maximum settings for these options is operating system dependent It is suggested that these options be configured to the maximum setting for an operating system If the settings are too high an error will be logged to the merge log file It is important that devices using asynchronous communications be configured to use full duplex network connections Using asynchronous communications in half duplex mode would greatly degrade performance Performance would more than likely be lower than if only synchronous communications were used Using Compression Decompression Callback Functions The purpose of registering a compression decompression callback is to more easily support compressed transfer syntaxes in DICOM Compressed transfer syntaxes are used to take advantage of the decreased image size that goes along with compressed pixel data This is important when dealing with large images or series of images that need to be stored or transmitted across a network The callbacks when registered are utilized any time the functions in Table 16 are called and the transfer syntax of a message has been set to JPEG_BASELINE JPEG EXTENDED 2 4 LOSSLESS HIER 14 2000 JPEG 2000 LOSSLESS ONLY or RLE M RGE Healthcare Merge DICOM
58. 0 7919 MC3 T5 0018 0091 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0018 1041 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0018 1060 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0018 1250 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0018 5101 VE Required attribute has no value 01 3 52 209 00 7919 T5 ae 0032 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 5 0020 0037 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 5 0020 0052 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 5 0020 0060 VI Unable to check condition 01 3 52 09 00 7919 MC3 5 0020 1040 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 5 0020 1041 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 5 0028 0006 VI Unable to check condition 01 3 52 09 00 7919 MC3 5 0028 0030 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 5 0028 0034 VI Unable to check condition 01 3 52 09 00 7919 MC3 5 0028 1101 VI Unable to check condition 01 3 52 09 00 7919 MC3 5 0028 1102 VI Unable to check condition 01 3 52 09 00 7919 MC3 5 0028 1103 VI Unable to check condition 01 3 52 09 00 7919 MC3 5 0028 1201 VI Unable to check condition 01 3 52 09 00 7919 MC3 5 0028 1202 VI Unable to check condition 01 3 52 09 00 7919 MC3 5 0028 1203 VI Unable to check condition
59. 50 VR U Class UID Length 23 gt 1 2 840 10008 3 1 2 Instance UID Length 44 gt 2 16 840 1 113669 4 lt Attribute gt lt Item gt lt Attribute gt Attribute Tag 00090010 VR Lo Code PCode PrivateCode Length PCODE lt Attribute gt Attribute Tag 00091010 VR LO Attribute Tag 00091015 VR UN PCode SAMPLE PCODE Length 6 gt 30y lt Attribute gt Attribute Tag 7FE00010 VR OW Encoding Base64 Length 262144 00 09 lt Attribute gt lt DataSet gt DcmFile Attribute Tag 00081155 VR U T3 ngth 1 gt I Name Referenced SOP 3 3 lt Attribute gt I Name Referenced SOP 960070 844 1026926027 44 ame Private Creator 11 gt SAMPLE ame Private PCode SAMPLE PCODE Length 6 gt Valuel lt Attribute gt ame Private 20 20 20 20 20 ame Pixel Data gt 06 00 04 00 04 00 02 142 M RGE Healthcare
60. AL COMPLETION This callback function is called by the Merge DICOM Toolkit Library only when triggered by your application For example your application might use MyPDStoreFunction to retrieve the value of the MC_ATT_PIXEL_DATA attribute 7FEO 0010 as follows MC Status MC Get Value To Function ImageMsgID PIXEL DATA NULL MyPDStoreFunction On making this call the toolkit library will repetitively callback MyPDStoreFunction until all the pixel data has been read from the message object without any errors In this case no user data is passed through to the callback function since UserInfo is NULL Performance Storing or setting aside Pixel Data a block at a time is especially useful for very large Tuning Pixel Data and or on platforms with resource e g memory limitations In this case you would also want to set LARGE DATA STORE to the value FILE in the Service Profile so that Merge DICOM Toolkit will also maintain the pixel data value stored in the message object itself in a temporary file If your application runs on a resource rich system you should set LARGE DATA STORE to the value MEM in the Service Profile and Merge DICOM Toolkit will keep the pixel data values in the message object stored in memory rather than using temporary files This should improve performance Also in this case you may want your callback function to store the Pixel Data in fewer big blocks or one
61. C STORE command for the DICOMDIR service even though it does not formally exist In the DICOM Standard Finally the DICOM file can be padded at the end with the Data Set Trailing Padding attribute FFFC FFFC whose value is specified by the standard to have no significance File Sets DICOM Files must be stored on removable media in a DICOM File Set A DICOM file set is defined as a collection of DICOM files sharing a common naming space within which file ID s are unique e g a file system partition A DICOM File Set ID is a string of up to 16 characters that provides a name for the file set A File ID is a name given to a DICOM file that is mapped to each media format specification in Part 12 of DICOM A file ID consists of an ordered sequence of one to eight components where each component is a string of one to eight characters One can certainly imagine mapping such a file ID to a hierarchical file system and this is done for several media formats in Part 12 It is important to note that DICOM states that no semantic relationship between DICOM files shall be conveyed by the contents or structure of file ID s e g the hierarchy This helps insure that DICOM files can be stored in a media format and file system independent manner The allowed characters in both a file ID s and file set ID s are a subset of the ASCII character set consisting of the uppercase characters A Z the numerals 0 9 and the underscore M RGE Heal
62. CODE EV 113011 DOM 1 MC Row 1 Concept DCID Document Title Name 113013 7012 Modifier DOM Best In Set 5 gt HAS CONCEPT MOD INCLUD DTID 1204 Language of 1 U E Content Item and Descendants 6 gt HAS OBS CONTEXT INCLUD DTID 1002 Observer 1 0 E Context 7 CONTAINS TEXT EV 113012 DCM Key 1 U Object Description 8 CONTAINS IMAGE Purpose of Reference 1 MC At least one of shall not be present Rows 8 9 and 10 shall be present 9 CONTAINS WAVEF Purpose of Reference 1 MC least one of ORM shall not be present Rows 8 9 and 10 shall be present 10 gt CONTAINS COMPO of Reference 1 MC At least one of SITE shall not be present Rows 8 9 and 10 shall be present M RGE Fiealthcare Merge DICOM Toolkit User s Manual The code below generates a valid DICOM KO object and illustrates how the template is encoded using the Merge DICOM Toolkit functions static char fileName KO demo dcm MC_STATUS status int srID childID tempId iteml item2 item3 unsigned short miVer 0x0100 Create SR Document as well as the root CONTAINER The template ID is 2010 and we used the Best in Set context ID from the CID 7010 Status MC SRH Create SR KEY OBJECT SELECTION DOC 2010 SR CC SEPARATE 113013 DCM Best In Set amp srID if status MC NORMAL COMPLETION proce
63. COM Toolkit Application Profile The following is a typical client s SCU configuration Acme Store SCP PORT NUMBER 104 HOST NAME acme suni SERVICE LIST Storage Service List Storage Service List SERVICES SUPPORTED SERVICE 1 1 4 Number of Services STANDARD CT In this case the client SCU would propose the CT Image Storage service in a single presentation contexts The transfer syntaxes for each service are the three standard non encapsulated DICOM transfer syntaxes The following example is the configuration for a client SCU that supports more than one presentation context for a service Acme Store SCP PORT NUMBER 104 HOST NAME acme_sunl SERVICE_LIST Storage_Service_List Storage_Service_List SERVICES_SUPPORTED 2 Number of Services SERVICE_1 STANDARD_CT SYNTAX_LIST_1 CT Syntax List 1 SERVICE 2 STANDARD CT SYNTAX LIST 2 CT Syntax List 2 CT Syntax List 1 SYNTAXES SUPPORTED 1 4 Number of Syntaxes SYNTAX 1 JPEG BASELINE CT Syntax List 2 SYNTAXES SUPPORTED 1 4 Number of Syntaxes SYNTAX 1 IMPLICIT LITTLE ENDIAN If a server SCP accepts both of these presentation contexts the client SCU must use the Set Message Transfer Syntax function to specify which presentation context to se
64. E Generic implant Template Storage C STORE Grayscale Softcopy Presentation State Storage C STORE Blending Softcopy Presentation State Storage C STORE Color Softcopy Presentation State Storage C STORE Pseudo Color Softcopy Presentation State Storage C STORE Implant Assembly Template Storage C STORE Implant Template Group Storage C STORE Implantation Plan SR Document Storage C STORE Intraocular Lens Calculations Storage C STORE Intravascular Optical Coherence Tomography Image Storage C STORE For Presentation Intravascular Optical Coherence Tomography Image Storage C STORE For Processing Key Object Selection C STORE Macular Grid Thickness and Volume Report C STORE Mammography CAD SR C STORE MR Image Storage C STORE MR Spectroscopy Storage C STORE Multi frame Grayscale Byte Secondary Capture Image Storage C STORE Multi frame Grayscale Word Secondary Capture Image Storage C STORE Multi frame Single Bit Secondary Capture Image Storage C STORE Multi frame True Color Secondary Capture Image Storage C STORE Nuclear Medicine Image Storage C STORE Positron Emission Tomography Image Storage C STORE Procedure Log C STORE Raw Data Storage C STORE Real World Value Mapping Storage C STORE C STORE RT Beams Delivery Instruction Storage M RGE 25 Fiealthcare 26 Service RT Beams Treatment Record Storage RT Brachy Treatment Record Storage RT Dose Storage RT lon Beams Treatment Record Storage RT lon Plan Storage
65. E Healthcare Merge DICOM Toolkit M RGE Fiealthcare User s Manual The IOD may specify restrictions on Content Items and Relationship Types that also constrain the flexibility with which Observation Context may be described The IOD may specify Templates that offer or restrict patterns and content in Observation Context Structured Reporting Templates Templates are patterns that specify the Concept Names Requirements Conditions Value Types Value Multiplicity Value Set restrictions Relationship Types and other attributes of Content Items for a particular application SR Document templates are defined in the Part 16 of the DICOM Standard Part 17 of the DICOM also has some explanatory information on encoding SR Documents The Merge DICOM Toolkit SR Functions follow DICOM Templates structures and allow straightforward encoding based on template tables SR Templates are described using tables of the form shown on Table 26 Table 26 SR Template Definition NL Rel with VT Concept VM Type Condition Value Set Parent Name Constraint 1 2 3 Row Number Each row of a Template Table is denoted by a row number The first row is numbered 1 and subsequent rows are numbered in ascending order with increments of 1 This number denotes a row for convenient description as well as reference in conditions The Row Number of a Content Item
66. E PCODE Length 6 gt INAgNAEy lt Attribute gt lt Attribute Tag 00100010 VR PN Name Patient s Name Length 28 gt Last First lt Attribute gt M RGE 141 Healthcare Merge DICOM Toolkit User s Manual Attribute Tag 2 7FE00010 VR OW Name Pixel Data Encoding Base64 Length 262144 gt HQAABgMAAATHBAM lt DataSet gt DcmFile lt Attribute gt XML structure with the default encoding of bulks and attributes with VR UN lt xml version 1 0 encoding utf 8 gt DcmFile FileMetaInfo Service STANDARD SEC CAPTURE Command C STORE RQ Attribute Tag 00020001 vR OB Information Version Length 2 gt Attribute Tag 00020016 VR AE ame File Meta 00 01 lt Attribute gt ame Source Application Entity Title Length 15 gt MERGE STORE SCP Attribute FileMetaInfo DataSet Service STANDARD SEC CAPTURE Command C STORE RQ TransferSyntax 1 2 840 10008 1 Attribute Tag 00080008 vg CS Length 24 ORIGINALNSECONDARYNO Attribute Tag 00080016 VR UI Length 25 gt 1 2 840 10008 5 1 4 Attribute Tag 00081111 VR SQ Performed Procedure Step Sequenc 2 mt ame Image Type HER Attribute ame SOP Class UID 1 1 7 Attribute ame Referenced Item Attribute Tag 000811
67. ED_FROM Source Content Item conveys spatial or temporal coordinates selected from the Target Content Item s E g SCOORD CLOSED 1 1 5 10 SELECTED FROM IMAGE 36 E g TCOORD SEGMENT 60 200mS SELECTED FROM WAVEFORM 109 Merge DICOM Toolkit 110 User s Manual Content Item Identifier Content Items are identified by their position in the Content Item tree They have an implicit order as defined by the order of the Sequence Items When a Content Item is the target of a by reference relationship its position is specified as the Referenced Content Item Identifier in the source Content Item Figure 19 illustrates an SR content tree and identifiers associated with each Content Item Content Item ID Content Item ID 01 02 Content Item ID 01 01 Content Item ID 01 01 02 Content Item ID 01 01 01 Figure 19 SR Item Identifier Observation Context Observation Context describes who or what is performing the interpretation whether the examination of evidence is direct or quoted what procedure generated the evidence that is being interpreted and who or what is the subject of the evidence that is being interpreted Initial Observation Context is defined outside the SR Document Content tree by other modules in the SR IOD i e Patient Module Specimen Identification General Study Patient Study SR Document Series Frame of Reference Synchronization General Equi
68. Failed return MC_CANNOT_COMPLY Read next chunk of pixel data from source into DataBlock and set BlockSize to the size of the chunk read in if ReadFailed return MC_CANNOT_COMPLY if LastBlockRead close Pixel Data source here ny IsLastBlock TRUE return MC_NORMAL_COMPLETION M RGE Healthcare 53 Merge DICOM Toolkit Performance Tuning Reading values from a message MC_Get_Value functions are polymorphic 54 User s Manual This callback function is called by the Merge DICOM Toolkit Library only when triggered by your application For example your application might use MyPDSupplyFunction to set the value of the MC PIXEL DATA attribute 7FEO 0010 as follows MC Status MC Set Value From Function ImageMsgID MC ATT PIXEL DATA NULL MyPDSupplyFunction On making this call the toolkit library will repetitively callback MyPDSupplyFunction until it indicates that all the pixel data has been read in without any errors In this case no user data is passed through to the callback function since UserInfo is NULL Supplying Pixel Data a block at a time is especially useful for very large Pixel Data and or on platforms with resource e g memory limitations In this case you would also want to set LARGE DATA STORE to the value FILE in the Service Profile and Merge DICOM Toolkit will store the Pixel Data value in a temporary file
69. ID 0x00080000 Ox7FDFFFFF EXPLICIT LITTLE ENDIAN NULL MyStreamHandler This call converts the attributes from 0008 0000 through 7FDF FFFF in the message object identified by MyMessageID into DICOM message stream using the explicit little endian transfer syntax Explicit little endian transfer syntax is one of the three DICOM Transfer Syntaxes supported by Merge DICOM Toolkit DICOM defines two other transfer syntaxes implicit little endian the default DICOM transfer syntax and explicit big endian See Part 5 of the DICOM Standard for a detailed description of transfer syntaxes 67 Merge DICOM Toolkit Performance Tuning Deflated Streams 68 User s Manual MyStreamHandler isa callback function you supply in your application that receives and manages the stream data a block at a time This callback function is similar to the example in Get Value To Function except that it handles a message stream rather than Pixel Data See the API description in the Reference Manual for further details Once your application has done the above and stored the stream somewhere you could later rebuild a message object containing only group 0008 using Status Stream To Message MyMessageID 0x00080000 0x0008FFFF EXPLICIT LITTLE ENDIAN NULL MyStreamProvider This call converts only the attributes in group 0008 of the stream supplied by your callback function MyStreamProvider a
70. Merge Healthcare 200 E Randolph Street Chicago IL USA 60601 877 44 MERGE Copyright 2012 Merge Healthcare Incorporated Unauthorized use reproduction or disclosure is prohibited This document has been prepared by Merge Healthcare Incorporated for its customers The content of this document is confidential It may be reproduced only with written permission from Merge Healthcare Specifications contained herein are subject to change and these changes will be reported in subsequent revisions or editions Merge Healthcare is a registered trademark of Merge Healthcare Incorporated DICOM is a registered trademark of National Electrical Manufacturers Association NEMA Merge DICOM Toolkit is a trademark of Merge Healthcare The names of other products mentioned in this document may be the trademarks or registered trademarks of their respective companies For assistance please contact Merge Healthcare Customer Support e n North America call toll free 1 800 668 7990 then select option 2 e International call Merge Healthcare in Canada 1 905 672 7990 then select option 2 e Email mdtsupport merge com Part Date Revision Description COM 620 December 2012 1 0 Updated bi annually Merge DICOM Toolkit User s Manual Contents 1 The DIGOM Standatd nte atate uie dern 1 The Merge DICOM Toolkit 0 cccceeceeececeeeeeceaeeeeeeeeeeeeecaaeeeeaaeseee
71. N printf Unable to open association with Ss n RemoteAppTitle printf Nt sWMn MC Error Message status return 1 else printf Connected to remote system s n RemoteAppTitle Do your messag xchange here status MC Close Association amp associationID if status MC NORMAL COMPLETION printf Close association failed n printf Nt sMn MC Error Message status return 1 Now you can exit normally M RGE Healthcare 43 Merge DICOM Toolkit Waiting for an User s Manual There are two methods to wait for associations for server applications The first is to use the MC_Wait_For_Association call The second method is to use the association MC Wait For Connection callin conjunction with the MC Process Association Request call The MC Wait For Association callis the traditional method for waiting for associations with Merge DICOM Toolkit The MC Wait For Connection call was introduced to address an inherent design problem with MC Wait For Association Specifically with the MC Wait For Association call if a remote system connecting is slow in sending its association negotiation information MC Wait For Assocation does not process any other connections while it is waiting for this information It is recommended that MC Wait For Connection be used for any new applications being
72. NCED SERIES SEQUENCE item2 MC Set Value From Int srID MC CURRENT REQUESTED PROCEDURE EVIDENCE SEQUENCE iteml Convert message to file MC Message To File srID fileName M RGE Healthcare 121 Merge DICOM Toolkit User s Manual Reading SR Documents Reading SR Documents is done in a similar way as encoding but in reverse sequence e Reading a File or receiving a message object e Reading root level attributes e Converting message object into SR object e Traversing SR content tree and extracting Content Node attributes The following code demonstrates a reading sequence for the Key Object Document generated above MC STATUS status int srID childID tempId SR CONTENT TYPE nodeType char conceptNameValue 512 char conceptNameScheme 512 char conceptNameMeaning 512 SR RELATIONSHIP relationship int isLast char sopClassUid 512 char sopInstanceUid 512 int refFramesCount convert file gt message gt SR objects status MC File To Message srID if status MC NORMAL COMPLETION printf MC File To Message Eror code d status return Here you can read root level attributes from the message status MC Message To SR srID if status MC NORMAL COMPLETION printf MC Message To SR Eror code d status return Get a concept name from the first CONTAINER node status MC SRH Get Concept Name srID conceptNam
73. ORMED PROCEDURE STEP SEQUENCE MC ATT PATIENTS NAME Jane Doo MC ATT PATIENT ID 234567 MC Set Value From String srID MC Set Value From String srID MC Set Value From String srID D D MC Set Value From String sr MC Set Value From String sr MC Set Value From String srID 1 2 3 4 5 6 7 200 MC Set Value From String srID MC Set Value From String srID MC Set Value From String srID MC Open Item amp iteml HIERARCHICAL SOP INST REF MACRO MC Set Value From String iteml WL 2 ada Dada T 1007 MC ATT PATIENTS BIRTH DATE 19991109 MC ATT PATIENTS SEX F MC ATT STUDY INSTANCE UID MC ATT SERIES INSTANCE UID MC ATT STUDY ID 345678 MC ATT SERIES NUMBER LTY MC_ATT_INSTANCE_NUMBER E MC Set Value To NULL srID MC ATT PERFORMED PROCEDURE CODE SEQUENCE STUDY INSTANCE UID MC Open Item amp item2 HIERARCHICAL SERIES REF MACRO MC Set Value From String item2 3 6 200 MC Open Item amp item3 REF 50 following UIDs are the same MC Set Value From String item3 MC Set Value From String item3 VL 2 3544 5 11 5 MC_ATT_SERIES_INSTANCE_UID as used in the Row 8 item MC_ATT_REFERENCED_SOP_CLASS_UID 1 2 3 4 1 MC_ATT_REFERENCED_SOP_INSTANCE_UID MC Set Value From Int item2 MC ATT REFERENCED SOP SEQUENCE item3 MC Set Value From Int iteml1 MC REFERE
74. OVIDING_DATA Callback is receiving OB OW OF data and a chunk of this data is being supplied Merge DICOM Toolkit has set CBdataSizePtr to the number of bytes of data it is providing at CbdataBufferPtr The length of the chunk must be less than INT_MAX Merge DICOM Toolkit will set CbisFirstPtr to TRUE not zero the first time it is providing data for this attribute s value i e when it is providing the first block of data Merge DICOM Toolkit sets CbisLastPtr to TRUE not zero the last time it will be providing data for this attribute s value i e when it is providing the last block of data FREE_DATA The memory associated with the enclosing message file or item is being freed and the callback can free its memory associated with the OB OW OF data Note that callbacks are only called with the callback type of the USE_FREE_DATA_CALLBACK configuration option is enabled in the system profile Because a single Callback Function s behavior and usage of parameters must vary based on the value of CBt ype this can all seem very confusing You may want to break for a beverage and read this section once more Also be sure to read the detailed specification of MC Register Callback Function inthe Reference Manual Sequences of Items The DICOM Value Representation SQ is used to indicate an attribute in a DICOM message that contains a value that is a sequence of items A sequence of items is a set of objec
75. Only one compressor and one decompressor may be registered for a message at a time If you use your own callback functions both callbacks are prototyped the same They must be prototyped as follows MC STATUS My De compressionCallback int CBMessageID void CBContext unsigned long CBdataLength void CBdataValue unsigned long CBoutdataLength void CBoutdataValue int CBisFirst int CBisLast int CBrelease CBMessageID allow a single Callback Function to handle requests for different messages CBContext is a pointer to a user defined structure that contains data that must be maintained between de compression calls because the pixel data may be presented and received over multiple callbacks CBdataLength CBdataValue CBisFirst and CBisLast are used to manage the data flow into the callback function When the callback is called with data a chunk is being supplied Merge DICOM Toolkit has set CBdataLength to the M RGE Healthcare 75 Merge DICOM Toolkit SPECIAL NOTE Built in Compressor and Decompressor 76 User s Manual number of bytes of data it is providing at CBdataValue The length of the chunk must be less than INT MAX Merge DICOM Toolkit will set CBisFirst to TRUE non zero the first time it is providing data i e when it is providing the first block of data Merge DICOM Toolkit sets CBisLast to TRUE non zero the last time it will be providing data i e when it is providing the
76. R groups Content Items and defines the heading or category of observation that applies to that content The heading describes the content of the CONTAINER Content Item and may map to a document section heading in a printed or displayed document 107 Merge DICOM Toolkit 108 User s Manual Relationship Types between Content Items Table 25 describes the Relationship Types between Source Content Items and the Target Content Items The choice of which may be constrained by the IOD in which this Module is contained Merge DICOM Toolkit Definition column specifies the enumerated value used in the Toolkit to identify the Content Item Relationship Table 25 SR Relationship Types Relationship Type CONTAINS Merge DICOM Toolkit Definition SR_REL_CONTAINS Description Source Item contains Target Content Item E g CONTAINER History CONTAINS TEXT mother had breast cancer CONTAINS IMAGE 36 HAS OBS CONTEXT SR_REL_HAS_OBS_CONTEXT Has Observation Context Target Content Items shall convey any specialization of Observation Context needed for unambiguous documentation of the Source Content Item E g CONTAINER Report HAS OBS CONTEXT PNAME Recording Observer Smith John Dr HAS CONCEPT MOD SR_REL_HAS_CONCEPT_MOD Has Concept Modifier Used to qualify or describe the Concept Name of the Source Content item such as to create a post coordinated description of a conc
77. Toolkit How to register a Compression Callback Function User Defined Compressor and or Decompressor User s Manual Table 16 Callbacks Utilized by Functions that set and get Pixel Data Function Callback Utilized t Encapsulated Value From Function Compressor Encapsulated Value From Function Compressor t Encapsulated Value To Function Decompressor t Next Encapsulated Value To Function Decompressor t Frame To Function Decompressor If there are no callbacks registered the above functions will work the same as MC Get Value To Function andMC Set Value From Function except encapsulation delimiters will be removed and inserted respectively MC Register Compression Callbacks is used to register the callback functions that take in pixel data and return a compressed image or take in compressed data and return the uncompressed pixel data You may provide your own function s to do this or you may use one of the built in compressors and decompressors supplied by Merge DICOM Toolkit The Register Compression Callbacks be used to register a Callback Function with the toolkit as follows status MC Register Compression Callbacks msgID MyCompressionCallback MyDecompressionCallback This call registers My De compressionCallback with the DICOM Toolkit library to handle data to be compressed decompressed for a message object when the above functions are called
78. Toolkit Extended Toolkit to assist in defining these services so that they can be supported by the toolkit 33 Merge DICOM Toolkit MERGE Environmental Variable 34 User s Manual Using Merge DICOM Toolkit You can use the Merge DICOM Toolkit out of the box by using its supplied utility programs and sample applications In this section we discuss how to configure the toolkit and to use the utility programs Use of the sample applications are described in the sample application guides Later we discuss how to develop your own DICOM applications using the Merge DICOM Toolkit library Configuration Merge DICOM Toolkit is highly configurable and understanding its configuration files is critical to using the library effectively Related parameters are grouped into sections in a configuration file as follows SECTION 1 PARAMETER 1 valuel PARAMETER 2 value2 SECTION 2 PARAMETER 3 value3 Related sections are grouped into one of four configuration files an initialization file an application profile a system profile and a service profile Each of these configuration files are discussed separately below Only the key configurable parameters are summarized in this document See the Reference Manual for detailed descriptions of all configuration files and their parameters Initialization File The Merge DICOM Toolkit Initialization File usually called merge ini pro
79. aSizePtr CBdataBufferPtr is not used REQUEST_FOR_DATA Callback is supplying OB OW data and a chunk of this data is being requested Callback must set CBdataSizePtr to the number of bytes of data you are providing at CbdataBufferPtr The length of the chunk must be less than INT_MAX Merge DICOM Toolkit will set CBisFirstPtr to TRUE not zero the first time it is requesting data for this attribute s value i e when you are to provide the first block of data Callback must set CbisLastPtr to TRUE not zero the last time you are providing data for this attribute s value i e when you are providing the last block of data M RGE 81 Healthcare Merge DICOM Toolkit User s Manual Value of Cbtype Required Callback Behavior REQUEST_FOR_DATA_WITH_OFFSET Callback is supplying OB OW data and a chunk of this data from a specific offset in the seekable stream is being requested CbdataSizePtr is the pointer to long which contains the offset of required data After data reading Callback must set CBdataSizePtr to the number of bytes of data you are providing at CbdataBufferPtr The length of the chunk must be less than INT_MAX Merge DICOM Toolkit will set CBisFirstPtr to TRUE not zero the first time it is requesting data for this attribute s value i e when you are to provide the first block of data Callback must set CbisLastPtr to TRUE not zero
80. ading of DICOM files and the creation maintenance and navigation of DICOMDIR s DICOM Toolkit features include message validation against the DICOM Standard support of sequences of items Callback Functions for flexible handling of Pixel Data and support of Private Attributes This section of the User s Manual attempts to present the highlights of the Merge DICOM Toolkit API in a logical manner as it might be used in real DICOM applications The function calls are presented in the context of example ANSI C source code snippets and alternative approaches are presented that tradeoff certain features for the benefits of increased performance Most of the discussions that follow pertain both to networking and media interchange applications only the Association Management Negotiated Transfer Syntaxes and Message Exchange sections are networking specific The last two sections DICOM Files and DICOMDIR are media interchange specific Library Initialization Your first call to the Merge DICOM Toolkit Library must always be the MC Library Initialization function This function specifies how and when you wish to initialize the library with the contents of its configuration files data dictionary and message info files Almost all typical applications will initialize themselves from configuration files and make use of the binary dictionary and message info files in building message objects So in most cases the initialize call will look
81. and ElementByte e The Group number of a private attribute must always be odd while for a standard attribute it is always even e Before encoding a private attribute into a message object your application must allocate a private block for that attribute and then add the attribute to that private block in that message object Private attributes are added to a message object using the MC Add Private Block andMC Add Private Attri bute calls MC Add Private Block is used to reserve a block of up to 255 private attributes Taking the example earlier in this document to add a private block to group 1455 of myMessage With a PrivateCode of ACME IMG INC you would make the call Status MC Add Private Block myMessageID ACME IMG CORP 0x1455 Once reserved a private block is referenced using a PrivateCode The following call could then be used to add an attribute that contains the name of a field engineer to the private block Status MC Add Private Attribute myMessageID ACME IMG CORP 0x1455 00 PN Up to 255 other private attributes could be added to the ACME IMG CORP private block in group 1455 using the above call E1ement Byte values of 01 through FF If more attributes are required another private block with a different PrivateCode will need to be added PrivateCodes must be used to refer to private attributes because private blocks may be placed in different locations within a private
82. andard are published as supplements For example the media extensions have been incorporated into the DICOM Standard as a supplement that contains addenda to various parts of the standard e g PS3 3 PS3 4 If you find that this document references a part of the Standard which you cannot find obtain the proper supplement from NEMA Other additions to the Standard e g new image objects or documents are also published as supplements NEMA also makes all supplements to the standard freely available on their FTP server You can reference these supplements at ftp medical nema org medical Dicom Final The Merge DICOM Toolkit The Merge DICOM Toolkit provides a generalized implementation of DICOM in an ANSI C Function Library which you can link with your application You make simple function calls to open connections with other DICOM devices on a network and to build and exchange DICOM messages or DICOM files Figure 2 presents a pictorial representation of a DICOM Application Entity The Merge DICOM Toolkit implements Parts 5 6 7 8 and 10 of the DICOM Standard It also makes it much easier for your application to implement according to Parts 3 and 4 by supplying many tools for the management of DICOM messages and to Part 12 by supplying hooks to your application s underlying file system M RGE Healthcare Merge DICOM Toolkit User s Manual DICOM Application Entity Association Negotiation Part 7 Annex D In
83. another Content Item or by reference to an Attribute from the dataset other than within the Content Sequence 0040 A730 Inclusion of Templates A Template may include another Template by specifying INCLUDE in the Value Type field and the identifier of the included Template in the Concept Name field All of the rows of the specified Template are in included in the invoking Template effectively substituting the specified template for the row where the inclusion is invoked Whether or not the inclusion is user optional mandatory or conditional is specified in the Requirement and Condition fields The number of times the included Template may be repeated is specified in the VM field We recommend that you implement templates as a subroutine or function call In that case the inclusion of the template will be implemented as a call to that template with passing parameters Some of the templates defined in DICOM Part 16 already have predefined parameters and they are indicated by a name beginning with the character Memory Management The Structured Reporting API is designed in such way that you only deal with types of objects e Message objects which are messages and message items e Structured Report objects which are the root SR Content Item and child Content Items You can convert back and forth between these objects and work with one object type at a time However it is imported to know how these objects are managed internally
84. application entities AE s Storage Computed Radiography Image Transfer of medical images Storage and related standalone data CT Image Storage between DICOM application Enhanced CT Image Storage entities either over a MR Image Storage network or using Enhanced MR Image Storage interchangeable media MR Spectroscopy Storage Enhanced MR Color Image Storage Spatial Fiducials Storage Spatial Registration Storage Deformable Spatial Registration Storage Ultrasound Image Storage Ultrasound Multi frame Image Storage Enhanced US Volume Storage Generic implant Template Storage Implant Assembly Template Storage Implant Template Group Storage Implantation Plan SR Document Storage Intraocular Lens Calculations Storage Macular Grid Thickness and Volume Report Nuclear Medicine Image Storage Positron Emission Tomography Image Storage Enhanced PET Image Storage Breast Tomosynthesis Image Storage The DICOM Standard actually refers to services as Service Object Pairs SOPs and meta services as Meta SOPs We avoid this terminology to avoid unnecessary detail and confusion M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare Service Class Services Description Intravascular Optical Coherence Tomography Image Storage For Presentation Intravascular Optical Coherence Tomography Image Storage For Processing Digital X Ray Image Storage For Presentation Digital X Ray Image Storage For Processing Dig
85. are MC File To Message and MC Message To File Remember that most DICOM files other than the DICOMDIR file are simply the information object portion of a DICOM message encapsulated within a DICOM file surrounded by a file preamble meta information and optional padding MC File To Message has a single FileID parameter and returns a status This call converts the FileID to a message handle by removing the file preamble meta information and optional padding from the file object and adding the command attributes While Merge DICOM Toolkit sets the values of many of these command type attributes automatically some services require the application to set them Once converted to a message object the object can be sent and received over the network using the calls detailed earlier Conversely MC Message To File has two parameters MessageID and FileName and also returns a status This call converts the MessagelID to a file handle by removing the command attributes from the message object and adding the file preamble and meta information attributes The file meta information attributes must be set by the user Optional padding can be added if required using the MC Write File call If the message was originally opened as an empty message and the command and service were not set then MC Set Service Command must be called before the file object can be validated These two functions are most often useful when reading and writin
86. ata needs to be right justified i e bit O contains data but the highest bits may not RGB and YBR must be non planar R1G1B1 R2G2B2 or YI Y2B1R1 YSYABSR3 JPEG 2000 JPEG 2000 LOSSLESS ONLY will cause a irreversible or reversible color transformation when compressing RGB data The Photometric Interpretation MUST be changed from RGB to YBR ICT if JPEG 2000 is used with COMPRESSION WHEN 2 USE LOSSY Yes Lossy color transform for lossy compression YBR RCT 2000 LOSSLESS ONLY or JPEG 2000 with COMPRESSION WHEN J2K USE LOSSY No Lossless color transform for lossless compression Similarly on the decompression end the Photometric Interpretation should be changed back to RGB but the Lossy Image Compression attribute should indicate it has been lossy compressed After using the standard compressor or decompressor the application should call Thread Release to free resources allocated by Pegasus before the thread that used the compressor or decompressor ends This is needed to avoid memory leaks on Linux and UNIX platforms The UPDATE GROUP 0028 ON DUPLICATE configuration option can also be enabled so Merge DICOM Toolkit will update the Group 0x0028 tags for you When this configuration option is enabled the Photometric Interpretation will be updated for you as mentioned above When decompressing an image the photometric interpretation will also be updated In addition when
87. ation and the callback function See the reference manual for a more detailed description of MC Write File and the YourToMediaFunction callback function One special variant on MC Write File is also provided by the toolkit e Write File Callback functions similar to MC Write File except that it allows for attributes whose values are of type OB or OW to be supplied by a Callback Function if and only if you have registered it with Register Callback Function The user s Callback Function can then deal with the Pixel Data as it sees fit Other Useful File Object Functions Other useful functions that operate on file objects include MC Reset Filename allows your application to change the file name associated with an existing file object This could be useful if you have read in a DICOM file modified its contents and then wish to write the file out with a new file name e MC Empty File clears the value from all attributes in the file object This function provides a more efficient mechanism for writing out several file objects of the same type Your application can simply empty and refill the attribute values rather than inducing the processing overhead of freeing and creating a whole new file object 91 Merge DICOM Toolkit Performance Tuning 92 User s Manual MC Set File Preamble and MC Get File Preamble allow specialized application to examine and modify the 128 byt
88. ay not be included in the message If included the attribute may or may not have a null value 2 The attribute must have a value and be included in the message If the value for the attribute is unknown and cannot be specified its value shall be null Private Attributes The DICOM Standard allows application developers to add their own private attributes to a message as long as they are careful to follow certain rules A private attribute is identified differently than are standard attributes Its tag is composed of an odd group number a private identification code string and a single byte element number For example ACME Imaging Inc might define a private attribute to hold the name of the field engineer that last serviced their equipment They could assign this attribute to private attribute tag 1455 IMG 00 This attribute has group number 1455 a private identification code string of ACME IMG and a single byte element number of 00 ACME could assign up 255 other private attributes to private group 1455 by using the other element numbers 01 FF Part 5 of DICOM explains how these private tags are translated to standard group and element numbers and encoded into a message while avoiding collisions Merge DICOM Toolkit handles these details for you DICOM makes a couple of rules that must be followed when using private attributes e Private attributes shall not be used in place of required Value Ty
89. be treated as failed and resent at a later time It is possible to create deadlock situations when writing an asynchronous application A situation may arise where both the client and server are attempting to send data to each other that would cause a deadlock In general applications should poll for incoming messages before sending a new message In particular a Storage SCU should poll for a response message before sending a new request message Because of the size of the messages exchanged it is most likely that a Storage SCU would deadlock if it were not checking for response messages Finally the configuration options TCPIP_SEND_BUFFER_SIZE and TCPIP RECEIVE BUFFER SIZE are important for maximizing network performance The send buffer specifies the amount of data that can be queued in the TCP IP stack of the OS without actually being sent The receive buffer specifies the amount of data that can be received by the TCP IP stack of the OS before a Merge DICOM Toolkit application must start reading the data These options allow data to be queued by the OS in the background while a Merge DICOM Toolkit application is doing other activities For instance an entire response message can usually be stored in a the send buffer and a call to MC Send Response Message return before any data has even been sent over the network Similarly an application calling MC Send Request Message Will return before all data has been sent This allows
90. bjects e g images medical imaging reports Figure 1 maps portions of the DICOM Standard dealing with networking to the ISO Open Systems Interconnection OSI basic reference model The organization and terminology of the DICOM Standard corresponds closely with that used in the OSI Standard ISO OSI Layers DICOM Parts Your DICOM Application Service and Message Application Definitions Parts 3 amp 4 N Message Exchange Part 7 used Encoding Parts 5 amp 6 Session amp Presentation DICOM Upper Layer ER Protocol Part 8 Network Data Link amp Physical Network Figure 1 The DICOM Protocol Stack Merge DICOM Toolkit Where to get the DICOM Standard Special Note User s Manual As auser of this toolkit you should have access to the DICOM Standard The Merge DICOM Toolkit takes care of most of the details of DICOM for you However the standard is the final word You will probably find Parts 2 6 most useful The DICOM Standard can be ordered from NEMA 1300 N 17 Street Suite 1847 Rosslyn VA 22209 USA http medical nema org The DICOM Standard is typically published every other year Each version includes approved changes since the last publishing The most recent version of the standard is available in PDF format and can be downloaded from NEMA s public ftp site at ftp medical nema org medical Dicom 2011 Please note that the DICOM Standard is evolving so rapidly that additions to the St
91. boldface Margin notes in the left margin are used to highlight important points or sections of the document Portions of the document that can relate directly to the performance of your application are marked with the special margin note Performance Tuning Sample commands appear in bold courier font while sample output source code and function calls appear in standard courier font Hexadecimal numbers are written with a trailing H For example 16 decimal is equivalent to 10H hexadecimal Understanding DICOM The twelve separate parts of the DICOM Standard can seem overwhelming and most would agree that they are difficult to read Part of what makes a successful standard is precision and detail Our goal here is to explain the key concepts without delving too far into the detail most of which is handled automatically for you by the DICOM Toolkit General Concepts Some key concepts that must be understood to use the DICOM Toolkit wisely are common across both DICOM networking and interchangeable media applications These concepts are discussed first Application Entities The DICOM Standard refers extensively to Application Entities AEs An application entity is simply a DICOM application If your application interacts with other applications on a network or with interchangeable media using the DICOM protocol it is an application entity DICOM also refers to Service Class Users SCUs and Service Class Providers SCPs
92. c Worklist Management Print Management Study Content Notification Services Storage Commitment Push Storage Commitment Pull DICOM Basic Directory Storage and storage of various italicized services from the other Service Classes Patient Root Find Patient Root Move Patient Root Get Study Root Find Study Root Move Study Root Get Patient Study Only Find Patient Study Only Move Patient Study Only Get Modality Worklist Find Basic Film Session Basic Film Box Basic Grayscale Image Box Basic Color Image Box Printer Printer Configuration Print Queue Management Pull Print Request Printer Referenced Image Box VOI LUT Box Presentation LUT Basic Annotation Box Basic Print Image Overlay Box SOP Class Print Job Image Overlay Retired Basic Grayscale Print Mgmt Meta Basic Color Print Mgmt Meta Pull Stored Print Mgmt Meta Ref Grayscale Print Mgmt Meta Ref Color Print Mgmt Meta Basic Study Content Notification User s Manua Description Ensures that SOP Instances stored with the storage service class will not be deleted after reception but will be stored safely and can be retrieved again at a later point Exists as a member of every DICOM File Set and contains general information about the file set anda hierarchical directory of the DICOM files contained in the file set Management of images through a query and retrieval mechanism based on a small number of key attributes Su
93. can in turn point down the hierarchy to a semantically related directory entity Part 3 of the DICOM Standard specifies the allowed relationships between directory records in the section defining the Basic Directory IOD We reproduce this table here see Table 6 for pedagogical reasons but you should refer to the DICOM Standard for the most up to date and accurate specification 29 Table 6 Allowed Directory Entity Directory Record Type Record Types which may be included in the next lower level Directory Entity Root Directory Entity 2 PATIENT TOPIC PRINT QUEUE HANGING PROTOCOL PRIVATE PATIENT STUDY HL7 STRUC DOC PRIVATE HL7 STRUC DOC PRIVATE STUDY SERIES VISIT RESULTS STUDY COMPONENT FILM SESSION PRIVATE SERIES IMAGE STORED PRINT RT DOSE RT STRUCTURE SET RT PLAN RT TREAT RECORD OVERLAY MODALITY LUT VOI LUT CURVE SR DOCUMENT PRESENTATION KEY OBJECT DOC SPECTROSCOPY RAW DATA WAVEFORM REGISTRATION FIDUCIAL VALUE MAP ENCAP DOC STEREOMETRIC PRIVATE The first row of this table specifies the directory records that can be contained within the Root Directory Entity M RGE Healthcare Merge DICOM Toolkit User s Manua Directory Record Record Types which may be included in the next lower level Directory Entity TOPIC STUDY SERIES IMAGE OVERLAY MODALITY LUT VOI LUT CURVE FILM SESSION PRIVATE VISIT PRIVATE RESULTS INTERPRETATION PRIVATE INTERPRETATION PRIVATE
94. ce Register Callback Function can be used to access image data only when needed The memory requirements of an application can be greatly reduced by using this functionality When reading messages from the network Read Message supplies the user s registered callback function with the image data If the data does not need to be byte swapped into the system s native endian the amount of data supplied with each call is dictated by the PDU size of the data received When the data is byte swapped the length of data is specified by the WORK BUFFER SIZE configuration value As the data is received it would typically be written to disk in this scenario When MC Read Message returns the user is given the message read from the network The message object still contains a link to the registered callback function This link 101 Merge DICOM Toolkit 102 User s Manual can be removed by calling MC_Set_Value_To_Empty The header data can then be examined and later written to disk When sending data over the network Send Request Message will call the user s registered callback function for the image data The data can be supplied to Merge DICOM Toolkit in any length as required by the user s application The data is typically read from disk at this point and directly passed to Merge DICOM Toolkit After MC Send Request Message receives the data it byte swaps the data if needed and then writes it to the netwo
95. ce Tuning User s Manua Function Type Description MC_Set_Value_From_Function Specifies a function that is called repeatedly to set C the value of an attribute of VR OB OW OF or UT e g pixel data or fixed width value a chunk at a time These attributes tend to have very large values Note This callback function is different than the type of Callback Function registered using MC_Register_Callback_Function See the later discussion of Callback Functions Both the MC_Set_Value and MC_Set_Next_Value function types have several variants depending on the data type of the variable from which you are assigning the value see Table 10 These variants can be very helpful because they perform the necessary type conversion from any reasonable ANSI C data type to any compatible DICOM value representation If a type conversion is not reasonable e g from short int to LT then MC_INCOMPATIBLE_VR will be returned as a STATUS code Also other error statuses will be returned if the conversion was reasonable but the value stored in the variable made the conversion impossible e g MC_INVALID_VALUE_FOR_VR MC_VALUE_OUT_OF_RANGE If your message object was opened using MC_Open_Message the status code INVALID TAG Will be returned if you attempt to set the value of an attribute that is not a part of that message object This additional level of validation is lost if you use MC Open Empty Message s
96. cient and capable DICOM application see Figure 3 Following is a description of the header files that must be included within your application and a description of the library s structure and the external components it uses at runtime to provide DICOM functionality M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare User s Manual other sample applications M Media App L Q R App Sample Store App e ASCH files Merge s or linked DICOM Message Info into Database and executable Data Dictionary MergeCOM 3 Advanced MERGECOM PRO Library MERGECOM APP binary files MERGECOM SRV or linked into executable TCP IP File Edi Sockets Library Driver DICOM Network Key Merge Components Your Components DICOM Database Maintenance Tools Extended Toolkit Aum Figure 3 Merge DICOM Toolkit Library Organization Header Files Your applications interface to the DICOM Toolkit Library is described in five supplied header files e mergecom h e mc3msg h e mca3media h e mcstatus h e diction h Merge DICOM Toolkit User s Manual The mergecom h header file contains the prototypes of the functions used to register your application with the toolkit library and manage associations with other DICOM AE s over the network Mc3msg h specifies the message object functions that allow you to populate or parse a me
97. co terit ade rede te ice 48 Message Objects dan ad EA 49 Building 50 Parsing 4 nnn enn nes 54 8 bit Pixel Data nete 58 Encapsulated Pixel 59 Icom Image Sequences uote eet reet conet 61 Validating Messages ducc seed ENR Tue se XE RR 62 Streaming 4024244 0 000 enne nnns nnns 67 Message Exchange Network enne 69 GEM OC all ates M 69 Asynchronous 2 71 Using Compression Decompression Callback FUNCTIONS 74 Using Callback Functions ssssseseseseeeeeeeenennnenen nennen nennen 80 SEQUENCES of cde nte t 83 DIGOM File sce en ete tirer 87 File System Interface Functions ssssssseeeeeenns 87 Creating a File Object essere nre 88 Reading FICS 89 Creating and Writing Files sse 90 Other Useful File Object 91 al 92 C
98. compressor is MC Standard Compressor and the built in decompressor is MC Standard Decompressor These routines utilize libraries from Pegasus Imaging Corporation www jpg com They support the JPEG BASELINE JPEG EXTENDED 2 4 JPEG LOSSLESS HIER 14 JPEG 2000 2000 LOSSLESS ONLY transfer syntaxes with photometric interpretations MONOCHROME1 MONOCHROME2 RGB and YBR There are limits on the performance of the Pegasus libraries These compressors are only available on platforms that Pegasus supports These are 32 64 bit Windows on x86 32 bit Solaris on SPARC and 32 64 bit Linux on x86 If using the built in Pegasus based compressor or decompressor the callbacks should be registered as follows status MC Register Compression Callbacks msgID MC Standard Compressor MC Standard Decompressor M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare s Manual o D o For JPEG_BASELINE JPEG_EXTENDED_2_4 and JPEG LOSSLESS HIER 14 images can be compressed or decompressed at a maximum rate of 3 images or frames per second For JPEG 2000 and JPEG 2000 LOSSLESS ONLY a dialog will be displayed on Windows each time the compressor or decompressor is used For other platforms a message will be displayed to stdout and a several second delay will occur Full licenses can be purchased from Pegasus and configured in Merge DICOM Toolkit to remove these compression and dec
99. d as UN VR to the network This option is being added to release 2 3 0 of the Merge DICOM Toolkit For SCP systems receiving UN VR tags when they cannot handle them the following can be done Configure the SCP to only negotiate the Implicit VR Little Endian transfer syntax when receiving objects 131 Merge DICOM Toolkit User s Manual With the help of these options most UN VR problems in the field can be fixed simply by changing configuration values with the Merge DICOM Toolkit 132 M RGE Healthcare Merge DICOM Toolkit M RGE Fiealthcare User s Manual Appendix A Frequently Asked Questions This appendix lists some frequently asked questions by Merge DICOM Toolkit users 1 I recently received a new version of Merge DICOM Toolkit and wonder what is required for me to upgrade to the new version There are several areas where changes typically occur between releases of the Merge DICOM Toolkit The following are specific areas to look at when upgrading to a new version e Upgrade the header files The mc3msg h mergecom h mc3media h and mcstatus h files typically change with each release These files must be updated when moving to a new Merge DICOM Toolkit software release There are several structures defined in these files which have been updated in the past to support new functionality Not updating these files can cause problems with the library e Upgrading the library The Merge DICOM Toolkit libra
100. d as follows Structure containing Message Validation Error Information typedef struct ValErr_struct unsigned long Tag Tag with validation error int MsgItemID ID of message or item object containing the tag int ValueNumber Value number involved zero if error is not value related 64 M RGE Healthcare Merge DICOM Toolkit User s Manual MC_STATUS Status Error status code VAL_ERR In this source the offending attribute s tag is printed out along with the error string associated with Status If the image object violates DICOM the output to standard output in this example might look like the following MC_Validate_Message tag 101010 error Invalid value for this example output tag s VR This output states that the attribute 0010 1010 in the message has a value that violates the value representation for that attribute If the application wished to go on to find other errors in the same message it would call MC Get Next Validate Error until the status returned equals MC END OF LIST meaning that no more errors exist in the message It is on the initial call to MC Validate Message that all the validation takes place and that the results of the validation for the entire message are logged to the message log file Subsequent calls to Get Next Validate Error simply step through the results of th
101. d it in later using callback mechanism or process it directly from the file using your own special filters or hardware e Open File Upto Tag Bypass Value Will read the attributes from the media into the file object including a specified tag but will not read the tag attributes value This function is most useful when the DICOM file contains large pixel data 7FEO 0010 attribute In this case the most effective way to handle it is to use the callback mechanism through Register Callback Function so the attribute values could be retrieved from media upon later request The user s application callback must then deal with reading data of seekable DICOM file stream from the given offset provided in REQUEST FOR DATA WITH OFFSET command See the Reference Manual for a detailed description of the use of these more DICOM Toolkit functions Creating and Writing Files Once a DICOM file object has been created using the MC Create File function and filled in by using either the MC Open File orthe MC Set Value functions or a combination of both the file can be written out to media using a single MC Write File function status MC Write File fileID 2 NULL FileToMedia if status MC NORMAL COMPLETION printf sNtError on MC_Write_File n prefix printf sNtNt sWMn prefix MC_Error_Message status return status M RGE Healthcare Merge DICOM Toolkit Performance Tuning
102. date File also exists in the DICOM Toolkit and will be discussed further in a later section Another file supplied with Merge DICOM Toolkit is the message txt file This file contains a listing of all the messages supported by the toolkit and the parameters they are validated against message txt is a useful guide in your application development because it specifies the attributes that can make up the object instance portion of each message type service command pair and is often easier to use as a quick reference than paging through two or three parts of the DICOM Standard message txt also specifies the contents of items and files see discussions of Sequence of Items and DICOM Files later in this document Remember though that the DICOM Standard is the final word and that message txt has its limitations as described further below Validate Message does not validate the attributes that make up the command portion of a DICOM message Command attributes attributes with a group number less than 0008 are also not specified in message txt The Merge DICOM Toolkit Library sets as many of the command group attributes as possible automatically In some services your application will need to set command attributes e g the Affected SOP Class UID attribute 0000 0002 in the C MOVE response message These special cases are described further in the Application Guides and in Part 7 of the DICOM Standard An excerpt of message txt foll
103. dding Attribute File Meta Info Attribute LI Object Instance Attribute Figure 7 A DICOM File The file meta information begins with a 128 byte buffer available for application profile or implementation specific use Application Profiles standardize a number of choices related to a specific clinical need modality or application and are specified in Part 11 of the DICOM Standard The next four bytes of the meta information contain the DICOM prefix which is always DICM in a DICOM file and can be used as identifying characteristic for all DICOM files The remainder of the file preamble and object instance is encoded using tagged attributes as in a DICOM Message The object instances that can be stored within the DICOM file are equivalent to a subset of the object instances that can be transmitted in network messages The services that can be performed to interchangeable media are italicized in Table 1 The Media Storage Service Class in Part 4 of the DICOM standard specifies which service command pairs can be performed to media Remember it is the service command pair that identifies the object instance portion of the message and it is only the object instance portion of the message that is stored in a DICOM file The command attributes associated with a network message are never stored in a DICOM File The service command pairs whose corresponding object instances can be stored to media are summarized in Table 5 23 24
104. decompressor for this transfer syntax When lossy compressing RGB data the standard compressor by default compresses the data into YBR FULL 422 format The compressor can also compress in YBR FULL format if the COMPRESSION RGB TRANSFORM FORMAT configuration option is set to YBR FULL The Photometric Interpretation tag must be changed by the application after compressing RGB data Similarly the Photometric Interpretation tag should be changed back to RGB before decompressing YBR_FULL or YBR FULL 422 data 77 Merge DICOM Toolkit 78 User s Manual Table 18 JPEG Extended Supported Photometric Interpretations and Bit Depths JPEG Extended Process 2 amp 4 Photometric MONOCHROME 1 RGB YBR_FULL_422 Interpretation MONOCHROME2 YBR_FULL meses fe e s The JPEG_LOSSLESS_HIER_14 transfer syntax is UID 1 2 840 10008 1 2 4 70 JPEG Lossless Non Hierarchical First Order Prediction Process 14 Selection Value 1 Default Transfer Syntax for Lossless JPEG Image Compression and uses Pegasus libraries 6220 6320 Table 19 details the photometric interpretation and bit depths supported by the standard compressor and decompressor for this transfer syntax The standard compressor does not do a color transformation to RGB data when compressing with JPEG_LOSSLESS_HIER_14 The Photometric Interpretation tag should be left as RGB in this case Table 19
105. descriptor for the socket over which message exchange will occur Again select can be used to wait asynchronously for a DICOM request or response message This is discussed further later under Message Exchange Negotiated Transfer Syntaxes Network Only Merge DICOM Toolkit supports all currently approved standard and encapsulated DICOM transfer syntaxes Encapsulated transfer syntaxes require compression of the pixel data contained in the message These messages can be sent and received by the toolkit although the toolkit will not do the actual compression and decompression Encoding of this pixel data is discussed below For DICOM Toolkit users the toolkit allows for the negotiation of more than one transfer syntax for a given DICOM service This functionality is of most use for applications supporting encapsulated transfer syntaxes This functionality may be disabled by use of the ACCEPT MULTIPLE PRES CONTEXTS configuration value In order to understand how it is implemented a more in depth description of DICOM association negotiation is required During association negotiation a client SCU application will propose a set of presentation contexts over which DICOM communication can take place Each presentation context consists of an abstract syntax DICOM service and a set of transfer syntaxes that the client SCU understands The server SCP will typically accept a presentation context if it supports the abstract
106. e Service name and command are improperly specified mc3file will act as if the 1 option was used and ask the user to input the correct service name and command num This option specifies the number of message files to b generated by mc3file If the g option is used this option is not needed on the command line If the c option is used mc3file assumes the number is 1 although a higher number can be specified on the command line mc3file will vary any fields that have a value representation of time when multiple files are generated although when the c option is used the utility will use the time fields as specified in the configuration file Thus multiple message files generated with the c option are identical M RGE Fiealthcare 39 Merge DICOM Toolkit g lt filename gt c filename t syntax User s Manual This option causes mc3file to generate an ASCII configuration file The file contains a listing of all the valid attributes for the specified messag The utility also adds sequences contained in the message along with their attributes Each attribute in the file contains the tag value representation and the default value MC3File uses for the attribute If a given attribute has more than one value the character M is used to delimit the values default value listed as NULL means the attribute is set to NULL If the filename specified already exists it will be written over
107. e DICOM file preamble The DICOM Toolkit Library defaults the preamble to all zeroes as directed by the standard so in most cases your application will not need to use these functions e MC List File is the analogue of MC List Message except that it lists the contents of a file object including the file preamble rather than a message object This is a very useful function for validation and diagnosis of your application See the description of MC List Message earlier in this document See the Reference Manual and sample media application for more information on these calls File Validation File validation occurs in much the same manner as message validation Before the file can be validated it must be read into a file object created with an Create File call If the file object was created using MC Create Empty File thenMC Set Service Command must be called to identify the type of file object before validation can occur Please see the earlier discussion of message validation as almost all of it applies equally well to file validation DICOM file validation does involve processing overhead The most significant overhead is in the accessing of the message info files and significantly less overhead is involved in actually validating the contents of the file object structure It is important to understand that depending on the way in which your message object was created this validation overhead can occur at
108. e directory where the configuration files are located the toolkit will be unable to find the files and produce this error Changing these paths to absolute paths will fix the problem It is inconvenient to set absolute paths for the various configuration options in the merge ini and mergecom pro files that need them Is there a way to make these pathnames be configurable at run time 133 Merge DICOM Toolkit Performance Tuning 134 User s Manual Merge DICOM Toolkit allows the placement of environment variables in these pathnames This allows setting of a root directory for these pathnames The following is an example of how this functionality is used in our configuration files e MERGECOM PRO MERGE_ROOT mc3apps mergecom pro e Inthis example MERGE ROOT would be an environment variable set in a similar fashion as the MERGE INI environment variable e Aspecial macro MC3INIDIR is used to represent the directory where merge ini is It is used like the environment variable with the difference that itis automatically resolved and does not need to be set e II MERGECOM PROFILE MERGECOM 3 SERVICES or MERGECOM 3 APPLICATIONS contain relative paths with a prefix MC3INIDIR or MC3INIDIR the toolkit considers the path relative to the location of the merge ini file For example MERGECOM 3 PROFILE MCS3INIDIR config mergecom pro The path of the profile file is config mergecom pro rela
109. e validation passing additional errors found back to the application In the above example the message log file contains the following report 01 3 52 09 00 7919 MCserver process messages T4 Processing a C STORE RQ request example log file 01 3 52 09 00 7919 MC3 T5 0008 0005 VI Unable to check condition 01 3 52 09 00 7919 MC3 5 0008 0023 VI Unable to check condition 01 3 52 09 00 7919 MC3 TS 1 0033 VI Unable to check condition 01 3 52 09 00 7919 MC3 T5 0010 1010 VE 41Y Invalid value for tag s VR 01 3 52 09 00 7919 MC3 T5 0018 0010 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 5 0018 0015 VE Required attribute has value 01 3 52 09 00 7919 MC3 T5 0018 0020 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0018 0021 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0018 0022 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0018 0023 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0018 0050 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0018 0080 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0018 0081 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0018 0082 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0018 0084 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0018 0085 VW Invalid attribute for service 01 3 52 09 0
110. eValue sizeof conceptNameValue conceptNameScheme sizeof conceptNameScheme conceptNameMeaning sizeof conceptNameMeaning if status MC NORMAL COMPLETION printf MC SRH Get Concept Name Eror code d status return printf Document Title s n conceptNameMeaning Reading information about the first child node The following code assumes the Cntent Items type and their sequence To make it more generic you would need to create a recursive loop and process each child based on the returned Content Item node type 2 status MC SRH Get First Child srID amp childID amp relationship amp nodeType amp isLast 122 M RGE Healthcare Merge DICOM Toolkit User s Manual if status MC NORMAL COMPLETION printf MC SRH Get First Child Eror code 5 status return First child expected to be the CODE item if nodeType SR NODE CODE Print concept code code value status MC_SRH_Get_Concept_Name childID conceptNameValue sizeof conceptNameValue conceptNameScheme sizeof conceptNameScheme conceptNameMeaning sizeof conceptNameMeaning if status MC NORMAL COMPLETION printf MC SRH Get Concept Name Eror code d status return printf s conceptNameMeaning status MC_SRH_Get_CODE_Data childID conceptNameValue sizeof conceptNameValue conceptNameScheme sizeof conceptNameScheme conceptNameMeaning
111. ecords are added to or removed from directory entities within the DICOMDIR file is very great and can be very cumbersome Fortunately the Merge DICOM Toolkit supplies functions that make DICOMDIR maintenance much simpler for your application The toolkit includes a basic in memory DICOMDIR MC Dir functions and enhanced on demand incremental DICOMDIR API Mc_DDH_ functions The enhanced functions are now described Opening and Navigation Opening a DICOMDIR file is simplified compared to other DICOM files because of the specifics of DICOMDIR Opening an existing DICOMDIR file can be done using MC DDH Open function by specifying the location of the file on disk This function reads in the DICOMDIR file attributes up to the record sequence attribute Attributes for each record are read on demand whenever the application requests a record that was not read before or a record that was released from memory A new DICOMDIR file can be created using MC Create function specifying the location of the file an optional File Set ID and a template file containing group 2 and 4 attributes for the new DICOMDIR The identifier returned by either of these functions can be used with most value access function e g MC Get Value functions with certain limitations as described in the description of these functions When the application is done with the DICOMDIR object it must release the object as a regular file using MC
112. ectory entity might contain two Patient directory records and a Topic directory record One of the Patient directory records references a directory entity containing multiple Series records and a Film Session record for that Patient Each of these Series records reference directory entities containing Image records for that patient It is these Image records that reference the DICOM file containing the image objects acquired for the Patient whose directory hierarchy we have traversed See Table 6 for a description of the allowed entity hierarchies This directory entity hierarchy is encoded within the DICOMDIR as a single potentially very complex sequence of items where each item is a directory record Byte offset attributes within the directory records are used to point to other directory records within the same directory entity as well as lower level directory entities if one exists referenced by a directory record DICOM File ID s are encoded in the directory record if the record references a particular DICOM file in the file set The key observation here is that rather than using nested Sequences of Items to encode the DICOMDIR hierarchy the standard chose to use a single potentially very large sequence of items and byte offsets The standard defines these byte offsets as being measured from the first byte of the file meta information As you might well imagine the complexity of maintaining these byte offsets accurately as directory r
113. ects that can be stored within the DICOM File Set Part 11 also includes useful templates to provide guidance in authoring media application conformance statements Part 12 details the characteristics of various physical medium and media formats that are referenced by the Media Storage Application Profiles of Part 11 M RGE Healthcare Merge DICOM Toolkit M RGE Fiealthcare User s Manual While parts 11 and 12 of DICOM are expected to evolve along with the introduction of new clinical procedures and the advancement of storage media and file system technology Part 10 should remain quite stable since it specifies file formats independent of medical application or storage technology Part 13 details a point to point protocol for doing print management services This part has been retired from the DICOM standard Part 14 specifies a standardized display function for displaying grayscale images Part 15 specifies Security Profiles to which implementations may claim conformance Profiles are defined for secure network transfers and secure media Part 16 specifies the DICOM Content Mapping Resource DCMR which defines the templates and context groups used elsewhere in the standard Part 17 consolidates informative information previously contained in other parts of the standard It is composed of several annexes describing the use of the standard Part 18 specifies a web based service for accessing and presenting DICOM persistent o
114. ed short on all supported platforms This unit of storage is sufficiently covering the ranges of all DICOM specified character sets A Unicode string is treated as an array of MC UChar with terminator U 0000 To use the Unicode conversion functions MC Enable Unicode Conversion must be called first with a non zero argument to initialize the conversion library This involves loading the two supplied shared objects ICUAC in the distribution refer to Platform Notes The loading process also involves loading the dependency files of the ICU4C libraries Users must ensure all dependency files are accessible at runtime All conversion functions require an output buffer and its size to be passed down as arguments This means that user must pre allocate a big enough buffer with sufficient space to receive the output If insufficient output space is detected the functions will return MC BUFFER TOO SMALL As a rule of thumb when converting from Unicode to DICOM character set create a buffer size equals to number of Unicode characters 16 The overestimation is to ensure that any escape sequence and terminator byte NULL can be accommodated When converting from DICOM character set to Unicode create a buffer size equals to number of input bytes 1 sizeof MC_Uchar The assumption is that DICOM character set can only produced one 16 bit Unicode character per input byte and one extra terminator byte U 0000 at the end of string There
115. ed and freed and the associated identifiers become invalid The Merge DICOM Toolkit updates and maintains all byte offsets that are part of the DICOMDIR structure automatically But one important note All the changes to a DICOMDIR are made in memory and are not committed to the media until an DDH Update callis made Storage of Directory Records Depending on the type of media being used the size of objects being stored and how many tags are stored the size of a DICOMDIR can grow quite large For this reason the toolkit delays the reading of the directory records until the application requests them Once a directory record is read into memory the application can call MC DDH Release Record torelease the memory associated with the record and all lower level records The toolkit will reload any released record from the DICOMDIR file when required M RGE Healthcare Merge DICOM Toolkit Adding private attributes to a message Assigning values to private attributes M RGE Healthcare User s Manual Private Attributes Private attributes supply a mechanism for applications to extend standard message objects and were discussed earlier in this document Private attributes in message objects are handled in much the same way as standard attributes with three major exceptions e standard attributes in the Merge DICOM Toolkit API are referenced by Tag while private attributes are referred to by PrivateCode Group
116. ed by two tools supplied with Merge DICOM Toolkit genconf and gendict genconf generates a ANSI C module containing the MC Config Values function providing the contents of the configuration files This module can be compiled and linked into your application along with the toolkit library to supply an initial configuration without accessing the file system This is done by specifying MC_Config_Values as the first parameter to MC_Library_Initialization gendict is similar to genconf in that it generates an ASCII C module but its function is named MC Dictionary Values be used initialize the library with the contents of the binary data dictionary file By compiling and linking this module into your application and by specifying MC Dictionary Values as the second parameter to the MC Library Initialization your application can access the data dictionary without accessing the file system The third parameter of MC Library Initialization isreserved for future use See the Reference Manual for further details on these two tools and MC Library Initialization Registering Your Application Before performing any network or media activity your application must register its DICOM Application Title with the Merge DICOM Toolkit The toolkit returns to you an Application ID a handle that is used to refer to this particular AE in subsequent function calls This DICOM Application Title is equivalent to the DICOM App
117. ed in conjunction with a callback function registered with MC Register Callback Function to manage pixel data Memory Management Merge DICOM Toolkit contains its own memory management routines that are optimized for how it uses memory They have been adapted to manage specific data structures that are frequently allocated by Merge DICOM Toolkit These include but are not limited to data structures for associations messages and tags The memory management routines have the characteristic that they do not actually free the memory that has been acquired Instead they mark the data as being free and place the memory in a list for reuse later These routines have been optimized to quickly acquire and free memory being used by Merge DICOM Toolkit They also allow Merge DICOM Toolkit to not depend on the memory management of a particular operating system These memory routines have also been extended for use with variable sized memory buffers Merge DICOM Toolkit uses these routines to allocate buffers in sizes between 4 bytes and 28K When an allocation is requested Merge DICOM Toolkit will take the smallest buffer that will fit the bytes requested These buffers will be kept in Merge DICOM Toolkit s internal memory pool and never freed For allocations M RGE Healthcare Merge DICOM Toolkit MC_Set_Value_From _Function M RGE Fiealthcare User s Manual larger than 28K Merge DICOM Toolkit will simply use the C functions mall
118. ed on in DICOM but the ordered pair notation is still useful and often easier to read Also the ordered pair notation is important when defining a Tag for a private attribute We will see later that all private attributes must have an odd group number Each attribute identified by a Tag Command Object Instance a Command Attribute LI Object Instance Attribute Figure 6 A DICOM Message DICOM Data Dictionary Attributes have certain characteristics that apply to them no matter what message they are used in These characteristics are specified in the DICOM Data Dictionary Part 6 of DICOM and are Value Representation VR and Value Multiplicity VM Value Representation can be thought of as the type specifier for the values that can be assigned to an attribute This includes the data type as well as its format The VRs defined by DICOM are listed in Table 3 You should refer to Part 5 of the standard for a detailed description of their legal values and formats Table 3 DICOM Value Representations VR s M RGE Healthcare Merge DICOM Toolkit Enumerated values vs Defined Terms Value Type VT M RGE Healthcare User s Manual Name Unsigned Long Integer String Long String Other Byte String Unlimited Text A single attribute can have multiple values Value Multiplicity defines the number of values an attribute can have VM can be specified as 1 1 k or 1 n where kis some i
119. ed with Merge DICOM Toolkit See that application s code for further example of encoding and decoding of sequences of items 86 M RGE Healthcare Merge DICOM Toolkit You must interface with the selected media device M RGE Fiealthcare User s Manual DICOM Files Maintaining a DICOM file set is a matter of maintaining various DICOM files and a single DICOM directory file DICOMDIR First the functions supplied by Merge DICOM Toolkit that operate on all DICOM files are described followed by a description of those functions that are especially suited for the complexities of the DICOMDIR file Figure 16 summarizes the DICOM file access function calls described in this section File System Interface Library Functions Functions MC_Write_File YourMediaToFunction file object DICOM Media DICOM Annlication Media MC Create File creates a file object MC Open File file object or Open File Bypass OBOW or MC Open File Upto Tag YourMediaFromFunction Figure 16 The DICOM File Access Functions in Merge DICOM Toolkit File System Interface Functions This may sound strange but all the media interchange functionality of the DICOM Toolkit relies on functions that you supply to interface with the particular physical medium and file system format on your target device This approach was chosen because of the wide variety of media and file system configu
120. eeseaeeesaeeseaeeeeaees 4 Development Platform 6 Library Structures ER ed 6 Header a DI 7 Merge DICOM Toolkit Library eene 8 Binary Message Information and Data Dictionary Files 8 Sample Applications 9 Merge DICOM Toolkit Extended 9 Documentation Roadmap cette oer ertt eret rexit re etn ete 10 11 Understanding DICOM 11 General Concepts 11 ocean cette reete reed era 11 Services and Meta 12 Information Model 2 tice rtt Ec eee hit baee Rs 16 INetWorklng e too on etae tom teta fen inde 17 COMIMANGS vs 17 Association 18 19 DICOM Data Dictionary 22 2 0 0 20 Message ena e eee cru erepta 21 Private AUriDUtes 22 Media Interchange erer
121. ension that describes the organization of the Merge DICOM Toolkit DICOM Database and how to use it to extend standard services and define your own private services Tools are supplied for converting the contents of the database into the binary runtime object database Sample The Sample Application Guide describes approaches to developing specific classes Applications of DICOM applications Image Transfer Query Retrieve Print HIS RIS Storage Media etc It highlights pertinent information from Parts 3 or 4 of the DICOM Standard in a more readable way and in the context of the DICOM Toolkit The Application Guide also details the DICOM messages that can be passed between applications on the network Also a sample application is described and the application supplied in source form for your platform Platform specific information required to use the DICOM Toolkit on your target platform are specified in Plattorm Notes This includes supported compilers compiler options link options configuration and run time related issues User s Manual Reference Manual E a Notes Figure 4 Merge DICOM Toolkit Documentation Roadmap DICOM Sample Extended Applications Toolkit Guide Manual 10 M RGE Fiealthcare Merge DICOM Toolkit Sample Margin Note Performance Tuning Client Server M RGE User s Manual Conventions This manual follows a few formatting conventions Terms that are being defined are presented in
122. ent e UC User Option Conditional May not be present May be present according to the specified condition Condition The Condition field specifies any conditions upon which presence or absence of the Content Item or its values depends This field specifies any Concept Name s or Values upon which there are dependencies References may also be made to row numbers e g to specify exclusive OR conditions that span multiple rows of a Template table The following abbreviations are used e XOR Exclusive OR One and only one row shall be selected from mutually exclusive options Note For example if one of rows 1 2 3 or 4 may be included then for row 2 the abbreviation rows 1 3 4 is specified for the condition IF Shall be present if the condition is TRUE may be present otherwise e If and only if Shall be present if the condition is TRUE shall not be present otherwise e CV Code Value e CSD Coding Scheme Designator e CM Code Meaning e CSV Coding Scheme Version M RGE Healthcare Merge DICOM Toolkit M RGE Fiealthcare User s Manual Value Set Constraint Value Set Constraints if any are specified in this field as defined or enumerated coded entries or as baseline or defined context groups The Value Set Constraint column may specify a default value for the Content Item if the Content Item is not present either as a fixed value or by reference to
123. ept or to further describe a concept E g CODE Chest X Ray HAS CONCEPT MOD CODE View PA and Lateral E g CODE Breast HAS CONCEPT MOD TEXT French Translation Sein E g CODE 2VCXRPALAT HAS CONCEPT MOD TEXT Further Explanation Chest X Ray Two Views Posteroanterior and Lateral HAS PROPERTIES SR REL HAS PROPERTIES Description of properties of the Source Content Item E g CODE Mass HAS PROPERTIES CODE anatomic location HAS PROPERTIES CODE diameter HAS PROPERTIES CODE margin M RGE Healthcare Merge DICOM Toolkit M RGE Fiealthcare Relationship Type HAS ACQ CONTEXT Merge DICOM Toolkit Definition SR_REL_HAS_ACQ_CONTEXT User s Manua Description Has Acquisition Context The Target Content Item describes the conditions present during data acquisition of the Source Content Item E g IMAGE 36 HAS ACQ CONTEXT CODE contrast agent HAS ACQ CONTEXT CODE position of imaging subject INFERRED FROM SR_REL_INFERRED_FROM Source Content Item conveys a measurement or other inference made from the Target Content Items Denotes the supporting evidence for a measurement or judgment E g CODE Malignancy INFERRED FROM CODE Mass INFERRED FROM CODE 9 5 INFERRED FROM SCOORD SELECTED FROM SR_REL_SELECT
124. er 1 set to 1 only if Unicode string is U 0000 terminated or set to exact number of Unicode characters int outputBufferSize char bytes output int outLen to receive the exact number of bytes produced excluding terminator enable Unicode conversion library FIRST only need to do once in your application status MC Enable Unicode Conversion 1 if status MC NORMAL COMPLETION printf failed to initialize Unicode library n equivalent to DICOM attribute 0008 0005 but in array form charsets 0 ISO 2022 IR 13 charsets 1 ISO 2022 IR 87 charsets 2 ISO 2022 IR 159 sufficent buffer to hold output each Unicode character wouldn t produce more than 16 bytes outputBufferSize numberOfUnicodeCharacter 16 bytes malloc outputBufferSize convert from Unicode to DICOM character set status MC Unicode To Byte charsets 3 const MC UChar uChars numberOfUnicodeCharacter outputBufferSize amp outLen bytes if status MC BUFFER TOO SMALL printf fail because buffer too small increase output buffer size n else if status MC NORMAL COMPLETION printf failed to convert n example to convert Korean character set to Unicode MC_STATUS status char firstCharset Korean dataset 0008 0005 is ISO 2022 IR 149 always take the first charset which is char bytes input input is defined externally a raw byte arra
125. er than 28K so the memory is freed after processing has been completed for the image This will keep the nominal memory usage of Merge DICOM Toolkit lower When passing data in chunks less than 28K it is recommended that sizes of 16K 20K 24K or 28K be used Using these size chunks will reduce the overhead in storing the data 99 Merge DICOM Toolkit MC_Read_Message MC Open File MC Stream To Message 100 User s Manual MC Set Value From Function can also be directed to store data in temporary files The LARGE DATA STORE and LARGE DATA SIZE configuration options in the mergecom pro file dictate when data is stored in temporary files When the LARGE DATA STORE option is set to FILE data elements that are larger than configured by the LARGE DATA SIZE option are stored in temporary files The size of buffer passed to Set Value From Function does not have an effect on memory usage Reading Messages from the Network Merge DICOM Toolkit has a single function for reading messages from the network MC Read Message creates a message object and loads the message into memory while reading from the network When using Merge DICOM Toolkit s standard memory management routines the method for storing the image data can be influenced Data is read from the network by PDUs However it is stored internally in sizes dictated by the WORK BUFFER SIZE configuration value If a chunk of data read is
126. er Syntaxes etc For example vendors creating images need to obtain their own organization ID and cannot use 10008 For future UIDs ISO has developed a joint relationship with CCITT and has changed the lt root gt structure Therefore new UIDs from ANSI will no longer be of the form 1 2 840 xxxxx but are currently assigned using the form lt root gt 2 16 840 1 10008 where of course 10008 is the organization ID 139 Fiealthcare Merge DICOM Toolkit 140 User s Manual Sample UID Format There are many methods that can be used to ensure the uniqueness of a UID The following is one example encoding of a UID to ensure uniqueness lt root gt lt serial gt lt process id gt lt timestamp gt lt count gt In this example lt root gt is the assigned root UID for an organization The lt serial gt component would be a unique serial number assigned to the product within the organization It may also be an encoding of the MAC address assigned to an Ethernet card in the system This field with the root gives a base for the UIDs that is unique for a specific device The remaining components ensure that the UID is unique within that device The lt process id gt field would be a process ID or thread ID for the process generating the UID The timestamp field would be a timestamp generated when the process or thread is created Finally the count field would be a unique counter that is incremented for each UID created S
127. erge DICOM Toolkit User s Manual if status MC_BUFFER_TOO_SMALL printf fail because buffer too small increase output buffer size n if status MC NORMAL COMPLETION i printf failed to get str n Deploying Applications There are several issues to consider when deploying a Merge DICOM Toolkit based application These include deciding which Merge DICOM Toolkit files are needed for your application how to set important configuration options to reduce problems in the field and how to deal with potential UN VR problems The following sections describe these issues in further detail Merge DICOM Toolkit Required Files There are a limited number of files required by Merge DICOM Toolkit applications These files are described in Table 28 Note that the use of some of these files can be avoided by using the genconf and gendict utilities These utilities generate a source file from the configuration files that can be compiled and linked into your application Table 28 Files needed when deploying an application File Description and Use merge ini Merge DICOM Toolkit initialization file This file contains logging information and pathnames for the other configuration files Use of this file can be avoided by using the genconf utility to link the file into the Merge DICOM Toolkit application mergecom pro Merge DICOM Toolkit system profile This file contains general run time configuration options Use of this fi
128. erse Records dirID amp findInfo FindSeriesCbk Adding and Deleting Records The addition or deletion of directory records are handled through two simple calls MC DDH Add Record andMC DDH Delete Record These calls modify only the toolkit s view on the DICOMDIR record hierarchy to apply the changes to the DICOMDIR file the application must call MC DDH Update When adding a record using DDH Add Record you pass in the identifier of the parent record or directory object if adding a top level record and optionally the record type to add In most of the cases the new record s type can be inferred from the type of the parent record and you can pass a NULL for the record type For instance level records the record type is determined by the SOP Class of the referenced instance and the toolkit accepts the SOP Class UID as the value of the record type If successful MC Record returns in the last parameter the identifier of the new toolkit record which can be used with MC Set Value methods to set attribute values An easier way to add attributes to the new record is using MC DDH Copy Values which can copy a specific set of attribute values from a message or file object into the new record When deleting a record using DDH Delete Record the only parameter required is the identifier of the record to delete When a directory record is deleted all lower level directory records are also delet
129. ery retrieve service class to retrieve the series of images When the images are exported to the workstation with an explicit VR transfer syntax the workstation fails to parse the first image received when it encounters the first UN VR attribute and the association is automatically aborted by the workstation We have added several methods to solve this interoperability problem through the Merge DICOM Toolkit s configuration files For SCU systems that are exporting UN VR tags to systems that cannot handle them the following can be done Configure the SCU to only use the Implicit VR Little Endian transfer syntax when exporting objects This can be done through the use of transfer syntax lists within the mergecom app file or through commenting out the UID definitions for the other transfer syntaxes within the mergecom pro file Set the UNKNOWN VR CODE configuration option in the mergecom pro file to OB This forces unknown VR attributes to be encoded as OB instead of as UN All implementations can handle OB encoding There are several drawbacks to this option If the attributes are encoded as OB it is harder for these attributes to be converted back to their normal VR Secondly this option changes all instances of the UN VR into OB Systems that can handle the UN VR will now also receive these attributes as OB Set the EXPORT UN VR TO NETWORK configuration option to No This will cause the Merge DICOM Toolkit to not export attributes encode
130. form a search in your database for matches for the attributes read in and send the proper response messages We re through with the message fr it up status MC Free Message amp iMessageID Retrieving pixel When retrieving the value of an attribute with a value representation of OB or OW data e g Pixel Data you can use the MC_Get_Value_To_Function Pixel Data tends to be very large and normally you use this function to read the data value a chunk or block at atime This function is the complement to the MC Set Value From Function described in the last section As an example your application could define a callback function MyPDStoreFunction whose purpose is to store Pixel Data to an external data sink so that your application uses less primary memory Pseudo code for this function follows MC STATUS MyPDStoreFunction int MsgID unsigned long Tag void UserInfo int BlockSize void DataBlock int IsFirstCall int IsLastBlock if IsFirstCall open pixel data sink e g file here using Tag and or UserInfo as a guide if OpenFailed return MC_CANNOT_COMPLY Take this chunk of pixel data from DataBlock and store it to the pixel data sink if StoreFailed return MC_CANNOT_COMPLY if isLastBlock M RGE 57 Healthcare Merge DICOM Toolkit User s Manual close Pixel Data sink here return MC NORM
131. formation Objects Part 3 Data Dictionary Part 6 Upper Layer Data Structures and Encoding Part 5 Association Services DICOM Message Services DICOM Storage M edia Element DIM SE and File Format Part 7 Part 10 Upper Layer Presentation Data Service DICOM M edia Formats Part 8 and Physical M edia Part 12 TEN Merge Your E Functionality Functionality Figure 2 The DICOM Application Layer The DICOM Toolkit also supplies useful utility programs for testing a DICOM network connection creating sample DICOM messages and writing them to a file and validating and listing the contents of DICOM messages Finally sample application manuals Image Transfer Query Retrieve Printing Media Storage Worklist Management etc along with sample working source code give you valuable examples to work from when developing your own DICOM applications The DICOM Standard and Merge s DICOM Toolkit allow applications to add private information to a DICOM message or file For most application developers this is more than sufficient For applications that need to define their own non standard private network or file services an optional Merge DICOM Toolkit Extended Toolkit is available M RGE 5 Healthcare Merge DICOM Toolkit Read your Platform Notes User s Manual Development Platform Requirements To use the Merge DICOM Toolkit Library you must run on a Merge DICOM Toolkit supported computing platform The DICOM Toolkit
132. g image files to and from DICOM media that were received or will need to be transmitted over the network as C STORE request messages DICOMDIR As discussed earlier in each DICOM File Set containing many DICOM files there must exist a single DICOM File with the reserved File ID DICOMDIR This file contains identifying information for the file set that most often includes a directory of the file sets contents A media interchange application would make use of and maintain the DICOMDIR to locate a particular file within the file set for processing Structure An information object portion of a DICOMDIR file has a special structure that is described in Part 3 PS 3 3 of the DICOM Standard We described this structure earlier in this document see Figure 8 as a hierarchy of directory entities where each directory entity contains a set of semantically related directory records These directory records can have a one to one relationship to a DICOM file within the file set described by the DICOMDIR and can also reference another lower level semantically related directory entity Directory records do not have to reference a DICOM file they can be used solely to contain information that helps an application navigate down the directory hierarchy to locate the desired DICOM file 93 Merge DICOM Toolkit DICOMDIR s are ugly But we pretty them up Navigating through a DICOMDIR 94 User s Manual As an example the Root dir
133. ge multi frame image and the user would like to free some of the memory associated with the object When developing a DICOM application with Merge DICOM Toolkit the most memory intensive operation is dealing with image data The following sections discuss various Merge DICOM Toolkit functions A description is given of how these functions manage memory in conjunction with various Merge DICOM Toolkit configuration settings Assigning Pixel Data MC Set Value From Function is used to assign OB OW or OF data to a DICOM tag These value representations are used to store image data or other large data elements Set Value From Function is described in further detail elsewhere in this manual Data can be passed to Merge DICOM Toolkit via Set Value From Function in several ways The entire data can be passed in a single call or the data can be supplied in several smaller chunks When passed data MC Set Value From Function Willallocate a buffer the size of the chunk passed to it and copy the data into this buffer for storage The size of data passed to MC Set Value From Function Will dictate how the image data is stored If the data is passed in chunks smaller than 28K Merge DICOM Toolkit s internal memory management code will be used If the chunks are larger than 28K 11 will be used to allocate storage for the buffers If large images are being dealt with it may be desirable to pass this data in chunks larg
134. gle root Content Item Node 1 that is the root of the SR Document tree The root Content Item conveys either directly or indirectly all of the other nested Content Items in the document The hierarchical structuring of the Content Tree provided by recursively nesting Content Items A parent or source Content Item has an explicit relationship to each child or target Content Item conveyed by the Relationship Type Figure 18 depicts the relationship of SR Documents to Content Items and the relationships of Content Items to other Content Items and to Observation Context 104 M RGE Healthcare Merge DICOM Toolkit User s Manual SR Document 1 ema gt 1 Content Item gt Note A Content Item may contain either Observation Context or other content related to Figure 18 SR Information Model Each Content Item contains the following Aname value pair consisting of o asingle Concept Name Code that is the name of a name value pair or a heading and o avalue text numeric code etc References to images waveforms or other composite objects with or without coordinates Relationships to other Items either by value through nested Content Sequences or by reference Note Some Content Item Types can have multiple values Content Item Types Table 24 defines all possible Content Item Types that can be used in the SR Document Content Module The choice of which may be c
135. group depending on what other blocks of private attributes have already been reserved PrivateCodes are a way to refer to these blocks independently of their physical location in the message stream Once private attributes have been added they can be assigned values identically to standard attributes except that all the MC Set Value functions are replaced with MC Set pValue functions The MC Set pValue functions require PrivateCode Group and ElementByte rather than Tag to identify an attribute For example to assign Adams John Robert Quincy as the name of the field engineer your application could call Status MC Set pValue From String myMessageID ACME IMG CORP 0x1455 00 Adams John Robert Quincy 97 Merge DICOM Toolkit Retrieving values from private attributes Check platform notes for multi threading support Performance Tuning 98 User s Manual Similarly retrieving values from private attributes makes use of Get pValue rather than MC Get Value functions The MC Get pAttribute Info callcan also be very useful in retrieving information about private attributes before your application begins to process them See the Reference Manual for further details on the handling of private attributes with these and other calls Multi threading Support The Merge DICOM Toolkit library has been designed to be thread safe Note however this thread safet
136. group length attributes when writing to files Setting this option to No increases Merge DICOM Toolkit performance This eliminates the need for Merge DICOM Toolkit to determine the length of groups when writing to media EXPORT UNDEFINED LENGTH SQ IN DICOMDIR This option determines how Merge DICOM Toolkit exports sequence attributes in DICOMDIRs When set to Yes the sequences in DICOMDIRs are encoded as undefined length This greatly improves performance when writing DICOMDIRs because Merge DICOM Toolkit no longer needs to calculate the length of sequence attributes in DICOMDIRs Which of the options listed above have the greatest impact on network performance The PDU MAXIMUM LENGTH TCPIP RECEIVE BUFFER SIZE and TCPIP SEND BUFFER SIZE configuration options have the greatest impact on network performance Setting these to higher values directly increases the network performance of Merge DICOM Toolkit EXPORT UNDEFINED LENGTH 50 can have large impact if many sequence attributes are included in the message being transferred M RGE Healthcare Merge DICOM Toolkit M RGE Fiealthcare 8 10 User s Manual sending 8 bit images with Merge DICOM Toolkit however after sending the data to another system the pixel data is byte swapped incorrectly What is causing this problem The Merge DICOM Toolkit Users Manual contains the section 8 bit Pixel Data which describes this problem This is typically only a pr
137. gth field in explicit value representation transfer syntaxes should be encoded as 2 bytes or 4 bytes so a general parser could not be properly written to handle future VRs The need for this supplement is mainly for use in archive systems An archive will typically want to preserve the private attributes contained within a message for later use There also may be a need to add support for new image objects with new VRs to an archive system without having to change the software Unfortunately the method that Supplement 14 specifies for encoding UN value representation attributes is typically not compatible with older DICOM implementations Versions previous to 2 2 2 of the Merge DICOM Toolkit do not parse these attributes properly The MC Read Message function call will fail and the association will be aborted if a UN VR attribute is received This has obviously caused a variety of interoperability problems in the field The typical DICOM scenario where UN VR can cause a DICOM communication failure is the following a modality exports a series of images to a PACS or archive system via the DICOM storage service class The images were encoded in the implicit VR little endian transfer syntax and contain multiple private attributes Later a DICOM workstation decided to retrieve the images from the archive or PACS system The workstation does not yet support UN VR however the PACS or archive system does The workstation uses the DICOM qu
138. he Merge DICOM Toolkit to supply DICOM network or media functionality The Merge DICOM Toolkit supplies you with a powerful and simplified interface to DICOM It lets you focus the important details of your application and the immediate needs of your end users rather than the complex and often confusing details of the DICOM Standard The goal of this manual is to give you basic understanding of DICOM and a clear understanding of the Merge DICOM Toolkit The DICOM Standard The Digital Imaging and Communications in Medicine DICOM Standard was originally developed by a joint committee of the American College of Radiology ACR and the National Electrical Manufacturers Association NEMA to facilitate the open exchange of information between digital imaging computer systems in medical environments Since its initial completion in 1993 the standard has taken hold More and more products are advertising DICOM conformance and more customers are requiring it DICOM has also been incorporated as part of a developing European standard by CEN as a Japanese standard by JIRA and is increasingly becoming an international standard DICOM Version 3 0 is composed of several hundreds of pages over sixteen separate parts Each part of the standard focuses on a different aspect of the DICOM protocol Part 1 Introduction and Overview Part 2 Conformance Part 3 Information Object Definitions Part 4 Service Class Specifications Part 5
139. ibutes VR e That all value type 1 attributes have a value and that value is not null e That all value type 2 attributes have a value and that value may be null e That a specified set of conditional attributes value type 1C or 2C are validated as value type 1 or 2 attributes when the specified condition is satisfied e That an attribute does not have too many or too few values for its specified value multiplicity e That an attribute that has enumerated values does not have a value that is not one of the enumerated values A warning is also issued if an attribute that has defined terms has a value that is not one of those defined terms e That a non private attribute is not included in the message that is not defined for that DICOM message service command pair M RGE 63 Healthcare Merge DICOM Toolkit User s Manual and what As mentioned Merge DICOM Toolkit does not capture all standard violations and the validation cannot DICOM Standard itself should be considered the final word when validating a do for you message Important limitations of Merge DICOM Toolkit validation include e DICOM Part 3 specifies Information Object Definitions IOD s as being composed of modules Each module contains attributes Only in the case of composite IOD s may an attribute be specified in DICOM Part 3 as being contained in either a User Optional or Conditional Module Merge DICOM Toolkit treats all such attributes as being value type 3 opt
140. ication ID that is used as a parameter The Set Message Callbacks function allows the user to directly associate Callback Functions for an application with a message or file object After calling Set Message Callbacks subsequent calls to functions such as MC Open File MC Message To Stream or MC Stream To Message can use Callback Functions for managing pixel data Note that when creating a message with Open Empty Message or MC Create Empty File itis necessary to add the pixel data tag into the message for Callback Functions to work properly This can be done through the use of MC Standard Attribute Without a placeholder tag in the message or file to signal Merge DICOM Toolkit that pixel should be included in the message or file Merge DICOM Toolkit will not know that Callback Functions should be used with the message or file When creating messages with Open Message or MC Create File this is not necessary M RGE Healthcare Merge DICOM Toolkit User s Manual How to register a The MC_Register_Callback_Function canbe used to register a Callback Callback Function Function with the toolkit as follows Status MC_Register_Callback_Function myApplicationID MC ATT PIXEL DATA myUserInfo MyCallbackFunction This call registers MyCallbackFunction with the DICOM Toolkit library to handle the pixel data 7FE0 0010 attribute for myApplicationlD myUserI
141. ies several types of objects application objects association objects message objects file objects and item objects Whenever you are given an ID e g Application ID AssociationID MessagelD FilelD or ItemID it is a handle to an instance of one of these objects Objects provide a convenient way for the toolkit to encapsulate related data while hiding unnecessary details from the application developer IDs also provide a convenient shorthand when making calls to the Merge DICOM Toolkit that operate on or make use of these objects A majority of the functionality supplied with the DICOM Toolkit deals with building parsing validation and exchange of DICOM messages files and items Your applications deal with network messages in Merge DICOM Toolkit as message objects and DICOM files as file objects Item objects are used for attributes that are of VR Sequence of Item SQ within both messages and files This section deals with message objects but many of these functions are polymorphic and also work on file and item objects These polymorphic functions will be called out in this section Additional functions that are particular to file objects or item objects will be described in later sections Private attributes in both message and file objects are handled in ways similar to those discussed in this section but will also be described later in this document 49 Merge DICOM Toolkit Opening a message Performance Tuning Fill
142. in a Template may or may not be the same as the ordinal position of the corresponding node in the encoded document The Merge DICOM Toolkit does not use this number in any way Nesting Level NL The nesting level of Content Items is denoted by gt symbols one per level of nesting below the initial Source Content Item of the Template in a manner similar to the depiction of nested Sequences of Items in Modules Tables in Part 3 of the DICOM When it is necessary to specify the Target Content Item s of a relationship they are specified in the row s immediately following the corresponding Source Content Item The Merge DICOM Toolkit provides functions to add nested child Content Items to the parent Content Item node The following function pattern shall be used to add a child node with the specific type and relationship MC SRH Add Type Child int AsrNodeID SR RELATIONSHIP Arelationship where Type is a child Content Item Type for example TEXT 111 Merge DICOM Toolkit User s Manual Relationship with Source Content Item Parent Relationship Type and Mode are specified for each row that specifies a target content item The Relationship Types are enumerated in the Table 25 Relationship Type and Mode may also be specified when another Template is included either top down or bottom up or both i e in the INCLUDE Template row of the calling Template or in all rows of the included Template
143. ince this opens an empty message object without any attributes to check against Applications where performance is critical may find it useful to use Open Message during initial development and replace these calls with Open Empty Message later in the development cycle after the implementation stabilizes Table 10 Acceptable Set Value VR combinations MC Set function type Function may be used to set values of attributes with these Value Representations we Tironi LE DS FD FL IS SL SS UL US SQ lue_From_UInt DS FD FL IS SL SS UL US SQ lue_From_ShortInt DS FD FL IS SL SS UL US SQ lue_From_UShortInt DS FD FL IS SL SS UL US SQ lue From LongInt AT DS FD FL IS SL SS UL US SQ lue From ULongInt AT DS FD FL IS SL SS UL US SQ lue From Float DS FD FL IS SL SS UL US SQ lue From Double DS FD FL IS SL SS UL US SQ M RGE Healthcare 51 Merge DICOM Toolkit User s Manua MC_Set function type Function may be used to set values of attributes with these Value Representations MC_Set_Value_From_String AS AT CS DA DS DT FD FL IS LO LT PN SH SL SS ST TM UI UL US UT SQ An example of opening a message for the BASIC_FILM_SESSION N CREATE RQ service command pair and setting a few of its attributes follows Note that after the message is sent the message object is freed Be sure to free
144. ing a message with values MC_Set_Value functions are polymorphic 50 User s Manual Building Messages Before you can build a message your application must create a message object using the Open Message function call In this call you specify a Service and Command name The DICOM Toolkit library uses these parameters to reference the proper message info file along with the data dictionary and builds an unpopulated message object instance for your application to fill in This message object contains empty attributes A Message ID is returned to your application that identifies this message object An alternative method exists for creating an empty message object MC Open Empty Message a service and command are not specified In this case the message info and data dictionary files are not referenced and an empty message object instance is opened This message object contains no attributes and the Set Service Command function must be called to set the service and command for this message before it can be sent over the network Since this approach avoids accessing the message info files it is more efficient However this approach also penalizes you in terms of runtime error checking This is discussed further later Once you have an open message object use the Set Value family of functions to build your message This family of functions can be broken into five types based on their functio
145. initions Performance Tuning M RGE Fiealthcare User s Manual Your application may want to take advantage of Merge DICOM Toolkit s message validation functionality before sending a DICOM message out on the network or before parsing and acting on a message received from some other device Also when constructing a request or response message it is important to note that for some services your application will need to set the value of command attributes in the message Refer back to the Validating Messages section of this document for further discussion Asynchronous Communications The DICOM standard defines an optional method for negotiation of an Asynchronous Operations Window The Asynchronous Operations Window allows the client and Server during association negotiation to define how many request messages can be sent over an association before a response message is required to be received When the Asynchronous Operations Window is not negotiated the default behavior of Merge DICOM Toolkit only one request message can be sent before a response is received Use of asynchronous operations can improve network performance when transferring a large number of messages over an association The specific fields negotiated over an association are the maximum number of operations sub operations or notifications invoked by the requester of the association and the maximum number of operations sub operations or notifications performed by the
146. int of performance overhead associated with message validation Message Object Creation Point at which file access overhead for validation Method occurs MC_Open_Message MC_Open_Message Empty Message MC Validate Message Note You must use MC Set Service Command before validating and or sending a message created in this manner MC Read Message MC Validate Message Using MC Open Message has an up front performance cost but provides additional validation as you set the value of attributes in the message object For the other two creation methods the cost occurs on validation itself Many times the MC Validate Message is selectively used in an application as a runtime option or conditionally compiled into the source code Validation might only be used during integration testing or in the field for diagnostic purposes Reasons for this include performance since the overhead associated with message validation may be an issue especially for larger messages having many attributes or on lower end platforms Also validation can clutter the message log with warnings and errors that may not be desirable in a production environment Performance issues related to message handling are discussed further under Message Exchange later in this document M RGE Healthcare Merge DICOM Toolkit M RGE Fiealthcare User s Manual Streaming Messages When DICOM messages are exchanged over a network they are in an e
147. ion values that reduce Merge DICOM Toolkit s memory requirements The following describes each of these options M RGE Healthcare Merge DICOM Toolkit Reducing memory usage for large DICOMDIRs M RGE Fiealthcare User s Manual FORCE OPEN EMPTY ITEM This configuration option performs the same function as using MC Open Empt y Message except that it is for items It is especially useful for reducing the amount of memory used when working with large DICOMDIRs LARGE DATA STORE and LARGE DATA SIZE These options control the ability of Merge DICOM Toolkit to store pixel data in temporary files instead of RAM This functionality is enabled by setting LARGE DATA STORE to FILE and adjusting LARGE DATA SIZE to the size of data element that you want spooled to temporary file Note that this will decrease performance e DICOMDIR STREAM STORAGE This option can be used when reading DICOMDIR files to reduce the amount of memory required to store directory records within the DICOMDIR What can be done to increase the performance of the Merge DICOM Toolkit There are several Merge DICOM Toolkit configuration values that impact performance in different ways The following is a summary of these options ELIMINATE ITEM REFERENCES This option improves the performance of the MC Empty Message MC Free Message MC Empty File MC Free File andMC Free Item functions This option will disable funct
148. ional e Also only in the case of composite IOD s e g Ultrasound Image Object used in storage services may certain modules be mutually exclusive e g curve and overlay modules The attributes defined in these modules are all treated as type 3 e For normalized services using the N EVENT REPORT command the actual contents of an N EVENT REPORT message are dependent on the Event Type ID being communicated Merge DICOM Toolkit treats all Event Type ID s identically when performing message validation namely it treats all attributes as type 3 An example An example of the use of MC Validate Message follows status MC Validate Message iMessageID amp error info Validation Levell if status MC DOES NOT VALIDATE printf MC Validate Message tag 1x error s error info Tag MC Error Message error info 5Status you may want to abort the association in this case as follows MC Abort Association amp associationID In this example the application validates the message object iMessagelID at Validation Levell that reports only errors validation Level2 could be used to report both warnings and errors while validation Level3 could be used to report errors warnings and informational messages If the status returned is anything other than MESSAGE VALIDATES your application can look at the error info structure passed back to decipher the violation error info is define
149. ionality within the toolkit that causes the toolkit to search all currently open message objects for references to an item that is being freed by one of these calls This call is especially useful when your application uses very large DICOMDIR files e PDU MAXIMUM LENGTH This option sets the maximum sized PDU that the toolkit will receive If during association negotiation the maximum sized PDU of the system negotiating with the toolkit application is larger than this value the PDU size will be limited to this value e Setting this option so that a PDU fits within an even multiple of the default TCP IP Maximum Segment Size MSS of 1460 bytes will increase performance Note that 6 bytes for the PDU header must be added to the configured maximum PDU size when calculating a multiple of the MSS Having the PDU Maximum length an even multiple of the MSS ensures that there are limited delays within TCP IP stack when transferring With the exception of the final TCP IP packet for a message all packets transferred should exactly fit within a TCP IP packet e WORK BUFFER SIZE This option specifies how the toolkit buffers data before storing it or passing it to a user s callback function Setting higher values for this option will increase performance e TCPIP RECEIVE BUFFER SIZE his option sets the TCP IP receive buffer size Higher values for this buffer generally will increase the network performance of the toolkit for server SCP
150. ions do not include Concept Name arguments because they are optional for those Content Item Types In that case a separate function can be used to set the Concept Name values as follows MC STATUS EXP FUNC MC SRH Set Concept Name int AsrNodeID const char AconceptNameValue const char AconceptNameScheme const char AconceptNameMeaning Templates define References to coded concepts take the following form EV or DT ConceptNameValue ConceptNameSheme ConceptNameMeaning 112 M RGE Healthcare Merge DICOM Toolkit Abbreviations used in templates M RGE Healthcare User s Manual For example EV T 04000 SNM3 Breast would mean that hardcoded values shall be used for that Concept Name Some template items don t have DT or EV abbreviation and just specify the hardcoded values Following abbreviations are used in template definitions e EV Enumerated Value values for are provided in the brackets e DT Defined Term values are provided in the brackets e BCID Baseline Context Group ID identifier that specifies the suggested Context Group The suggested values can be found in the DICOM Part 16 and identified by a Context ID provided in the brackets e DCID Defined Context Group ID identifier that specifies the Context Group for a Coded Value that shall be used The values can be found in the DICOM Part 16 and identified by a Context ID provided in the brackets e BTID Baseline Te
151. ironmental variable to point to the proper configuration files as described earlier mc3comp The mc3comp utility can be used to compare the differences between two DICOM objects The objects can be encoded in either the DICOM file or stream format and do not have to be encoded in the same format The utility will output differences in tags between the messages taking into account differences in byte ordering and encoding The syntax for the utility is the following mc3comp tl syntax t2 lt syntax gt file o m1 m2 filel file2 tl syntax Optional specify transfer syntax of filel message where syntax il for implicit little endian default el for explicit little endian for explicit big endian t2 syntax Optional specify transfer syntax of file2 message where syntax il for implicit little endian default el for explicit little endian for explicit big endian e file Optional exception file of all tags to ignore in comparison o Compare OB OW e g binary pixel data 1 Compare filel DICOM 3 file format 2 Compare file2 DICOM 3 file format h Show these options filel DICOM SOP Instance message fil file2 Another DICOM SOP Instance message fil Example mc3comp t1 il m2 o 1 img 1 dcm 36 M RGE Fiealthcare Merge DICOM Toolkit mc3conv Convert Image User s Manual The mc3conv utility can
152. ital Intra oral X Ray Image Storage For Presentation Digital Intra oral X Ray Image Storage For Processing Digital Mammography Image Storage For Presentation Digital Mammography Image Storage For Processing Raw Data Storage RT Beams Delivery Instruction Storage RT Beams Treatment Record Storage RT Brachy Treatment Record Storage RT Dose Storage RT Plan Storage RT Image Storage RT Structure Set Storage RT Treatment Summary Record Storage RT lon Beams Treatment Record Storage RT Ion Plan Storage VL Endoscopic Image Storage VL Microscopic Image Storage VL Photographic Image Storage VL Slide Coordinates Microscopic Image Storage VL Whole Slide Microscopy Image Storage Video Endoscopic Image Storage Video Microscopic Image Storage Video Photographic Image Storage XA XRF Grayscale Softcopy Presentation State Storage X Ray Angiographic Image Storage X Ray Radiofluoroscopic Storage X Ray 3D Angiographic Image Storage X Ray 3D Craniographic Image Storage Enhanced XA Image Storage Enhanced XRF Image Storage Secondary Capture Image Storage Autorefraction Measurements Storage Keratometry Measurements Storage 13 Merge DICOM Toolkit 14 Service Class User s Manual Services Description Lensometry Measurements Storage Ophthalmic Axial Measurements Storage Ophthalmic Visual Field Static Perimetry Measurements Storage Subjective Refraction Measurements Storage Visual
153. ith minimal usage of coded entries typically used in Document Title and headings and a hierarchical tree of headings under which may appear text and subheadings Reference to SOP Instances e g images or waveforms or other SR Documents is restricted to appear at the level of the leaves of this primarily textual tree This structure simplifies the encoding of conventional textual reports as SR Documents as well as their rendering e Enhanced SR Information Object Definition The Enhanced Structured Report SR IOD is a superset of the Basic Text SR IOD It is also intended for the representation of reports with minimal usage of coded entries typically Document Title and headings and a hierarchical tree of headings under which may appear text and subheadings In addition it supports the use of numeric measurements with coded measurement names and units Reference to SOP Instances e g images or waveforms or SR Documents is restricted to appear at the level of the leaves of this primarily textual tree It enhances references to SOP Instances with spatial regions of interest points lines circle ellipse etc and temporal regions of interest e Comprehensive SR Information Object Definition The Comprehensive SR IOD is a superset of the Basic Text SR IOD and the Enhanced SR IOD which specifies a class of documents the content of which may include textual and a variety of coded information numeric measurement values references to the
154. kit SR functions The Merge DICOM Toolkit has several types of functions that can be used for reading writing Structured Report IODs Low level attribute access functions These are the same functions that are used to work with the attributes in the message objects Every SR Content Item ID is mapped to the Message Item ID and can be used to set or get additional attributes that are not covered by the High Level API Low level navigation and conversion functions These functions providing mapping and conversion between message objects and SR objects Content Items Following functions are included C_SR_Add_Root Creates a new SR root object and maps it to the existing message object C_Message_To_SR Creates SR tree structure from the message and maps each SR Content Item with the corresponding message item C_SR_Add_Child Creates SR Content and maps it to the existing message item C SR Get First Child Retrieves the first child Content Item object ID C_SR_Get_Next_Child Retrieves the next child Content Item object ID C SR Delete Child Deletes a child Content C_SR_To_Message Releases memory allocated by SR tree objects and rebuilds underlying message object High Level functions for encoding SR These functions can be used to build an entire SR document tree with minimum coding The following functions are included C_SRH_Create_SR Creates
155. l be referred to as response messages When a DICOM service is stored to interchangeable media in a DICOM File the structure of a DICOM File is a slightly specialized class of DICOM message Media interchange is discussed in detail later the only important thing to realize for now is that much of what is discussed relating to DICOM Messages also applies to DICOM Files DICOM specifies the required message structure for each service command pair For example the Patient Root Find C FIND RQ service command pair has a specific message structure The command portion of a message is specified in Part 7 of the standard while the object instance portion is specified in Parts 3 and 4 A message is constructed of attributes having values with each attribute identified by a tag An attribute is a unit of data e g Patient s Name Scheduled Discharge Date A tag is 4 byte number identifying an attribute e g 00100010H for Patients Name 0038001CH for Scheduled Discharge Date 19 Merge DICOM Toolkit Groups and Elements Know your VR s 20 User s Manual A tag is usually written as an ordered pair of two byte numbers The first two bytes are sometimes called a group number with the last two bytes being called an element number e g 0010 0010 0038 001C This terminology is partly a remnant of the ACR NEMA Standard where elements within a group were related in some manner This can no longer be depend
156. le can be avoided by using the genconf utility to link it into the Merge DICOM Toolkit application mergecom app Merge DICOM Toolkit application profile This file contains configuration information about the services supported by the Merge DICOM Toolkit application and information about remote DICOM applications Use of this file can be avoided by using the genconf utility to link it into the Merge DICOM Toolkit application mergecom srv Merge DICOM Toolkit services file This file contains information about the services supported by Merge DICOM Toolkit Use of this file can be avoided by using the genconf utility to link it into the Merge DICOM Toolkit application mrgcom3 msg Merge DICOM Toolkit message information file This file contains validation information for DICOM messages This file is required if the MC_Open_Message MC_Create_File MC_Validate_Message MC_Validate_File or MC_Validate_Attribute functions are called from the Merge 128 M RGE Healthcare Merge DICOM Toolkit User s Manua File Description and Use DICOM Toolkit application mrgcoms3 dct Merge DICOM Toolkit data dictionary file This file contains information about all of the DICOM attributes Use of this file can be avoided by using the gendict utility to link it into the Merge DICOM Toolkit application Configuration Options The majority of Merge DICOM Toolkit s configuration options can be used to solve intero
157. le must be created to add the DICOM Part 10 Meta Header information This header can be written out from within the callback After the end of the meta header the message can be streamed to disk with a call to MC Message To Streanmin the transfer syntax specified in the Meta Header As subsequent image data is passed to the user s callback function the data can be written to file Because the endian of the transfer syntax being written may be different than the endian of the system being used there may be a need for byte swapping of the pixel data in this implementation There is a potential risk with this implementation Although the current definition of the DICOM image types does not include any data elements after the pixel data future versions may add data elements there M RGE Healthcare Merge DICOM Toolkit M RGE Fiealthcare User s Manual DICOM Structured Reporting The Merge DICOM Toolkit provides high level functionality to handle DICOM Structured Report SR Documents This functionality provides a simple way for encoding and decoding SR Document content by manipulating content items and their attributes instead of tags and values Structured Report Structure and Modules The DICOM standard Part 3 defines the following generic types of SR Information Object Definitions IODs e Basic Text SR Information Object Definition The Basic Text Structured Report SR IOD is intended for the representation of reports w
158. lication Entity Title defined earlier If your application is a server this application title must be made known to any client application that wishes to connect to you If your application is a client your application title may need to be made known to any server you wish to connect to depending on whether the server is configured to act as an server SCP only to particular clients for security reasons For example if your application title is Query you would register with the toolkit as follows MC Status MC Register Application amp MyAppID ACME Query SCP If you wish to disable your application and free up its resources to the system you should release it as follows MC Status MC Release Application amp MyAppID Even if your application is a media interchange only application you still need to register it so that the DICOM Toolkit Library has some way to refer to this application in other calls such as MC Register Callback Function M RGE Healthcare Merge DICOM Toolkit Opening and closing an association User s Manual Current and potentially future DICOM service classes assume that Application Entity Titles on a DICOM network are unique For instance the retrieve portion of the Query Retrieve service class specifies that an image be moved to a specific Application Entity Title and not to a specific hostname and listen port If two identical Application Entity Titles existed o
159. lications sending request messages after a call to Send Request Message the application should retrieve the Message ID tag from the message and save it until a response message has been received For applications sending response messages the Message ID should be retrieved out of the request message and set in the Message ID Being Responded To tag for the response message when a response is sent Service lists are utilized to configure the invoked and performed operations for an SCU and SCP The configuration of service lists is discussed in the previous section of this document describing the Application Profile configuration file The MC Get Association Info function can be utilized by an SCU or SCP application to determine the asynchronous operations invoked and performed that were negotiated for an association Merge DICOM Toolkit also keeps track of the asynchronous operations negotiated and will prevent the user from exceeding the operations sub operations and notifications performed or invoked that were negotiated 73 Merge DICOM Toolkit Deadlocks possible with asvnchronous Performance Tuning Use Full Duplex Networks with asynchronous commnications 74 User s Manual When writing asynchronous applications care should be taken in keeping track of the resultant status of all request messages that were sent In particular if an association is aborted all outstanding operations or notifications should
160. lier can be used to read attribute values from the file object Also the same Set Value family of functions can be used to modify the values of file attributes The variants on MC Open File are also provided by the toolkit e Open File Bypass OBOW Will read in an attribute s value that is of type OB or OW but will not store it if and only if you have registered a Callback Function with MC Register Callback Function for that attribute Instead the offset of the attribute s value from the beginning of the file along with the length of the value will be passed to the user s registered Callback Function The user s Callback Function can then deal with the Pixel Data as it sees fit e g ignore it read it in later stream it in to improve the memory consumption or process it directly from the file using your own special filters or hardware e MC Open File Tag Will stop reading the attributes from media into the file object when it reaches the first attribute greater than a specified tag The offset in bytes from the beginning of the file to the beginning of the first attribute greater than the specified tag is returned The user s application must then deal with reading in the rest of the DICOM file from media This function is most useful when the DICOM file contains pixel data 7FEO 0010 as its last attribute and this pixel data is very large In these instances you may wish to ignore the pixel data rea
161. like the following MC Status MC Library Initialization NULL NULL NULL Configurable parameters can be modified by your application after library initialization at runtime by using the Set Config Value functions These functions are detailed in the Reference Manual If you change the configuration of the library at runtime using the MC Set Config Values functions and wish to reset it to its initial state you should use the Library Reset function which has no parameters It resets the library to its initial state using the same options as originally specified in the MC Library Initialization call You should always check the return code from any function call to Merge DICOM Toolkit to see if an error occurred Any value other than NORMAL COMPLETION implies an error A possible error code for this callis INVALID LICENSE when the toolkit is not configured with a valid license number All error codes that can be returned for each API function call are specified in the Reference Manual M RGE 41 Fiealthcare Merge DICOM Toolkit 42 User s Manual Statically Linked Configuration In specialized applications such as embedded systems or where performance at initialization time is critical one can specify different parameter values to MC Library Initialization to call initialization functions rather than accessing files These initialization functions are generat
162. ll server SCP applications built with the DICOM Toolkit also have built in support of the Verification Service Class and the C ECHO command The command syntax follows mc3echo c count count r remote host l local app title p remote port r remote host 1 local app title p remote port remote app title Integer number specifying the number of echoes to If c is not specified one send to the remote host echo will be performed Host name of the remote computer If r is not specified the default value for remote host is configured in the Application Profile Application title of this program If 1 is not specified the default value for local app title is MERGE ECHO SCU Port number the remote computer is listening on If p is not specified the default value for remote host is configured in the Application Profile M RGE Healthcare 37 Merge DICOM Toolkit Display Message Contents DICOM Message Validation Tool User s Manual mc3list mc31list displays the contents of binary DICOM message files an easy to read manner The message files could have been generated by mc3file see below or written out by your application mc3list is a useful educational tool as well as a tool that can be used for off line display of the DICOM messages your application generates or receives The command syntax follows mc3list filename t syntax
163. lt Attribute gt FileMetaInfo DataSet Service STANDARD SEC CAPTURE Command C STORE RQ TransferSyntax 1 2 840 10008 1 2 1 Attribute Tag 00080008 VR CS Name Image Type Length 24 gt ORIGINAL SECONDARY OTHER lt Attribute gt lt Attribute Tag 00080016 VR UI Name SOP Class UID Length 25 gt 1 2 840 10008 5 1 4 1 1 7 lt Attribute gt lt Attribute Tag 00080020 VR DA Name Study Date Length 8 gt 20020717 lt Attribute gt lt Attribute Tag 00080030 VR TM Name Study Time Length 6 gt 123429 lt Attribute gt lt Attribute Tag 00080060 VR CS Name Modality Length 2 gt 0T lt Attribute gt lt Attribute Tag 00081111 VR SQ Name Referenced Performed Procedure Step Sequence Length 1 gt Item Attribute Tag 00081150 VR UI Name Referenced SOP Class UID Length 23 gt 1 2 840 10008 3 1 2 3 3 lt Attribute gt lt Attribute Tag 00081155 VR UI Name Referenced SOP Instance UID Length 44 gt 2 16 840 1 113669 4 960070 844 1026926027 44 lt Attribute gt lt Item gt lt Attribute gt lt Attribute Tag 00090010 VR LO Name Private Creator Code PCode PrivateCode Length 11 gt SAMPLE PCODE lt Attribute gt lt Attribute Tag 00091010 VR LO Name Private PCode SAMPLE PCODE Length 6 gt Valuel lt Attribute gt lt Attribute Tag 00091015 VR UN Name Private PCode SAMPL
164. lue To NULL e EMPTY VALUE and MC INVALID TAG return values both mean that a message does not contain a value for the specified attribute The use of these return values depends on how the message file or item containing the attribute was created e When using the MC Open Message MC Create File Open Item function to create an object Merge DICOM Toolkit loads a list of all of the valid attributes for the object For these types of objects the MC Get Value functions will return MC EMPTY VALUE when an attribute defined for the object does not have a value They will return MC INVALID TAG for attributes that are not defined for the object 137 Merge DICOM Toolkit 138 11 12 User s Manual e When the object has been created using MC Open Empty Message MC Create Empty File or MC Read Message Merge DICOM Toolkit will return MC INVALID TAG for any attribute that does not have a value defined trying to assign the value to a DICOM attribute within a message but Merge DICOM Toolkit will not allow me to do this When I call the MC Set Value functions they are returning INVALID TAG How I add this attribute e This problem occurs when using Open Message OrMC Create File to create a message or file of a particular type These functions restrict the attributes that can be added to a message Only those attributes that have been defined for
165. ly when it is needed When writing a network application the image data can be supplied to the user directly as it is read off the network The data can also be supplied when it is about to be written to the network This functionality can also be used when creating and reading DICOM files Finally MC Register Callback Function can be used to save an image to disk as it is received over the network Replacing Merge DICOM Toolkit s Memory Management Functions For Pixel Data When using MC Register Callback Function to replace Merge DICOM Toolkit s memory management functions the user would still use MC Get Value To Function and MC Set Value From Function to access the image When requested Merge DICOM Toolkit will receive or supply the attribute s value to the registered callback There are several additional requirements for this to function properly MC Set Message Callbacks must be called for the message or item before calling MC Set Value From Function MC Set Message Callbacks associates the callback function registered to a specific application to a message Also when a message or file object s memory is released the registered callback function is not notified There must be a link in the user s application between the registered callback and the code that is freeing the object Accessing Data When Needed When dealing with large multi frame images it is sometimes impractical to load the entire image into memory at on
166. m filename Filename containing message to display t Specify transfer syntax of message where syntax il implicit little endian el explicit little endian or eb explicit big endian m Optional display a DICOM file object If the DICOM service and or command cannot be found in the message file a warning will be displayed but the message will still be listed The default transfer syntax is implicit little endian the DICOM default transfer syntax If the transfer syntax is incorrectly specified the message will not be displayed correctly mc3valid The mc3valid utility validates binary message files according to the DICOM standard and notifies you of missing attributes improper data types illegal values and other problems with a message mc3validis a powerful educational and validation tool that can be used for the off line validation of the DICOM messages your application generates or receives The command syntax follows mc3valid filename w i s serv c lt cmd gt 1 m q t lt syntax gt filename Filename containing message to validate e Display error messages only w Display error and warning messages default I Display informational error and warning messages s lt serv gt Optional force the message to be validated against service name serv used along with c c cmd Optional force the message to be validated against command name cmd
167. model specifies the relationship between the different types of objects also called entities managed in DICOM For example a Patient has one or more Studies each of which are composed of one or more Series and zero or more Results etc Most of DICOM s services perform actions on or with object instances An object can be thought of as a class of data CT Image Film Box etc while an object instance is an actual occurrence of an object a particular CT Image a populated Film Box etc There are two types of objects and hence object instances defined in DICOM Normalized objects are objects consisting of a single entity in the DICOM information model e g a Film Box Composite objects are composed of several related entities e g an MR Image When possible it is preferable to deal with normalized object instances over the network because they contain less redundant data and can be more efficiently managed by an application Most services inherited from the ACR NEMA Version 2 x Standard are composite services operate on composite object instances for reasons of backward compatibility Newly introduced services such as the HIS RIS and Print Management Services tend to be normalized services operate on normalized object instances object instances are referred to as SOP Instances or managed SOPs in the DICOM standard M RGE Healthcare Merge DICOM Toolkit User s Manual Networking Certain aspects of DICOM
168. mplate ID identifier that specifies a template suggested to be used in the creation of a set of Content Items The referenced template can be found in the DICOM Part 16 and identified by a Template ID provided in the brackets e DTID Defined Template ID identifier that specifies a template that shall be used in the creation of a set of Content Items The referenced template can be found in the DICOM Part 16 and identified by a Template ID provided in the brackets Value Multiplicity VM The VM field indicates the number of times that either a Content Item of the specified pattern or an included Template may appear in this position Table 27 specifies the values that are permitted in this field Table 27 Permitted Values for VM Expression i where i represents Definition Exactly i occurrences where i gt 1 E g when i21 there shall be an integer one occurrence of the Content Item in this position i j From i to j occurrences where i and j are gt 1 and j gt i 1 n One or more occurrences 113 Merge DICOM Toolkit 114 User s Manual Requirement Type The Requirement Type field specifies the requirements on the presence or absence of the Content Item or included Template The following symbols are used e Mandatory Shall be present e Mandatory Conditional Shall be present if the specified condition is satisfied e U User Option May or may not be pres
169. n MEDIA FILE META INFO VER amp miVer sizeof miVer MEDIA TRANSFER SYNTAX UID MC Set Value From Buffer srID MC Set Value From String srID 1 2 9840 10008 1 2 1 MC Set Value From String srID MC Set Value From String srID MergeCOM3 1 0 MC Set Value From String srID MC Set Value From String srID gia via 7 3007 7 MEDIA_IMPLEMENTATION_CLASS_UID 72 16 840 1 112669 249311287 A_IMPLEMENTATION_VER_NAME MEDIA STORAGE SOP CLASS UID 1 2840 1000925 1 4 5 1 88 597 5 MEDIA STORAGE 5 INSTANCE UID Set other required attributes for the KO IOD MC ATT SOP CLASS UID MC Set Value From String srID 1 22 840 10008 5 1 4 1 1 88 59 MC Set Value From String srID MC Set Value From String srID MC Set Value From String srID MC Set Value From String srID MC Set Value From String srID D D D D MC Set Value From String sr MC Set Value From String sr MC Set Value From String sr MC Set Value From String sr MC Set Value To NULL SsrID MC ATT SOP INSTANCE UID 1 2 3 4 5 6 7 300 MC ATT STUDY DATE 19991029 MC ATT CONTENT DATE 19991029 STUDY TIME 154500 MC ATT CONTENT TIME 154510 MC ATT ACCESSION NUMBER 123456 MC MODALITY KO MC ATT MANUFACTURER MERGE MC REFERRING PHYSICIANS NAME Luke Will Dr M D MC ATT REFERENCED PERF
170. n a network a server application can only be configured to move images to one of these applications For this reason the DICOM Application Entity Title for your applications should be configurable Association Management Network Only Once you have registered one or more networking applications you will probably want to initiate an association if you are a client or wait for an association if you are a server To initiate an association as a client you make an MC Open Association call You specify your Application ID and the Remote Application Title of the server you wish to connect to If the association is accepted the function returns normally with an Association ID that is used to refer to this association in future calls When you are done making DICOM service requests sending and receiving messages over the association you should release the association with an Close Association call You also have the option of using the MC Open Secure Association call Use that function if you will be supplying additional code that will maintain a secure connection using a protocol such as Secure Socket Layer SSL or Transport Layer Security TLS Refer to the Merge DICOM Toolkit Reference manual for more information about the MC Open Secure Association call Client Side Example status MC Open Association MyStoreClientId amp associationID RemoteAppTitle NULL NULL NULL if status MC NORMAL COMPLETIO
171. n generate new binary files and keep the toolkit current This also reduces the number of changes that must be made in the core DICOM Toolkit library over time The extended version of this toolkit makes some of these tools available to application developers who need to significantly extend the standard with private attribute and private service definitions The files for the extended version are packaged with the standard toolkit The extended version supplies you with an ASCII file database of the standard that you can extend along with executables for your platform that translate these ASCII files to the binary message info and data dictionary files used by the toolkit at run time In this way you can extend the toolkit to validate your own private attributes and services Merge DICOM Toolkit User s Manual Documentation Roadmap The Merge DICOM Toolkit documentation is structured as shown in Figure 4 The User s Manual is the foundation for all other documentation because it explains the concepts of DICOM and the DICOM Toolkit Before plunging into the Reference Manual or Sample Application Guide you should be comfortable with the material in the User Manual Read Me FIRST The Reference Manual is where you go for detailed information on the DICOM Toolkit This includes the Application Programming Interface API toolkit configuration the runtime object database and status logging The DICOM Message Database Manual is an optional ext
172. n of compression callbacks is described later in this document Compression libraries are also included on several platforms including Windows Sun Solaris and Linux An example of encapsulated pixel data is illustrated in Table 13 59 Merge DICOM Toolkit User s Manua Table 13 Sample Encapsulated Pixel Data Pixel Data Element Basic Offset First Fragment Single Second Fragment Single Sequence Table with NO Frame of Pixel Data Frame of Pixel Data Delimiter Item Item Value Item Item Item Value Item Item Value Sequenc Tag Length Tag Length Tag Length e Delim Tag 0000 0000 Compresse 0000 FFFE 0000 0000H E000 04C6H d Fragment E000 EODD 0000H E000 Fragment 4 4 4 bytes 4 bytes 04C6H 4 bytes 4 bytes 024 H 4 bytes 4 bytes bytes bytes bytes bytes As specified by the DICOM standard the various elements shown in Table 13 excluding the compressed pixel data fragments are encoded in little endian format The compressed pixel data fragments are treated as OB and thus do not have an endian Figure 10 contains the sample pixel data of Table 13 in little endian format DICOM Message Stream DICOM Header Information EO 00 00 00 00 EO C6 04 00 00 First Compressed Fragment Encode Data FE FF 00 EO 4A 02 00 00 Second Compressed Fragment E FF DD EO 00 00 00 00 Hr Figure 10
173. nality as specified in Table 9 Most of these functions have three parameters in common a MsgItemID to specify the message object a Tag to specify the attribute whose value is being set and a Value being assigned to the attribute See the Reference Manual for detailed specifications of these functions The Set Value family of functions also operate on DICOM file objects and item objects since both of these objects are also constructed of DICOM attributes Table 9 The Set Value Family of Functions Function Type Description MC_Set_Value Sets the first and possibly only value of an attribute in a message object There are ten functions of this type the one you use depends on the data type of the value you are assigning to the attribute e g string short int long int float MC_Set_Next_Value Sets the next value of a multi valued attribute in message object There are ten functions of this type the one you use depends on the data type of the value you are assigning to the attribute e g string short int long int float MC Set Value To NULL Sets the value of an attribute in a message object to NULL This means that the attribute is included in the message but has a NULL value MC Set Value To Clears the value of an attribute in a message object This means the attribute has no value and is not included in the message M RGE Healthcare Merge DICOM Toolkit Performan
174. ncapsulated transfer syntax must be called upon creation of the ICON IMAGE item so that you may register compression callbacks and utilize them Reading from network a file or a stream No special conditions are required if the image is streamed in via Open File MC Read Message Stream To Message The sequence item automatically assumes ENDIAN if the pixel data contained in ICON IMAGE is of defined EXPLICIT LITTLE length OR transfer syntax of the parent if the pixel data contained in ICON IMAGE is of undefined length MC Duplicate Message If duplicating from unencapsulated to an encapsulated compressed transfer syntax then the icon will be unencapsulated by default To change the behavior set DUPLICATE ENCAPSULATED ICON to Yes in the mergecom pro This can be done dynamically via MC Set Bool Config Value 61 Fiealthcare Merge DICOM Toolkit message txt can be very useful 62 User s Manual Validating Messages Once your application has a populated message object either one that you have built or one that you have received and are about to parse Merge DICOM Toolkit supplies DICOM Toolkit DICOM message validation functionality The MC_Validate_Message function will validate the specified message object instance against the DICOM Standard s specification for that service command pair A file object validation function MC Vali
175. ncoded format specified by the DICOM standard and the negotiated transfer syntax Merge DICOM Toolkit calls this encoded format a message stream and supplies powerful functions that allow your applications to work directly with message streams When your application builds or parses messages as described earlier it works with a Merge DICOM Toolkit message object This message object abstracts and encapsulates the DICOM message and hides its details from the developer When you send the DICOM message object over the network Merge DICOM Toolkit internally creates a DICOM message stream that is passed over the network This message stream is an encoded stream of bytes that follows all the rules of DICOM Merge DICOM Toolkit also supplies function calls to the developer to generate and read DICOM message streams directly see Figure 1 1 MC Message To Stream converts a message object to a message stream while MC Stream To Message converts a message stream into a message object Also Get Stream Length is supplied to calculate the length of the DICOM stream that would result from using the MC Message To Stream call DICOM Message Stream MC Message To Stream Message it Object essage i i i MC Stream To Message Functionality Object Figure 11 Relationship between a Message Object and a Message Stream A callto MC Message To Stream could look like the following Status MC Message To Stream MyMessage
176. nd a message over as follows MC Status C Set Message Transfer Syntax ImageMsgID JPEG BASELINE M RGE 47 Fiealthcare Merge DICOM Toolkit User s Manual Transfer Syntax Server SCP applications are configured differently than client SCU applications Lists for SCPs An SCP should include all of the transfer syntaxes a service supports in a single transfer syntax list If more than one transfer syntax list is used for a service server SCP applications will only support the transfer syntaxes contained in the first transfer syntax list The following is an example configuration for a server SCP Storage Service List SERVICES SUPPORTED 1 4 Number of Services SERVICE 1 STANDARD CT SYNTAX LIST 1 CT Syntax List SCP CT Syntax List SCP SYNTAXES SUPPORTED 4 4 Number of Syntaxes SYNTAX 1 JPEG BASELINE SYNTAX 2 EXPLICIT LITTLE ENDIAN SYNTAX 3 IMPLICIT LITTLE ENDIAN SYNTAX 4 EXPLICIT BIG ENDIAN As discussed previously for server SCP applications the order in which transfer syntaxes are specified in a transfer syntax list dictates the priority Merge DICOM Toolkit places on them during association negotiation In this case Merge DICOM Toolkit would select PEG BASELINE if proposed followed by EXPLICIT LITTLE ENDIAN IMPLICIT LITTLE ENDIAN and EXPLICIT BIG ENDIAN
177. nd places them in the message identified by MyMessageID Itis important that the transfer syntax specified in this call is identical to that used to create the stream or the call will fail with an error The same kind of performance issues apply in the callback functions discussed above as in those callbacks used with Get Value To Function and MC Set Value From Function Namely your setting of LARGE DATA STORE should take into consideration the capabilities of your platform Message streams can be very valuable to your application for debugging and validation purposes By writing DICOM message streams out to a binary file you have a compact and reproducible representation of a message You can directly examine the binary message stream to see how the data would be sent over the network Also you can read this binary file in again later to reconstruct the original message object Once you have the message object you can use the usual toolkit functions to examine or alter its contents The transfer syntax Deflated Explicit VR Little Endian gives you the ability to use the deflate algorithm to compress the entire data set This transfer syntax was added mostly for structured reports which are extremely redundant in their encoding with considerable repetition of strings and tags The toolkit uses zlib to implement deflate inflate This is an open source library that is built into the toolkit Messages of this transfer
178. nd provide worthwhile but primitive examples of how to approach your application with the toolkit While you will see that the toolkit saves you a great deal of DICOM work it does not implement your end application for you Association Negotiation One of the two areas where Merge DICOM Toolkit does a great deal of the DICOM work for you is in opening an association Session with another DICOM AE over the network DICOM application entities need to agree on certain things before they operate with one another open an association these include e the services that can be performed between the two devices which also impacts the commands and object instances that can be exchanged e transfer syntax that shall be used in the network communication The transfer syntax defines how the commands and object instances are encoded on the wire The exchange of DICOM commands and object instances can only occur over an open association DICOM defines an association negotiation protocol see Figure 5 In the most common DICOM services a client application entity SCU proposes an association with a server AE SCP However some services define a mechanism where the client can be the SCP which opens an association with the SCU This is used when an SCP sends asynchronous event reports to an SCU through the N EVENT REPORT command This is done through DICOM role negotiation which is used during standard association negotiation
179. network If the data is stored in file format the MC Open File Bypass OBOW Or Open File Upto Tag MC Open File Upto Tag Bypass Value functions can be used to leave the image data on disk until it is sent over the network M RGE Healthcare Merge DICOM Toolkit MC_Register_Callback Function M RGE Fiealthcare User s Manual Using Registered Callbacks Merge DICOM Toolkit also supplies a method to allow the user to manage image data through the use of registered callback functions Register Callback Function associates a callback function with a DICOM attribute such as pixel data These callbacks are limited to attributes with the value representations of OB OW or OL When encountered the attribute s data is passed to the registered callback function instead of being stored within Merge DICOM Toolkit The callback is also used to supply the attribute s data The size of data elements for which to use callbacks can also be specified The CALLBACK MIN DATA SIZE configuration option can specify the minimum size or length required for use of a registered callback function There are three models in which Register Callback Function can be used First it can be used to seamlessly replace Merge DICOM Toolkit s memory management functions Use of this function can for the most part be hidden from the application Secondly the function can be used as an interface to receive or supply data on
180. nfo can be set to NULL or point to a user defined structure that can be used to communicate application specific data to the Callback Function A single Callback Function can be multiply registered to handle many tags Also a single Callback Function will handle both transmittal and reception of the data associated with the Tag s MyCallbackFunction is prototyped as follows MC STATUS MyCallBackFunction int CBMessageID Callback Function unsigned long CBtag void myUserInfo CALLBACK TYPE CBtype unsigned long CBdataSizePtr void CBdataBufferPtr int CBisFirstPtr int CBisLastPtr CBMessageID and CBtag allow a single Callback Function to handle requests for different message and tag combinations myUserInfo is a pointer to the user defined structure passed in from the MC Register Callback Function described above Based on the value of CBt ype your Callback Function determines how it is to behave whether it is to supply receive the length of the entire attributes value or supply receive a chunk of value data CBdataSizePtr CBdataBufferPtr CBisFirstPtr and CBisLastPtr are used to manage the data flow Table 22 describes this behavior Table 22 Callback Function Behavior Based on Value of CBtype parameter Value of Cbtype Required Callback Behavior REQUEST_FOR_DATA_LENGTH Callback is supplying OB OW OF data and the length of the entire attributes value is being requested The length is passed back using CBdat
181. nous events 46 User s Manual Handle messag xchange here It is during message exchange where you detect that the association has been closed and act accordingly Three additional functions MC_Get_Association_Info MC Get First Acceptable Service and MC Get Next Acceptable Service allow the client or server to query the characteristics of an association This is useful to a client so that it knows what subset of services transfer syntaxes and DICOM roles that it proposed have been accepted and can now perform with the server Similarly a server can look at characteristics of the association request such as the network node name of the client and either accept or reject the association See the Reference Manual for a detailed description of these functions In specialized cases where the server application is waiting on several asynchronous events not just the association event the Get Listen Socket call be made to request the file descriptor for the DICOM listen socket In this way the server application can do a select system call on this and other file descriptors When the select returns with an event on the DICOM listen socket descriptor the application can call MC Wait For Association get an immediate response Similarly once the association is established both the client and server applications can use the Get Association Info call to get the file
182. nteger value and n represents many For example Part 6 specifies the VM of Scheduled Discharge Time 0038 001D as 1 while the VM of Referenced Overlay Plane Groups 2040 0011 is 1 99 VR 9 m Message Handling Given the number of services and commands specified in Table 1 and Table 2 it is clear that there are a great deal of messages to manage in DICOM Remember each service command pair implies a different message Fortunately you will see later that Merge DICOM Toolkit saves the application developer a great deal of work in the message handling arena DICOM specifies the required contents of each message in Parts 3 4 and 7 of the standard For each attribute included in a message additional characteristics of the attribute are defined that only apply within the context of a service These characteristics are Enumerated Values Defined Terms and Value Type DICOM specifies that some attributes should have values from a specified set of values If the attribute is an enumerated value it shall have a value taken from the specified set of values A good example of enumerated values are M F O for Patient s Sex 0010 0040 in Storage services If the attribute is a defined term it may take its value from the specified set or the set may be extended with additional values An example of defined terms are CREATED RECORDED TRANSCRIBED APPROVED for Interpretation Status ID 4008 0212 in Results Management services If
183. ntf NtError on MC_Wait_For_Association n printf NtNt sWMn MC Error Message status printf NtNtProgram aborted abort is calledApplicationID MyApplicationID printf NtUnexpected application identifier on C_Wait_For_Association n printf t tProgram aborted n abort JM Accept Association associationID if status MC NORMAL COMPLETION printf NtError on MC Accept Association Mn printf t t s n MC_Error_Message status return 44 M R G Fiealthcare Merge DICOM Toolkit MC_Wait_For_Connection User s Manual Handle messag xchange here It is during message exchange where you detect that the association has been closed and act accordingly When using the MC Wait For Connection callin a server application the time to wait is specified and a pointer to a socket variable is supplied Upon successful completion the socket for the incoming connection is returned and must be passed to MC Process Association Request to actually process the connection After MC Wait For Connection completes a typical server application will create a child thread or process to handle the incoming connection and return back to calling MC Wait For Connection to wait for the next incoming association You also have the option of using the MC Process Secure Association Request call for processing secure associations Use that function if you will be sup
184. numerated Values M F O 0010 0050 Patient s Insurance Plan Code Sequence SQ 3 M RGE Fiealthcare Merge DICOM Toolkit User s Manual Item Name s PATIENTS INSURANCE PLAN CODE 0010 1000 Other Patient IDs LO 3 0010 1001 Other Patient Names PN 3 0010 1005 Patient s Birth Name PN 3 0010 1020 Patient s Size DS 3 0010 1040 Patient s Address LO 3 0010 1060 Patient s Mother s Birth Name PN 3 0010 1080 Military Rank LO 3 0010 1081 Branch of Service LO 3 0010 1090 Medical Record Locator LO 3 0010 2000 Medical Alerts LO 3 0010 2110 Contrast Allergies LO 3 0010 2150 Country of Residence LO 3 0010 2152 Region of Residence LO 3 0010 2154 Patient s Telephone Numbers SH 3 0010 2160 Ethnic Group SH 3 0010 21A0 Smoking Status CS 3 Enumerated Values YES NO UNKNOWN 0010 21B0 Additional Patient History LT 3 0010 21C0 Pregnancy Status US 3 Enumerated Values 0001 0002 0003 0004 0010 21D0 Last Menstrual Date DA 3 0010 21F0 Patient s Religious Preference LO 3 0010 4000 Patient Comments LT 3 0038 0004 Referenced Patient Alias Sequence SQ 2 Item Name s REF_PATIENT_ALIAS 0038 0050 Special Needs LO 3 0038 0500 Patient State LO 3 What validation While Merge DICOM Toolkit s validation is not foolproof it is very useful and will catch can do for you many standard violations It validates the following That the value assigned to an attribute is appropriate for that attr
185. oFile is the file system interface callback function you must author to read from your media device described earlier as the YourFromMediaFunction The parameters for this callback function must agree with the following prototype MC STATUS MediaToFile char filename void userInfo int dataSize void dataBuffer int isFirst int isLast fileName identifies the file you should be reading e g PNR1 HDR3 AMR62 dataSize specifies the even number of bytes of data you are providing and dataBuffer is address of the data isFirst indicates whether this is the first chunk of data read e g you should open the file isLast is setto a non zero value by your application when it has finished returning data e g has closed the You can decide for yourself how you wish to read in the data from the physical file all at once or a block at a time The library will callback MediaToFile until you indicate that all data has been read The userInfo parameter can be used to pass application specific data between the sample application and the callback function See the reference manual for a more detailed description of MC Open File and the YourFromMediaFunction callback function M RGE 89 Healthcare Merge DICOM Toolkit Performance Tuning 90 User s Manual Once the file object has been opened the same MC Get Value family of parsing functions used for message objects described ear
186. oblem on Big Endian machines To summarize the problem on big endian machines we expect 8 bit data to be byte swapped We do not look at the bits allocated and bits stored tags to determine that the pixel data itself is 8 bit data we always treat pixel data 7 0 0010 as OW The pixel data must be assigned as byte swapped or the function MC Byte Swap OBOW should be called after setting the pixel data recently upgraded to a new release of the Merge DICOM Toolkit Since this upgrade have been having problems with the MC Set Value functions returning MC INVALID TAG This code worked before the upgrade What is causing these problems The Merge DICOM Toolkit data dictionary changes from release to release In some cases the identification number for a particular message type changes When upgrading if you do not change all of the data dictionary files this error will occur The following files should be upgraded with each release e diction h e mergecom srv e mrgcom3 msg e mrgcom3 dct What are the differences between the MC NULL VALUE MC EMPTY VALUE and MC INVALID TAG return values of the Get Value functions e The MC NULL VALUE return value is used to identify when an attribute within a DICOM message has zero length DICOM allows attributes that have a Value Type of 2 to be set to zero length when their value is unknown An attribute can be set to zero length in Merge DICOM Toolkit with MC Set Va
187. oc and free Under most conditions Merge DICOM Toolkit breaks up large DICOM data elements such as pixel data into chunks of data smaller than 28K so that they can be managed through these routines The end result of these routines is that applications using Merge DICOM Toolkit typically expand to the maximum amount of memory used at one time The total memory allocation will not shrink from this point In applications that repeatedly perform a consistent operation the memory being used by Merge DICOM Toolkit should stabilize and not increase in size In applications using Merge DICOM Toolkit from multiple threads this memory usage is not as consistent and depends on the timing of the threads using Merge DICOM Toolkit As a result of these routines the first time an application performs a DICOM operation is typically slower than subsequent operations Merge DICOM Toolkit supplies the MC Report Memory and MC Cleanup Memory routines to allow some user control over this memory management MC Report Memory reports how much memory is currently allocated and in use by Merge DICOM Toolkit The Cleanup Memory routine can be used to actually free memory allocated by Merge DICOM Toolkit The routine looks for blocks of memory that are no longer in use by Merge DICOM Toolkit and frees them with the operating system This can be useful when a Merge DICOM Toolkit application reads a large DICOM object such as a large DICOMDIR or a lar
188. of the DICOM Standard discusses how UIDs are composed encoded and registered Summary of UID Composition A UID is composed of a number of numeric values as defined by ISO 8824 The following is a typical example of a UID 1 2 840 10008 2 45 1 12345 A UID is composed of two parts a lt root gt and a lt suffix gt and has the following form UID lt root gt lt suffix gt where lt root gt is assigned by a registration authority e g ANSI with the distinguishing component being the organization ID The lt root gt portion of the UID uniquely identifies an organization while the lt suffix gt portion is used to uniquely identify a specific object within the scope of the organization While the lt root gt component of the UID stays constant the lt suffix gt portion will change in a manner that will provide uniqueness for objects that need UIDs Note this implies that the organization is responsible for maintaining the uniqueness of the lt suffix gt For example using the UID above lt root gt 1 2 840 10008 and lt suffix gt 2 45 1 12345 Where the organization ID portion of the lt root gt 10008 distinguishes organizations from each other Note The above example is typical for UIDs obtained by ANSI during the time when the DICOM standard was first released The organization ID of 10008 has actually been assigned to NEMA and is used as part of the lt root gt for DICOM standard UIDs such as SOP Classes Transf
189. om String failed n printf Nt sWMn MC Error Message status 52 M RGE Healthcare Merge DICOM Toolkit Supplying pixel data User s Manual MC Free Message amp messageID MC Abort Association amp associationID MC Release Application amp applicationID return 1 Set other attributes here status MC Send Request Message associationID messageID xt status MC NORMAL COMPLETION printf MC Send Request Message failed Nn printf Nt sWMn MC Error Message status MC Free Message amp messageID MC Abort Association amp associationID MC Release Application amp applicationID return 1 void MC Free Message amp messageID When setting the value of an attribute with a value representation of OB or OW e g Pixel Data you can use the MC Set Value From Function Pixel Data tends to be very large and normally you use this function to supply the data value a chunk or block at a time As an example your application could define a callback function MyPDSupplyFunction whose purpose is to supply Pixel Data Pseudo code for this function follows MC STATUS MyPDSupplyFunction int MsgID unsigned long Tag int IsFirstCall void UserInfo int BlockSize void DataBlock int IsLastBlock if IsFirstCall open pixel data source e g file here using Tag and or UserInfo as a guide if Open
190. ome vendors also include fields within the UID to identify the type of UID For example the first component after the root within the UID may be a 1 for Study Instance UIDs a 2 for Series Instance UIDs and 3 for SOP Instance UIDs Occasionally a product identifier will also be included within a UID This may be a unique number assigned to a product within an organization Finally a number may also be added to signify the software revision number for a product that is generating the UID Obtaining a UID The root portion of the UID should be registered by an organization that guarantees global uniqueness The American National Standards Institute ANSI is the registration authority for the United States Other national registration authorities exist for nations throughout the world such as IBN in Belgium AFNOR in France BSI in Great Britain DIN in Germany and COSIRA in Canada Obtaining a UID From ANSI ANSI is the registration authority for the US for organization names i e root under the global registration process established by the International Standards Organization ISO and the International Telegraph and Telephone Consultative Committee CCITT ANSI s registration service conforms with CCITT X 660 and ISO IEC 9834 1 The ANSI organization name registration service assigns one name component to the hierarchy defined by CCITT and ISO IEC An organization seeking registration may do so by submitting a Req
191. ompression limits The licenses can be configured in the mergecom pro configuration file The JPEG_BASELINE transfer syntax is UID 1 2 840 10008 1 2 4 50 JPEG Baseline Process 1 Default Transfer Syntax for Lossy JPEG 8 Bit Image Compression and uses Pegasus libraries 6420 6520 Table 17 details the photometric interpretation and bit depths supported by the standard compressor and decompressor for this transfer syntax When lossy compressing RGB data the standard compressor by default compresses the data into YBR FULL 422 format The compressor can also compress in YBR FULL format if the COMPRESSION RGB TRANSFORM FORMAT configuration option is set to YBR FULL The Photometric Interpretation tag must be changed by the application after compressing RGB data Similarly the Photometric Interpretation tag should be changed back to RGB before decompressing YBR FULL Or YBR FULL 422 data Table 17 JPEG Baseline Supported Photometric Interpretations and Bit Depths JPEG Baseline Photometric MONOCHROME1 RGB YBR FULL 422 Interpretation MONOCHROME2 YBR FULL The JPEG EXTENDED 2 4 transfer syntax is UID 1 2 840 10008 1 2 4 51 JPEG Extended Process 2 amp 4 Default Transfer Syntax for Lossy JPEG 12 Bit Image Compression Process 4 only and uses Pegasus libraries 6420 6520 Table 18 details the photometric interpretation and bit depths supported by the standard compressor and
192. only apply to networking when using the DICOM Toolkit This includes networking commands and association negotiation Commands DICOM defines a set of networking commands Each service uses a subset of these DICOM commands to perform the service over a network These commands usually act on object instances The C commands operate on composite object instances while the N commands operate on normalized object instances The DICOM commands and brief descriptions of their actions are listed in Table 2 Table 2 DICOM Commands DICOM Commands Description C STORE Transfer an object instance to a remote AE C GET Retrieve object instance s from a remote AE whose attributes match a specified set of attributes C MOVE Move object instance s from a remote AE whose attributes match a specified set of attributes to yet another remote AE or possibly your own AE which would be another form of retrieval C FIND Match a set of attributes to the attributes of a set of object instances on a remote AE C ECHO Verify end to end communications with a remote AE N EVENT REPORT Report an event to a remote AE N GET Retrieve attribute values from a remote AE N SET Request modification of attribute on a remote AE N ACTION Request an action by a remote AE N CREATE Request that a remote AE create a new object instance N DELETE Request that a remote AE delete an existing object instance Wh These DICOM commands can be thought of as primitives that e
193. onstrained by the IOD in which this Module is contained Merge DICOM Toolkit Definition column specifies the enumerated value used in the Toolkit to identify the Content Item Type M RGE 105 Fiealthcare Merge DICOM Toolkit 106 Table 24 SR Content Item Types Item Type Merge DICOM Toolkit Definition Concept Name User s Manual Description TEXT SR_NODE_TEXT Type of text Free text narrative e g Findings description of unlimited or name of length May also be used identifier e g to provide a label or Lesion ID identifier value NUM SR_NODE_NUM Type of numeric Numeric value fully value or qualified by coded measurement representation of the e g BPD measurement name and unit of measurement CODE SR_NODE_CODE Type of code Categorical coded value e g Findings Representation of nominal or non numeric ordinal values DATETIME SR_NODE_DATETIME Type of Date and time of DateTime e g occurrence of the type of Date Time of event denoted by the onset Concept Name DATE SR_NODE_DATE Type of Date Date of occurrence of the e g Birth Date type of event denoted by the Concept Name TIME SR_NODE_TIME Type of Time Time of occurrence of the e g Start Time type of event denoted by the Concept Name UIDREF SR NODE UIDREF Type of UID Unique Identifier UID of e g Study the entity identified by the Instance UID Concept Name PNAME SR NODE PNAME Role of person
194. onverting Files to from 93 DIG OMB M 93 iv M RGE Healthcare Merge DICOM Toolkit M RGE Fiealthcare User s Manual ud 93 Opening and Navigation sse 94 Adding and Deleting 96 Storage of Directory 96 Private 97 Multi threading 5 enne 98 Memory 2 98 Assigning Pixel 99 Reading Messages from the 100 Loading Messages from 100 Using Registered Callbacks essen 101 DICOM Structured Reporting sse 103 Structured Report Structure and 103 Content Item 105 Relationship Types between Content Items 108 Content Item Identifier nnns 110 Observation 4 22 1 entente entren nennen 110 Structured Reporting Templates
195. or in both places There shall be no conflict between the Relationship Type and Mode of a row that includes another Template and the Relationship Type and Mode of the rows of the included Template When the relationship is defined in a form as R RTYPE it means that Relationship Mode is By reference and Relationship Type is RTYPE For example R INFERRED FROM Merge DICOM Toolkit provides following functions to encode decode references MC ATUS EXP_FUNC MC_SRH_Add_Reference nt AsrNodeID R RELATIONSHIP Arelationship nt AsrRefNodeID _S i S i MC STATUS EXP FUNC MC SRH Get Reference int AsrNodeID int AsrRefNodeID Value Type VT The Value Type field specifies the SR Value Type of the Content Item or conveys the word INCLUDE to indicate that another Template is to be included substituted for the row The Merge DICOM Toolkit uses explicit function call for each Content Item Type as it described above Concept Name Any constraints on Concept Name are specified in this field as defined or enumerated coded entries or as baseline or defined context groups Alternatively when the VT field is INCLUDE the Concept Name field specifies the template to be included The Merge DICOM Toolkit uses following arguments to specify the Concept Name const char AconceptNameValue const char AconceptNameScheme const char AconceptNameMeaning You will find that some of the funct
196. orm file interchange functionality are in turn classified into three roles e File Set Creator FSC Uses M WRITE operations to create a DICOMDIR file and one or more DICOM files e File Set Reader FSR Uses M READ operations to access one or more files in a DICOM file set An FSR shall not modify any files of the file set including the DICOMDIR file e File Set Updater FSU Performs M READ M WRITE and M DELETE operations It reads but shall not modify the content of any DICOM files other than the DICOMDIR file It may create additional files by means of an M WRITE or delete existing files by means of an M DELETE The concept of these roles is used within the DICOM conformance statement of an application entity that supports media interchange to more precisely express the capabilities of the implementation Conforming applications shall support one of the capability sets specified in Table 8 DICOM conformance is described in greater detail in the next section M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare Table 8 Media Application Operations and Roles Media Roles M WRITE M READ M DELETE M INQUIRE M INQUIRE FILE SET FILE FSC Mandatory required Mandatory FSR not Mandatory required required Mandatory required Conformance Part 2 of DICOM discusses conformance and is important to any AE developer For
197. ows for the service command pair DETACHED PATIENT MANAGEMENT GET RSP as an illustration For each attribute in the message at least one line of data is specified This first line includes the tag attribute name value representation and value type Additional lines may be included for the attribute to list conditions enumerated values defined terms and item names for attributes with a VR of SQ You should refer to the DICOM Standard parts 3 and 4 for a detailed description of particular conditions and their meanings HH HE DETACHED PATIENT MANAGEMENT N GET RSP a EH HH HE EE HE EE 0008 0005 Specific Character set CS IG Condition EXPANDED_OR_REPLACEMENT_CHARACTER_SET_USED Defined Terms ISO IR 100 ISO IR 101 ISO IR 109 ISO IR 110 ISO IR144 ISO IR 127 ISO IR 126 ISO IR 138 ISO IR 148 0008 1110 Referenced Study Sequence 50 2 Item Name s STUDY 0008 1125 Referenced Visit Sequence SQ 2 Item Name s 0010 0010 Patient s Name PN 2 0010 0020 Patient ID LO 2 0010 0021 Issuer of Patient ID LO 3 0010 0030 Patient s Birth Date DA 2 0010 0032 Patient s Birth Time TM 3 0010 0040 Patient s Sex S 2 E
198. ows the user to specify the first eight characters of the names of the DICOM message files being generated mc3file will then append a unique count to the end of the filename for each message being generated The default value is file when creating a DICOM file and message when creating the format that DICOM messages send over a network MC3File retrieves default values for attributes from the text file default pfl Unlike the info pfl and diction pfl files which are converted into binary files default pfl is used as a text file It will first be searched for in the current directory and then in the message information directory This file contains default values for all messages and for specific service command pairs This file can be modified to contain defaults specific for the user although it is recommended that a backup of the original be kept If this file is modified there are no guarantees that the messages generated will validate properly 40 M RGE Healthcare Merge DICOM Toolkit Check Return Codes User s Manual Developing DICOM Applications The Merge DICOM Toolkit Application Programming Interface API provides simple yet powerful DICOM functionality Function calls are provided that open associations with remote servers wait for associations from remote clients and deal with DICOM message exchange over an open association Functions are also provided for the creation and re
199. pe 1 1C 2 or 2C attributes e possible value representations VRs used for private attributes shall be only those specified by the standard see Table 4 The way you use private attributes in your application can also greatly affect your conformance statement DICOM conformance is discussed in greater detail later M RGE Healthcare Merge DICOM Toolkit DICOM File Structure DICOM objects that can be written to media M RGE Healthcare User s Manual Media Interchange The DICOM Standard specifies a DICOM file format for the interchange of medical information on removable media This file format is a logical extension of the networking portion of the standard When an object instance that was communicated over a network would also be of value when communicated via removable media DICOM specifies the encapsulation of these object instances in a DICOM file DICOM Files A DICOM File is the encapsulation of a DICOM object instance along with File Meta Information File meta information is stored in the header of every DICOM file and includes important identifying information about the encapsulated object instance and its encoding within the file see Figure 7 File Preamble 128 byte field optional extra padding attribute FFFC FFFC Four byte DICOM Prefix DICM Each attribute identified by a Tag R B L Kile Meta Object Instance Information WI Y Byte Stream N Optional Pa
200. perability problems in the field There are some options however that can be set before deploying a Merge DICOM Toolkit application to help reduce potential problems These options are listed in Table 29 with descriptions of how they can be set Table 29 Configuration options to consider when deploying an application Configuration Option Description ACCEPT_ANY_APPLICATION_TITLE When set to NO Merge DICOM Toolkit requires that the Application Entity title sent in an association request match one of the registered application titles for the SCP When there is no match the association will be automatically rejected Setting this option to YES will eliminate some association negotiation problems in the field for SCP applications ACCEPT_ANY_HOSTNAME When set to NO Merge DICOM Toolkit will attempt to resolve the IP address of the SCU application into a hostname If this resolution cannot be done the association will automatically be rejected Setting this option to YES will reduce configuration problems in the field for SCP applications EXPORT_UN_VR_TO_MEDIA Setting this option to NO will cause UN VR attributes to not be exported when writing DICOM Part 10 format files with MC Write File or MC_Write_File_By_Callback See the following sections for a further discussion of UN VR EXPORT UN VR TO NETWORK Setting this option to NO will cause UN VR attributes to not be exported over the network with MC Send Request Message
201. plying additional code that will maintain a secure connection using a protocol such as Secure Socket Layer SSL or Transport Layer Security TLS Refer to the Merge DICOM Toolkit Reference manual for more information about the Process Secure Association Request call Server Side Example of MC Wait For Connection MC SOCKET theSocket status MC Wait For Connection 1 amp theSocket if status MC NORMAL COMPLETION printf NtError on MC Wait For Connection Mn printf NtNt sWMn MC Error Message status printf NtNtProgram aborted Nn abort status MC Process Association Request theSocket Service List 1 amp calledApplicationID amp associationID if status MC NORMAL COMPLETION printf NtMC Process Association Request error Mn printf t t s n MC Error Message status printf NtNtProgram aborted abort if calledApplicationID MyApplicationID printf NtUnexpected application identifier on C Wait For Association Nn printf NtNtProgram aborted abort status MC Accept Association associationID if status MC NORMAL COMPLETION printf NtError on MC Accept Association Mn printf t t s n MC_Error_Message status return M RGE Healthcare 45 Merge DICOM Toolkit Querying the associations characteristics Using select to handle asynchro
202. pment and SR Document General modules Observation Context defined by attributes in these modules applies to all Content Items in the SR Document Content tree and need not be explicitly coded in the tree The initial Observation Context from outside the tree can be explicitly replaced If a Content Item in the SR Document Content tree has Observation Context different from the context already encoded elsewhere in the IOD the context information applying to that Content Item shall be encoded as child nodes of the Content Item in the tree using the HAS OBS CONTEXT relationship That is Observation Context is a property of its parent Content Item The context information specified in the Observation Context child nodes i e target of the HAS OBS CONTEXT relationship adds to the Observation Context of their parent node Content item and shall apply to all the by value descendant nodes of that parent node regardless of the relationship type between the parent and the descendant nodes Observation Context is encoded in the same manner as any other Content Item Observation Context shall not be inherited across by reference relationships Observation DateTime is not included as part of the HAS OBS CONTEXT relationship and therefore is not inherited along with other Observation Context The Observation DateTime Attribute is included in each Content Item which allows different observation dates and times to be attached to different Content Items M RG
203. pports the exchange of any type of worklist from one AE to another Printing or filming of medical images and image related data on a hard copy medium Also storage of print related data to interchangeable media Allows one DICOM AE to notify another DICOM AE of the existence contents and source location of the images of a study 15 Merge DICOM Toolkit DICOM Information Model Objects vs object instances Normalized vs composite 16 Service Class Patient Management Services Detached Patient Management Detached Visit Management Detached Patient Mgmt Meta User s Manual Description Creation and tracking of the subset of patient and patient visit information that is required to aid in the management of radiographic studies Study Management Detached Study Management Creation scheduling performance and tracking of imaging studies Study Component Management Modality Performed Procedure Step Modality Performed Procedure Step Notification Modality Performed Procedure Step Retrieve Results Management Detached Results Management Detached Interpretation Management Detached Results Mgmt Meta Creation and tracking of results and associated diagnostic interpretations Information Model The DICOM Standard includes the specification of a DICOM Information Model A detailed entity relationship diagram of this model is included in both parts 3 and 4 of the standard This
204. rations allowed by the DICOM Standard and the potentially unlimited combination of media devices device drivers and file system combinations for which DICOM media interchange applications may be developed Your application need only supply two file system interface functions that the DICOM Toolkit Library calls back a YourFromMediaFunction that reads from your media of choice and a YourToMediaFunction that performs the write operations to the same These functions will be described in greater detail in the following sections and they are often very simple to write see the Sample Media Application supplied with the toolkit 87 Merge DICOM Toolkit Performance Tuning 88 User s Manual You will find that the DICOM Toolkit provides powerful DICOM media functionality by supplying your application with e a greatly simplified way to deal with the complex encoding and decoding required within a DICOM file e very powerful DICOMDIR file navigation and maintenance functionality e an API that is very consistent with that used for the maintenance of DICOM messages used in network functionality many of the encoding and decoding functions already described apply equally well to DICOM file objects To perform all this functionality on your medium of choice you need only supply the two file system interface functions just discussed Creating a File Object Before the contents of an existing DICOM file can be read in or a new
205. rk This functionality is conducive to storing a message s header data separately from its image data Depending on system requirements this may be an aid in quickly loading image data while bypassing Merge DICOM Toolkit The complete image file can be reassembled later using Merge DICOM Toolkit Saving Received Images Directly to Disk In conjunction with the registered callback function data can also be stored directly to disk when it is being read The image s header data can be written to disk from within the registered callback The user must write the attribute tag value representation if needed and the length of the image data attribute to the file The image data is written to the file in subsequent calls to the user s registered callback function When Read Message is parsing a message being received it will notify the user s registered callback function when it has parsed the header information and determines the image data s length The registered callback function will be called with the PROVIDING DATA LENGTH flag and is supplied the Message ID of the message being read At this point the user can stream the header file to disk with MC Message To Stream As the image data is received it can be added to the end of this file Data can also be stored as DICOM files with this method The message cannot be converted into a file object at this point with MC Message To File as would normally done So a separate fi
206. ry itself must be updated It is recommended that your application be recompiled against the new version of the library instead of just replacing the library e Upgrading the data dictionary files The diction h mergecom srv mrgcom3 msg and mrgcom3 dct files must all be updated when upgrading the Merge DICOM Toolkit data dictionary Upgrading some but not all of these files can cause subsequent problems e Upgrading the configuration files Upgrading the merge ini mergecom pro and mergecom app configuration files is option Although new configuration options are often added to these files Merge DICOM Toolkit will assume default values for these options if they are not included in a configuration file These files do not have to be updated when moving to a new release Note however that the descriptions of configuration options are often updated and it is useful to have the latest versions of these files running the toolkits sample applications for the first time have set the MERGE INI environment variable to point to the merge ini file However the MC Library Initialization call is still returning MC CONFIG INFO ERROR What is the cause of this problem This is usually only a problem under Windows The merge ini file contains several entries that point to the locations of the other toolkit configuration files These entries contain relative pathnames for the other files If the sample applications are not executed from th
207. s Allocated 8 bits Stored and a High bit of 7 VR OW The DICOM standard specifies that the first pixel byte should be set to the east significant byte of the OW value The next pixel byte should be set to the most significant byte of the OW value This implies that on big endian machines 8 bit pixel data is byte swapped from the OB encoding method To make dealing with 8 bit pixel data easier on big endian machines the toolkit has the function MC_Byte_Swap_OBOW This function byte swaps OW data word by word This function can be called after setting or before retrieving pixel data Encapsulated Pixel Data Merge DICOM Toolkit supports handling of single frame and multi frame pixel data in encapsulated transfer syntaxes dealing with it in the same manner as standard pixel data using the following calls MC Set Encapsulated Value From Function MC Set Next Encapsulated Value From Function MC Close Encapsulated Value MC Get Encapsulated Value To Function MC Get Next Encapsulated Value To Function MC Get Frame To Function Merge DICOM Toolkit will encode supplied data in an encapsulated format and generate the basic offset table The data of basic offset table could be retrieved using call MC Get Offset Table To Function Merge DICOM Toolkit will provide data without the encapsulation delimiters The data can be compressed or decompressed using a registered compression callback Registratio
208. s are only accessed from one thread at a time For instance Merge DICOM Toolkit assumes that only a single thread will manipulate a message object at one time Please check the platform notes to see if a platform supports multi threading Shared libraries or dynamic link libraries DLL s are normally supplied by Merge DICOM Toolkit for platforms which support them When a Merge DICOM Toolkit Application is first run it reads in its configuration files usually named merge ini mergecom app mergecom pro and mergecom srv Toolkit configuration is described later in this document and is detailed further in the Reference Manual Usually it is desirable to keep these configurable parameters in ASCII files for easy modification When modifying your configuration files your application must be re run for those changes to take effect In cases where the toolkit configuration is unlikely to be changed or it is desirable to make these changes within the running application the toolkit configuration can be compiled into your application Most configurable parameters can be dynamically modified and reset within your running application Binary Message Information and Data Dictionary Files A great deal of the power of Merge DICOM Toolkit lies in its message handling and message validation capabilities Message Objects are what is communicated between DICOM Application Entities When your application creates a DICOM message object the library acces
209. ses a binary message info file with information about that class of message This info file describes to the library what attributes to expect as part of that message and each attribute s characteristics Value Type Conditions and Enumerated or Defined Terms M RGE Healthcare Merge DICOM Toolkit Performance Tuning The sample applications and application guides can be a big help M RGE Fiealthcare User s Manual Another binary file containing the data dictionary is also accessed by the library The data dictionary contains other characteristics of attributes Name Value Representation and Value Multiplicity Merge DICOM Toolkit gives you added flexibility by not requiring your application to make use of the message info file Certain API calls allow you to open messages without accessing the info files This means that the toolkit cannot validate your message against the DICOM standard but this may not always be necessary once an application becomes stable These options are discussed in greater detail in the Developing DICOM Applications section of this document Two specialized classes subclasses of message objects are also supported by the DICOM Toolkit Library items and files Items are DICOM sub messages that can be stored in a DICOM message within a sequence of items DICOM files are specialized DICOM messages that contain additional file meta information and are written to or read from interchangeable media
210. sizeof conceptNameMeaning if status MC_NORMAL COMPLETION printf MC SRH Get CODE Data Eror code d status return printf 5 conceptNameMeaning Reading information about the next child node status MC SRH Get Next Child srID amp childID amp relationship amp nodeType amp isLast if status MC NORMAL COMPLETION printf MC SRH Get Next Child Eror code d status return Second child expected to be the TEXT item if nodeType SR NODE TEXT Print concept code text value status MC_SRH_Get_Concept_Name childID conceptNameValue sizeof conceptNameValue conceptNameScheme sizeof conceptNameScheme conceptNameMeaning sizeof conceptNameMeaning if status MC_NORMAL COMPLETION printf MC SRH Get Concept Name Eror code d status return printf s conceptNameMeaning status MC SRH Get TEXT Data childID strBuffer sizeof strBuffer if status MC NORMAL COMPLETION printf MC SRH Get TEXT Data Eror code d status return printf Ss n strBuffer Reading information about the next child node status MC_SRH_Get_Next_Child srID amp childID amp relationship amp nodeType amp isLast if status MC NORMAL COMPLETION M RGE Healthcare 123 Merge DICOM Toolkit Check platform notes for Unicode support User s Manual printf MC SRH Get Next Child Eror code d status return
211. ss error here return Skipping Row 2 and 3 of the template and encoding Row 4 The code is taken from the CID 7012 status MC SRH Add CODE Child srID SR REL HAS CONCEPT MOD 113011 DCM Document Title Modifier 113015 DCM Series amp childID if status MC NORMAL COMPLETION process error here return Skipping Row 5 and 6 of the template and encoding Row 7 The code is taken from the CID 7012 The text value shall describe the image selection status MC SRH Add TEXT Child srID SR REL CONTAINS 113012 DCM Key Object Description Doctor s comments on selection amp childID if status MC NORMAL COMPLETION process error here return Adding an IMAGE from Row 8 The values 1 2 3 4 1 1 2 3 4 5 1 suppose to be an image SOP Class and SOP Instance status MC SRH Add IMAGE Child srID SR REL CONTAINS 19233901 13233342531 echildi if status MC NORMAL COMPLETION process error here return Convert SR to the message A status MC SR To Message srID if status MC NORMAL COMPLETION process error here return Add other root lvel attributes The error handling is skipped here in order to make a compact code Please add eeror handling if you use it 120 M RGE Healthcare Merge DICOM Toolkit User s Manual Set file meta informatio
212. ssage and supply you with powerful message validation features Mc3media h contains the functions used to create and maintain DICOM files and the DICOMDIR directory of a DICOM file set Mcstatus h specifies functions that allow your application to interpret the status codes returned from DICOM Toolkit calls Finally diction h supplies useful defines with descriptive names for all the DICOM Tags you might refer to in your applications Your application must include these header files to make use of the appropriate toolkit library functionality Merge DICOM Toolkit Library The Merge DICOM Toolkit Library usually named mc3adv a or mc3adv 1ib is the object code library for your computing platform that you link into your DICOM application This library services your calls to the DICOM Toolkit In the process of servicing networking calls the DICOM Toolkit requires the services of a Berkeley Sockets or WinSock Library for your platform If you are performing any DICOM network operations this sockets library must also be linked with your application Finally if you are using the library to maintain a DICOM file set you may need a special purpose library to interface with your media storage device The Merge DICOM Toolkit library has been carefully designed to be re entrant and has been validated to be thread safe on several multi threading capable platforms Note however that with only a few exceptions Merge DICOM Toolkit assumes that object
213. ssociation over which you wish to read the message The MessagelID returned to you identifies the message received The messages Service and Command are also returned to your application to aid it in further processing The other important parameter in an Read Message callis Timeout Timeout specifies in seconds how long your process will wait for a message before the Read Message call times out and returns control to your application code If your application is running in a multi tasking environment your process will be blocked during this waiting period and the system processor will be available for other processes Setting Timeout to 0 is equivalent to polling since MC Read Message returns immediately whether a message has been received or not A Timeout of 1 indicates wait forever or until a message arrives before returning In specialized cases where the application reading the request or response message is waiting on several asynchronous events not just the message event the MC Get Association Info callcan be used to get the file descriptor for the socket over which message exchange will occur The select system call can then be used to wait asynchronously for a DICOM request or response message When select returns on the DICOM message file descriptor MC Read Message can be called and will return immediately with the received message M RGE Healthcare Merge DICOM Toolkit Asynchronous def
214. status MC NORMAL COMPLETION BadStatus status serviceList 0 CT JPEG serviceList 1 CT DEFAULT serviceList 2 0 status MC NewProposedServiceList TEST LIST1 serviceList if status MC NORMAL COMPLETION BadStatus status In this example NewSyntaxList is used to create a transfer syntax list This routine is passed an array transfer syntaxes that are placed in the list and the user specifies a name for the syntax list Similar to the creation of syntax lists in the application profile the order in which transfer syntaxes are defined in the list dictates the priority Merge DICOM Toolkit places on the transfer syntaxes when negotiating an association The MC NewServiceFromName routine is used to create individual services within a service list Each service in a dynamic service list must be created in this way The MC NewProposedServiceList routine can then be used to create a new service list consisting of services created with NewServiceFromName It is passed an array of pointers to the names of services to be contained in the service list In addition to these functions Merge DICOM Toolkit supplies a number of other routines for freeing service lists that are created dynamically and for creating service lists Please reference the Merge DICOM Toolkit Reference Manual for further details on these functions Message Objects Merge DICOM Toolkit suppl
215. syntax are still stored as message objects while the toolkit is handling them Only when a message is streamed is the message deflated inflated M RGE Healthcare Merge DICOM Toolkit Sending Messages M RGE User s Manual Message Exchange Network Only General We have discussed how associations are managed as well as how messages objects are populated and parsed Now we discuss how these DICOM messages are exchanged with other application entities over the network The exchange of DICOM messages between AE s only occurs over an open association After the DICOM client SCU application opens an association with a DICOM server SCP the client sends request messages to the server application For each request message the client receives back a corresponding response from the server The server waits for a request message performs the desired service and sends back some form of status to the client in a response message This process along with the corresponding Merge DICOM Toolkit Function calls are pictured in Figure 12 Request Message MC_Send_Request_Message DICOM DICOM MC_Read_Message Client Open Association Server MC Read Message Send Response Message Response Message Figure 12 Message Exchange in Merge DICOM Toolkit Applications These three calls have the following form status MC Send Request Message AssociationID RequestMessageld status MC
216. t instances where each object instance can also contain attributes that have a VR of SQ This powerful capability allows the nesting of objects or the definition of container objects such as folders film boxes directories etc One can think of these nested objects as message objects minus the command portion Figure 15 shows a DICOM message containing a sequence of items running two levels deep Note that these nested sequences are contained within the same Message Stream Sequences of items can also be contained in a DICOM file and we will see that they are contained in DICOMDIR s An attribute whose value is a sequence of items is simply an attribute that has a potentially large and complex value Fortunately Merge DICOM Toolkit allows your application to deal with sequences of items an item at a time and hierarchically as pictured in Figure 15 and takes care of the encoding of the sequence within the DICOM message stream 83 Merge DICOM Encoding and decoding attributes in an item Toolkit User s Manual SQ Attribute Command Object Instance eee DICOM Message SQ Attribute Item 1 Item 2 Item 1 Sequence of Items Sequence of Items Command Attribute an Object Instance Attribute Figure 15 A DICOM Message containing doubly nested sequences of items Each item object in a sequence is a special class or subclass in object oriented terminology of a message object All the message building and parsing
217. tem into a sequence status MC Open Item amp itemID PREFORMATTED GRAYSCALE IMAGE if status MC NORMAL COMPLETION printf Unable to open request message n printf Nt sMn MC Error Message status return 1 status MC Set Value From String itemID MC ATT PIXEL ASPECT RATIO 1 if status MC NORMAL COMPLETION printf MC Set Value From String failed n printf Nt sWMn MC Error Message status MC Free Item amp itemID return 1 status MC Set Next Value From String itemID PIXEL ASPECT RATIO 1 if status MC NORMAL COMPLETION printf MC Set Value From String failed n printf Nt sWMn MC Error Message status M RGE Healthcare 85 Merge DICOM Toolkit User s Manual MC Free Item amp itemID return 1 callbackInfo messageID itemID encode other item attributes here now encode the item into the sequence Status MC Set Value From Int messageID MC ATT PREFORMATTED GRAYSCALE IMAGE SEQUENCE itemID if status MC NORMAL COMPLETION printf MC Set Value From Int failed n printf Nt sWMn MC Error Message status MC Free Message amp messageID MC Free Item amp itemID return 1 This excerpt is taken from the sample print application suppli
218. thcare Merge DICOM Toolkit The DICOMDIR hierarchy M RGE Healthcare User s Manual The DICOMDIR The DICOM Directory File or DICOMDIR is a special type of a DICOM File A single DICOMDIR must exist within each DICOM file set and is always given the file ID DICOMDIR Itis the DICOMDIR file that contains identifying information about the entire file set and usually dependent on the Application Profile a directory of the file set s contents Figure 8 shows a graphical representation of a DICOMDIR file and its central role within a DICOM File Set DICOM File Set DICOM DIR File File Set Identification Root Dir Entity 1 1 1 Print Queue Dir Records Film Session DICOM Files Print Queue Dir Entities 1 Basic Grayscale or Color t Basic Image Box Dir Image DICOM Files Figure 8 A DICOM Directory File DICOMDIR within a DICOM File Set If the DICOMDIR file contains directory information it is composed of a hierarchy of directory entities with the top most directory entity being the root directory entity A Directory Entity is a grouping of semantically related directory records A Directory Record identifies a DICOM File by summarizing key attributes and their values in the file and specifying the file ID of the corresponding file The file ID can then be used in the context of the native file system to access the corresponding DICOM file Each directory record
219. the message type and can be found in our message txt file can be assigned to the message or file e When adding an attribute that has not been defined for a message MC Add Standard Attribute can be called to add the tag to the definition of the message Subsequent calls to the MC Set Value functions will then allow the user to assign the attribute How encode tags in a message that are invalidly encoded according to DICOM When call the MC Set Value From String it does not return MC NORMAL COMPLETION The Set Value From String function s return values for invalid DICOM encoding are actually warning return values and not failures When MC INVALID 5 IN VALUE and MC INVALID VALUE FOR VR are returned the value is still encoded It is a common mistake in Merge DICOM Toolkit applications for it to fail when Set Value From String returns value other than MC NORMAL COMPLETION lf desired the above return values can be ignored and treated as normal completion M RGE Healthcare Merge DICOM Toolkit M RGE User s Manual Appendix B Unique Identifiers UIDs UIDs provide the capability to identify many different types of items The purpose of UIDs are to guarantee the uniqueness of these different types of items DICOM uses UIDs to uniquely identify items such as SOP classes image instances and network negotiation parameters Part 5 Section 9 along with Annexes B and C
220. this set is extended by an application with another term such as IN PROCESS it should be documented in that application s conformance statement The most important characteristic of an attribute that is specified on a message by message basis is the Value Type VT The VT of an attribute specifies whether or not that attribute needs to be included in a message and if it needs to have a value Attributes can be required optional or only required under certain conditions conditional attributes Conditional attributes are always specified along with a condition The value types defined by DICOM are listed in Table 4 Note that a null valued attribute has a value that value being null zero length 21 Merge DICOM Toolkit Odd groups are private 22 User s Manual Table 4 DICOM Value Types VT s Value Type VT Description The attribute must have a value and be included in the message The value cannot be null empty The attribute must have a value and be included in the message only under a specified condition The value cannot be null If that condition is not met the attribute shall not be included in the message The attribute must have a value and be included in the message only under a specified condition If the value for the attribute is unknown and cannot be specified its value shall be null If that condition is not met the attribute shall not be included in the message The attribute is optional It may or m
221. tive to the location of the merge ini file testing the sample applications for the first time and cannot get the client SCU application to connect to the server SCP for any of the sample applications The MC Open Association function is returning MC SYSTEM ERROR It appears as though the connection is opening but it is quickly dropped Why is this happening As a security measure the MC Wait For Association function used in SCPs attempts to determine the hostname of SCUs connecting to it If it cannot determine the remote hostname it will drop the connection The MC Wait For Association function uses the local system s host file or its configured domain name server to translate the SCU s IP address into its hostname By configuring the SCU s hostname in your local hosts file this problem will be eliminated Also the ACCEPT ANY HOSTNAME configuration value in the mergecom pro file disables this checking What can be done to reduce the memory requirements of the Merge DICOM Toolkit There are several methods for reducing the memory requirements of Merge DICOM Toolkit The first method is to use either the Open Empty Message Create Empty File functions when creating message and file objects These functions reduce memory by not reading in all of the information needed for validation of messages and files respectively These functions will also improve performance There are several configurat
222. tribute s value arrives on an association during an MC Read Message call By the time the MC Read Message returns to the application the attribute value will already have been handled by your registered Callback Function The Callback Function could be used by the server to treat this large block of OB OW data usually pixel data specially e g store in a frame buffer filter through decompression hardware write to disk without any overhead introduced by the message object A client SCU application can call MC Register Callback Function to register a Callback Function that will be called repetitively as the attribute s value is transmitted over an association during an MC Send Request Message or MC Send Response Message call During either of these calls the attribute value will be handled by your registered Callback Function before these calls can return to your application The Callback Function can also be used by the client to specially manage OB OW data e g read from a frame buffer filter through compression hardware or software read from disk without any overhead introduced by the message object Callback Functions can also be used in other situations through the use of MC Set Message Callbacks Normally Callback Functions are associated with a message or file when a Merge DICOM Toolkit function contains an application ID as a parameter or when an association ID is associated with an appl
223. uest for Registration application form along with a fee as of August 1996 the fee is 1 000 to the Registration Coordinator The Request for Registration application form can be obtained from ANSI by use of the following information American National Standards Institute 11 West 42 Street New York New York 10036 TEL 212 642 4900 FAX 212 398 0023 M RGE Healthcare Merge DICOM Toolkit User s Manual Appendix C XML structure The Merge DICOM Toolkit provides an API to convert a DICOM message file or item into an XML string The basic structure of the XML string created from a DICOM message by the MC_Message_To_XML API looks like the following XML structure with the Base64 encoding of bulks and attributes with VR UN lt xml version 1 0 encoding utf 8 gt DcmFile FileMetaInfo Service STANDARD SEC CAPTURE Command C STORE RQ Attribute Tag 00020001 VR OB Name File Meta Information Version Length 2 gt AAE lt Attribute gt Attribute Tag 00020002 VR UI Name Media Storage SOP Class UID Length 25 gt lt Attribute gt Attribute Tag 00020003 VR UI Name Media Storage SOP Instance UID Length 29 gt lt Attribute gt lt Attribute Tag 00020010 VR UI Name Transfer Syntax UID Length 19 gt 1 2 840 10008 1 2 1 lt Attribute gt Attribute Tag 00020016 VR AE Name Source Application Entity Title Length 15 gt MERGE_STORE_SCP
224. umber of Unicode characters enable Unicode conversion library FIRST only need to do once in your application status MC Enable Unicode Conversion 1 if status MC NORMAL COMPLETION printf failed to initialize Unicode library n Status MC Set Value From UnicodeString msgID MC PATIENT NAME inputLen inputStr if status MC NORMAL COMPLETION printf failed to set str n example of MC_Get_Value_To_UnicodeString int msgID assigned elsewhere when message was created int rawLen MC_UChar outputStr MC_size_t outputBufferSize int outLen actual number of Unicode characters produced excluding U 0000 terminator enable Unicode conversion library FIRST only need to do once in your application status MC Enable Unicode Conversion 1 if status MC NORMAL COMPLETION printf failed to initialize Unicode library n get raw attribute length status MC_Get_Value_Length msgID MC ATT PATIENT NAME 1 value index starts from 1 amp rawLen if status MC NORMAL COMPLETION printf failed to get length n create sufficent output buffer outputBufferSize rawLen 1 sizeof MC UChar add 1 for the U 0000 terminator outputStr malloc outputBufferSize Status MC Get Value To UnicodeString msgID MC PATIENT outputBufferSize amp outLen outputStr M RGE 127 Healthcare M
225. ure remote nodes at run time The following example illustrates how MC_Open_Association can be used to specify remote node information MC_STATUS mcStatus int applicationID int associationID char remoteAE 64 2 char remoteHostname 100 char serviceList 100 int remotePort strcpy remoteAE MERGE STORE SCP strcpy remoteHostname myhost merge com strcpy serviceList Storage Service List remotePort 104 mcStatus MC Open Association applicationID amp associationID remoteAE amp remotePort remoteHostname serviceList Note that the service list used to negotiate with the remote node still must be pre configured It is assumed that the services supported by an SCU application are predetermined UN VR DICOM Supplement 14 Unknown Value Representation became a part of the DICOM standard on June 3 1997 This supplement adds a new value representation UN to the DICOM standard It was developed to fix two related holes in the DICOM standard When standard or private attributes were received in an implicit value representation VR transfer syntax and the user does not have a knowledge of the VR of the attributes there is no way to represent the VR for these attributes in an explicit VR transfer syntax M RGE Healthcare Merge DICOM Toolkit M RGE Fiealthcare User s Manual Every time a new VR is added to the standard there is no way to determine if the len
226. uring normal synchronous operations there typically is no network activity while a Storage SCU waits for a response message from an SCP Because there is a time when no data is being sent from the SCU to the SCP a network is typically underutilized by synchronous DICOM transfers Also sending a large number of small images typically is slower than sending a smaller number of large images because a higher percentage of the association time is spent waiting on response messages Figure 13 illustrates how an SCU waits on a response from the SCP while the SCP processes a message 71 Merge DICOM Toolkit 72 User s Manual SCU SCP CLP Read Request Msg 1 Send Request Msg 1 2 r Process Request Msg 1 Read Response Msg 1 4 J Send Response Msg 1 Send Request Msg 2 Read Request Msg 2 2 r Process Request Msg 2 Read Response Msg 2 r Send Response Msg 2 Figure 13 Timing of Message Exchange During Synchronous Transfers When asynchronous operations are negotiated the SCU can poll for a response message but if a message is unavailable it can start sending the next request message right away if the max operations will not be exceeded This allows an SCU to more fully utilize the network bandwidth There is only a small time when the SCU polls for a response message during which data is not being sent from the SCU to the SCP The majority of changes required to implement asynchronous communications are
227. used along with s 1 Optional list and select possible service command pairs m Optional specify the input file as being a DICOM file object q Optional disable prompting for correct service command pairs E Specify transfer syntax of message where syntax il implicit little endian el explicit little endian or eb explicit big endian This command validates the specified message file printing errors warnings and information generated to standard output The user can force the message to be validated against a specified DICOM service command pair if the message does not already contain this information 38 M RGE Healthcare Merge DICOM Toolkit Limitations DICOM Message Generation Tool User s Manual If the service command pair is not contained in the message the program will list the possible service command pairs and the user can select one of them When using this program with a batch file this option can be shut off with the q flag The default transfer syntax is implicit little endian the DICOM default transfer syntax If the transfer syntax is incorrectly specified the message cannot be validated While mc3valid s message validation is quite comprehensive it does have limitations These limitations are discussed in detail in the description of the MC Validate Message function in the Reference Manual The DICOM Standard should always be considered the final authority
228. ve useful when running into difficulties communicating with other implementations of DICOM over a network and can be used by Merge service engineers in diagnosing lower level network problems See the Appendix B Configuration Parameters of the Reference Manual for details on Toolkit s configuration Message Logging Merge DICOM Toolkit supplies a message logging facility whereby three primary classes of messages can be logged to a specified file and or standard output e Errors e Warnings e Status Error messages include unrecoverable errors such as association aborted or failure to connect to remote application Other error messages may be catastrophic but it is left to the application to determine whether or not to abort an association such as an invalid attribute value or missing attribute value in a DICOM message Warnings are meant to alert toolkit users to unusual conditions such as missing parameters that are defaulted or attributes having values that are not one of the defined terms in the standard Status messages give high level messages describing the opening of associations and exchanging of messages over open associations As discussed earlier other more detailed logging can be obtained by using the T1 MESSAGE through T9 MESSAGE logging levels For example the T5 MESSAGE logging level can be used to log the results of an MC Validate Message call see the Reference Manual
229. very networking ere your 7 application takes service is built from In the context of a particular Service these primitive actions over translate to explicit real world activities on the part of an Application Entity Hence DICOM places requirements on an application implementing a DICOM service DICOM is careful to only express high level operational requirements and leaves the creative detail and look and feel of the application entity to the developer commands are referred to as DIMSE Services in the DICOM Standard M RGE 17 Healthcare Merge DICOM Toolkit User s Manual Request vs For every command there is both a request and a response A command request response indicates that a command should be performed and is usually sent to an SCP A command response indicates whether a command completed or its state of completion and is usually returned to an SCU Example request commands are C STORE RQ N GET RQ and N SET RQ Example response commands are C STORE RSP N GET RSP and N SET RSP IMPORTANT It is important to note that this service definition level is where the Merge DICOM Toolkit Library leaves off and your Application begins While Merge DICOM Toolkit supplies sample application guides and running sample application source code for your platform they are only supplied as an example They clearly explain the requirements that implementing certain DICOM services places on your application a
230. vides the DICOM Toolkit with its top level configuration It specifies the location of the other three configuration files along with message and error logging characteristics There are two options to access the merge ini file for your runtime environment The function Set MergeINI canbe used to assign the path where the merge ini file is located You can also set the MERGE INI environmental variable to point to the Merge Initialization File This variable can be set within a command shell for example In Unix C shell setenv MERGE INI users mc3adv merge ini In Unix Bourne Korn or Bash shell MERGE_INI users mc3adv merge ini export MERGE INI In DOS command shell set MERGE_INI mc3adv merge ini See the Platform notes for your platform if none of these methods apply M RGE Healthcare Merge DICOM Toolkit M RGE Fiealthcare User s Manual The initialization file contains one MergeCOM3 section that points to the location of the other three Merge DICOM Toolkit initialization files specifies characteristics of the message error log kept by the DICOM Toolkit library turns particular types of logging on and off and specifies where the messages are logged file screen both or neither In most cases the INFO WARNING and ERROR messages will be sufficient The MESSAGE settings where n is an integer between 1 and 9 turns on lower level protocol tracing capabilities These capabilities can pro
231. was designed to be portable and is available for many platforms e g Sun Solaris 8 Sparc Sun Solaris 10 Intel Linux Windows XP Vista 7 MacOS X If it is not currently available for your target platform please contact Merge Healthcare We may already be working on the port Once on a supported platform you will need an ANSI C compiler along with the Standard C Libraries You will also need a Berkeley Sockets or WinSock for Windows 95 98 NT 2000 2003 XP Library for interfacing to TCP IP and a linker to link your application with the libraries In the case of the MacOS version of the toolkit no additional socket libraries are needed Your development environment or at a minimum your target environment should run on a machine with a network interface over which you can run the TCP IP protocol The DICOM Toolkit library supplies you with the DICOM protocol that runs on top of TCP IP If your application will write DICOM files to interchangeable media you will need a device driver for the media storage device and a programming interface between your operating system and the file system on that device More specific requirements can be found in the Platform Notes pamphlet specific to a platform This could include supported OS versions supported compilers and linkers and required compiler build options Library Structure Understanding the organization and components of the Merge DICOM Toolkit Library is important to developing an effi
232. y may contain escape sequence int numberOfByte 1 set to 1 if input is NULL terminated or set it to exact number of input bytes MC UChar uChars output int outputBufferSize int outLen to receive the exact number of Unicode characters produced excluding terminator enable Unicode conversion library FIRST only need to do once in your application status MC Enable Unicode Conversion 1 if status MC NORMAL COMPLETION printf failed to initialize Unicode library n sufficent buffer to hold output each input byte can produce one MC UChar outputBufferSize numberOfByte 1 sizeof MC UChar add 1 for terminator U 0000 126 M RGE Healthcare Merge DICOM Toolkit User s Manual uChars malloc outputBufferSize convert from DICOM character set to Unicode status MC_Byte_To_Unicode firstCharset bytes numberOfByte outputBufferSize amp outLen uChars if status MC BUFFER TOO SMALL printf fail because buffer too small increase output buffer size n else if status MC NORMAL COMPLETION printf failed to convert n Below is an example usage of the Set and Get functions example of MC Set Value From UnicodeString int msgID assigned elsewhere when message was created MC UChar inputStr assigned elsewhere as the input Unicode source int inputLen 1 if input is U 0000 terminated or set to exact n
233. y is not enabled on all platforms Please check the platform notes to be sure that Merge DICOM Toolkit is thread safe on your platform There are some assumptions however concerning the thread safety of Merge DICOM Toolkit In most cases it is assumed that a Merge DICOM Toolkit object is only accessed from one thread at a time This applies to Message objects file objects item objects and association objects Note however that different instances of an object can always be manipulated in different threads at the same time There are exceptions to this rule however The following is a summary of them The MC Abort Association function call can be called when Merge DICOM Toolkit is working on an association in another thread The MC Send Request Message MC Send Response Message MC Read Message MC Close Association and MC Abort Association functions can all be used in one thread while another thread is calling MC Abort Association Within another thread This is useful when allowing a user to asynchronously cancel an in progress association It is also possible to access tags within a message as it is being read from the network It is possible to call the Set Value MC Set pValue Get Value and MC Get pValue routines from one thread while another thread is calling the Read Message Tag MC Continue Read Message MC Continue Read Message to Stream routines or when these routines are us

Merge DICOM Toolkit™ C/C++ User`s Manual v

Contents

Download Pdf Manuals

Related Search

Related Contents

Merge DICOM Toolkit&trade; C/C++ User`s Manual v

Contents

Download Pdf Manuals

Related Search

Related Contents

Merge DICOM Toolkit™ C/C++ User`s Manual v