When a DICOM image is loaded into ImageGear, it is loaded into a DIB just like any other supported image. In addition to the actual image, the following DICOM-specific data structures are also loaded: File Meta Information Header (if present) and the Data Set. This section explains how to read and/or manipulate the data in the Data Set or File Meta Information Header, or how to create your own Data Set or File Meta Information Header.

Get and Set Data Set and Part 10 Header Data

With the exception of the first function listed below, these functions can be used for getting or setting various parts of the Part 10 Header data. These functions are useful when you are creating a new DICOM file.

Insert a New Data Element

ImageGear allows you to insert any number of Data Elements to an existing Data Set, or to a new Data Set that you have created by calling MED_DCM_DS_create(). (See the section "Creating a Data Set" below.)

DICOM Data Sets are sorted numerically by Tag number. Therefore, the Current Data Element does not affect the index position where your new Data Element is inserted. ImageGear takes your Tag number and automatically sorts the new DE into the correct position in the array. The Current Data Element does, however, determine the level at which the new DE is stored. For example, if the Current Data Element is in level 0 and has a Tag value of (0028, 0010) and your new DE has a Tag value of (0028, 0015), the new DE will be inserted into level 0 and positioned somewhere below the Current DE so that its unique Element Number fits numerically in ascending order.

You have complete flexibility in what kind of DEs you can add to the Data Set. For each new DE, you have to supply ImageGear with a Tag structure, a VR, and the data. You can add it to any Group, to any position, with any VR, and with any data that you desire.

An example of using MED_DCM_DS_DE_insert():

HIGEAR hIGear;
AT_DCM_TAG tag = 0x00111111;
AT_DCM_VR vr = MED_DCM_VR_CS;
char data[256] = "Data for test element";
DWORD dwSizeOfData = strlen(data);
MED_DCM_DS_DE_insert(hIGear, tag, vr, data, dwSizeOfData);

This function requires you to supply the following values: a Tag, a VR, a Data Field, and the size of the data for the Data Field. Below are brief descriptions of what you would need to know in order to set these arguments.

Set the Tag Value

All standard Tag values for a DICOM file are assigned constants in enumIGMedTag enumeration. You can also add your own user-defined Tag using MED_DCM_util_tag_info_add().

Set the VR

The DICOM specification assigns specific VRs for each defined public Tag. In other words, for a particular Tag, you must always use the specified VR. There are a few rare exceptions to this rule, and it is for this reason that you should tell MED_DCM_DS_DE_insert() what VR the data has.

If you don't know the VR for a particular Tag that you are adding, you can find out easily by calling the function MED_DCM_util_tag_info_get(), which returns you its VR as a constant.

Set the Data for a VR of CS

There are no constants in ImageGear defined for those Data Elements which have a VR of CS. Refer to Part 3 of the DICOM specification for the valid Code Strings which you can enter for data of type CS.

Here is a sample call to insert a Data Element with a Tag of DCM_TAG_PhotometricInterpretation, which has a VR of CS (Code String). You must use one of the defined values from Part 3 of the DICOM specification. The allowed values are: "MONOCHROME1", "MONOCHROME2", "PALETTE COLOR", "RGB", "HSV", "ARGB", "CMYK", "YBR_FULL", "YBR_FULL_422", and "YBR_PARTIAL_422".

MED_DCM_DS_DE_insert(hIGear, DCM_TAG_PhotometricInterpretation, MED_DCM_VR_CS,
"MONOCHROME2", 11);

Set the Data Field

What kind of data can be stored to the Data Field depends on the Tag type, the VR, the restriction flags and the Value Multiplicity (VM) defined for the Tag. It is very helpful to call MED_DCM_util_VR_info_mode()or MED_DCM_util_VR_info_string()so that you can find out what kind of restrictions are placed on the kind of data that you would like to enter. Some types of Data Fields are tricky to work with. VRs of Person Name and Code String place a number of restrictions on what can go into the Data Field, and how it is to be formatted. For these VR types, you must consult Part 5 of the DICOM specification.

