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.
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.
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() |
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.
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.
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); |
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); |
ImageGear supports the following modes for saving JPEG compressed DICOM images:
See JPEG for a description of JPEG Filter Control Parameters.
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:
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.
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:
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); |
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.
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:
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:
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.
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.