Home

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

1. HHEPFHEREEERES EEE REESE HERE HEE ERE HEHE HEE HEHE HEHE HEHE HEH HE FH DETACHED PATIENT MANAGEMENT N_GET_RSP PAAA ARAARA RARA REE EEE ERE ERE ERE HEE HEE HEHE HEHE HEHE HEHE HEHE HH 0008 0005 Specific Character set Cs TC 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 SQ 2 Item Name s REF_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 CS 2 Enumerated Values M F O 0010 0050 Patient s Insurance Plan Code Sequence SQ 3 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
2. The path of the profile file is config mergecom pro relative to the location of the merge ini file Lam 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 MC_Open_Empty_Message or MC_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
3. 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 HDR3 AMR62 that will be given to the new object STANDARD_MR is the service name and C_STORE_RQ is the command name identifying the class of file object being created see Table 5 It is important to realize that Mc_Create_File _ does not create the physical DICOM file out on the media the MC_Write_File call described later does that MC_Create_File corresponds to the MC_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 aMC_Create_Empty_File available for media interchange 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 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
4. is used to delimit the values A default value listed as NULL means the attribute is set to NULL If the filename specified already exists it will be written over 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 lt filename gt 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 lt sy
5. 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 s tError on MC_Write_File n prefix printf s t t s n prefix MC_Error_Message status return status MC_Free_File amp filelID Free 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 set to 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 YourToMediaFunction M RGE Healthcare Merge DICOM Toolkit Performance Tuning M RGE Healthcare User s Manual The parameters for this callback function must agree with the following prototype static MC_STATUS FileToMedia char filename void userinfo int dataSize void dataBuffer int 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
6. This option determines if Merge DICOM Toolkit encodes 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 e 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 7 Which of the options listed above have the greatest impact on network performance e 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 e EXPORT_UNDEFINED_LENGTH_SQ can have a large impact if many sequence attributes are included in the message being transferred 130 M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare 8 10 User s Manual l am 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 bi
7. 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 MC_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 M RGE D Healthcare Merge DICOM Toolkit User s Manual R Object ID M ject ID Message _ Obie ecr Ee EH __ SR Content Ohiect Item node Attributes Gantant SR Content SR Content SR Content Omen Item node Item node Item node Seauence Item i Ohiect SR Content Item node Attribu ltem l Ohiect Attri ltem SE mena Cont Attributes Seat 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 MC_Duplicate_Message will not work on the messages mapped with the SR object 114 M RGE Healthcare Merge DICOM Toolkit User s Manual Overview of the Merge DICOM Toolkit SR functions The Merge
8. BPD 5mm INFERRED FROM SCOORD SELECTED FROM SR_REL_SELECTED_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 107 Merge DICOM Toolkit 108 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 Root Content Item ID Se Content Item ID 01 02 Content Item ID Content Item ID 01 01 01 01 01 02 Figure 19 SR Item Identifier Content Item ID 0101 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
9. Itis composed of several annexes describing the use of the standard Part 18 specifies a web based service for accessing and presenting DICOM persistent objects 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 Message Exchange Part 7 we Encoding Parts 5 amp 6 Session amp Presentation DICOM Upper Layer ee D 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 a user 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
10. 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 ak status MC_SRH_Get_First_Child srID amp childID amp relationship amp nodeType amp isLast 120 M RGE Healthcare Merge DICOM Toolkit User s Manual if status MC_NORMAL COMPLETION printf MC_SRH_Get_First_Child Eror code d 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 Ss conceptNameMeaning status MC_SRH_Get_CODE_Data childID conceptNameValue sizeof conceptNameValue conceptNameScheme sizeof conceptNameScheme conceptNameMeaning sizeof conceptNameMeaning if status MC_NORMAL COMPLETION printf MC_SRH_Get_CODE_Data Eror code d status return
11. Patient Study SR Document Series Frame of Reference Synchronization General Equipment 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 d
12. attribute can be set to zero length in Merge DICOM Toolkit with MC_Set_Value_To_NULL e The MC_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 of MC_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 131 Merge DICOM Toolkit 132 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 am 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 MC_INVALID_TAG How can add this attribute e This problem occurs when using MC_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
13. there is no way to determine if the length 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 PAC
14. 6920 for lossless Table 21 details the photometric interpretation and bit depths supported by the standard compressor and decompressor for this transfer syntax M RGE 77 Healthcare Merge DICOM Toolkit SPECIAL NOTES Merge DICOM Toolkit can update group 0x0028 for you 78 User s Manual Table 21 JPEG 2000 Lossless Supported Photometric Interpretations and Bit Depths JPEG 2000 Lossless Photometric MONOCHROME 1 YBR_RC RGB Interpretation MONOCHROME2 T SERIES GE Se fe e ee When using the standard compressor all data 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 Y1Y2B1R1 Y3Y4B3R3 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_J2K_USE_LOSSY Yes Lossy color transform for lossy compression YBR_RCT if JPEG_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 M
15. DICOM Toolkit has several types of functions that can be used for reading writing Structured Report lODs 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 e Cap Add Boot Creates a new SR root object and maps it to the existing message object H C_Message_To_SR Creates SR tree structure from the message and maps each SR Content Item with the corresponding message item e C_SR_Add_Child Creates a new SR Content Item and maps it to the existing message item e C_SR_Get_First_Child Retrieves the first child Content Item object ID e C_SR_Get_Next_Child Retrieves the next child Content Item object ID D C_SR_Delete_Child Deletes a child Content Item e Cap 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 e C_SRH_Create_SR Creates an empty SR root object e C_SRH_Add_Type_Child Adds
16. 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 single 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 102 M RGE Healthcare Merge DICOM Toolkit User s Manual 1 Content Item Note A Content Item may contain either Observation Context or other content Figure 18 SR Information Model Each Content Item contains the following e A name value pair consisting of o a single Concept Name Code that is the name of a name value pair or a heading and o avalue text numeric code etc e References to images waveforms or other composite objects with or without coordinates e 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 T
17. Only those attributes that have been defined for 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 can I 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 MC_Set_Value_From_String function s return values for invalid DICOM encoding are actually warning return values and not failures When MC_INVALID_CHARS_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 MC_Set_Value_From_String returns a value other than MC_NORMAL_COMPLETION If desired the above return values can be ignored and treated as normal completion M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare 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 a
18. 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 While Merge DICOM Toolkit s validation is not foolproof it is very useful and will catch many standard violations It validates the following e That the value assigned to an attribute is appropriate for that attributes VR e That all value type 1 attributes have a value and that value is not null 62 M RGE Healthcare Merge DICOM Toolkit and what validation cannot do for you An example M RGE Healthcare User s Manual That all value type 2 attributes have a value and that value may be null 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 That an attribute does not have too many or too few values for its specified value multiplicity 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 That a non priva
19. 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 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 101 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
20. Toolkit The MC_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 large 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 toa DICOM tag These value representations are used to store image data or other large data elements MC_Set_Value_From_Function is described in further detail elsewhere in this manual Data can be passed to Merge DICOM Toolkit via Mc_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 will allocate 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_Funct
21. 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 FILM 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 SQ 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 Encoding items in To encode an item into an attribute of Value Representation SQ treat the attribute as a sequence a multi valued integer where each value is an ItemID This means using the MC_Set_Value_From_Int andMC_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 and MC_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 Item into a sequence status MC_Open_Item amp itemID PREFORMATTED_GRAYSCALE_IMAGE if status MC_NORMAL_COMPLETION printf Unable to open request message n M RGE 83 Healthcare Merge DICOM Toolkit User s Manual printf t s n return 1 MC_Error_Message status status MC_Set_Valu MC_ATT_PIXEL_ ASP From_String item
22. 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 application 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 MC_Write_File_By_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 MC_Register_Callback_Function The users 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 e 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 effici
23. as reference in conditions The Row Number of a Content Item 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 109 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
24. being supplied The length is passed in using CbdataSizePtr CbdataBufferPtr 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 PROVIDING_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 e when
25. 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 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 sample DICOM File Service application is 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 m
26. in the description of the MC_Validate_Message function in the Reference Manual The DICOM Standard should always be considered the final authority 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 can be validated or listed with the mc3list and mc3valid utilities The command syntax for mc3 file is the following mc3file lt serv gt lt cmd gt lt num gt 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 u
27. 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 CBdataSizePtr 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 80 M RGE Healthcare Merge DICOM Toolkit User s Manual Value of Cbtype Required Callback Behavior PROVIDING_DATA_LENGTH Callback is receiving OB OW OF data and the length of the entire value for this attribute is
28. 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 M RGE 81 Healthcare Merge DICOM Toolkit Encoding and decoding attributes in an item 82 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 object 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 mi
29. it is waiting for this information It is recommended that MC_Wait_For_Connection be used for any new applications being 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 sta
30. 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 As an example the Root directory 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 91 Merge DICOM Toolkit DICOMDIR s are ugly But we pretty them up Navigating through a DICOMDIR 92 User s Manual 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
31. lt Attribute Tag 00091015 VR UN Name Private PCode SAMPLE 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 135 Healthcare Merge DICOM Toolkit User s Manual lt Attribute Tag 7FE00010 VR OW Name Pixel Data Encoding Base64 Length 262144 gt HQAABgMAAATHBAM lt DataSet gt lt DemFile gt 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 lt DcemFile gt lt FileMetaInfo Service STANDARD_SEC_CAPTURE Command C_STORE_RQ gt lt Attribute Tag 00020001 VR 0B Information Version Length 2 gt lt Attribute Tag 00020016 VR AE ame File Meta 00 01 lt Attribute gt ame Source Application Entity Title Length 15 gt MERGE _ STORE_SCP lt Attribute gt lt FileMetaInfo gt lt DataSet Service STANDARD_SEC_CAPTURE Command C_STORE_RQ TransferSyntax 1 2 840 10008 1 lt Attribute Tag 00080008 VR CS Length 24 gt ORIGINAL SECONDARY O lt Attribute Tag 00080016 VR UI Length 25 gt 1 2 840 10008 5 1 4 lt Attribute Tag 00081111 VR SoQ Performed Procedure Step Sequenc Zelts ame Image Type HER lt Attribute gt ame
32. managed SOPs in the DICOM standard M RGE Healthcare Merge DICOM Toolkit User s Manual Networking Certain aspects of DICOM only apply to networking when using the DICOM Toolkit This includes networking commands and association negotiation Commands DICOM defines a set of networking commande 7 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 instan
33. may do so by submitting a Request 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 lt DcemFile gt lt FileMetaInfo Service STANDARD_SEC_CAPTURE Command C_STORE_RQ gt lt Attribute Tag 00020001 VR 0OB Name File Meta Information Version Length 2 gt AAE lt Attribute gt lt Attribute Tag 00020002 VR UI Name Media Storage SOP Class UID Length 25 gt lt Attribute gt lt 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 lt Attribute Tag 00020016 VR AE Name Source Applicat
34. 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 uae DICOM Client Open Association Serv r MC_Read_Message MC_Send_Response_Message MC_Read_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_Send_Response_Message AssociationID ResponseStatus ResponseMessagelID status MC_Read_Message AssociationID Timeout amp MessagelID amp ServiceName amp Command The parameters to the MC_Send_Request_Message and MC_Send_Response_Message include an AssociationlID identifying the open association over which the message is to be sent and a MessagelID identifying the message object to be sent The MC_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 M RGE Healthcare Merge DICOM Tool
35. 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 syntax are still stored as message objects while the toolkit is handling them Only when a message is streamed is the message deflated inflated 67 Merge DICOM Toolkit Sending Messages 68 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
36. received a message object use the MC_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 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 User s Manual 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 MC_Get_Next_Value Gets the next value of a multi valued attribute in a messa
37. tag lx error Sait error_info gt Tag MC_Error_Message error_info gt Status 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_Level11 that reports only errors Validation_Level2 could be used to report both warnings and errors while Validation_Level13 could be used to report errors warnings and informational messages If the status returned is anything other than MC_MESSAGE_VALIDATES your application can look at the 63 Merge DICOM Toolkit User s Manual error_info structure passed back to decipher the violation error_info is defined as follows ij Structure containing Message Validation S 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 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 examp
38. the image and the icon_image will be sent as the negotiated unencapsulated transfer syntax 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 Message is compressed Icon is compressed Minor intervention is required Special creation of icon The only difference is MC_Set_Message_Transfer_Syntax sqID lt encapsulated transfer syntax gt must now be called upon creation of the ICON_IMAGE item so that you may register compression callbacks and utilize them M RGE Healthcare Merge DICOM Toolkit message txt can be very useful M RGE Healthcare User s Manual Reading from network a file or a stream No special conditions are required if the image is streamed in via MC_Open_File MC_Read_Message o0rMC_Stream_To_Message The sequence item automatically assumes EXPLICIT_LITTLE_ENDIAN if the pixel data contained in ICON_IMAGE is of defined length OR transfer syntax of the parent if the pixel data contained in ICON_IMAGE is of undefined length MC_Duplicate_Message If du
39. underlying file system M RGE Healthcare Merge DICOM Toolkit User s Manual DICOM Application Entity Association Negotiation Part 7 Annex D Information 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 Media Formats Part 8 and Physical M edia Part 12 Kev M erge Your ey 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 Manua
40. 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 Healthcare User s Manual larger than 28K Merge DICOM Toolkit will simply use the C functions malloc 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
41. 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 Merge DICOM Toolkit will encode supplied data in an encapsulated format and generate the basic offset table Merge DICOM Toolkit will provide data without the encapsulation delimiters The data can be compressed or decompressed using a registered compression callback Registration 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 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 Item Item Value ltem Item Item Value Sequenc Tag Length Tag Length Tag Length FFFE 0000 FFFE 0000 Compresse FFFE 0000 Compresse FFFE 0000 e 0000H E000 04C6H d F
42. 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 85 Merge DICOM Toolkit Performance Tuning 86 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 anAPI 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 DICOM file can be created a file object must be created The MC_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 EJ status MC_Create_File amp fileID fileName STANDARD_MR C_STORE_RQ
43. 1 status MC_Set_Value_From_String messagelID MC_ATT_NUMBER_OF_COPIES 1 if status MC NORMAL COMPLETION printf MC_Set_Value_From_String failed n printf t s n MC_Error_Message status 52 M RGE Healthcare Merge DICOM Toolkit Supplying pixel data User s Manual MC_Free_Message amp messagelID MC_Abort_Association amp associationID MC_Release_Application amp applicationID j return 1 Set other attributes here Wi status MC_Send_Request_Message associationID messagelID if status MC_NORMAL_COMPLETION printf MC_Send_Request_Message failed n printf t s n MC_Error_Message status MC_Free_Message amp messagelID MC_Abort_Association amp associationID MC_Release_Application amp applicationID return 1 void MC_Free_Message messagelID When setting the value of an attribute with a value representation of OB or OW eg 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 IsFirs
44. CID Document Title Name 113013 7012 Modifier DCM 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 n U E Context 7 gt CONTAINS TEXT EV 113012 DCM Key 1 U Object Description 8 gt CONTAINS IMAGE Purpose of Reference 1 n MC At least one of shall not be present Rows 8 9 and 10 shall be present 9 gt CONTAINS WAVEF Purpose of Reference 1 n MC At least one of ORM shall not be present Rows 8 9 and 10 shall be present 10 gt CONTAINS COMPO Purpose of Reference 1 n MC At least one of SITE shall not be present Rows 8 9 and 10 shall be present M RGE Healthcare 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 SZ 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 process error here return Skipping Row 2 and 3 of the template and encoding Row 4 The
45. C_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 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 M RGE Healthcare Merge DICOM Toolkit Server Callbacks Client Callbacks Other uses of Callbacks Use of empty messages require adding the pixel data taa M RGE 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 thes
46. 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 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 IPv6 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 appli
47. 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 M RGE Healthcare Merge DICOM Toolkit User s Manual 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 Ht Ha aE a EH HH HH OH EE EE aE aE aE aE EE HE HE EE A AE aE aE EE HE EEO EEE aE HE aE EE EEE EOE EE aE aE aE EE EE BASIC_FILM SESSION MN SEI BO Ht HE a a EH HH HH OH EE EE aE HEE EH HOE EEE EE aE aE HE HE HE EOE EEE EE aE EE EEE EOE EE AA Odd 0008 0005 Specific Character set cs 3 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 0012 Instance Creation Date DA 3 0008 0013 Instance Creation Time T 3 0008 0014 Instance Creator UID UI 3 0008 0016 SOP Class UID UI 3 0008 0018 SOP Instance UID
48. E C STORE C STORE C STORE M RGE Healthcare Service Command Enhanced Structured Reporting C STORE 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 RT Beams Delivery Instruction Storage C STORE M RGE 25 Healthcare 26 Service RT Beams Treatment Record Storage RT Br
49. EATED RECORDED TRANSCRIBED APPROVED for Interpretation Status ID 4008 0212 in Results Management services If 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 Viel 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 I
50. FAULT STANDARD_CT DEFAULT 0 1 48 M RGE Healthcare Merge DICOM Toolkit User s Manual if 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 MC_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 MC_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 M
51. File usually called merge ini provides 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 MC_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 Healthcare 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 Tn_MESSAGE settings where nis an integer between 1 and 9 turns on lower level protocol tracing capabi
52. ID ECT RATIO 1 if status MC_NORMAL COMPLETION printf MC_Set_Value_From_String failed n printf t s n MC_Error_Message status MC_Free_Item amp itemID return 1 MC_Set MC_ATT_PIX ext_Value_From_String itemID EL _ASPECT_RATIO 1 status LE status MC_NORMAL_COMPLETION printf MC_Set_Value_From printf t s n MG Error MC_Free_Item amp itemID return 1 String failed n essage status callbackInfo messageID itemID other item attributes here ncod now encode th item into the sequence MC_Set_Value_From_Int messagelID MC_ATT_PREFORMATTED_GRAYSCALE_IMAG status ENC itemID EQU r if status MC_NORMAL_COMPLETION printf MC_Set_Value_From_Int failed n printf t s n MC_Error_Message status MC_Free_Message amp messagelID MC_Free_Item amp itemID return 1 r This excerpt is taken from the sample print application supplied with Merge DICOM Toolkit See that application s code for further example of encoding and decoding of sequences of items 84 M RGE Healthcare Merge DICOM Toolkit You must interface with the selected media device M RGE Healthcare User s Manual DICOM Files Maintaining a DICOM file set is a matter of maintaining various DICO
53. INE 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 decompression limits The licenses can be configured in the mergecom pro configuration file 75 Merge DICOM Toolkit 76 User s Manual 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_FU
54. Intravascular Optical Coherence Tomography Image Storage For Processing 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 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 Services Description Lensometry Measurements
55. LL_422 data Table 17 JPEG Baseline Supported Photometric Interpretations and Bit Depths JPEG Baseline Photometric MONOCHROME1 RGB YBR_FULL_422 Interpretation MONOCHROME2 YBR_FULL Bits Stored Bits Allocated Samples Per Pixel 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 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 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 ws e ERD aenea e e e e fe M RGE Healthcare Merge DICOM Toolkit User s Manual The JPEG_LOSSLESS_HIER_14 transfer synta
56. M 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 Anolication Media MC_Create_File creates a file object MC_Open_File file object or MC_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 configurations 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
57. 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 In 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 391 May 2012 1 0 Updated bi annually Merge DICOM Toolkit User s Manual Contents Uvervlew ee 1 The DICOM Standard oe iesed age duiestettes esi a a a a 1 The Merge DICOM Toolkit aaccess e E 4 Development Platform Requirements cccccccceesecceeeeeeeseceecaeeeeeeeeese
58. 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 Standard 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
59. OM files contained in the file set Management of images through a query and retrieval mechanism based on a small number of key attributes Supports 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 Study Management Services Detached Patient Management Detached Visit Management Detached Patient Mgmt Meta Detached Study Management Study Component Management Modality Performed Procedure Step Description Creation and tracking of the subset of patient and patient visit information that is required to aid in the management of radiographic studies Creation scheduling performance and tracking of imaging studies 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 o
60. ON PRIVATE VISIT PRIVATE RESULTS INTERPRETATION PRIVATE INTERPRETATION PRIVATE STUDY COMPONENT PRIVATE FILM SESSION FILM BOX PRIVATE FILM BOX BASIC IMAGE BOX PRIVATE BASIC IMAGE BOX PRIVATE PRIVATE PRIVATE Not applicable PRINT QUEUE FILM SESSION PRIVATE M RGE 31 Healthcare Merge DICOM Toolkit File Management Services File Management Roles 32 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 file set and assign them a 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
61. 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 may 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 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 t
62. Q 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 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 SZ Send the Film Session Creation message ay status MC_Open_Message amp messageID BASIC_FILM_SESSION N_CREATE_RQ if status MC_NORMAL COMPLETION printf Unable to open request message n printf t s n 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 n printf t s n MC_Error_Message status MC_Free_Message amp messagelID 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 t s n MC_Error_Message status MC_Free_Message amp messagelID MC_Abort_Association amp associationID MC_Release_Application amp applicationID return
63. RT_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 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 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 Configuring configuration file to configure SCP applications that it communicates with Using this remote nodes at e aire e Ee configuration file requires that remote applications be configured before the library is initialized It may be desirable to configure remo
64. S or archive system does The workstation uses the DICOM query 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 125 Merge DICOM Toolkit 126 User s Manual Set th
65. SOP Class UID 1 1 7 lt Attribute gt ame Referenced lt Item gt lt Attribute Tag 00081150 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 lt Attribute Tag 00090010 VR Lo Code PCode PrivateCode Length PCODE lt Attribute gt lt Attribute Tag 00091010 VR Lo lt Attribute Tag 00091015 VR UN PCode SAMPLE PCODE Length 6 gt 30y lt Attribute gt lt Attribute Tag 7FE00010 VR OW Encoding Base64 Length 262144 00 EE lt Attribute gt lt DataSet gt lt DcemFile gt lt Attribute Tag 00081155 VR U Ty 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 136 M RGE Healthcare
66. Sample Margin Note Performance Tuning Client Server M RGE Healthcare Conventions This manual follows a few formatting conventions Terms that are being defined are presented in 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 a
67. Storage Ophthalmic Axial Measurements Storage Ophthalmic Visual Field Static Perimetry Measurements Storage Subjective Refraction Measurements Storage Visual 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 Ma
68. 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 records 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 API Mc_Dir_ functions and an 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_DDH_Create _ function specifying the location of the file an optio
69. Toolkit would select JPEG_BASELINE if proposed followed by EXPLICIT_LITTLE_ENDIAN IMPLICIT_LITTLE_ENDIAN and EXPLICIT_BIG_ENDIAN Gl Network message exchange is discussed further in 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 syntaxIds 0 JPEG_BASELINE syntaxIds 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 0 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_DE
70. UID created Some 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 lt root gt 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 lt root gt 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
71. _Open_Message or MC_Create_File this is not necessary 79 Healthcare Merge DICOM Toolkit How to register a Callback Function Callback Function User s Manual The MC_Register_Callback_Function can be used to register a Callback 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 myApplicationID myUserInfo 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 CBMessagelID unsigned long CBtag void myUserInfo CALLBACK_TYPE CBtype unsigned long CBdataSizePtr void CBdataBufferPtr int CBisFirstPtr int CBisLastPtr CBMessagelID 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
72. _Stream converts a message object to a message stream while MC_Stream_To_Message converts a message stream into a message object Also MC_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 Mess Object SE i MC Su To Mess Functionality Object EE Figure 11 Relationship between a Message Object and a Message Stream A call to MC_Message_To_Stream _ could look like the following Status MC_Message_To_Stream MyMessageID 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 a 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 M RGE Healthcare Merge DICOM Toolkit Performance Tuning Deflated Streams M RGE Healthcare User s Manual 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 MyStreamHandler _ is a callback function you supply in your application that receives and manages the stream data a block at a t
73. a aaia adia 34 ContiguratiON asien araa a aa A a aaa 34 Initialization EE 34 M RGE Healthcare Merge DICOM Toolkit User s Manual Message Loogimg ttnt ttuan tn Annt EE EA AEEE ESAE EE AANE EE En AE EEEn nE EEEn E Enant 35 Utility el tele TC 36 IMCSCOMP TEEN 36 Ale 0 gene nce Pere Coen E Corer rT errr Pernt creer tcc rarer coreer ter pert creer eer 37 IMCBOCHO EE 37 le EEN 38 meva sco fectee cecvenerg cae dvsebs coeeaiee E eerenadattnt dacented ates 38 UU 39 Developing DICOM Applications cccccceeceeeeceeceeeeeeeeeencaeeeeeeesesecnueaeeeeeeeeeteeaees 41 Library vie e e 41 Statically Linked Configuration ccccceeeceeeeeeneeeeeeeneeeeeeeeeeeeeaeeeee teaser tnaeeeees 42 Registering Your Application ccccceeeseceeeeeeeeeeeeeeneeeeeeeaeeeeeeaeeeeeenaeeeeeenaeeeeeeaas 42 Association Management Network On 43 Negotiated Transfer Syntaxes Network On 46 Dynamic Service EE 48 Message ODjeCts AAI 49 Building WO Le GETT 50 Parsing MESSAGES EE 54 B bit te 58 Encapsulated Pixel Data 59 eil EK Ee 60 Validating Messages ia NEA 61 Streaming Messages 66 Message Exchange Network On 68 Genaral penra 68 Asynchronous Communications ssseseeseeeieeseerrestrtestirrssttrnnsttrnssternnsree nent 70 Using Compression Decompression Callback Functions cccceseeeeeees 73 Using Callback FUNCTIONS nat 79 SEGUENCES OF Mensis aaia aaia aaa aaa aia a aada 82 DICOM WEE 85 Fi
74. a new child node where Type is a child Content Item Type for example TEXT e C_SRH_Set_Type_Data Sets additional attributes for the Content Item node D C_SRH_Add_Reference Creates a reference to another Content Item node by reference e 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 p Healthcare 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 e C_SRH_Get_First_Child Retrieves the first child Content Item relationship and node type e 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 e 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 e MC_SRH_Create_Type_Node Creates a new Content Item node specified by Type The node is created as a standalone Message Item without SR object e MC_SRH_Add_C
75. able 1 DICOM Services Classes and their Component Services Service Class Services Description Verification Verification Verifies application level communication between DICOM 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 2 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 Verge DICOM Toolkit M RGE Healthcare Service Class Services Description Intravascular Optical Coherence Tomography Image Storage For Presentation
76. able 24 defines all possible Content Item Types that can be used in the SR Document Content Module 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 Type M RGE 103 Healthcare Merge DICOM Toolkit 104 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 Uniq
77. achy Treatment Record Storage RT Dose Storage RT lon Beams Treatment Record Storage RT lon Plan Storage 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 Healthcare 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 Wavefo
78. also improve performance There are several configuration 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 Healthcare User s Manual e FORCE_OPEN_EMPTY_ITEM This configuration option performs the same function as using MC_Open_Empty_Message except that it is for items It is especially useful for reducing the amount of memory used when working with large DICOMDIRs e 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_S1ZE 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 e ELIMINATE_ITEM REFERENCES This option improves the performance of the MC_Empty_Message MC_Free_Message MC_Empty_File MC_Free_File an
79. 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 application ID that is used as a parameter The MC_Set_Message_Callbacks _ function allows the user to directly associate Callback Functions for an application with a message or file object After calling Mc_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 MC_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_Add_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 MC
80. 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 Mc_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 7 0 7 0 Byte 0 MSb Pixel2 LSb Byte 0 MSb Pixel1 LSb Byte1 MSb Pixel ep Byte1 Msb Pixel2 gb Byte2 MSb Pixel4 L b Byte 2 MSb Pixel3 LSb Byte3 MSb _Pixel3 Lan pute 3 MSb_ Pixel4 Lsb Byte4 MSb_ Pixel6 L b Byte 4 MSb Pixel5 LSb Bytes MSb PixelS ep Bytes MSp _Pixel6 L t e D e Big Endian Machines Little Endian Machines Figure 9 Sample Pixel Data Byte Streams for 8 bits Allocated 8 bits Stored and a High bit of 7 VR OW M RGE Healthcare Merge DICOM Toolkit User s Manual The DICOM standard specifies that the first pixel byte should be set to the least 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
81. ase the network performance of the toolkit for server SCP 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 129 Merge DICOM Toolkit User s Manual e TCPIP_SEND_BUFFER_SIZEW 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 e EXPORT_UNDEFINED_LENGTH_SQW 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 e 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 e EXPORT_GROUP_LENGTHS TO MEDIA
82. ationship Types between Content ems nsen 106 Content Item Identifier iesst aaan inin iaaa aR a 108 Observation Context 108 Structured Reporting Templates nenes eenr tn nreesrrnnn rn nnnrennn nn 109 Memory Management 2 ccccccccecseneeeeeceeceeeeeeneeeeeneneeseeceneeeedeneseneeeeneees 113 Overview of the Merge DICOM Toolkit SR functions ce eeeeeeeeeeeeeee 115 Encoding SR Documents cccceecceeeeeeeeeeeeeeeeeeeeeeseneeeeeseeeaeeesenaeeeseeaees 116 Reading SR Documents ecenin 120 Deploying Applications cc ceeeeeceeeeeteeeeeeseneeeeeeaeeeeeeaeeeeeeaeeeeesaeeeeeenaeeeeeeneeeeseaas 122 Merge DICOM Toolkit Required Files 0 ececeeeeeeeeeeeeeeeeeeeetneeeeeeneeeeetneeeeee 122 Configuration Optom resser Covet gpeteeetese edi AE EECH 123 Configuring Remote Nodes for SCU Applications 0 0 0 0 eeeeeeeenteeeeeeeee 124 UN Wd 125 Appendix A Frequently Asked Questions snssseesennnenesenttnnrresttnr tn nenertn nnne nenene 127 Appendix B Unique Identifiers UlDei nnee ne 133 Summary of UID COMPposSition ee eee ee eeeeeeeeeeeeeeeeeeeeeeeeseeeeeeeseeeaeeeeeenaees 133 Sample UID Format sseesseeiieeseesseennrnnseestttnnrenssttttttnnnnsstnnnttn nn nnsn tennan nnne eE nn 134 Obtaining a UID EE 134 Obtaining a UID From ANS 134 Appendix XML structure sssssssesetensseeett tr rtnssttttttnttnsstttttn nnanet ttnn Ennn arrn en ennan nnne 135 v Merge DICOM Toolkit Use
83. bstract 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 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 fora 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 MC_Get_First_Acceptable_Service and MC_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 MC_Get_Message_Transfer_Syntax function must be used to retrieve this transfer syntax The following is a typical call to this function MC_Status MC_Get_Message_Transfer_Syntax ImageMsgID amp transferSyntax Exchange of messages ove
84. cally 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 To tag 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 applications sending request messages after a call to MC_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 kee
85. cation 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 objects 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 Healthcare 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
86. ce N DELETE Request that a remote AE delete an existing object instance These DICOM commands can be thought of as primitives that every networking Wh SC eave ae eee 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 4 commands are referred to as DIMSE Services in the DICOM Standard M RGE 17 Healthcare Merge DICOM Toolkit Request vs response IMPORTANT 18 User s Manual For every command there is both a request and a response A command request 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 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 onl
87. ce 01 3 52 09 00 7919 MC3 T5 0020 1041 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0028 0006 VI Unable to check condition O1 3 52 09 00 7919 MC3 T5 0028 0030 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0028 0034 VI Unable to check condition 01 3 52 09 00 7919 MC3 T5 0028 1101 VI Unable to check condition O1 3 52 09 00 7919 MC3 T5 0028 1102 VI Unable to check condition O1 3 52 09 00 7919 MC3 T5 0028 1103 VI Unable to check condition 01 3 52 09 00 7919 MC3 T5 0028 1201 VI Unable to check condition 01 3 52 09 00 7919 MC3 T5 0028 1202 VI Unable to check condition O1 3 52 09 00 7919 MC3 T5 0028 1203 VI Unable to check condition 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 Patiente Age 0010 1010 The log states that the message contains 41yY 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 041yY There is also one other error flagged in this message The required attribute View Position 0018 5101 had no value Man
88. character set consisting of the uppercase characters A Z the numerals 0 9 and the underscore _ M RGE Healthcare Merge DICOM Toolkit The DICOMDIR hierarchy M RGE Healthcare 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 4 Print Queue Dir Records Film Session DICOM Files Print Queue Dir Entities Basic Grayscale or Color Image Box 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 correspo
89. code is taken from the CID 7012 Si 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 ai status MC_SRH_Add_IMAGE_Child srID SR_REL_CONTAINS Mlele ER EE HE ecnildiD if status MC_NORMAL COMPLETION process error here return Convert SR to the message ny 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 S 118 M RGE Healthcare Merge DICOM Toolkit User s Manual Set file meta information MEDIA_FILE_META_INFO_VER amp miVer sizeof miVer MEDIA_TRANSFER_SYNTAX_UID MC_Set_Valu
90. command pairs whose corresponding object instances can be stored to media are summarized in Table 5 23 24 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 STOR
91. csnsaeeeeees 6 Library e 6 Header Files aivicecs cles dene eegene tiers delienad niet ege ER 7 Merge DICOM Toolkit LiDrary eececeeeeeeeeeeeeeneeeeeeneeeeeenaeeeeeeaeeeeeenaeeeeeeaas 8 Binary Message Information and Data Dictionary Files 00aaeneneeeeeee 8 Sample Applications ccccccccceceeeeeceecaeceeeeeeececaaeaeeeeeeesececsaeceeeeeeesensenaeeeeees 9 Merge DICOM Toolkit Extended ToolKit 0 ce eeccceeeeeeeeeeeeneeeeeeetieeeeeeneeeeeeaas 9 Documentation Roadmap i imscieiiesaiii naiinis iaaiiai iaaii aiita 10 el e 11 Understanding DICOM wisi cctv aadi acide acl eeil E a SES 11 General Concepts stees ccd teciidadecesteacdecavaadacend ad EES EES ed 11 Application E 11 Services and Meta Services c cecccccccececeeeeeeeeaeeeceeeeeseeeceaeeeeeeeeeeeeenaees 12 Information MOGEl iis 20 said eccachas RN leach sebad caasutdicectenaddassuiddaastansdiasechdddeatenddees 16 Klee lu EE 17 ell ET 17 Association Negotiation 2 00 ccceccccceeceeceeeeeeenneeeeeseeeeeeeceeeeeenaeeeeeeneeeeeenas 18 MOCSSAGCS EE 19 DICOM Data Dictionary osio eani EEE 20 Message Handing EE 21 Se Ende 22 Media Interchange peann a ie avai eege EES 23 DICOM Files issn eSEE EE E EA EE 23 Elte iuuat a 28 THe e Uer ell 29 File Management Roles and Services 0 c cceececeeceeeteeeeeeneeeeetneeeeesneeeeee 32 COMMPORMANGS isinna a acavcasadacesensadd tdeaseatacandanancabacceseds 33 Using Merge DICOM Tool irurita iiaii aiina aiia aa
92. d MC_Free_Item functions This option will disable functionality 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 This option sets the TCP IP receive buffer size Higher values for this buffer generally will incre
93. d 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 O1 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 O1 3 52 09 00 7919 MC3 T5 0018 0082 VW Invalid attribute for service O1 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 00 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 gI 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 O1 3 52 09 00 7919 MC3 T5 0020 0032 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0020 0037 VW Invalid attribute for service 64 M RGE Healthcare Merge DICOM Toolkit User s Manual O1 3 52 09 00 7919 MC3 T5 0020 0052 VW Invalid attribute for service 01 3 52 09 00 7919 MC3 T5 0020 0060 VI Unable to check condition 01 3 52 09 00 7919 MC3 T5 0020 1040 VW Invalid attribute for servi
94. e EXPORT_UN_VR_TO_NETWORK configuration option to No This will cause the Merge DICOM Toolkit to not export attributes encoded 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 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 M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare 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 lib
95. e MC_Open_Secure_Association call Client Side Example status MC_Open_Association MyStoreClientId amp associationID RemoteAppTitle NULL NULL NULL if status MC_NORMAL COMPLETION printf Unable to open association with s n RemoteAppTitle printf t s n 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 t s n MC_Error_Message status return 1 Now you can exit normally A 43 Merge DICOM Toolkit User s Manual Waiting for an There are two methods to wait for associations for server applications The first is to association use the MC_Wait_For_Association call The second method is to use the C_Wait_For_Connection callin conjunction with the C_Process_Association_Request call The C_Wait_For_Association call is 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
96. e 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 MC_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 MC_Register_Callback_Function to register a Callback Function that will be called repetitively as the attribute 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
97. e message s with one or more matches See the Query Retrieve Sample Application Guides for further detail s Again your application should free the message object when done using it Example of parsing y First is Patient ID status MC_Get_Valu a C FIND RQ Messag ay To_String FindMessagelID Next is Patient nam status MC_Get_Valu MC_ATT_PATIENT_ID 64 PatientID e To_String FindMessagelID Next is patients bi status MC_Get_Valu MC_PATIENTS_NAME 64 szPatientName rth day To_String FindMessagelID MC_PATIENTS_BIRTH_DATE 8 szPatientBday Finally patients s status MC_Get_Valu ex To_String iMessageID MC_PATIENTS_SEX 16 szPatientSex Now you can perform matches for the att a search in your database for ributes read in and send the proper M RGE Healthcare Merge DICOM Toolkit User s Manual response messages Xy 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 a time This function is the complement
98. e object use the MC_Set_Value family of functions to build your message This family of functions can be broken into five types based on their functionality 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 MC_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 MC_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 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_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 mes
99. e_From_Buffer srID MC_Set_Value_From_String srID WL S40 L0008 1 21 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 WL gaia Ga e300 7 MEDIA_IMPLEMENTATION_CLASS_UID To l6 8405 E DC EA ME LI A_IMPLEMENTATION_VER_NAME MEDIA _STORAGE_SOP_CLASS_UID WL 2o840 10008253 Let E E MEDIA_STORAGE_SOP_INSTANCE_UID Set other required attributes for the KO IOD MC_ATT_SOP_CLASS_UID MC_Set_Value_From_String srID 1 2 28402100086 2541 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 srID MC_ATT_SOP_INSTANCE_UID 1 2 3 4 5 6 7 300 MC_ATT_STUDY_DATE 19991029 MC_ATT_CONTENT_DATE 19991029 MC_ATT_STUDY_TIME 154500 MC_ATT_CONTENT_TIME 154510 MC_ATT_ACCESSION_NUMBER 123456 MC_ATT_MODALITY KO MC_ATT_MANUFACTURER MERGE MC_ATT_REFERRING_PHYSICIANS_NAME Luke Will Dr M D MC_ATT_REFERENCED_PERFORMED_PROCEDURE_STEP_SEQUENCE MC_ATT_PATIENTS_NAME Jane Doo MC_ATT_PATIENT_ID 234567 MC_Set_Value_From_String srID MC_Set_Value_From_Strin
100. ecting data from records through the MC_DDH_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 RootID argument The toolkit will call the provided callback for each record encountered during traversal The callback can dynamically control the traversal using various return values Here is an example on how to use MC_DDH_Traverse_Records _ tofinda specific series record Find Information Structure typedef struct RecordFind_Struct char matchValue int matchRecordID char butt 256 RecordFind Find callback MC_TRAVERSAL STATUS FindSeriesCbk int CrtRecID void CbhkData C_STATUS status C_DIR_RECORD_TYPE recType MC_REC_TYPE_UNKNOWN RecordFind findInfo RecordFind CbkData Check for record type C_DDH_Get_Record_Type CrtRecID amp recType if recType MC_REC_TYPE_SERIES return MC_TS_CONTINU Gl Check for matching Series Instance UID status MC_Get_Value_To_String CrtRecID MC_ATT_SERIES_INSTANCE_UID 256 findInfo gt buff if status MC_NORMAL_COMPLETION if strcmp findInfo gt matchValue findInfo gt buff 0 Found a match findInfo gt matchRecordID CrtRecID return MC_TS_STOP Continue the traversal with the ne
101. ed by a Tag Wht eet WS L File Meta Object Instance Information y WI Y Byte Stream N Optional Padding Attribute File Meta Info Attribute 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 an identifying characteristic for all DICOM files The remainder of the file preamble and object instance is encoded using tagged attributes as ina 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
102. emory 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 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 _ 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 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
103. ent 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 e MC_Set_File_Preamble andMC_Get_File_Preamble allow specialized application to examine and modify the 128 byte 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 89 Merge DICOM Toolkit Performance Tuning 90 User s Manual 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 MC_Create_File call If the file object was created using MC_Create_Empty_File then MC_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 app
104. er SCP accepts both of these presentation contexts the client SCU must use the MC_Set_Message_Transfer_Syntax function to specify which presentation context to send a message over as follows MC_Status C_Set_Message_Transfer_Syntax ImageMsgID JPEG_BASELINE M RGE 47 Healthcare 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 Number of Services SERVICE_1 STANDARD_CT SYNTAX_LIST_1 CT_Syntax_List_SCP CT_Syntax_List_SCP SYNTAXES_SUPPORTED 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
105. erge DICOM Toolkit Reference Manual for further details on these functions Message Objects Merge DICOM Toolkit supplies several types of objects application objects Objects are useful 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 th
106. eric 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 with 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
107. essage 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 can 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 Too
108. essage 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 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 in WORK_BUFFER_S1ZE 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 MC_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_To_Message is used to read DICOM stream objects and MC_Open_File MC_Open_File_Bypass_OBOw and MC_Open_File_Upto_Tag are used to read DICOM Par
109. f a DICOM Information Model A detailed entity relationship diagram of this model is included in both parts 3 and 4 of the standard This 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
110. f that condition is not met the attribute shall not be included in the message The attribute is optional It may or may 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 ACME_IMG_INC 00 This attribute has group number 1455 a private identification code string of ACME_IMG_INC 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 mus
111. 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 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_Process_Secure_Association_Request Call Server Side Example of MC_Wait_For_Connection MC_SOCKET theSocket status MC_Wait_For_Connection 1l amp theSocket if status MC_NORMAL COMPLETION printf tError on MC_Wait_For_Connection n printf t t s n MC_Error_Message status printf t tProgram aborted n abort status MC_Process_Association_Request theSocket Service_List_1 amp calledApplicationID amp associationID if status MC_NORMAL COMPLETION printf tMC_Process_Association_Request error n printf t t s n MC_Error_Message status printf t tProgram aborted n abort if calledApplicationID MyApplicationID printf tUnexpected application identifier on C_Wait_For_Association n printf t tProgram aborted n abort status MC_Accept_Association associationID if status MC_NORMAL COMPLETION printf tError on MC_Accept_Association n
112. g srID MC_Set_Value_From_String srID D D MC_Set_Value_From_String sr MC_Set_Value_From_String sr WL 22S oe Ga LOO 5 MC_Set_Value_From_String srID W123 4 326072200 7 MC_Set_Value_From_String srID MC_Set_Value_From_String srID MC_Set_Value_From_String srID MC_Open_Item amp item1l HIERARCHICAL_SOP_INST_REF_MACRO MC_Set_Value_From_String iteml EE Daa Fa LOO 7 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 ui ad MC_ATT_INSTANCE_NUMBER Ve AE MC_Set_Value_To_NULL srID MC_ATT_PERFORMED_PROCEDURE_CODE_SEQUENCE MC_ATT_STUDY_INSTANCE_UID MC_Open_Item amp item2 HIERARCHICAL _SERIES_REF_MACRO MC_Set_Value_From_String item2 WL 26345 66 lt 14200 MC_Open_Item amp item3 REF_SOP following UIDs are the same MC_Set_Value_From_String item3 MC_Set_Value_From_String item3 D Ll i 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 iteml MC_ATT_REFERENCED_SERIES_SEQUENCE item2 MC_Set_Value_From_Int srID MC_ATT_CURRENT_REQUESTED_PROCEDURE_EVIDENCE_SEQUENCE iteml1 Convert me
113. ge 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 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 eo 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 a 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 eg 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 val
114. he message object without any errors In this case no user data is passed through to the callback function since UserInfo is NULL Storing or setting aside Pixel Data a block at a time is especially useful for very large Pixel Data and or on platforms with resource eg 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 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
115. her files If the sample applications are not executed from the 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 127 Merge DICOM Toolkit Performance Tuning 128 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 In this 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 it is automatically resolved and does not need to be set e f MERGECOM_3_ 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 MC3INIDIR config mergecom pro
116. hild 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 116 M RGE Healthcare Merge DICOM Toolkit 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 Rei with Parent VT Concept Name VM Reg Condition Value Set Typ Constraint e 1 CONTAI DCID 7010 Key Object 1 M Root node NER Selection Document Titles 2 gt HAS CONCEPT MOD CODE EV 113011 DCM 1 n U Document Title Modifier 3 gt HAS CONCEPT MOD CODE EV 113011 DCM 1 UC IF Row 1 Concept DCID Document Title Name 113001 7011 Modifier DCM Rejected for Quality Reasons or 113010 DCM Quality Issue 4 gt HAS CONCEPT MOD CODE EV 113011 DCM 1 MC _ IF Row 1 Concept D
117. hough that the DICOM Standard is the final word and that message txt has its limitations as described further below MC_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 61 Merge DICOM Toolkit What validation can do for you User s Manual An excerpt of message txt follows for the service command pair DETACHED_ PATIENT_ MANAGEMENT RSP as an illustration N_ GET 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
118. ibe the Concept Name of the Source Content item such as to create a post coordinated description of a concept 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 106 M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare Relationship Type HAS ACQ CONTEXT Merge DICOM Toolkit Definition SR_REL_HAS_ACQ_CONTEXT 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 Lymphadenopathy E g NUM
119. ices you may need the Merge DICOM Toolkit Extended Toolkit to assist in defining these services so that they can be supported by the toolkit 33 Merge DICOM Toolkit MERGE _INI 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
120. ifferent observation dates and times to be attached to different Content Items M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare 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 bel with VT Concept VM Reg 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
121. ime This callback function is similar to the example in MC_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 MC_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 MySt reamProvider and places them in the message identified by MyMessageID It is 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 MC_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
122. ime is critical one can specify different parameter values to MC_Library_Initialization to call initialization functions rather than accessing files These initialization functions are generated 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 and can be used to 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 is reserved 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 t
123. ing the request or response message to handle is waiting on several asynchronous events not just the message event the asynchronous MC_Get_Association_Info call can be used to get the file descriptor for the events M 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 McC_Read_Message can be called and will return immediately with the received message RGE 69 Healthcare Merge DICOM Toolkit Asynchronous definitions Performance Tuning 70 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
124. ion Entity Title Length 15 gt MERGE_STORE_SCP lt Attribute gt lt FileMetaInfo gt lt DataSet Service STANDARD_SEC_CAPTURE Command C_STORE_RQ TransferSyntax 1 2 840 10008 1 2 1 gt lt 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 c 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 lt Item gt lt 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
125. ion 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 malloc 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 larger 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 97 Merge DICOM Toolkit MC_Read_Message MC_Open_File MC_Stream_To_Message 98 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_S1IZE 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 MC_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 m
126. ions can be used to solve interoperability 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 M RGE 123 Healthcare Merge DICOM Toolkit User s Manua Configuration Option Description EXPO
127. ired compiler build options Library Structure Understanding the organization and components of the Merge DICOM Toolkit Library is important to developing an efficient 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 H SE d Media App Sample Q R App Sample Store App ess TL ASCH files Merge s or linked DICOM Application Message Info into library header files Database and executable Data Dictionary Config Files KEE MergeCOM 3 Advanced MERGECOM PRO Library i MERGECOM APP binary files MERGECOM SRV or linked into executable TCP IP File System Sockets Library Dev Driver Interchangeable Media Device DICOM Network S Key optional Merge DICOM Database Components Maintenance Tools SS SE Components 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 mc3media h e mestatus h e diction h Merge DICOM Toolkit User s Manual The mergecom h header file contains the prototypes of the functi
128. is section but will also be described later in this document M RGE 49 Healthcare Merge DICOM Toolkit Opening a message Performance Tuning Filling 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 MC_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 _ Wwhere 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 MC_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 messag
129. ism 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 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 myMessagelID ACME_IMG_CORP 0x1455 00 PN Up to 255 other private attributes c
130. 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 only 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 applica
131. k ping operation but at the DICOM application level rather than the TCP IP transport level All 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 C count r remote_host 1 local_app_title p remote port r remote_host l 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 l 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 in an easy to read manner The message files could have been generated by mc3file see below or written out by your application mc31list is a useful educational tool as well as a tool that can be used for off line display of the DICOM messages your ap
132. kit mc3conv Convert Image User s Manual The mc3conv utility can 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 lt tag gt lt 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 lt syntax gt il for implicit little endian default el for explicit little endian eb 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 lt tag gt the tag that is to be changed in hex 0x lt new value gt the value for the tag in quotes multi values separated as vall val2 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 networ
133. kit User s Manual Receiving Messages 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 association 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 MC_Read_Message _ callis Timeout Timeout specifies in seconds how long your process will wait for a message before the MC_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 ornot A Timeout of 1 indicates wait forever or until a message arrives before returning Using select In specialized cases where the application read
134. l Development Platform Requirements To use the Merge DICOM Toolkit Library you must run on a Merge DICOM Toolkit supported computing platform The DICOM Toolkit 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 requ
135. l see the Reference Manual 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 768 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 diff 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 Toolki
136. lback 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 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 JPEG_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 For JPEG_BASEL
137. le System Interface Functions aeseeeesseessseseerressernnsennnnnnnnatnnnananunseennas 85 Creating a Fil ODj Cinoncucncnareicani ii nan 86 Reading HOTT 87 Creating and Writing Files siss issmsiia siinid raai niia aii a 88 Other Useful File Object Funchons ec eceeeee cence ee eeeeeeeeeeeeeeeseeeeeeteenaees 89 File Validation 0 cc eeeeeeeee sence eect ee ee etne ee ee eneee ee taeeeeetaeeeee sees eetiaeeeeesieeeeee 90 Converting Files to from Messages 90 DICOMDIR ET 91 iv M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare User s Manual SUCU cenare EEE E EEEE EEEE EEEE 91 Opening and Navigation 92 Adding and Deleting RecordS sseeessseessrsesssrneseennenssnnasnenneesannaattnnaanannaanennaae 94 Storage of Directory RecordS essseeesssessersesesrneersnnaattnneatinnaanennddnannaaetnnaananaa 94 Private Attributes eeeaaeeeeeeennesenneseennensnnnntennnntenanntannnatinnnntannennannantannnananannaan naaa 95 Multi threading Support 96 Memory Management et ugueRZ gege E E EEES 96 Assigning He CT 97 Reading Messages from the Network ceeeceeeeeeeeeeeeeeteneeeeeseneeeeetteeeee 98 Loading Messages from Disk cccceeeeeeeeeeteeeeeeeeneeeeeeteeeeeteeeeeesnaeeeeeed 98 Using Registered Callbacks A 99 DICOM Structured Reporting erse EEE 101 Structured Report Structure and Modules cccccccceceeeeeeeeeeeeeeeeseeeeeeeees 101 Content kem Types cscnccssteveetasier AA a 103 Rel
138. le 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 MC_Get_Next_Validate_Error simply step through the results of the 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 T5 0008 0023 VI Unable to check condition 01 3 52 09 00 7919 MC3 T5 0008 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 O1 3 52 09 00 7919 MC3 T5 0018 0015 VE Required attribute has no 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 Invali
139. lication The data is typically read from disk at this point and directly passed to Merge DICOM Toolkit After MCc_Send_Request_Message receives the data it byte swaps the data if needed and then writes it to the network 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 Mc_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 t
140. lies 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 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 MC_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 MC_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 att
141. lities These capabilities can prove 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 cal
142. lkit This includes the Application Programming Interface API toolkit configuration the runtime object database and status logging The DICOM Message Database Manual is an optional extension 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 Platform Notes This includes supported compilers compiler options link options configuration and run time related issues User s Manual DH Reference Manual a H Notes Figure 4 Merge DICOM Toolkit Documentation Roadmap DICOM Sample Extended Applications Toolkit Guide Manual 10 M RGE Healthcare Merge DICOM Toolkit
143. long with Annexes B and C 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 s
144. me configuration options Use of this file 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 M RGE Healthcare Merge DICOM Toolkit User s Manual File Description and Use 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 DICOM Toolkit application mrgcom3 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 opt
145. n and get an immediate response Similarly once the association is established both the client and server applications can use the MC_Get_Association_Info call to get the file 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 a
146. nal 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_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 e g study records MC_DDH_Get_Parent_Record can be 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 MC_DDH_Release_Record Of MC_DDH_Delete_Record M RGE Healthcare Merge DICOM Toolkit User s Manual Modifications to the content of existing records are not allowed The toolkit provides an easy and fast way for searching and coll
147. nding DICOM file Each directory record 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 Merge DICOM Toolkit User s Manual Table 6 Allowed Directory Entity Directory Record Type Record Types which may be included in the next lower level Directory Entity Root Directory Entity 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 30 M RGE Healthcare Merge DICOM Toolkit User s Manual Directory Record Type Record Types which may be included in the next lower level Directory Entity Ste TOPIC STUDY SERIES IMAGE OVERLAY MODALITY LUT VOI LUT CURVE FILM SESSI
148. nst char AconceptNameMeaning You will find that some of the functions 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 110 M RGE Healthcare Merge DICOM Toolkit Abbreviations used in templates M RGE Healthcare 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 EV Enumerated Value values for are provided in the brackets DT Defined Term values are provided in the brackets 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 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 p
149. ntax gt are il for implicit little endian el for explicit little endian and eb for explicit big endian f lt file gt This option allows 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 M RGE Developing DICOM Applications The Merge DICOM Toolkit Application Programming Interface API provides simple yet powerful DICOM functionality Function calls are p
150. nus 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 SQ Attribute Command Object Instance o eee DICOM Message SQ Attribute EN BE Nee Item 1 Item Sequence of Ite Item 1 Item 2 Item 1 Sequence of Items Sequence of Items E Command Attribute 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 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
151. o 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 file 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_Stream in 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 Healthcare 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 gen
152. 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 on 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 MC_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 th
153. of the calling Template or in all rows of the included Template 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 AsrNodelID R_RELATIONSHIP Arelationship nt AsrRefNodelID _S i S i MC_STATUS EXP_FUNC MC_SRH_Get_Reference int AsrNodelID int AsrRefNodelID 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 co
154. ons 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 message 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 ha
155. oolkit 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 Application 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 ACME_Query_SCP 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 M RGE Healthcare 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
156. ormation 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 writing 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
157. ostic purposes Reasons for this include performance since the overhead associated with message M RGE 65 Healthcare Merge DICOM Toolkit 66 User s Manual 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 Streaming Messages When DICOM messages are exchanged over a network they are in an encoded 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 11 MC_Message_To
158. ould be added to the ACME_IMG_CORP private block in group 1455 using the above call and Element 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 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 myMessagelID ACME_IMG_CORP 0x1455 00 Adams John Robert Quincy 95 Merge DICOM Toolkit Retrieving values from private attributes Check platform notes for multi threading support Performance Tuning 96 User s Manual Similarly retrieving values from private attributes makes use of MC_Get_pValue rather than Mc_Get_Value functions The MC_Get_pA
159. penalizes you in the area of run time error checking M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare 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 if Read in the DICOM file 7 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 fileID is the handle of a previously created file object and NULL specifies that you aren t passing any user information to MediaToFile MediaToFile 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 dataBuffe
160. pical 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 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 MC_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 MC_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 MC_NORMAL_COMPLETION implies an error A possible error code for this call is MC_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 41 Healthcare Merge DICOM Toolkit 42 User s Manual Statically Linked Configuration In specialized applications such as embedded systems or where performance at initialization t
161. plicating 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 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_Validate_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 t
162. plication generates or receives The command syntax follows mc3list lt filename gt t lt syntax gt m filenam 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 lt filename gt w i s lt serv gt c lt cmd gt 1 m q t lt syntax gt lt filename gt 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 agains
163. pper 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 the service name and command are improperly specified mc3file will act as if the l option was used and ask the user to input the correct service name and command lt num gt 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 Healthcare 39 Merge DICOM Toolkit g lt filename gt c lt filename gt t lt syntax gt 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
164. pping Storage M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare Service Class Storage Commitment Media Storage Query Retrieve Basic 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 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 and a hierarchical directory of the DIC
165. pplications 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 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 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 T
166. printf Ss n 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 Ss 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 121 Merge DICOM Toolkit 122 User s Manua printf MC_SRH_Get_Next_Child Eror code d status return Next child expected to be the IMAGE item if nodeType SR_NODE_IMAGE status MC_SRH_Get_IMAGE_Data childID sopClassUid sizeof sopClassUid sopIn
167. 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 asynchronous 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 ay 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 MC_Get_Listen_Socket call can 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_Associatio
168. ps 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 72 M RGE Healthcare Merge DICOM Toolkit Deadlocks possible with asvnchronous Performance Tuning Use Full Duplex Networks with asynchronous commnications M RGE Healthcare 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 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
169. r 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 file 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 87 Merge DICOM Toolkit Performance Tuning 88 User s Manual Once the file object has been opened the same MC_Get_Value family of parsing functions used for message objects described earlier can be used to read attribute values from the file object Also the same MC_Set_Value family of functions can be used to modify the values of file attributes Two special variants on MC_Open_File are also provided by the toolkit e MC_Open_File_Bypass_OBOW will read in an attribute s value that is of type OB or OW but will no
170. r Process Request Msg 2 Read Response Msg 2 lt J r Send Response Msg 2 X a 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 on the SCU side A traditional SCP can effectively support asynchronous communications by simply enabling its negotiation over associations It 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
171. r s Manual vi M RGE Healthcare Merge DICOM Toolkit Overview This User s Manual is intended for developers of medical imaging applications who are using the 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 on 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 differen
172. r the network is discussed further below The presentation contexts supported for client SCU applications using Merge DICOM Toolkit are also defined through the Merge DICOM Toolkit Application Profile The following is a typical client s SCU configuration Acme_Store_SCP PORT_NUMBER 104 HOST_NAME acme_sunl SERVICE_LIST Storage_Service_List Storage_Service_List SERVICES_SUPPORTED SERVICE_1 1 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_1l SERVICE 2 STANDARD_CT SYNTAX_LIST_2 CT_Syntax_List_2 CT_Syntax_List_1 SYNTAXES_SUPPORTED 1 Number of Syntaxes SYNTAX_1 JPEG_BASELINE CT_Syntax_List_2 SYNTAXES_SUPPORTED 1 Number of Syntaxes SYNTAX_1 IMPLICIT_LITTLE_ENDIAN If a serv
173. ragment E000 024AH d EODD 0000H E000 Fragment 4 4 4 bytes 4 bytes 04C6H 4 bytes 4 bytes 024A 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 M RGE 59 Healthcare Merge DICOM Toolkit User s Manual DICOM Message Stream DICOM Header Information EO 00 00 00 00 EO C6 04 00 00 First Compressed 8 Fragment Encode Data FE FF 00 EO 4A 02 00 00 Second Compressed e Fragment FE FF DD EO 00 00 00 00 Figure 10 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 Icon Image Sequences The Icon Image Sequence can contain small thumbnail images This sequence also contains the Pixel Data Tag 7FE0 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 60 Message is uncompressed Icon is uncompressed There is no user intervention required An association will negotiate one of the unencapsulated transfer syntaxes and both
174. ransfer 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 JPEG_LOSSLESS_HIER_14 JPEG_2000 JPEG_2000_LOSSLESS_ONLY or RLE 73 Merge DICOM Toolkit How to register a Compression Callback Function User Defined Compressor and or Decompressor User s Manua 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 If there are no callbacks registered the above functions will work the same as MC_Get_Value_To_Function and MC_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 uncompre
175. rary e Upgrading the library The Merge DICOM Toolkit library 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 lam 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 ot
176. ributes 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 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 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 M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare User s Manual MC_File_To_Message hasasingle 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 toa file handle by removing the command attributes from the message object and adding the file preamble and meta inf
177. rm 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 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 Merge DICOM Toolkit Naming DICOM File Sets and File ID s 28 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 Lensomet
178. rovided in the brackets BTID Baseline Template 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 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 Definition i where i represents Exactly i occurrences where i gt 1 E g when i 1 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 111 Merge DICOM Toolkit 112 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 M Mandatory Shall be present e MC Mandatory Conditional Shall be present if the specified condition is satisfied e U User Op
179. rovided 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 reading 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 ty
180. ry Measurements Storage C STORE Media Storage Directory Storage C STORE Merge DICOM Toolkit defines a 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
181. s 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 objects 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 Toolki
182. s important to any AE developer For 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 havea 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 serv
183. sage object This means the attribute has no value and is not included in the message M RGE Healthcare Merge DICOM Toolkit Performance Tuning Function Type Description MC_Set_Value_From_Function Specifies a function that is called repeatedly to set 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 MC_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 eg MC_INVALID_VALUE_FOR_VR MC_VALUE_OUT_OF_RANGE If your message object was opened using MC_Open_Message the status code MC_INVALID_TAG will be returned if you attempt to set the value of an attribute tha
184. ssage 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 During 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 M RGE Healthcare Merge DICOM Toolkit M RGE Healthcare User s Manual SCU SCP r T j Read Request Msg 1 Send Request Msg 1 3 a S J E 4 r Process Request Msg 1 Read Response Msg 1 4 f Send Response Msg 1 a Pp S Send Request Msg 2 lt Read Request Msg 2 S J gt sea lee
185. ssage to file MC_Message_To_File srID fileName M RGE Healthcare 119 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 templId SR_CONTENT_TYPE nodeType char conceptNameValue 512 char conceptNameScheme 512 char conceptNameMeaning 512 SR_RELATIONSHIP relationship int isLast char sopClassUid 512 char sopInstanceUid 512 ink 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 j if status MG 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 conceptNameValue sizeof conceptNameValue conceptNameScheme sizeof conceptNameScheme conceptNameMeaning sizeof conceptNameMeaning if status
186. ssed 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 MC_Register_Compression_Callbacks can 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 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 CBMessagelID void CBContext unsigned long CBdataLength void CBdataValue unsigned long CBoutdataLength void CBoutdataValue int CBisFirst int CBisLast int CBrelease CBMessagelID 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 s
187. ssible to access tags within a message as it is being read from the network It is possible to call the MC_Set_Value_ MC_Set_pValue_ MC_Get_Value_ and MC_Get_pValue_ routines from one thread while another thread is calling the MC_Read_Message_To_Tag MC_Continue_Read_Message MC_Continue_Read_Message_to_Stream routines or when these routines are used 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
188. stanceUid 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 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 merde In 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 ti
189. t is not a part of that message object This additional level of validation is lost if you use MC_Open_Empty_Message _ since this opens an empty message object without any attributes to check against Applications where performance is critical may find it useful to use MC_Open_Message _ during initial development and replace these calls with MC_Open_Empty_Message _ later in the development cycle after the implementation stabilizes Table 10 Acceptable MC_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 MC_Set_Value_From_Buffer UNKNOWN_VR An example of opening a message for the BASIC_FILM_SESSION N CREATE R
190. t service name serv used along with c c lt cmd gt Optional force the message to be validated against command name cmd 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
191. t 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 network If the data is stored in file format the MC_Open_File_Bypass_OBOW or MC_Open_File_Upto_tTag 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 Healthcare 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 MC_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_S1IZE configuration option can specify the minimum size or length required for use of a registered callback function There are three models in which MC_Register_Callback_Function can be used First
192. t Library and require that you set your MERGE_INI environmental 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 lt syntax gt t2 lt syntax gt file o m1 m2 filel file2 t1 lt syntax gt Optional specify transfer syntax of filel message where lt syntax gt il for implicit little endian default el for explicit little endian eb for explicit big endian t2 lt syntax gt Optional specify transfer syntax of file2 message where lt syntax gt il for implicit little endian default el for explicit little endian eb for explicit big endian e lt file gt Optional exception file of all tags to ignore in comparison 0 Compare OB OW e g binary pixel data mil Compare filel in DICOM 3 file format m2 Compare file2 in 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 m o 1 img 1 dcm 36 M RGE Healthcare Merge DICOM Tool
193. t Pixel Data which describes this problem This is typically only a problem 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 e0 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 MC_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
194. t 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 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 1 NEMA Standards Publication No PS 3 5 1993 DICOM Part 5 Data Structures and Encoding p 4 M RGE 1 Healthcare 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
195. t be followed when using private attributes e Private attributes shall not be used in place of required Value Type 1 1C 2 or 2C attributes e The 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 identifi
196. t 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 accesses 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 Healthcare 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
197. t of the ACR NEMA Standard where elements within a group were related in some manner This can no longer be depended 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 Command Attribute 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 Name 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 Multiplicit
198. t 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_Upto_Tag will read attributes of the file into the file object only up to a specified tag The offset in bytes from the beginning of the file to the beginning of the first attribute equal to or 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 read it in later or process it directly from the file using your own special filters or hardware 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
199. tCall 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 OpenFailed 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 ar if ReadFailed return MC_CANNOT_COMPLY if LastBlockRead close Pixel Data source here SE 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_ATT_PIXEL_DATA attribute 7FE0 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 m
200. te attribute is not included in the message that is not defined for that DICOM message service command pair As mentioned Merge DICOM Toolkit does not capture all standard violations and the DICOM Standard itself should be considered the final word when validating a message Important limitations of Merge DICOM Toolkit validation include 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 optional 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 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 of the use of MC_Validate_Message follows status MC_Validate_Messag iMessageID amp error_info Validation_Levell if status MC_DOES_NOT_VALIDATE printf MC_Validate_Message
201. te 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 Itis assumed that the services supported by an SCU application are predetermined 124 M RGE Healthcare Merge DICOM Toolkit UN VR interoperability problems M RGE Healthcare User s Manual 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 Every time a new VR is added to the standard
202. ther 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
203. they are file system dependent operations DICOM AE s that perform 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 User s Manual Table 8 Media Application Operations and Roles Media Roles M WRITE M READ M DELETE M INQUIRE M INQUIRE FILE SET FILE FSC Mandatory not not required Mandatory Mandatory required FSR not Mandatory not required not required Mandatory required Conformance Part 2 of DICOM discusses conformance and i
204. tion May or may not be present 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 XOR rows 1 3 4 is specified for the condition e IF Shall be present if the condition is TRUE may be present otherwise e IFF 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 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 ano
205. tion 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 once MC_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 MC_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 99 Merge DICOM Toolkit 100 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 MC_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 app
206. 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 71 Merge DICOM Toolkit Send Request Msg 1 Send Request Msg 2 Read Response Msg 1 Send Request Msg 3 Read Response Msg 2 SCU User s Manual Read Request Msg 1 Process Request Msg 1 Send Response Msg 1 Read Request Msg 2 Process Request Msg 2 Send 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_To_Tag and Message ID must be set for asvnchronous MC_Continue_Read_Message_To_Stream 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 automati
207. 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 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 N EVENT 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 me
208. 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 UseriInfo 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 ai if StoreFailed return MC_CANNOT_COMPLY if isLastBlock close Pixel Data sink here return MC_NORMAL_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 MC_ATT_PIXEL_DATA NULL MyPDStoreFunction M RGE 57 Healthcare Merge DICOM Toolkit Performance Tuning 58 User s Manual On making this call the toolkit library will repetitively callback MyPDStoreFunction _ until all the pixel data has been read from t
209. ttribute_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 safety 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 po
210. tus MC_Wait_For_Association Service_List_1 1 amp calledApplicationID amp associationID if status MC_NORMAL COMPLETION printf tError on MC_Wait_For_Association n printf t t s n MC_Error_Message status printf t tProgram aborted n abort ii if calledApplicationID MyApplicationID printf tUnexpected application identifier on C_Wait_For_Association n printf t tProgram aborted n abort ii status MC_Accept_Association associationID if status MC_NORMAL COMPLETION printf tError on MC_Accept_Association n printf t t s n MC_Error_Message status return a4 M RGE Healthcare 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
211. uch as SOP Classes Transfer 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 133 Merge DICOM Toolkit 134 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 lt timestamp gt 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
212. ue Identifier UID of e g Study the entity identified by the Instance UID Concept Name PNAME SR_NODE_PNAME Role of person 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 Verge 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 con
213. ues from attributes with these Value Representations MC_Get_Value_To_Int DS FD FL IS SL SS UL US SQ MC_Get_Value_To_Uint DS FD FL IS SL SS UL US SQ MC_Get_Value_To_ShortInt DS FD FL IS SL SS UL US SQ 55 Merge DICOM Toolkit 56 MC_Get function type MC_Get_Value_To_UshortInt MC_Get_Value_To_LongInt MC_Get_Value_To_UlongInt MC_Get_Value_To_Float MC_Get_Value_To_Double MC_Get_Value_To_String MC_Get_Value_To_Function MC_Get_Value_To_Buffer User s Manua 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 A special purpose function exists in the MC_Get_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 respons
214. ugh the N EVENT REPORT command This is done through DICOM role negotiation which is used during standard association negotiation 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 M RGE Healthcare Merge DICOM Toolkit Service Command Pair Attributes Values and Tags M RGE Healthcare User s Manual 1 a Association Requested 2 Et Association Accepted sew 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 Fig
215. upplied Merge DICOM Toolkit has set CBdat aLength to the number of bytes of data it is providing at CBdataValue The length of the chunk must be less than INT_MAX 74 M RGE Healthcare Merge DICOM Toolkit SPECIAL NOTE Built in Compressor and Decompressor M RGE Healthcare User s Manual 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 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 cal
216. ure 6 Messages containing command requests will be referred to as request messages while messages containing command responses will 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 Patients Name Scheduled Discharge Date A tag is a 4 byte number identifying an attribute eg 00100010H for Patient s Name 0038001CH for Scheduled Discharge Date 19 Merge DICOM Toolkit Groups and Elements Know your VR s 20 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 remnan
217. utes 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 MC_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 deleted 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 MC_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 to release 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 mechan
218. veys the Document Title if the ONTAINER is the Document Root Content Item or the category of observation CONTAINER 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 105 Merge DICOM Toolkit 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 descr
219. x 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 JPEG Lossless Supported Photometric Interpretations and Bit Depths JPEG Lossless Non Hierarchical Process 14 Photometric MONOCHROME 1 RGB Interpretation MONOCHROME2 Bits Stored 2 to 16 ie 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 peso e Jo fee e aeneae gt fe o gt _ 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
220. xt series record instead of lower level instance records return MC_TS_STOP_LOWER void FindSeries RecordFind findInfo findInfo matchValue 1 2 3 4 5 6 7 8 9 findInfo matchRecordID 0 MC_DDH_Traverse_Records dirID amp findInfo FindSeriesCbk M RGE 93 Healthcare Merge DICOM Toolkit Automatic deletion of referenced items Make sure you are committed 94 User s Manual 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 MC_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_DDH_Add_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 attrib
221. y defines the number of values an attribute can have VM can be specified as 1 k 1 k or 1 n where k is some integer 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 ES a 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 CR
222. y 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 Performance is involved in actually validating the contents of the message structure It is Tuning 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 Point 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 aruntime option or conditionally compiled into the source code Validation might only be used during integration testing or in the field for diagn
223. y supplied as an example They clearly explain the requirements that implementing certain DICOM services places on your application and 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 the 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 thro

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