The lpData parameter is a binary buffer, which can contain a character string, a BYTE or WORD array, or one or several of numbers, such as Integers or Floats. Below there is an example how to set a value of VR=FD (double):

DOUBLE dblRefPixelValueX = 1.234;
MED_DCM_DS_DE_insert(hIGear, DCM_TAG_ReferencePixelPhysicalValueX, MED_DCM_VR_FD,
&dblRefPixelValueX, sizeof(DOUBLE));

Set the Length of a Data Field

Because some VRs allow a range of values, the length of all Data Fields cannot be assumed. For this reason, you must supply ImageGear with the length of your data.

Insert a Sequence of Data Elements

Use the following steps to create and fill a sequence (SQ) of Data Elements:

1. Insert the Data Element of VR = SQ. This positions you one level lower in the DataSet hierarchy. At this level you can only add items to the sequence, not the Data Elements.
2. Insert the DCM_TAG_ItemItem Data Element to denote the beginning of a new item in the sequence. This positions you one level lower in the DataSet hierarchy. Now you can add Data Elements to the embedded Data Set.
3. Insert the data elements you would like to insert to this item.
4. Insert the DCM_TAG_ItemDeliminationItem Data Element to denote end of the item. This positions you one level higher. Repeat steps 2-4 for every item you would like to add.
5. Insert the DCM_TAG_SequenceDeliminationItem Data Element to denote the end of the sequence. This moves you one level higher - to the same level where you added the SQ Data Element.

Examples on creating a Data Element Sequence are below. Note that it is completely valid to add same Data Elements to different Items within a Sequence.

AT_DCM_TAG  tag;
char        data_str[64];
tag = DCM_TAG_ReferencedStudySequence;
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_SQ, NULL, 0);
tag = DCM_TAG_ItemItem;
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_xx, NULL, 0);
tag = DCM_TAG_ReferencedSOPClassUID;
strcpy( data_str, "1.23.456.7.8.90.1234567890.2");
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_UI, data_str, strlen(data_str));
tag = DCM_TAG_ReferencedSOPInstanceUID;
strcpy( data_str, "1.23.456.7.8.90.1234567890.2.1");
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_UI, data_str, strlen(data_str));
tag = DCM_TAG_ItemDelimitationItem;
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_xx, NULL, 0);
tag = DCM_TAG_ItemItem;
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_xx, NULL, 0);
tag = DCM_TAG_ReferencedSOPClassUID;
strcpy( data_str, "1.23.456.7.8.90.1234567890.3");
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_UI, data_str, strlen(data_str));
tag = DCM_TAG_ReferencedSOPInstanceUID;
strcpy( data_str, "1.23.456.7.8.90.1234567890.3.1");
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_UI, data_str, strlen(data_str));
tag = DCM_TAG_ItemDelimitationItem;
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_xx, NULL, 0);
tag = DCM_TAG_SequenceDelimitationItem;
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_xx, NULL, 0);

Delete a Data Element

Data Elements can be deleted by calling MED_DCM_DS_curr_remove(). This function removes the DE designated by the Current Data Element. Therefore, you can use one of the MED_DCM_DS_move_...() functions to position the Current Data Element to the DE you want to remove.

Some calls to MED_DCM_DS_curr_remove() result in deletion of more than one Data Element:

• If you are going to delete a DE with a VR of SQ, all the items and consequently DEs below it will be deleted also.
• If you are going to delete a DE of type Item (FFFE, EOOO), all DEs below it will also be deleted.

The following types of DEs may not be deleted:

• Sequence Delimitation Item (SQD) - (FFFE, EODD)
• Item Delimitation Item (ID) - (FFFE, EOOD)

Trying to delete DEs of these types will have no affect on the Data Set. These type of DEs will be automatically deleted by ImageGear when their accompanying set of DEs are deleted.

