Working with Data Sets

A Data Set is a collection of Data Elements stored in a DICOM file. Each DICOM file may or may not include a header consisting of a Preamble and a Prefix. For more information about the DICOM File Format, refer to the An Overview of the DICOM File Format or the DICOM Standard, published by the

National Electrical Manufacturers Association

1300 N. 17th Street

Rosslyn, Virginia 22209 USA

hereafter referred to as the DICOM Standard.

Each DICOM file represents a separate class of information. For example, one DICOM file may represent the Computed Tomography Image class, and another DICOM file may represent the Radiotherapy Structure Set class. However, both classes would not be contained in the same DICOM file. For a list of the standard classes supported by DICOM, refer to the IOD Class Constants. In addition to the standard classes supported by DICOM, user-defined classes may also be added.

For each class supported by DICOM there are certain modules contained in each class. Each module consists of a number of Data Elements, each Data Element having its own tag. These Data Elements can be mandatory or optional, depending on the module and the class. For a list of the default modules supported by DICOM, refer to IOD Module Constants. For a list of default Data Elements (tag values) supported by DICOM, refer to Data Element Tag Constants. For more details concerning the DICOM File Format, refer to An Overview of the DICOM File Format and the DICOM Standard. In addition to the standard modules and data elements supported by DICOM, user-defined modules and data elements may also be added.

LEADTOOLS maintains the Data Set internally as a tree structure. In this documentation the tree will be referred to as the Data Set, and individual members of the Data Set will be referred to as Data Elements or items. Some of the functions provided by LEADTOOLS allow you to evaluate the Data Set as a tree or as a list. All functions pertaining to the Data Sets are in the class LDicomDS.

LEADTOOLS provides a number of functions for maneuvering through the Data Set, getting and setting Data Set information, getting and setting Data Element values, searching the Data Set, and creating, loading and saving Data Sets.

For creating, initializing, loading and saving Data Sets, LEADTOOLS provides the following functions:

LDicomDS::LDicomDS

LDicomDS::InitDS

LDicomDS::LoadDS

LDicomDS::LoadDSMemory

LDicomDS::SaveDS

For maneuvering through the Data Set use the following functions:

LDicomDS::GetRootElement

LDicomDS::GetParentElement

LDicomDS::GetChildElement

LDicomDS::GetFirstElement

LDicomDS::GetLastElement

LDicomDS::GetPrevElement

LDicomDS::GetNextElement

LEADTOOLS provides several functions for searching the Data Set. To find specific modules, use LDicomDS::FindModule and LDicomDS::FindIndexModule. You can find specific Data Elements using LDicomDS::FindFirstElement, LDicomDS::FindLastElement, LDicomDS::FindPrevElement, LDicomDS::FindNextElement, and LDicomDS::GetElementOffset.

To insert new items in the Data Set, call LDicomDS::InsertElement or LDicomDS::InsertModule. To insert one or more images in a Data Element of type TAG_PIXEL_DATA, use LDicomDS::InsertImage or LDicomDS::InsertImageList.

To copy a Data Set, call the overloaded LDicomDS::CopyDS.

A DICOM Data Set can have private data, which is stored in private tags. Standard DICOM tags are identifiable because their group number is even. Private tags have odd group number. To reserve private data elements, private creator data elements must first be created. Use the following functions to work with private creator data elements and private elements:

You can delete individual items from the Data Set using LDicomDS::DeleteElement. You can delete entire modules from the Data Set, using LDicomDS::DeleteModule. To delete all items in the Data Set, call LDicomDS::ResetDS. To delete one or more images in a Data Element of type TAG_PIXEL_DATA, use LDicomDS::DeleteImage.

To retrieve values stored in the Value Field of the Data Element LEADTOOLS provides the following:

LDicomDS::FreeValue

LDicomDS::GetAgeValue

LDicomDS::GetBinaryValue

LDicomDS::GetCharValue

LDicomDS::GetCountValue

LDicomDS::GetDateRangeValue

LDicomDS::GetDateTimeRangeValue

LDicomDS::GetDateTimeValue

LDicomDS::GetDateValue

LDicomDS::GetDoubleValue

LDicomDS::GetFloatValue

LDicomDS::GetImage

LDicomDS::GetImageList

LDicomDS::GetLongValue

LDicomDS::GetLong64Value

LDicomDS::GetShortValue

LDicomDS::GetStringValue

LDicomDS::GetTimeRangeValue

LDicomDS::GetTimeValue

To set values stored in the Value Field of the Data Element use the following:

LDicomDS::SetAgeValue

LDicomDS::SetBinaryValue

LDicomDS::SetCharValue

LDicomDS::SetDateRangeValue

LDicomDS::SetDateTimeRangeValue

LDicomDS::SetDateTimeValue

LDicomDS::SetDateValue

LDicomDS::SetDoubleValue

LDicomDS::SetFloatValue

LDicomDS::SetImage

LDicomDS::SetImageList

LDicomDS::SetLongValue

LDicomDS::SetShortValue

LDicomDS::SetStringValue

LDicomDS::SetTimeRangeValue

LDicomDS::SetTimeValue

To convert a value to or from a string, use LDicomDS::GetConvertValue or LDicomDS::SetConvertValue.

To determine whether you have a valid pointer to a data element, call LDicomDS::ExistsElement.

When a function that gets a bitmap from a data set is called, such as LDicomDS::GetImage or LDicomDS::GetImageList, LEADTOOLS, by default will pre-process the data in the bitmap handle for optimum display and image processing. To change this behavior, call the LDicomDS::SetKeepPixelDataIntactFlag function with bSet set to TRUE. This will keep LEADTOOLS from pre-processing the image data. To determine whether pre-processing is currently enabled or disabled, call LDicomDS::GetKeepPixelDataIntactFlag.

LEADTOOLS provides several functions for retrieving information about the Data Set or the DICOM file. LDicomDS::ConformanceDS determines whether the Data Set conforms to the standard. To determine the number of images in a specified Data Element or in the entire Data Set use LDicomDS::GetCountImage. To determine the number of modules present in the entire Data Set use LDicomDS::GetCountModule. You can determine which level a specific element is on by calling LDicomDS::GetLevelElement.

Transferring data between a server and a client requires that both entities use the same transfer syntax. The transfer syntax for a data set can be changed using the LDicomDS::ChangeTransferSyntax function.

To determine whether an element is volatile, call LDicomDS::IsVolatileElement.

The DICOM toolkit offers extensive debugging and status information by optionally notifying the user of each internal error that occurs. To enable this feature call the function LDicomDS::SetDebugDS to specify the callback function which will be called each time the user needs to be notified. This feature is disabled by default.

To retrieve information about the specified image, call the LDicomDS::GetInfoImage function.

To retrieve information about the file, call the LDicomDS::GetInfoDS function.

Finally, for getting and setting the contents of the Preamble, LEADTOOLS provides LDicomDS::GetPreamble and LDicomDS::SetPreamble.

For a list of macros available for use, refer to DICOM Macros.

For more information on the DICOM File Fomat, refer to An Overview of the DICOM File Format and the DICOM Standard.