Saving DICOM Images

Save DICOM images in the same way as you save images of all other formats, using one of the Formats Component saving methods. You can use Page or Document saving modes, and all Image Sources that are supported for writing by the Formats Component. Use DICOM Filter Control Parameters to control saving of the DICOM images. See also Using ImageGear MD Component.

The important requirement for saving a DICOM image is that the image must have a DICOM DataSet structure attached to it. If it does not have a DataSet, the saving function will return an error. If the image being saved out was originally a DICOM image (and assuming that you have not altered its Data Set to contain illegal values), you can save it by simply calling one of the IGFormatsCtl Control saving functions.

If the image was loaded from a non-DICOM file, you need to add a DataSet to the image, and fill it with appropriate Data Elements. Please remember that it is up to you to add all the Mandatory Data Elements to make it a valid DICOM file. When you create the Data Set, a handful of basic Data Elements are added to it. These values were taken from the image. Note that they are not sufficient to satisfy the requirements of the DICOM Standard. For instruction on how to create and fill a Data Set see the section Working With DICOM Data Structures.

You can specify a compression when saving a DICOM image file. The following table lists supported compression modes and the corresponding DICOM Transfer Syntaxes:

IG_COMPRESSION_NONE	MED_DCM_TS_IMPLICIT_VR_LE
IG_COMPRESSION_JPEG	MED_DCM_TS_JPEG_LOSSY
IG_COMPRESSION_RLE	MED_DCM_TS_RLE
IG_COMPRESSION_JPEG2K	MED_DCM_TS_JPEG_2K

Use SAVE_SYNTAX control parameter to save a DICOM image with other Transfer Syntaxes.

Saving DICOM Images with JPEG Compression

ImageGear supports the following modes for saving JPEG compressed DICOM images:

JPEG Lossy Baseline or Extended

This is the default mode for saving DICOM images with JPEG compression in ImageGear. In this mode, depending on the channel depth of the source image, ImageGear saves it as either 8 bits per channel, using "JPEG Baseline (Process 1)" transfer syntax, or as 9..12 bits per channel, using "JPEG Extended (Process 2 & 4)" transfer syntax.

Use one of these ways to save an image as DICOM JPEG Baseline or Extended:

Save the image, passing IG_FORMAT_DCM | IG_COMPRESSION_JPEG << 16 to the SaveFormat parameter. JPEG control parameter SAVE_TYPE should be set to IG_JPG_LOSSY. DICOM control parameter SAVE_SYNTAX is ignored.
Save the image as IG_FORMAT_DCM. Set DICOM control parameter SAVE_SYNTAX to either MED_DCM_TS_JPEG_LOSSY or MED_DCM_TS_JPEG_EXTENDED_PR_2_4. JPEG control parameter SAVE_TYPE is ignored.

JPEG Lossy Baseline Only

This mode provides compatibility with viewers that do not support JPEG Extended coding process (12-bit images). In this mode ImageGear saves images as 8 bits per channel, using "JPEG Baseline (Process 1)" transfer syntax. If the image has greater bit depth, ImageGear reduces it to 8 bits per channel for saving.

To save an image as DICOM JPEG Baseline, use IG_FORMAT_DCM saving format. Set DICOM control parameter SAVE_SYNTAX to MED_DCM_TS_JPEG_BASELINE_PR_1_ONLY. JPEG control parameter SAVE_TYPE is ignored.

For compatibility with earlier versions of ImageGear, MED_DCM_TS_JPEG_BASELINE_PR_1 constant has the same meaning as MED_DCM_TS_JPEG_LOSSY: the image is saved using either Baseline or Extended process. To save with the Baseline process, make sure to use MED_DCM_TS_JPEG_BASELINE_PR_1_ONLY constant.

JPEG Lossless

In this mode, depending on the channel depth of the source image, ImageGear saves it as 8...16 bits per channel, using "JPEG Lossless, Non-Hierarchical (Process 14)" transfer syntax.

Use one of these ways to save an image as DICOM JPEG Lossless:

Save the image, passing IG_FORMAT_DCM | IG_COMPRESSION_JPEG << 16 to the SaveFormat parameter. Set JPEG control parameter SAVE_TYPE to IG_JPG_LOSSLESS. DICOM control parameter SAVE_SYNTAX is ignored.
Save the image as IG_FORMAT_DCM. Set DICOM control parameter SAVE_SYNTAX to either MED_DCM_TS_JPEG_LOSSLESS, or MED_DCM_TS_JPEG_LOSSLESS_FIRSTORDER. JPEG control parameter SAVE_TYPE is ignored.

Saving a Multi-Frame DICOM Image

ImageGear Medical component allow the saving of single-frame as well as multi-frame (multi-page) images.

Use the following steps to create a multi-frame DICOM image from an individual IGPage Object:

Create or load first frame into IGPage Object.
Create the DataSet if it is not present.
Add the DCM_TAG_NumberOfFrames tag to the DataSet, if it is not present. Value of this tag is irrelevant but its presence is necessary.
Save the image using any standard ImageGear saving function. (Saving functions from Medical component do not support saving multi-frame images.)
* Create or load second frame into IGPage Object.
Create Data Set if it is not present.
Add the DCM_TAG_NumberOfFrames tag to the Data Set, if it is not present.
Save the image, specifying the same file name that you used for the first frame.

* Repeat for all consequent frames.

Use the following steps to save an IGDocument Object as DICOM:

Create or load all pages of the IGDocument Object.
Add DataSets to all pages of the document, if they are not present.
Add the DCM_TAG_NumberOfFrames tag to the DataSet, if it is not present. Value of this tag is irrelevant but its presence is necessary.
Save the Document.

It is important to note that only a few DICOM modalities allow the presence of multiple frames in the image, while the others do not. When you try to add a frame to an existing DICOM file, ImageGear checks the file for presence of the NumberOfFrames (0028, 0008) Data Element. If it is present ImageGear tries to append the frame, otherwise ImageGear considers the file as belonging to a single-frame modality and returns an error.

Several limitations that are imposed by the DICOM standard are listed below.

All frames of the image must have same dimensions, bit depth, and photometric interpretation. All frames must use the same Transfer Syntax (compression). ImageGear returns an error if these conditions are not met.
ImageGear Medical only supports appending a frame at the end of the DICOM image, but not insertion or overwriting of frames.
ImageGear Medical writes the DICOM DataSet only when writing the first frame, and does not modify it when adding frames. The only exclusion is the "Number Of Frames" Data Element, which is always kept consistent with the actual number of frames.
Number of Frames Data Element has the Value Representation of Integer String. i.e., the integer value is represented by an ASCII string. ImageGear Medical uses all of the 14 positions for storing the Number of Frames Data Element. This allows rewriting Number of Frames without shifting the whole DataSet. ImageGear Medical will not append a frame to a file where Value Length of the Number of Frames DE is less than 14 (for example, if the file has been created by some other vendor).

If you need to insert or delete a frame, or modify DataSet in the DICOM image, create a new image with the modified DataSet, copy necessary frames to it, and then delete the original image.