Get and Set Data of the Current Data Element

Notice that all functions in this group include "curr" as part of their names. Below is a description of these functions..

Create a Data Set

If you have a HIGEAR image to which you would like to attach a Data Set, call MED_DCM_DS_create(). This file might have been loaded from a non-DICOM format or may be a DICOM file in which you've destroyed the Data Set (see the section above).

This function creates an empty Data Set and attaches it to the ImageGear's image. The function creates a Data Set structure (outlined above) and fills it with a few Data Elements whose values can be derived from the image. This function also requires you to supply a Transfer Syntax that is saved in the Part 10 Header template as the original Transfer Syntax (as if it was loaded from a DICOM file). If you then save the image and specify a different Transfer Syntax, you overwrite the TS value specified at the time of Data Set creation.

Delete a Data Set

If you have loaded a DICOM image file and do not need to keep the Data Set around you can free up the memory used to store all the Data Elements by calling MED_DCM_DS_destroy(). Once this function is called the remaining image is no different than any other ImageGear image that was created from any other non-DICOM format. The removed Data Set is discarded and cannot be recovered.

Create a Part 10 Header

When a DICOM image is loaded with the ImageGear Medical, a Part 10 Header Template is initialized automatically. If you save the image as a Part 10-compliant image (which is the default option), the values from this template are used to fill the header saved with the file.

For those wishing to modify or read the values stored in the Part 10 Header Template, the component supplies 11 constants. All except the last one correlate directly to the fields found in a Part 10 Header. The last constant can be used by ImageGear to store the length of the Private Info field, and is for informational purposes.

Below is the list of Part 10 constants. Each one is followed by its size in bytes. A check appears next to each field that is considered "Mandatory" by the specification. ("Mandatory" is one of three possible "Types" for a DICOM DE. The other Types are "Optional", and "Mandatory Depending on some Condition".)

Please note the following about the above constants:

• You can set DCM_PART10_ITEM_PREAMBLE to anything you want as long as it doesn't exceed 128 bytes
• DCM_PART10_ITEM_VERSION is set by the toolkit to a default value of 1. You should not change this.
• DCM_PART10_ITEM_TRANSSYNTAXUID - we set the value of this DE when the image is loaded. You can read this value; you can even set this value. But when the image is saved your setting are ignored.

If you enter data in DCM_PART10_ITEM_PRIVINFO, it is stored with the new Part 10 Header. Also, ImageGear calculates its size and saves this information internally. This read-only size information is not made part of the template but is kept in case you need to know how much memory to allocate when getting the information from DCM_PART10_ITEM_PRIVINFO. DCM_PART10_ITEM_PRIVINFO_SIZE isn't stored to the new Part 10 header.

Here is an example of a Part 10 field being populated:

char szPreamble[] = "This DICOM File is MINE!";
DWORD size_of_data;
size_of_data = sizeof(&szPreamble[0]);
MED_DCM_DS_part10_set(hIGear, DCM_PART10_ITEM_PREAMBLE, &szPreamble[0],
&size_of_data);

Update DICOM DataSet without Updating Pixel Data

There are cases when an application needs to update DataSet of a DICOM file, while leaving PixelData unchanged. For example, if the image is compressed using a Lossy compression scheme, this will avoid degradation of image quality.

Use MED_DCM_DS_update_file() function to update DataSet in a DICOM file, without changing its pixel data.

Critical Data Elements

In this manual, we use the term "Critical Data Elements" for those DEs that are used to help load a DICOM image correctly. It's important to note that when certain IP methods are called, the toolkit alters the Data Set. For example, when an aspect of the image has been altered (for instance, by image processing) so, that the Critical DEs no longer correctly describe the image, the Data Set have to be altered. When the image is actually saved, ImageGear also analyzes the DIB and set its own values for the Critical Data Elements of the file being saved. The original values are ignored.

The Critical Data Elements are: