ImageGear for C and C++ on Linux v19.10 - Updated
Load and Save DICOM Images
User Guide > How to Work with... > Formats with Additional Functionality > DICOM > Load and Save DICOM Images

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.

See DICOM in the File Formats chapter for detailed information about ImageGear support for the DICOM format.

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.

Description Function
DICOM-specific saving function MED_DCM_save_DICOM()
DICOM-specific saving function for a file that has already been opened and for which you have a File Descriptor handle MED_DCM_save_DICOM_FD()
Baseline ImageGear saving functions

IG_save_file()
IG_save_FD()
IG_save_mem()
IG_fltr_save_file()

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.

This section provides information about saving DICOM images...

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:

 
Copy Code
   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:

 
Copy Code
      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:

 
Copy Code
/* 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:

See JPEG for a description of JPEG Filter Control Parameters.

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:

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:

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:

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:

C and C++
Copy Code
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.

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.

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:

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.