With the MD component loaded (see Attaching Components), your application is ready to load and save DICOM image files in addition to the file formats normally supported by ImageGear.

Loading DICOM Images

Load DICOM images in the same way as you load images of all other formats, using one of the Formats Component loading methods. You can use Page or Document loading modes, and all Image Sources that are supported by the Formats Component. Use DICOM Filter Control Parameters to control loading of the DICOM images.

Saving DICOM Images

There are several ways to save DICOM images using ImageGear. The functions included as part of the MD component API have a number of DICOM specific parameters. The others are included in the baseline API. You may need to pass the DICOM parameters to these functions via the Filter Control Parameters. You can also use the ImageGear's Multi-Page Image API to load and save multi-page (cine) DICOM images. The saving functions are listed below.

The important consideration in writing a DICOM image is whether the image being saved out was originally a DICOM image. If the image was originally a DICOM image (and assuming that you have not altered its Data Set to contain illegal values), the saving of such an image is quite a simple process. This section describes how to save an image that has a valid Data Set, how to use the DICOM-specific saving functions, and what Image Control options can be used to save the image when using the baseline functions.

Using the DICOM Specific Saving Function

MED_DCM_save_DICOM() saves the DICOM file using the name specified by the first argument. Here is a sample call:

   MED_DCM_save_DICOM("OmyBack.dcm", hIGear,
   MED_DCM_TS_JPEG_LOSSY_8, TRUE, TRUE,
   MED_DCM_PLANAR_PIXEL_BY_PIXEL, TRUE, 100, 0);

Notice that the setting for Transfer Syntax in the sample call indicates that JPEG compression should be used on the file. For this reason, the second-to-last argument nJPEGQuality is used. This is the quality setting for lossy JPEG compression. The setting shown (100) results in the highest quality that is possible using this compression scheme. If a different Transfer Syntax had been specified, the setting of nJPEGQuality would have been meaningless.

Note that DICOM is a multi-page format. When you save an image into an existing DICOM file, ImageGear tries to append this image at the end of the file. If, for some reason, appending the image is not possible, ImageGear returns an error. If you do not want to append a page, delete the existing file before saving to that filename, or use IG_fltr_save_file() with the bOverwrite parameter set to TRUE.

Using a File Descriptor

If you are saving a DICOM image to a file for which you have a File Descriptor handle, call MED_DCM_save_DICOM_FD(). Here is a sample call:

      MED_DCM_save_DICOM_FD(fd, hIGear, MED_DCM_TS_EXPLICIT_VR_LE, FALSE, TRUE,
MED_DCM_PLANAR_PIXEL_BY_PIXEL, TRUE, 0, 0);

Using Baseline ImageGear API Calls

ImageGear baseline API functions can also be used to save a DICOM image. However, as these functions do not contain any of the custom parameters for saving a DICOM image, you may need to make some Filter Control calls first. You will find the list of available DICOM filter control parameters for saving in the section DICOM Filter Control Parameters.

Here is an example of setting DICOM filter control parameters for saving and then calling the baseline saving function. All of the parameters' values used below are different from the component's default values:

/* get current value of SAVE_SYNTAX control parameter */
IG_fltr_ctrl_get(IG_FORMAT_DCM, "SAVE_SYNTAX", FALSE, NULL, NULL,
(LPVOID)nSaveSyntax, sizeof(nSaveSyntax));
/* set new value to SAVE_SYNTAX control parameter */
IG_fltr_ctrl_set(IG_FORMAT_DCM, "SAVE_SYNTAX", (LPVOID)MED_DCM_TS_EXPLICIT_VR_LE,
sizeof(nSaveSyntax));
/* get current value of SAVE_SMALLEST control parameter */
IG_fltr_ctrl_get(IG_FORMAT_DCM, "SAVE_SMALLEST", FALSE, NULL, NULL,
(LPVOID)bSaveSmallest, sizeof(bSaveSmallest));
/* set new value to SAVE_SMALLEST control parameter */
IG_fltr_ctrl_set(IG_FORMAT_DCM, "SAVE_SMALLEST", (LPVOID)TRUE,
sizeof(bSaveSmallest));nErrcount = IG_save_file(hIGear, "knee.dcm", IG_SAVE_DCM);

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 using a general ImageGear saving function, such as IG_fltr_save_file, and passing IG_FORMAT_DCM | IG_COMPRESSION_JPEG << 16 to the lFormatType 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, using a general ImageGear saving function.
  • 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.
• Save the image using a DICOM-specific saving function.
  • Set nSyntax parameter 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.

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

