Using LEADTOOLS DICOM SCU

The LEADTOOLS DICOM Scu .NET Class Library provides classes that allow you to quickly add the common DICOM messaging interface used in PACS-enabled image viewer workstations to your DICOM Image Viewer application. Now you can have an Image Display actor query and retrieve PACS or Image Archives of patient studies, series or image instances. In addition, you can create an easy-to-use interface for an Image Viewer AE to store any images, waveforms, reports, etc., to PACS.

Although this high-level object automatically performs the connection, DICOM Association negotiations and DICOM messaging, it also exposes interfaces so you can customize the process before the object sends a message to server.Before and after message events enable application-level transaction logging (i.e. for HIPAA compliance) and a full DICOM message dump of all transactions.

Features

• High-level object
• Automatic connection, DICOM Association negotiations and DICOM messaging
• Exposed interfaces allow customization of the process before the object sends a message to the server.
• Before and after message events enable application-level transaction logging (i.e. for HIPAA compliance) and a full DICOM message dump of all transactions.

These features allow you to quickly add standard DICOM Query/Retrieve and Storage services support to your applications in order to communicate with any PACS with only few lines of code. View the diagram that shows how the Leadtools.Dicom.Scu interacts with a PACS server. LEADTOOLS DICOM SCU acts as a Service Class User (SCU) for the Study Root Query/Retrieve Service of standard Query/Retrieve Information Models defined in the DICOM Standard to query PACS and to move DICOM composite instances to itself or other peer servers (SCPs).

Note: The Study Root Query/Retrieve Information Model is identical to the Patient Root Query/Retrieve Information Model except that the top level is the study level and the attributes of patients are considered to be Attributes of studies.

The following two DIMSE-C Services are used when constructing the SOP Classes of the Query/Retrieve Service Class:

• C-FIND
• C-MOVE

LEADTOOLS DICOM SCU supports both baseline (Hierarchical) and extended behavior (Relational) searches as defined in the DICOM Standard for the DIMSE-C C-FIND and C-MOVE services. Extended SCU behavior is negotiated when the Association is established. If an option within the extended behavior is not agreed upon in the negotiation, then only the baseline SCU behavior is performed with respect to that option.

This component also provides a default DICOM listener interface for receiving DICOM objects when the move destination AE Title is the same as the AE Title of query SCU or a title is not supplied. This built-in listener acts as a Service Class Provider (SCP) for the standard DICOM Storage Service Class. It accepts any IOD objects (i.e. images, waveforms, reports, presentation state etc.) and any encoding (i.e. compressed and uncompressed transfer syntaxes) supported by this version of LEADTOOLS.

The StorageSCU class facilitates transferring Composite IOD Instances (i.e. images, waveforms, reports, presentation state, etc.) to PACS using the DICOM C-STORE DIMSE-C service. If you specify the compression preference for the transfer, the StorageSCU object automatically changes the image to have the compression supported by the destination PACS Archive. The class can store any Composite IOD object (i.e. images, waveforms, reports, presentation state etc.) using any encoding (i.e. compressed and uncompressed transfer syntaxes) supported by this version of LEADTOOLS.

LEADTOOLS PACS Storage Classes

Connecting to a PACS Server

Establishing a DICOM Secure Connection

Storing Objects to a PACS Server

Querying PACS for Study Information

Retrieving Objects from a PACS Server

Using a Built-in DICOM Storage Server (SCP)

Logging DICOM Transactions

Connecting to a PACS Server

The high-level DicomSCU manages all of the connection and association as needed for the DICOM DCMSE services it performs. The DicomConnection Class is used for this process.

All calling application connection information needed for associations are exposed as properties of this object. Using its various methods and events you can control connections and associations, as when canceling an ongoing process or closing a connection. If a connection is unexpectedly interrupted (aborted or closed), events are. Applications can write event handlers and Override methods in order to update users about the status of the communication process and to log information.

The built-in SCP is used internally. The built-in SCP is not exposed to the user.

Establishing a DICOM Secure Connection

1. Configure the Remote SCP to support secure communications (A sample SCP is installed as part of the LEADTOOLS PACS Framework installation).

   1. Create a new instance of DicomScp.

   2. Initialize the following properties:

      1. AETitle
      2. PeerAddress
      3. Port

2. Create an scu (StoreScu,QueryRetrieveScu) using the constructor that allows you to specify the security mode.

3. Add event handlers:

   1. StoreScu.PrivateKeyPassword Event handler to fill in the password when requested.
   2. StoreScu.AfterSecureLinkReady Event handler to be notified when the secure link has been established.

4. Set up the secure communications:

   1. Call StoreScu.SetTlsCipherSuiteByIndex to set the cipher suite for the specified index.
   2. Call StoreScu.SetTlsClientCertificate to set the certificate for the client.

5. Connect to the remote Scp. If a secure association is established you will be notified via the StoreScu.AfterSecureLinkReady event.

