Tag Archives: Print SCU

Please note that adding these custom elements to DICOM Printer 2 workflows is a task that requires a little knowledge of XML. If you feel that the post is too technical for you, then ask someone with IT experience to help.

Recap

In our previous post, we went through installation and configuration of basic film output. Although this is great for basic use, most facilities we’ve come across like to see their identity expressed on their product.

So, we’ll want to go from this:

To this!

First Things First

In the previous post, we used the Configuration Wizard. The Wizard does the basics, but to add a logo we need to dig into the actual configuration file. To see it, launch the DICOM Printer Control Center. It can be found via the Start Menu, or by searching in Windows 8.

You will then see the main control window.

Switch to the Configuration tab. If you followed the previous tutorial, you will see the following text:

The text box will be 80% wide and 3% tall, with the font automatically adjusted to fit.

The foreground colour will be white (0xFFFFFF) and the background will be a semi-transparent (0x80), black (000000) rectangle. This will allow the text to be read even when overlaying part of the image.

The completed configuration, with the addFooter action added to the workflow, looks like this:

This is the first in a series of posts explaining how to use DICOM Printer 2. It’s a complex tool, with some very simple uses. Despite our best efforts to make the world wholly digital, this is one of the most popular!

Goal

To print true-size images of dental x-ray, with a facility logo in the corner of the film.

We’re looking to create something like this:

Note that:
1. There is logo at top left.
2. Patient information is outputted at top right.
3. Clinic information appears at the bottom.

This tutorial will go through the few steps required to output the image. We will tackle the logo and patient demographics in a separate post.

The Setup Wizard will take you through the process and then offer to run the Configuration Wizard. In the first screen, select Film Printer:

You will be presented with the following screen:

Select our imager model family from the drop down, e.g., AGFA Drystar 5300. If you don’t see your imager, select Generic, or the closest match from the same vendor.

If you choose Generic, then be sure to look up your imager dot pitch and enter it into the Standard Resolution field. The best place to find this is usually the imager brochure from the manufacturer website.

If the imager brochure lists the dot pitch in microns, then you can convert this value to DPI using Google. For example, if your imager lists a 50 micron dot size, then Google ’50 microns to inches’, then divide 1 by the result. The answer in this case 1 / 0.00196850394 = 507.9, or 508 x 508.

You should probably leave the defaults unchanged for this example.

Enter the Printer AE Title, IP Address and Port Number of the imager.

Then click Commit!

You’re Ready to Print!

Launch your application and Print, then select the DICOM Printer 2 printer from the print dialog.

Introduction

DICOM Multi-tool (“DMT”) is a multi-purposed DICOM engine. It was originally written to provide functionality for specific medical devices, but has been authored in such a way that it can be used in a variety of contexts, including Query, Store, Move, Print and Worklist in both SCU and SCP roles.

The following sections are extracted from the DMT manual, with the aim to provide a concise and relevant peek at the fundamental usage paradigm. Our purpose here is to provide an instantly usable example, which is why this document contains a little more by way of actual links, and specific procedures, which do not normally form part of our documentation.

Getting DMT

Downloading DMT for Testing Purposes

A working copy of the DICOM Multi-tool is available via the following link:

This package includes the binaries, as well as a set of selected example queries. After installation, please explore the Start Menu for new links.

Note: Build 91 of DMT, which has been selected for this example, is out of date. Although contemporary request syntax has changed somewhat from this version, it is still more then adequate for this purpose.

Installation

Two modes of installation are available, generic and silent, which can be selected using a command-line argument.

Silent Mode Installation

In silent mode no window is shown and every parameter is either set to its default value, or overriden with additional comman-line arguments. Thus far, three arguments have been exposed — program files location, whether to install as a service, as well as where to store the configuraton file.

Generic Mode Installation

Generic mode of installation is the default. It allows the user to select a program files location path and whether or not to install the DICOM Multi-tool service.

This mode of installation will occur when you double-click the installation package. Please do so now and follow on-screen instructions. You may be asked to reboot your computer after installation has completed.

Usage

Basic Principles

DICOM Multi-tool listens for incoming requests on one of selected communication channels. Requests are text-based — they have a very similar format to HTTP requests — and allow the caller to engage and monitor a single DICOM service, retrieve application status, check log entries and, if necessary, terminate the application.

Requests to start a DICOM service always require a number of parameters. They take the form of an XML document, each one specific to a given task.

The following is an example of a request to start a client that stores all .dcm files in a specified folder to a PACS running at 127.0.0.1 and port 104 using the RLE Lossless format (other formats include JPEG, RAW, etc):

