Trispark Java DICOM Toolkit User Guide

If you have downloaded an installer distribution, run the installer. If you have downloaded JDT as a zip file, unzip the file into a directory of your choice.

The Trispark Java DICOM Toolkit is a small footprint 100% java library and API for building DICOM applications. The library has the following features:

Customers having purchased a distribution license and/or source code license are entitled to one year of technical support via email starting from the purchase date. The support also includes minor updates and bug fix releases.Support can be renewed annually.

If you have any technical questions contact support@trispark.com.

This software library requires a basic understanding of the DICOM standard. The DICOM standard is quite an extensive standard published by National Electrical Manufacturers Association 1300 N. 17th Street Rosslyn, Virginia 22209 USA

The official ACR/NEMA home page of the DICOM standard is medical.nema.org.

A very good site on DICOM with links to the various parts of the standard, correction proposals and supplements in PDF format is David Clunie’s Medical Imaging Format site.

The parts of the DICOM standard that are particularly relevant with respect to this library are:

The DICOM File Format is described in Part 10 of the DICOM Standard: "Media Storage and File Format for Data Interchange". A DICOM file consists of a file header followed by a File Meta Information Data Set and a Data Set representing a single SOP Instance.

DICOM files and raw Data Sets (without the 128 byte preamble and group 0x0002) can be read from arbitrary inputstreams using the com.archimed.dicom.DicomReader class. The DicomReader class has a number of methods for reading DICOM data.

DicomObject read (java.io.InputStream in)

This method can read both raw data sets and DICOM files and will return a DicomObject containing all the data elements within the DICOM file or raw data set. When the supplied inputstream points a to DICOM File, the File Meta Information is also read and stored in a separate DicomObject retrievable with getFileMetaInformation(). When the supplied inputstream points to a raw data set, the transfer syntax of the data set is assumed to be Implicit VR Little Endian. See the other read methods for reading raw data sets in other transfer syntaxes.

The simplest way of using this method is with the following code:

DicomObject read (java.io.InputStream in,boolean readpixels)

This method does the same as the previous one but in addition allows you to specify whether to parse or skip pixel data during the reading. This method is mainly here for backwards compatibility. Skipping arbitrary tags can also be achieved by registering a TagReadListener on the DicomReader.

DicomObject read (java.io.InputStream in, int transfersyntax , boolean readpixels)

Use this method to read a raw data set. The transfer syntax is not detected but must be specified. Note: The DicomObject class also contains a number of read methods. These methods are maintained for backwards compatibility. New implementations should use the DicomReader class to read DICOM files and data sets.

A TagReadListener makes it possible to listen to the reading of individual data elements and possibly modify the DicomObject while it is being read. TagReadListeners are registered with a DicomReader. During the reading of a DICOM file or raw data set, the DicomReader will fire a TagReadEvent just before reading the value field of a data element for which TagReadListeners are registered. The TagReadEvent contains a property dataReadStatus that determines how the value field of a data element is read after all listeners are notified:

READ_TAG_DATA After all the listeners have been notified the DicomReader will continue to read the value field of the data element normally as any other data element. This is the default.

SKIP_TAG_DATA The DicomReader will skip the entire value field of the data element and will place an empty data element in the DicomObject. The underlying inputstream will be moved forward to the beginning of the next data element by the DicomReader.

SKIP_TAG The DicomReader will skip the entire value field of the data element. No empty data element is places within the DicomObject. The underlying inputstream will be moved forward to the beginning of the next data element by the DicomReader.

NEXT_TAG The DicomReader assumes that one of the listener will read the value field of the data element and that when all listeners are notified, the inputstream is positioned just before the next data element or the end of the stream if this was the last data element in the data set.

DICOM files and raw datasets (without the 128 byte file header and 0x0002 group) can be written to arbitrary input streams using the com.archimed.dicom.DicomWriter class. The DicomWriter class has three write methods for writing to output streams. These methods allow you to control:

This method writes a DicomObject to an outputstream as a DICOM file or a data set depending on the boolean argument dicomfile.

File Meta Information: The File Meta Information to be used when writing a DICOM file, can be specified through the FileMetaInformation property of the DicomObject. If this property contains a non-null DicomObject, the File Meta Information data elements - data elements of group 2 - of the DicomObject contained in this property are used. If this property is null, the DicomReader generates File Meta Information with the following data elements:

