ImageGear for C and C++ on Linux v19.10 - Updated
MED_DCM_save_DICOM
API Reference Guide > MD Component API Reference > MD Component Functions Reference > File Functions > MED_DCM_save_DICOM

This function saves a DICOM image file.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI MED_DCM_save_DICOM(
        const LPSTR lpszFileName, 
        const HIGEAR hIGear, 
        const AT_MODE nSyntax, 
        const BOOL bIncludeGroupLengths, 
        const BOOL bSaveAsPart10, 
        const AT_MODE PlanarConfiguration, 
        const BOOL IncludeSmallestLargest, 
        const UINT nJPEGQuality, 
        const DWORD dwReserved
);

Arguments:

Name Type Description
lpszFileName const LPSTR A far pointer to the name of the file to save.
hIGear const HIGEAR The HIGEAR handle of the image to save. This HIGEAR must have an attached DICOM Data Set.
nSyntax const AT_MODE Set to the type of Transfer Syntax with which to save the image.
bIncludeGroupLengths const BOOL Set this Boolean variable to TRUE if you want to store the Group Lengths with the image.
bSaveAsPart10 const BOOL Set this Boolean variable to TRUE if you want to save a Part 10 header with the image.
PlanarConfiguration const AT_MODE Determines how RGB pixel values are to be saved to the DICOM image file. The Planar Configuration Data Element (0028, 0006) will be automatically inserted and this value stored in it. If the Data Set already contains (0028,006) its value is ignored and the value of this parameter is used instead. This parameter is used for RGB only. It is ignored for all other image types. Set to one of the constants that begins with MED_DCM_PLANAR_.
IncludeSmallestLargest const BOOL

If the image's original Data Set did not contain Data Elements for Smallest Image Pixel Value (0028,0106) and Largest Image Pixel Value (0028,0107) and you set IncludeSmallestLargest = TRUE, ImageGear will scan the image and determine a values for these DEs. Smallest Image Pixel Value and Largest Image Pixel Value will be included in the Data Set of the DICOM image being saved, and will contain the ImageGear-determined values. The values of the DE from the original Data Set (if any) will be ignored.

If you set IncludeSmallestLargest = FALSE, ImageGear will not determine this value for you, and the Data Set of the image being saved will not include the Smallest Image Pixel Value and Largest Image Pixel Value Data Elements. However, if the original Data Set did contain these DEs, ImageGear will preserve and include them in the Data Set being saved.

nJPEGQuality const UINT The value of this argument is only relevant to lossy JPEG compression. When using any other compression scheme, this value will be ignored. (This setting would be meaningless for Lossless JPEG compression). Set to the amount of pixel data to preserve during lossy JPEG compression. The range of valid values is 1-100 with a default value of 70. Higher settings result in higher quality and a larger file. Note that even at 100, JPEG compression is not capable of being completely "lossless." The compression used, if any, is set by nSyntax. (MED_DCM_TS_JPEG_LOSSY_8 indicates the use of 8-bit JPEG compression).
dwReserved const DWORD Reserved for future use. Set to 0 for now.

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Supported Raster Image Formats:

All pixel formats supported by ImageGear for C and C++.

The image must have a DICOM DataSet attached to it. Use MED_DCM_DS_exists to check whether the image contains a DataSet.

Remarks:

This function cannot be used to save an image of any other format. It provides a convenient way to save DICOM images, using DICOM-specific saving options. However, general saving functions such as IG_fltr_save_file, together with DICOM control parameters, provide greater flexibility for saving DICOM images. We recommend that you use the latter way of saving DICOM images.

In order to save an image as a DICOM file the HIGEAR must have a Data Set attached to it. If you loaded the HIGEAR from a DICOM file then there already is a Data Set attached. If not, you can use the function MED_DCM_DS_create() to create one. If you are not sure if the image has a Data Set, call MED_DCM_DS_exists() to find out. If you are going to create a Data Set using MED_DCM_DS_create(), then you must still populate the Data Set with valid Data Elements using MED_DCM_DS_DE_insert().

The nSyntax parameter determines how the DICOM image file is encoded. The valid options are the constants whose names begin with MED_DCM_TS_ (except for _TS_UNKNOWN, and _TS_AUTODETECT).

Group Lengths are optional in a DICOM image file. By default, Group Lengths are not stored in the Data Set that is attached to the HIGEAR. If you have read a DICOM file that included Group Lengths, they have been discarded as they were found. Set bIncludeGroupLength to TRUE to have them recreated and placed in the Data Set as it has been written to disk.

DICOM Image files are supposed to be written to disk using the Meta-Info Header that is defined in Part 10 of the DICOM Specification. However, many DICOM applications choose not to use this header. If bSaveAsPart10 is set to TRUE, the Meta Information Header will be placed at the beginning of the file. Setting this to FALSE will skip the header.

If the image is saved without a Part 10 header, it is often called a Raw DICOM image file. Note that the Part 10 Header Data Elements are not stored the same way as other Data Elements in the Data Set. If you wish to store this data you must populate the header using the MED_DCM_DS_part10_set() function before writing the file.

 If your application supports unicode or multi-byte strings, you can open a file yourself and pass us the FD handle. If you prefer to open your own file, use MED_DCM_save_DICOM_FD().