Once a request is read, DICOM Multi-tool attempts to parse it and invoke the specified function or task. Results are passed back to the caller using similar, HTTP request-based, responses.

Responses indicate status of the operation and can provide intermediate results for some of the tasks. For example, when a DICOM query client is used, every response contains a single matching record. Such pieces of data are also embedded in XML documents.

The format of both requests and responses is covered in detail in the DMT Manual.

Start-up Modes

DICOM Multi-tool can be used in two modes: as a standalone console application, or as a Windows service. The following table shows the differences. They are covered further.

Standalone

Service

Can be executed using a path stored in the registry

Starts automatically with Windows. Can also be executed or terminated using the native Windows service controller or by invoking the application with specific command-line arguments

Supports both communication channels (network and console)

Supports only network communciation

Settings can be provided only using command-line arguments

Loads settings from the configuration file

Sends log messages to the console and stores them internally

Log messages are only stored internally and are available on request

Standalone Start-up Mode

In standalone mode DICOM Multi-tool starts as a typical Windows console application. The software setup program creates a link to it in the Start Menu, allowing easy execution. You can also do this manually using a command-line interpreter (cmd.exe). Just change the directory to where the DICOM Multi-tool has been installed and start it, passing the -e parameter, e.g.

Note: When showing outut of Windows command-line interpreter, for the sake of readability we remove current directory path and replace command-prompt with UNIX-style $ mark.

In order that you may access it from within your application, the setup program stores the full path to the DICOM Multi-tool executable in the Windows registry. This value is stored in the following key: HKEY_LOCAL_MACHINE\SOFTWARE\Flux Inc.\DICOM Multi-tool under the Program Path name and is of type REG_SZ.

By default in standalone mode DICOM Multi-tool accepts requests and provides responses using the console. You can change this behaviour by providing a -communication-channel NETWORK argument right after the -e switch.

Hint: A full listing of command-line arguments and registry settings is provided in Appendices A and B at the end of the DMT Manual.

Standalone mode is used mainly for testing purposes but can also be invoked in a production environemnt; for example, when access to system services is constrained.

Service Start-up Mode

Unless selected otherwise, the DICOM Multi-tool installation program creates a new system service in Windows, called “DICOM Multi-tool” and configures it to start automatically with the operating system. You can query the current state of this service by executing the DICOM Multi-tool program with a -v switch, like so:

In order to start the service, you can either invoke the executable without any parameters, or use system tools availble in windows, e.g.:

$ net start "DICOM Multi-tool"
The DICOM Multi-tool service is starting.
The DICOM Multi-tool service was started successfully.

With DMT service you can communiate only using network connection.

Communication

Messages

As mentioned in the introductionary part above, communication between DICOM Multi-tool and users is conveyed using text-based, HTTP-like, messages:

requests are created by a user and sent to the Multi-tool,

responses are sent back by the application.

Structure Overview

There are two main sections contained within both request and response messages.

Each message contains a header comprised of plain text and encoded using strict rules.
The first element of every header contains a message-specific string followed by a line feed character. For requests this string specifies a command to be executed, e.g. QUIT. For responses, it indicates a status like ERROR 3.

Following the first, special, line are header fields. Header fields are colon-separated name-value pairs, also in a plain text string format and terminated by a line feed character. The last header field must be terminated by two line feed characters, indicating the end of the entire header.

The following is an example of a request header, with line feed characters indicated by <LF> marks:

Immediately following the header is the message body. This portion is optional and can contain virtually any information. Currently, however, the message body supports storage of only a single XML document with command arguments (in case of requests) or operation results (in case of responses). For example, the following are DICOM query client arguments stored in the body of a request message:

Hint: Message syntax is described using EBNF notation in the DMT Manual.

Requests

The first line of every request message must specify a command to be executed by the Multi-tool. The most common command is the START command, which tells DMT to start a DICOM service or some other task. Immediately following the START string there must be a space character and then a service or task name.

Subsequent lines

Version, mandatory, tells the applicaton what is the version of this request,

Date, optional, the date and time of when this request was sent,

Expires-After, optional, default 30, specifies number of seconds Multi-tool has to process this message (Note: to process, not to perform the task!). When no Date is provided, the timer starts when the first line of the request is received.

Body-Type, mandatory when body is present, specifies body format using Internet media type identifier (see. RFC 2046). Only the text/xml and application/xml formats are supported at the moment,

Body-Length, specifies number of bytes (octets) comprsing the body. Required when Body-Format indicates a format inappropriate for streaming.

Hint: Since prsently only XML documents can be stored in the message body this field is optional, allowing clients to write XML directly to pipe or socket and not witholding it in order to calculate the length.