Transfer Syntax: When writing a raw Data Set, the transfer syntax is Implicit VR Little Endian. When writing a DICOM file, the Transfer Syntax is determined by the FileMetaInformation. If no File Meta Information is specified, the DICOM file is written in Implicit VR Little Endian Transfer Syntax.

Sequence lengths: sequences are written with undefined length when this write method is used.

Group lengths: group lengths are generated and added to the data set during to writing to the outputstream.

This method writes a DicomObject to an outputstream as a DICOM file or a data set depending on the boolean argument dicomfile.

File Meta Information: The File Meta Information to be used when writing a DICOM file, can be specified through the FileMetaInformation property of the DicomObject. If this property contains a non-null DicomObject, the File Meta Information data elements - data elements of group 2 - of the DicomObject contained in this property are used. If this property is null, the DicomReader generates File Meta Information with the following data elements:

Transfer Syntax: specified by the transfersyntax argument.

Sequence lengths: sequences are written with undefined length when the value of the sequencesUndefined argument is true and written with defined length when the value is false.

Group lengths: group lengths are generated and added to the data set during to writing to the outputstream.

This method is identical to the previous write method with the exception that the generation of group length data elements can be turned on or off depending on the value of the groupLengths argument.

Note: The DicomObject class also contains a number of write methods. These methods are maintained for backwards compatibility. New implementations should use the DicomWriter class to write DICOM files and data sets.

The DICOM standard defines a number of data types known as value representations (VR) and specifies for every data element which value Representation to use for data typing and formatting the value(s) of that data element. Similarly the Java Language has a number of data types such as String,Integer,Float,…​ and JDT has defined a few extra custom types to represent values of data elements.

JDT contains two types of setters/getters to retrieve and modify values of data elements in a dataset:

Deprecation Note: Type unsafe getters and setters like DicomObject.set(java.lang.Object), java.lang.Object DicomObject.get() are deprecated and new implementations should avoid using them.

Type Map

The map below specifies the supported getters and setters of the DicomObject class and DataElement class. For example, the AE value representation has String and byte[] as supported types for typesafe setters and getters of DicomObject and DataElement. This means that for AE data elements the all set,add and get methods are supported that take or return a byte array or a String as an argument or return type. Other set, add or get methods will throw an exception.

The DICOM standard defines a registry of unique identifiers (UID) that are used throughout the standard. JDT has defined registry classes that hold these unique identifiers together with a description. More specifically JDT defines registry classes for

All UID registry classes have defined constants which are used to identify the UIDs contained in the registry.

All registry classes inherit from the com.archimed.dicom.UID superclass. Registry entries are represented as com.archimed.dicom.UIDEntry objects.

The class com.archimed.dicom.SOPClass represents every publicly defined SOP class as an int constant and as a constant of type SOPClassUID. For example, the Basic Film Box SOP class is both represented as

The class com.archimed.dicom.TransferSyntax represents every publicly defined transfer syntax as an int constant and as a constant of type TransferSyntaxUID. For example, the Basic Film Box SOP class is both represented as

The DICOM standard defines a registry of all public DICOM Data Elements. This registry assigns a unique tag, a name, a value representation and semantics to every Data Element that it contains. As the DICOM standard evolves, this registry grows together with the DICOM data model.

The com.archimed.dicom.DDict class represents the Data Element Registry. It defines a constant for every Data Element defined within the registry and it contains the Value Representation, group-element pair and description of every Data Element. The name of the constant is in most cases the concatenated description for the Data Element given in the DICOM Standard with the exception that illegal characters according to the Java syntax are removed. The DDict class has constants defined for:

The DDict class also defines constants for all Value Representations.

A number of set and get methods of DicomObject expect a DDict constant as one of it’s arguments to identify the Data Element for which to set or retrieve values.

A DICOM file and a Data Set are represented in memory by an object of class com.archimed.dicom.DicomObject. This class acts as a container of Data Elements. Depending on the Value Multiplicity a Data Element can hold one or more values. Data Elements can also be empty , which means that they are present in the Data Set or DICOM file but they don’t contain any values: the length of their value field is 0. The Java type of the retrieved values follows the Java-DICOM type map.

The DicomObject class contains set and and append methods to add and update values of Data Elements. A Data Element can be identified by specifying a DDict constant or by specifying the group-element pair of the Data Element.

