IOD Demo Help

IOD Demo Help - How to add your own IOD Class

Purpose:

This demo is provided with the intention to show the users how to add new IODs, which can be proprietary or will be defined in the future DICOM specifications.

Background:

An Information Object Definition (IOD) is an object-oriented abstract data model used to specify information about Real-World Objects. An IOD provides communicating Application Entities with a common view of the information to be exchanged. Information Object Definitions (IODs) are defined in the PS 3.3 of the DICOM standard.

LEADTOOLS maintains a tree, internally, of all available Information Object Definitions (IODs), Unique Identifiers (UIDs), Value Representations (VRs) and Element Tag table included in standard and user defined.

Below is an example of the contents of the STANDALONE OVERLAY IOD MODULES as specified in PS 3.3 of the DICOM standard.

TABLE A.9-1

STANDALONE OVERLAY IOD MODULE

IE | MODULE | Reference | Usage
Patient | Patient | C.7.1.1 | M
Study | General Study | C.7.2.1 | M
 | Patient Study | C.7.2.2 | U
Series | General Series | C.7.3.1 | M
Equipment | General Equipment | C.7.5.1 | M
Overlay | Overlay Identification | C.9.1 | M
 | Overlay Plane | C.9.2 | M
 | SOP Common | C.12.1 | M

The table below shows the elements that constitute the “Overlay Identification” module:

TABLE C.9-1

OVERLAY IDENTIFICATION MODULE ATTRIBUTES

Attribute Name | Tag | Type | Attribute Description
Overlay Number | (0020,0022) | 2 | A number that identifies this Overlay.
Overlay Date | (0008,0024) | 3 | The date the Overlay was created.
Overlay Time | (0008,0034) | 3 | The time the Overlay was created
Referenced Image Sequence | (0008,1140) | 3 | A Sequence which provides reference to a set of Image SOP Class/Instance pairs. Uniquely identifies the image significantly related to this overlay. One or more items may be included in this Sequence.
>Referenced SOP Class UID | (0008,1150) | 1C | Uniquely identifies the referenced SOP Class. Required if Referenced Image Sequence (0008,1140) is sent.
>Referenced SOP Instance UID | (0008,1155) | 1C | Uniquely identifies the referenced SOP Instance. Required if Reference Image Sequence (0008,1140) is sent.

Concepts covered in this demo:

    1. How to remove an IOD class from LEADTOOLS IOD Table.

    2. How to remove an UID from LEADTOOLS UID Table.

    3. How to remove elements within an IOD module from LEADTOOLS IOD Table.

    4. How to add a new UID to LEADTOOLS UID Table.

    5. How to add a new IOD class to LEADTOOLS IOD Table.

    • Adding a new IOD class

    • Adding new Modules to the IOD class

    • Adding elements for each Module

    6. How to use newly created IOD class to create a data set.

    7. How to insert overlay data to a dataset

    8. How to populate some elements with data in the dataset

    9. How to save DICOM Data Set as DICOM file on disk

To simulate the process of adding a new IOD class, first delete the IOD and UID for an existing IOD class from LEAD’s IOD and UID tables. Then add them back to the appropriate tables as a new IOD class and use that class for creating a DICOM file.

Below is the demo’s main window:

This window contains three panels and three buttons. The upper left panel contains a brief description of the current step being processed. The upper right panel contains a tree view data structure, a graphical representation of the data model of an IOD class.

The third panel contains seven fields displaying different tags for the current IOD element:

    • Overlay Rows : displays the overlay bitmap height (this can be modified)

    • Overlay Columns : displays the overlay bitmap width (this can be modified)

    • Overlay Type : G

    • Overlay Origin : 1/1

    • Overlay Bits Allocated : 1

    • Overlay Bit Position : 0

    • Overlay Data : Text to add to the overlay Bitmap.

Note: For this demo, a common IOD Class – Standalone Overlay Storage is used.

In the lower left part of the main dialog window, there are three buttons.

    1. The first button can have four different values, depending on the current step of the demo

    • Delete IOD Class

    • Add IOD Class

    • Create DICOM

    • Save DICOM

    2. Help – Click this button to activate this help.

    3. Close – Click this button to close the demo.

The four steps below explain the functionality of this demo. Each of the sub-steps is pointed out in the demo by the corresponding message window and by the changes that can be seen in the tree view.

1. Delete IOD Class – delete the IOD Class from the LEADTOOLS predefined IOD Table.

Inside the code of the demo there is a L_BOOL CMainDlg::Find_Delete_IOD() function that shows you how to find specific IOD classes, modules and elements in the LEAD predefined IOD structure.

First find the IOD class using the LDicomIOD::FindClass() function as shown in the code below:

pClassIOD = m_IOD.FindClass(USER_CLASS);

if (pClassIOD == NULL)

{

return FALSE;

}

Now, search the specific module using LEADTOOLS LDicomIOD::FindModule() member function, and, in order to find a specific element from the Module “Overlay Identification”, move the tree cursor to the element level, using the LDicomIOD::Find() member function.