Responses

Since complete integration is not an aim of this document, this section has been omitted. Response format is defined in detail in the DICOM Multi-tool Manual.

Learning by Example

Now we’re ready to proceed to a concrete example. First we walk through installing some supporting tools, and then proceed directly to authoring a simple request, and receiving a response.

Preparing Some Tools

A large portion of the testing of any DICOM application can be performed using one or more of the tools provided as part of the Offis DCMTk toolkit. This toolkit contains binaries for storage, echo, and query, as well as those for about two dozen additional contexts.

For example, using DCMTk you can run a simple PACS (storescp.exe), which stores to a local folder, and responds to queries (findscp.exe). You can also echo this PACS using echoscu.exe and run queries using findscu.exe.

We will only use one of the DCMTk binaries, storescp.exe, for this example, but obtaining the entire kit will assist you greatly with any future DICOM development.

Using DCMTk as a Store SCP

Included within the DCMTk archive appropriate for your platform, is storescp (storcescp.exe on Windows), which can be used to run a simple SCP that responds to C-ECHO requests and stores files in a local folder.

To create a simple Store SCP, simply drop into a command shell, navigate to the DCMTk binary folder, and run:

$ storescp.exe -v 10104

This creates an instant daemon that stores all received DICOM datasets into sub-folders of the current path. The SCP will accept storage requests on port 10104 from any AE title, and does not require any particular destination AE title be specified.

Example: DICOM Multi-tool Echo SCU

In this example, we will be creating a simple Store SCP using DCMTk and performing a C-ECHO request using DICOM Multi-tool. The purpose of this example is to familiarise the reader with one of the available invocation and communication interfaces.

Onward

First, add DICOM Multi-tool to your path:

Open up the Advanced System Properties of your Windows installation, and add the following to your PATH:

%PATH%;C:\\Program Files\\Flux Inc\\DICOM Multi-tool

Start a command shell and run:

$ DicomMultiTool.exe

The command should execute, and wait for command input. This will produce no output, but the tool will continue to accept characters you type until you press ctrl-c, which you should do now.

Create a Store SCP

Next, create a simple Store SCP, using DCMTk’s storescp utility — this is essentially a mini-PACS. If you haven’t yet installed DCMTk, then please follow the instructions located earlier in this document.

To create a simple Store SCP using DCMTk, run:

$ storescp -v -d 10104
D: $dcmtk: storescp v3.6.0 2011-01-06 $
D:

The -d and -v arguments cause storescp to output the verbose information above. This process will continue to listen for connections on port 10104 until you press ctrl-c.

Create the C-ECHO Request

Now we create a Verification SCU request XML document, and invoke DMT for the actual request.

Open a command shell, and make a copy of the Echo SCU example to the %TEMP% folder:

Note: A perceptive reader will notice that the syntax of this requests is a little different than the one provided earlier in this document. That is because build 91 is older, and we’ve made the syntax a smidgen more readable since then. The key difference in newer versions is that the request body no longer needs to be enclosed in a CDATA block.

Save the XML, this is now our complete request.

Invoke DMT and Pass the Request

That’s it, we’re ready to run DMT, to do this:

Make sure the Store SCP is still running in an open command window.

Open a new shell or find one that’s available.

Pass the request to a new instance of DICOM Multi-tool:

type %TEMP%\01.xml | DicomMultiTool.exe

Note: The format of this command is necessary because DMT accepts requests using STDIN, and passes results using STDOUT. Non-console modes of operation, such as using TCP requests, would obviously not involve this syntax.

Result

Assuming all goes well, the command above will produce the following output:

Success! Our Echo request is complete. A quick look at the DCMTk command window will reveal the association log and more detailed information, which is not particularly relevent for actual use, but can be informative when troubleshooting.

Conclusion

We hope this example has served to illustrate basic DICOM Multi-tool use. If you wish to learn more, then please contact us immediatley. We love to drone on and on about the most obscure aspects of our code and we look forward to hearing from you so that we may bore you nearly to death.

Supplement

Installing DCMTk binaries on OS X

To obtain DCMTk for Mac, make sure you have the latest version of Xcode installed, as well as Homebrew, and then run:

Once you’ve done this, the binaries are available for use in any directory.

Installing DCMTk binaries on Ubuntu

To install on any Debian-based OS that supports Aptitude, run:

sudo apt-get install dcmtk

This automatically installs the libraries and permits use from any path.

Note that if you will be testing DMT from a Windows machine against services running on a posix box, then you will likely have to adjust the IP addresses in examples to reflect this structural dichotomy.