On a number of occasions it can be useful to generate a list of the Data Elements of a DICOM file as formatted text. This can be done directly with the DicomObject.dumpVRs methods or with the class com.archimed.dicom.DumpUtils that gives some more control over the formatting. Regardless of which method is used, all data elements are always listed in a tabular format with columns

To reflect the nested sequence structure of DICOM file, Data elements contained in sequences are indented. The size of the indentation is dependent on the sequence depth. Values of type OW or OB (eg: pixeldata) are cutoff at a fixed number of bytes.

The DICOM standard supports the usage of non-ASCII character sets for various value representations (see Dicom Standard Part V) . If a DICOM file or DICOM dataset has tag values encoded in other character sets than the default , the used character sets must be specified in the SpecificCharacterSet tag (0x0008,0x0005). In general this tag can be multi-valued as multiple character sets can be used in a single DICOM file or DICOM dataset with the code extensions technique.

When retrieving non-default charset encoded values out of DicomObjects, JDT will represent them as String objects hereby decoding the values in the dataset or DICOM file into a Unicode String. JDT relies here on the fact that Java Strings are Unicode and every used DICOM character set can be properly represented as a java String object. JDT will use the character sets specified in the SpecificCharacterSet tag when converting data element values into Java Strings.

Before DIMSE messages can be exchanged between AEs, an Association between the AEs has to be established. When your application is the initiator of DIMSE messages you need to create a TCP/IP network connection with the AE with which you want to exchange messages and request an Association over the TCP/IP network connection. The remote AE will either acknowledge or reject the Association request. Typically SCUs are the initiator of DIMSE messages and thus request the creation of an Association with remote AEs. For example a Storage SCU that wants to send a DICOM image to a Storage SCP , will typically create a TCP/IP connection to the Storage SCP and request an Association on the TCP/IP connection. Also SCPs sometimes need to request Associations when they need to send N-EVENT-REPORT DIMSE messages.

When a DICOM Application Entity is the Acceptor of Associations it must be able to listen to incoming Associate Request messages and respond with Acknowledge or Reject messages. Such application entities typically wait for incoming TCP/IP connection requests on a certain port number. Once a TCP/IP connection is established the application reads the incoming Associate Request message, processes the message and responds with an Associate Acknowledge or Associate Reject message. Application Entities that act as the SCP for Service Classes must be able to accept incoming association requests. Application Entities that act as an SCU for Service Classes that provide notifications through the N-EVENT-REPORT DIMSE message, must also be able to accept incoming Association Requests.

The functionality of listening to TCP/IP connection requests and establishing TCP/IP connections is not embedded within the JDT classes. Use the classes of the java.net package or an alternative TCP/IP network package to listen to and establish connections. JDT requires an inputstream and outputstream of an open connection for reading and writing data.

Typically applications that accept Association requests and provide the exchange of DIMSE messages over established associations, act as a server and must be able to handle a number of active associations concurrently. JDT makes no assumptions on the choice of server architecture and how the concurrent connections are managed.

After an association has been established between two AEs, the AEs can begin exchanging DIMSE messages. These messages are sent and received with the same AssociationIO instance used to establish the association.

DIMSE messages always have a Command part and can optionally have a Data Set carrying the data associated with the Command. For example the C-ECHO-RQ message , which is used in the Verification SOP Class , has no associated Data Set. The C-STORE-RQ message, used in the Storage Service Class, always has a related Data Set.

When two AEs are connected through an association, one AE will always take the role of invoking DIMSE-Service-User and will send Command Request Messages. The other AE will take the role of performing DIMSE-Service-User and will answer the Command Request messages with Command Response messages. Except for the C-CANCEL Command Request messages (C-CANCEL-FIND,C-CANCEL-MOVE and C-CANCEL-GET) every Command Request message has a corresponding Command Response message. For example the C-STORE-RQ message has a corresponding C-STORE-RES message.

A Command Request message can be answered with multiple Command Response messages. For example a C-FIND-RQ message used to query a PACS system with the Query/Retrieve Service class, can result in multiple C-FIND-RES messages being returned.

Every DIMSE message is sent in the context of a negotiated presentation context. The presentation context ID is used to identify in which presentation context a DIMSE message is sent.

The creation and handling of Command Request messages and Command Response messages is done with the com.archimed.dicom.network.Command class and the com.archimed.dicom.network.Dimse class. The Dimse class represents a complete Command Request or Command Response message including the used presentation context ID, the Command part of the message and an optional Data Set. The Command class represents the Command part of the DIMSE message. Because a Command is a special kind of Data Set, the Command class is a subclass of com.archimed.dicom.DicomObject.