• Save the image as IG_FORMAT_DCM, using a general ImageGear saving function.
  • Set DICOM control parameter SAVE_SYNTAX to MED_DCM_TS_JPEG_BASELINE_PR_1_ONLY.
  • JPEG control parameter SAVE_TYPE is ignored.
• Save the image using a DICOM-specific saving function.
  • Set nSyntax parameter 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 using a general ImageGear saving function, such as IG_fltr_save_file, and passing IG_FORMAT_DCM | IG_COMPRESSION_JPEG << 16 to the lFormatType parameter.
  • Set JPEG control parameter SAVE_TYPE should be set to IG_JPG_LOSSLESS.
  • DICOM control parameter SAVE_SYNTAX is ignored.
• Save the image as IG_FORMAT_DCM, using a general ImageGear saving function.
  • 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.
• Save the image using a DICOM-specific saving function.
  • Set nSyntax control parameter to either MED_DCM_TS_JPEG_LOSSLESS or MED_DCM_TS_JPEG_LOSSLESS_FIRSTORDER.
  • JPEG control parameter SAVE_TYPE is ignored.

To JPEG Using Baseline ImageGear Calls

It is worth mentioning that lossy JPEG in the case of DICOM could imply a 12-bit channel depth. However, many image viewers do not support this format. To ensure that a DICOM saved as a JPG is viewable after saving, the use of 12-bit channel depth may need to be disabled before saving the image:

IG_fltr_ctrl_set(IG_FORMAT_JPG, "SAVE_ALLOW_LOSSY12BPCSAVING", (LPVOID)FALSE, sizeof(AT_BOOL));
IG_fltr_save_file(dicomImage, "DicomToImage.jpg", IG_SAVE_UNKNOWN, 1, TRUE);

From a Non-DICOM Image

If you have created a Data Set for a loaded non-DICOM image and wish to save it, please remember that it is up to you to add all the Mandatory Data Elements to make it a valid Part 3 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 Part 3 of the Standard.

As a Multi-Frame DICOM Image

ImageGear MD component allows you to save single-frame as well as multi-frame (multi-page) images. Saving a multi-frame DICOM image is pretty straightforward. Use any standard image saving function from ImageGear baseline API. Image saving functions from Medical API do not support saving of multi-frame images.

Use the following steps to create a multi-frame image:

1. Create or load the first frame into HIGEAR.
2. Create the DataSet, if it is not present.
3. Add the DCM_TAG_NumberOfFrames tag to the DataSet, if it is not present. The value of this tag is irrelevant, but its presence is necessary.
4. Save the image using any ImageGear baseline saving function.
5. * Create or load the second frame into HIGEAR.
6. Create Data Set if it is not present.
7. Add the DCM_TAG_NumberOfFrames tag to the Data Set, if it is not present.
8. Save the image, specifying the same file name that you used for the first frame.
9. * Repeat for all subsequent frames.

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

All frames of the image should have same dimensions, bit depth, and photometric interpretation. All frames should use the same Transfer Syntax (compression). ImageGear returns an error if these conditions are not met.

Another important fact about DICOM format is that it has a continuous structure, which means all the Data Elements as well as image frames go one after another. This results in the following limitations:

• Inserting a frame in a file that contains multiple frames would lead to rewriting all the subsequent frames. The same thing would happen when overwriting a frame in a file that uses some compression. Changed size of the compressed frame would lead to rewriting the whole file. To prevent such unpredictable time-consuming operations, ImageGear only supports appending a frame at the end of the DICOM image, but not insertion or overwriting of frames.
• ImageGear 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.
• The "Number of Frames" Data Element has a Value Representation of "Integer String", i.e., it is stored in the file as a character string rather than an integer. This string can occupy up to 14 characters. Now imagine that you are appending frame to a file that has 99 frames. The number 99 occupies two bytes in the file (because it is composed of two digits). After a frame is added, the Number Of Frames DE becomes 100, needing 4 positions for its storage (three digits plus padding). This results in the need of shifting the whole file by two bytes. To prevent this, ImageGear always leaves the maximum of 14 positions for storing the Number Of Frames DE. Moreover, it does not append a frame to a file where Value Length of the Number of Frames Data Element is less than 14 (for example, if the file has been created by some other vendor1).

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 the necessary frames to it, and then delete the original image.

Using ImageGear's Multi-Page Image API

You can use ImageGear's Multi-Page Image API calls (Multi Page Image Functions IG_mpi_...; Multi Page Image Functions and Multi Page Image File Functions IG_mpf_...Multi Page Image File Functions) for loading and saving multi-frame DICOM images. Just note that ImageGear only supports the appending of frames but not insertion, deletion, or overwriting of frames.