Storing Objects to PACS

With the high-level StoreSCU object you can easily store DICOM files to a PACS Server with only a few lines of code. The StoreSCU object does the ground work related to lower level connection and association and negotiates for the appropriate transfer syntaxes. In addition, it is possible to:

• Instruct the object to transfer the data using lossy, lossless or uncompressed/native format.
• Store all of the DICOM files indexed by a DICOMDIR or stored in a folder in a batch mode
• Send a single DICOM file on disk or memory resident files in DicomDataSet.

The StoreSCU object uses the C-STORE DIMSE-C Service when storing. Any supported Composite IOD objects (i.e. images, waveforms, reports, presentation state etc.) in any encoding (i.e. compressed and uncompressed transfer syntaxes) supported by this version of LEADTOOLS can be stored.

Steps for Storing Objects

1. Configure the Remote SCP (A sample SCP is installed as part of the LEADTOOLS PACS Framework installation)

   1. Create a new instance of DicomScp

   2. Initialize the following properties:

      1. AETitle
      2. PeerAddress
      3. Port

2. Add an Event Handler

   1. StoreScu.AfterCStore Event handler to get the C-STORE-RSP status for the last C-STORE-REQ to the server.
   2. StoreScu.AfterAssociateRequest Event to identify problem with association.

3. Store the DICOM Composite IOD objects to the server

   1. Create a new instance of the StoreScu class
   2. Initialize the compression property to the desired option (i.e. Lossless. Lossy etc.)

   3. Call the appropriate overloaded StoreScu.Store method. The following options are available:

      1. Store a single DICOM file or DICOMDIR file. If the file is a DICOMDIR all files indexed in the DICOMDIR will be sent.
      2. Store DICOM part 10 files found using a search pattern string (recursively when specified) in a directory and its sub directories.
      3. Store a DICOM dataset in memory (i.e. DicomDataSet)

For a detailed example of storing objects please refer to the StoreScu documentation as well as the DICOM High Level Demo installed as part of the LEADTOOLS PACS Framework Installation.

Querying PACS for Study Information

The query service is performed by the QueryRetrieveScu class. This high-level object allows you to quickly add standard DICOM Query/Retrieve services support to your applications. For example, you can have your application collect patient/study information stored in a PACS archive using the standard DICOM message protocol.

All levels (e.g. Study, Series, Image) of the Study Root Query/Retrieve Information Model -- FIND are supported. Also, both Hierarchical Queries and Relational-queries are supported by this object. Preference is given to relational queries when supported by the query SCP. Applications enable the Study Root Query/Retrieve Information Model -- FIND (1.2.840.10008.5.1.4.1.2.2.1) SOP Class service for their application as a service class user (SCU). Queries are performed using the C-FIND operation. C-FIND responses return the matches found against the keys present in the request Identifier.. The FindQuery class allows the user to quickly build a query matching filter which also includes the support for the date and time range query attribute. To provide a custom dataset of query attributes (i.e. in memory or a saved on disk), use the overloaded QueryRetrieveScu.Find method to send a C-FIND message to the server. The object copies the query filter FindQuery object to the custom query attribute list before sending the C-FIND-REQ message.

For each matching response from the server, this object fires a query-level matching event (e.g. MatchStudy, MatchSeries, MatchInstance). Call the lower level Find method (e.g. FindSeries and FindInstances) to drill down the study hierarchy. These methods should be called outside of any QueryRetrieveScu event. Use the Move method (e.g. MoveStudy, MoveSeries, MoveInstances) in the matching events to retrieve or move the data at the level of query.

At any time during the query process and before the QueryRetrieveScu.AfterCFind event is called, the user can cancel the process by calling the CancelRequest method or can abort a connection by calling the Abort method. This object also invokes the BeforeCFindEvent before sending the C-FIND-REQ to the server, allowing you to customize the attribute list. Once the C-FIND-REQ process is completed, the AfterCFind event is called. In addition, more detail instance level query attributes are sent to the server based on the series modality as recommended in the IHE Radiology Technical Framework for the following queries:

• Presentation State Specific Query
• Evidence Document Instance Specific Query
• SR Instance Specific Query
• Key Image Note Instance Specific Query

Steps for Querying a Server

1. Configure the Remote SCP (A sample SCP is installed as part of the LEADTOOLS PACS Framework installation)

   1. Create a new instance of DicomScp

   2. Initialize the following properties:

      1. AETitle
      2. PeerAddress
      3. Port

2. Build a matching query filter

   1. Create a new instance of the FindQuery class.
   2. Initialize the query filter using the appropriate properties of the FindQuery class (i.e. PatientID, AccessionNumber, Date, etc.).
   3. Set the QueryLevel to the appropriate level (e.g. STUDY for a study level query)