See the topics on

for details on sending and receiving DIMSE messages as an invoking DIMSE-Service-User or a performing DIMSE-Service-User.

The invoking DIMSE-Service-User sends Command Request messages to a remote AE and receives Command Response messages from the remote AE. For DIMSE messages related to an operation service such as the C-STORE service or the N-CREATE service the invoking DIMSE-Service-User has the role of the Service Class User (SCU). For DIMSE messages related to a notification service - the N-EVENT-REPORT message - the invoking DIMSE-Service-User has the role of a Service Class Provider (SCP).

You use the static create methods of the Command class to create new Command instances for request messages and you use the Dimse class to create the actual messages containing the presentation context ID, the Command object and an optional Data Set. To send the messages, you must use the AssociationIO instance that was used for establishing the Association. For example to send a C-ECHO-RQ message to a remote AE, which never has an associated data set, you would typically do something like:

You must use the same AssociationIO instance for reading a Command Response message from the network than the instance used for establishing the Association and sending the Command Request. The read method of AssociationIO will return a Dimse object that contains the presentation context ID of the presentation context used for sending the Command Response, the Command itself and an optional Data Set.

The performing DIMSE-Service-User receives Command Requests after an association has been established. The same AssociationIO instance that was used to establish an association, must be used to read DIMSE Command Requests and write DIMSE Command Responses.

The following example shows the reception of a C-ECHO-RQ on an established association.

See Example2.java for a complete example of receiving a C-ECHO-RQ message and sending back a C-ECHO-RES message.

In general an association may be established with a number of accepted presentation contexts corresponding to different service classes. As a result a performing DIMSE-Service-User may not know in advance which type of Command Request it is going to receive and it should be prepared to receive multiple types of Command Requests and process them accordingly. The program structure must reflect this so that the program flow is determined by the type of Command Request that is received.

After the performing DIMSE-Service-User has received and interpreted a Command Request message, he answers with one or more Command Response messages. The Command class contains a number of static methods that create proper Command Responses for corresponding Command Requests. The methods will create Command Responses with a message ID corresponding to the Command Request specified in the first argument. The other arguments in the create methods are used the specify values of additional Data Elements present in the Command Response.

For example, to create a C-ECHO-RES response message for a C-ECHO-RQ request message:

After the exchange of DIMSE messages is completed, the requestor of an Association must release the Association. The requestor of the Association must send a Release Request message and the acceptor of the Association must respond with a Release Response message:

Under normal circumstances an Abort message is never sent to a remote AE. However, in the event that an exception occurs and the association with the remote AE must be terminated, you can send an Abort message with a source and reason parameter. For example:

Configuring TLS works in general by replacing the default socket factory with a com.archimed.dicom.network.tls.ConfigureTLSSocketFactory instance. Use the static factory method ConfigureTLSSocketFactory.getFactory to create a socket factory capable of creating TLS sockets with various cipher suites, TLS protocols, keystores and trust stores. For example:

Sockets created from this socket factory will encrypt according to the specified protocols and cipher suites. The enum class ConfigurableTLSSocketFactory.ConnectionProfile contains predefined TLS protocols and cipher suites according to the connection profiles BCP195 and BCP195 non-downgrading specified in the DICOM standard (PS 3.15)

All implementations of com.archimed.dicom.scu follow a common usage pattern.

The factory classes also contain a few methods that execute a complete DICOM network conversation including association establishment, performing an operation like a verification (DICOM ping) or store operation and then release the association.

All SCU instances are subclasses of the interface com.archimed.dicom.scu.SCU and share functionality to configure TLS and a number of common network parameters like timeouts:

Refer to Configuring Transport Layer Security for more information.

Use the com.archimed.dicom.scu.CEchoSCUFactory class to perform a DICOM ping (C-ECHO) to a remote device in one go:

When the ping is succesful, the call will simply return. When the ping fails, the call will throw an Exception.

If the network connection should be secure and other parameters like timeouts must be configured, do something like

Create a MultiCStoreSCU instance by using one of the factory methods of com.archimed.dicom.scu.CStoreSCUFactory. The various factory methods differ only in how the DICOM SOP instances like images to be stored are specified:

