DICOM Basics - Viewing DICOM Images

This is part of my series of articles on the DICOM standard. If you are totally new to DICOM, please have a quick look at my earlier article titled “Introduction to the DICOM Standard” for a quick introduction to the standard. It might be useful to also look at my other three tutorials listed below to understand what is inside a DICOM file:

  1. DICOM Basics - Making Sense of the DICOM File

  2. DICOM Basics - Creating a DICOM File

  3. DICOM Basics - Extracting Image Data

This tutorial also assumes that you know the basics of Java or any equivalent object-oriented language such as C# or C++.

Introduction

This tutorial that will illustrate how to implement some basic operations such as viewing (single and multi-frame images) as well as window width and level operations. Radiologists and other users of DICOM images do far more than these operations. I will cover some of these more advanced image manipulation operations such as zooming, rotation, measurements, overlays/annotations, etc after I have covered some additional background necessary to understand these operations better in this series. So let us proceed to understand the basics.

Before We Get Started…

Much like my previous programming examples, I will use the most bare minimum code and approach to help illustrate the concepts that I cover in this tutorial. This means that the code I write here is best suited to simply show the concept that I am trying to explain and is not necessarily the most efficient code to deploy in real life and in a production environment.

To get started, you will need to configure a few things on your machine including a Java development environment as well as the PixelMed toolkit before you can run the example if you want to try this out yourself.

  1. Download and install the Eclipse Java IDE from here (or use any other IDE you prefer)

  2. Download the PixelMed toolkit library from here

  3. Ensure that the PixelMed.jar library (and any runtime dependencies required) are included in your Java project’s class path

  4. You can find the source code and the jpeg image used in this tutorial on GitHub

  5. You can download more DICOM images from this site if you want as well

Implementation Details

The PixelMed library provides a number of classes to enable us to display DICOM images. These classes are all located in the com.pixelmed.display package as you might expect. The SingleImagePanel class is the simplest one that we will require to implement DICOM image-related viewing, frame navigation and window width/level operations. This class has a constructor that take an instance of the SourceImage class (also from the com.pixelmed.display package) as a parameter. To make this class easier to demonstrate, I have overridden the SingleImagePanel class with some additional behavior. This new overridden class OverriddenSingleImagePanelForDemo has behavior to listen to both key and mouse events to perform both frame navigation and as well as update window width/level information on the screen. The SingleImagePanel class already has an implementation to perform frame navigation listening for mouse wheel scroll operation, but I am providing another implementation here to make the visualization easier for beginners. A JFrame class from the Java swing library is used as a container for the SingleImagePanel class. This is all we need. The main class that runs this entire demo is shown below.

    package com.saravanansubramanian.dicom.pixelmedtutorial;

    import java.awt.Color;
    import javax.swing.JFrame;
    import com.pixelmed.display.SourceImage;

    public class ViewScrollAndWindowWidthAndLevelingDemo {
        
        public static void main(String[] args) {
            String dicomInputFile = "D:\\JavaProjects\\Sample Images\\XA-MONO2-8-12x-catheter";
            try {
                JFrame frame = new JFrame();
                SourceImage sImg = new SourceImage(dicomInputFile);
                System.out.println("Number of frames: " + sImg.getNumberOfFrames());
                ImagePanelDemo singleImagePanel = new OverriddenSingleImagePanelForDemo(sImg);
                frame.add(singleImagePanel);
                frame.setBackground(Color.BLACK);
                frame.setSize(sImg.getWidth(),sImg.getHeight());
                frame.setTitle("Demo for view, scroll and window width/level operations");
                frame.setVisible(true);
                
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    }

“The greatest part of a writer’s time is spent in reading, in order to write: a man will turn over half a library to make one book.” ~ Samuel Johnson

Run the ViewImageWithWindowWidthAndLeveling class below (making adjustments to the code to point to any multi-frame DICOM image as necessary, or use the one that I uploaded along with the source code). This will launch a window. Highlight this window, and press the left or right keyboard button for instance and hold that button down and you will be able to navigate through the frames one at a time or continuously depending on how long you hold it down. This will give you an idea of what a cine-loop might look like. This is how one can scroll through a multi-frame DICOM image.

Now, click and drag the mouse on this window from left to right to control window width. Or, click and drag the mouse on this window from top to bottom for window level or centering. The screen capture below shows the code needed to achieve this behavior. As you can a lot of functionality is already provided by the SingleImagePanel class. The screen capture of the window showing the image as well as additional information regarding the image such as window width, level as well as the frame number are shown below the code illustration below as well.

    package com.saravanansubramanian.dicom.pixelmedtutorial;

    import java.awt.Color;
    import java.awt.Font;
    import java.awt.event.KeyEvent;
    import java.awt.event.MouseEvent;
    import com.pixelmed.display.SingleImagePanel;
    import com.pixelmed.display.SourceImage;
    import com.pixelmed.display.event.FrameSelectionChangeEvent;
    import com.pixelmed.event.ApplicationEventDispatcher;
    import com.pixelmed.event.EventContext;

    public class OverriddenSingleImagePanelForDemo extends SingleImagePanel {
        
        //initialize these to some default values
        private static final long serialVersionUID = 1L;
        private int frameIndex = 0;
        private int MaxFrames = 1;

        public OverriddenSingleImagePanelForDemo(SourceImage sImg) {
            super(sImg);
            MaxFrames = sImg.getNumberOfFrames();
            this.setSideAndViewAnnotationString(getTextToDisplay(1),30, "SansSerif",Font.BOLD, 14, Color.WHITE,true);
        }

        private String getTextToDisplay(int frameIndexNumber) {
            return " Window Width->" + (int) this.windowWidth 
                    + " Level(or Center)->" + (int) this.windowCenter 
                    + " Frame Index->" + frameIndexNumber;
        }
        
        @Override
        public void keyPressed(KeyEvent e) {
            super.keyPressed(e);
            if(frameIndex == MaxFrames){ //this is to reset the frame loop
                frameIndex = 0;
            }
            ApplicationEventDispatcher.getApplicationEventDispatcher()
            .processEvent(new FrameSelectionChangeEvent(new EventContext("Pass info here"), frameIndex++));
            UpdateDisplayInformation();
            
        }

        private void UpdateDisplayInformation() {
            this.sideAndViewAnnotationString = getTextToDisplay(frameIndex);
        }
        
        @Override
        public void mouseDragged(MouseEvent e) {
            super.mouseDragged(e);
            UpdateDisplayInformation();
        }

    }

DICOM Window Width/Level Demo

This concludes this short but hopefully useful tutorial on implementing simple view operations on a DICOM image file. Like I said earlier, I will be coming back to this topic to cover more advanced scenarios such as zoom, rotate, measure and annotate operations in a future tutorial. However, in the next tutorial in this series, I will show how to read as well as create DICOM directories as these enable us to manage large numbers of images that are often generated by most modalities such as CT, MR or ultrasound. If you have any questions or comments regarding this tutorial, please feel free to send me an email. Please note that I may not get back to you right away due to work and other commitments.

Footnote: The DICOM standard restricts the file names/identifiers contained within to 8 characters (either uppercase alphabetic characters and numbers only) to keep in conformity with legacy/historical requirements. It also states that no information must be inferred/extracted from these names. The file names usually don’t have a .dcm extension when they are stored as part of a media such as CD or DVD. I use longer names to keep these details from being a distraction right now, but I still want to mention what the standard states here so that no confusion arises as a result.