3. Add C-FIND response handles

   1. Add the following event handlers to handle the query response from server:
      1. QueryRetrieveScu.MatchStudy Event
      2. QueryRetrieveScu.MatchSeries Event
      3. QueryRetrieveScu.MatchInstance Event
      4. QueryRetrieveScu.AfterAssociateRequest Event to identify any problem with the association.

4. Send a C-FIND Message

   1. Create a new instance of the QueryRetrieveScu class
   2. Call the QueryRetrieveScu.Find Method and pass the instance of DicomSCP and FindQuery object to send a C-FIND-REQ message to a PACS Server defined by the DicomSCP.

5. Canceling a C-FIND process

   1. Call the QueryRetrieveScu.CancelRequest method to cancel the current C-FIND action

6. Aborting a connection

   1. Call the QueryRetrieveScu.AbortRequest method to abort the current connection

For a detailed example of querying a server please refer to the QueryRetrieveScu documentation as well as the DICOM High Level Client Demo installed as part of the LEADTOOLS PACS Framework Installation.

Retrieving Objects from DICOM Server

The QueryRetrieveScu class is also used for retrievals using the C-MOVE operation. Send a C-MOVE-REQ message to the server to retrieve the object to itself or to move it to another server. Three overloaded Move methods move objects at three levels (i.e. Study, Series, Image) of the Study Root Query/Retrieve Information Model -- MOVE (1.2.840.10008.5.1.4.1.2.2.2) SOP class.

The object retrieve service is typically performed in conjunction with the query service. Send the C-MOVE-REQ message to the PACS server having the AE Title of Retrieve AE Title when the object instance availability is ONLINE or NEARLINE. This information is provided in the Availability and RetrieveAETitle property in the appropriate query matching events (e.g. MatchStudy, MatchSeries, MatchInstances) of the query process.

The QueryRetrieveScu class also supports both Hierarchical and Relational moves when such extended negotiation is supported by the SCP. The object also invokes BeforeCMoveEvent before sending a C-MOVE-REQ to the server, allowing customization of the attribute list. Once the C-MOVE-REQ process is completed the AfterCMove event is called. At any time during the C-MOVE process and before the AfterCMove Event is called, the process can be cancelled by calling the CancelRequest method.

Steps for Retrieving Objects from Server

1. Configure the Remote SCP (A sample SCP is installed as part of the LEADTOOLS PACS Framework installation)

   1. Create a new instance of the DicomScp

   2. Initialize the following properties:

      1. AETitle
      2. PeerAddress
      3. Port

2. Add response event handlers

   1. Add the following event handler to handle the move request response from the server:
      1. QueryRetrieveScu.AfterCMove Event
      2. QueryRetrieveScu.AfterAssociateRequest Event to identify any problem with the association.

3. Send a C-MOVE-REQ Message

   1. Create a new instance of the QueryRetrieveScu class
   2. Call the appropriate overloaded QueryRetrieveScu.Move method based on the level of the move (i.e. Study level, Series Level etc.), and pass the AE Title of the move destination server and remote SCP object.

An alternate option is to call the Move method of the Study Class, Series Class or CompositeObjectInstance Class from the MatchStudy, MatchSeries, or MatchInstance events when used in conjunction with the QueryRetrieveScu.Find method when InstanceAvailability is set to "online" or "nearline". Note that the DicomScp should be initialized to RetrieveAETitle server.

1. Canceling a C-MOVE process

   1. Call the QueryRetrieveScu.CancelRequest method to cancel the current C-MOVE action.

2. Aborting a connection

   1. Call the QueryRetrieveScu.AbortRequest method to abort the current connection.

For a detailed example of retrieving objects from a server please refer to the QueryRetrieveScu documentation as well as the DICOM High Level Demo Client installed as part of the LEADTOOLS PACS Framework Installation.

When the DicomConnection.AETitle is the same as the DestAE argument of the Move method and DicomConnection.HostPort is initialized with an available open port, the QueryRetrieveScu object will start a DICOM listening service in order to receive DICOM objects from the server via the DICOM storage service (C-STORE). This built-in DICOM listener service listens to the host port for incoming DICOM connections and will only accept an AE with a calling AE Title that matches the Move Server. Each time the listener service receives a Storage SOP Class object instance it calls the OnReceiveCStoreRequest handler to handle the dataset. Once the C-MOVE process is completed, the built-in storage SCP will shut down.

During the Association process all Storage SOP Classes in any transfer syntaxes supported by this version of LEADTOOLS are accepted. This acts as the SCP for the Storage SOP Class.

Logging DICOM Transactions

The DicomSCU object can automatically log all bidirectional DICOM message transactions between the remote server and itself. Simply configure a path for the log file using the DebugLogFilename property and turn on logging by setting EnableDebugLog to true.

To record additional information and DICOM datasets call the overloaded Log method. In addition, lower level access to all connection and message transactions are provided, allowing more customization and to use detail logging for communication-level trouble-shooting.