Please take note that when you delete an IOD class, all the modules with all their elements get deleted also. In the demo, first, an element is deleted, then a module and in the end an entire IOD class. Every time when a specific operation is completed successfully, a specific message will be displayed.

As an example, delete module Overlay Identification and implicitly all elements from this module (Overlay Number, Date, Time etc), with the LDicomIOD::Delete() function, like in the following sample of source code:

// Delete module Overlay Identification and implicitly all elements from this

// module (Overlay Number, Date, Time etc)

m_IOD.Delete(pModuleIOD);

// Show a message indicating that the module was deleted

Add_IOD_Tree(pModuleIOD, "Delete Module Overlay Identification\nSuccess!");

2. Add IOD Class – click the button to add “IOD Class Standalone Overlay Storage”

In order to create a new IOD class you must add:

    • UID Class in LEADTOOLS UID table

    • IOD Class in LEADTOOLS IOD table

    • IOD Modules to the IOD Class

    • IOD Elements to the IOD Modules

In the code below, you can learn how to add the IOD Module General Study and the IOD Elements for this module, using the LDicomIOD::Insert() LEAD function:

pModuleIOD = m_IOD.Insert(pClassIOD,

TRUE,

MODULE_GENERAL_STUDY,

"General Study",

IOD_TYPE_MODULE,

IOD_USAGE_M,

"");

if (pModuleIOD == NULL)

{

return FALSE;

}

pElementIOD = m_IOD.Insert(pModuleIOD,

TRUE,

TAG_STUDY_INSTANCE_UID,

"Study Instance UID",

IOD_TYPE_ELEMENT,

IOD_USAGE_1,

"");

.............................................................................................................................................................................................................................

The "Add" process takes place in the same way like the delete process but in a reverse order. First we create an IOD class:

    • add the UID and IOD for the class

pElementUID = m_UID.Insert("1.2.840.10008.5.1.4.1.1.8",

"Standalone Overlay Storage",

UID_TYPE_CLASS);

if (pElementUID == FALSE)

{

return FALSE;

}

    • insert the class in the IOD table

pClassIOD = m_IOD.Insert(NULL,

FALSE,

USER_CLASS,

"Standalone Overlay Storage",

IOD_TYPE_CLASS,

0,

"1.2.840.10008.5.1.4.1.1.8");

if (pClassIOD == NULL)

{

return FALSE;

}

    • display a message of success, if the insertion process was OK

Add_IOD_Tree(0, "Insert Class Standalone Overlay Storage\nSuccess!");

The second step is to insert the different IOD modules and the final step is to add the different elements for each module (if appropriate).

//Add IOD Module Overlay Identification

pModuleIOD = m_IOD.Insert( pClassIOD,

TRUE,

MODULE_OVERLAY_IDENTIFICATION,

"Overlay Identification",

IOD_TYPE_MODULE,

IOD_USAGE_M,

"");

.............................................................................................................................................................................................................................

//Add IOD Elements for the module Overlay Identification

pElementIOD = m_IOD.Insert( pModuleIOD,

TRUE,

TAG_OVERLAY_NUMBER,

"Overlay Number",

IOD_TYPE_ELEMENT,

IOD_USAGE_2,

"");

Add_IOD_Tree(pModuleIOD, "Insert Element Overlay Number\nSuccess!");

.............................................................................................................................................................................................................................

3. Create DICOM – click the button in order to create a DICOM file, using the newly inserted class

In the third step you are going to use the IOD Class template created before, initializing a new DICOM Data Set using the LDicomDS::InitDS() function and passing it as parameter the new class:

L_INT CMainDlg::Create_Class()

{

m_DS.InitDS(USER_CLASS, DS_LITTLE_ENDIAN | DS_EXPLICIT_VR);

return TRUE;

}

4. Save DICOM – first fill the fields of the dialog, then click the button in order to save the new DICOM file.

Create a new DataSet using the newly created IOD class, and then fill in the values for the module Overlay Plane. First set the default values for the module (Patient, General Study, etc.) in which the data will be inserted.

Find the different elements from the modules, using LDicomDS::FindFirstElement() and insert the new data values using LDicomDS::SetShortValue(), like in the example bellow:

nData = GetDlgItemInt(IDC_EDIT_ORIGIN);

pElement = m_DS.FindFirstElement(NULL, TAG_OVERLAY_ORIGIN, FALSE);

m_DS.SetShortValue(pElement, &nData, 1);

To create the Overlay Data in memory, use LEADTOOLS API L_CreateBitmap() and L_CreateLeadDC() for the memory context of the Overlay Data. To set the element Overlay Data, use LDicomDS::SetBinaryValue() like in the following source code sample:

pElement = m_DS.FindFirstElement(NULL, TAG_OVERLAY_DATA, FALSE);

m_DS.SetBinaryValue(pElement, hFileInMemory, uMemSize);

In the end save the DICOM file using LDicomDS::SaveDS().

For additional information on any of these functions, see the LEAD Tools Document Imaging help files. To understand better the use and the meaning of the DICOM terms used in this help and in this demo, please consult the DICOM v3.0 Standard.