When the DICOM SOP instances are specified as DicomObject instances or File objects, JDT will read them in fully in memory before sending the SOP instances down the network via a C-STORE (unless the DicomObject is constructed with BulkDataReference data elements).

When the DICOM SOP instances are specified as an Iterator of inputstreams, the SOP instances contained in the inputstreams are directly streamed onto the network encapsulated in a C-STORE request, hereby conserving memory usage. In this case all the combinations of SOP classes and transfer syntaxes that will occur in the iterator, must be specified upfront in the factory method, so that the proper association with support for all these combinations can be proposed.

Documentation pending…​

A C-GET is used to retrieve DICOM SOP instances like images from a remote DICOM device. Unlike a C-MOVE, the SOP instances are sent by the remote DICOM device via C-STORE requests over the same network connection and association that is used to for the C-GET request and response.

Use the CGetSCUFactory to create a MultiCGetSCU instance that can perform multiple consecutive C-GET request/responses and receive SOP instances via C-STORE request/responses.

When creating a MultiCGetSCU, the caller must specify the storage SOP classes and transfer syntaxes that need to be negotiated and supported in the association. SOP instances like images that match the specified identifier but have a SOP class or transfer syntax not negotiated , cannot be retrieved.

Create a MultiCMoveSCU instance by using one of the factory methods of com.archimed.dicom.scu.CMoveSCUFactory.

A MultiCMoveSCU is capable of sending C-MOVE requests and receiving C-MOVE responses. A MultiCMoveInstance has various executeCMove methods where one can optionally specify an implementation of com.archimed.dicom.scu.MultiCMoveSCUHandler to be notified of C-MOVE responses as they are received from the remote DICOM device.

A MultiCMoveSCU does not by itself run a Storage SCP and is as such not capable of receiving C-STORE requests. Use the com.archimed.dicom.network package classes to implement a Storage SCP that can be used in conjunction with the MultiCMoveSCU and receive SOP instances that are sent by the remote DICOM device as a result of the C-MOVE requests sent by the MultiCMoveSCU to the remote DICOM device.

Alternatively one can you use a MultiCGetSCU to retrieve SOP instances such as images with one network connection and association , initiated by the SCU.

Logging and interpreting log messages can be an invaluable tool during the debugging and testing of your applications and in general provides detailed information on the execution of code. JDT provides a small logging package com.archimed.log that is used internally by the other JDT packages to output log messages during the execution of various methods of JDT classes.

Because JDT is normally integrated into other applications, application developers may have already chosen an existing logging framework like for example Apache Log4J or the java.util.logging package. The com.archimed.log package does not make use directly of any existing logging framework but can be set up so that it delegates the generation of log statements to an underlying existing logging framework. In the absence of an existing logging framework, the package can generate log statements on its own.

By default, JDT is configured to use one instance of com.archimed.log.DefaultJdtLogger for writing all log messages from all the JDT classes. The DefaultJdtLogger class defines seven log levels comparable with the Log4J log levels. The default level is OFF which means no log messages are written. The DefaultJdtLogger class holds a reference to a single OutputStream to which all log messages are written and which is initialized to System.out.

For example, to set the output level to the ERROR level and to direct the output of log messages to System.err :

The logging mechanism in JDT is based on two interfaces:

The JdtLoggerFactory interface defines one method that returns references to JdtLogger implementing classes. The JdtLogger interface defines the necessary methods for logging messages at various log levels. A JdtLoggerFactory can be specified with the static setJdtLoggerFactory method of the com.archimed.dicom.Jdt class.

All JDT classes that use logging retrieve a reference to a JdtLogger by first retrieving the current JdtLoggerFactory and then retrieving a JdtLogger by using the getJdtLogger class of the factory.

For example the DicomObject class has declared:

By default, the installed factory is the com.archimed.log.DefaultJdtLoggerFactory which keeps a reference to a single com.archimed.log.DefaultJdtLogger instance. This factory can be replaced by another factory that returns different implementations of JdtLogger.

In general to replace the default logging with logging from an existing log framework, one has to:

As an example of replacing the default logging, two classes are provided that enable JDT to use Log4j as the logging framework:

The two classes wrap functionality of the org.apache.log4j.Logger class. To enable JDT logging using these classes the default factory must be replaced with this new factory:

From that point on , JDT will log messages according to the current Log4j configuration. For example, to enable DEBUG level logging on all classes of JDT one would typically do: