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.

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:

L_DicomCreateDS

L_DicomInitDS

L_DicomLoadDS

L_DicomLoadDSMemory

L_DicomSaveDS

For maneuvering through the Data Set use the following functions:

L_DicomGetRootElement

L_DicomGetParentElement

L_DicomGetChildElement

L_DicomGetFirstElement

L_DicomGetLastElement

L_DicomGetPrevElement

L_DicomGetNextElement

LEADTOOLS provides several functions for searching the Data Set. To find specific modules, use L_DicomFindModule and L_DicomFindIndexModule. You can find specific Data Elements using L_DicomFindFirstElement, L_DicomFindLastElement, L_DicomFindPrevElement, and L_DicomFindNextElement. Search for an item having a specific tag by calling L_DicomFindFirstDescendant. Find the next item having a specific tag by calling L_DicomFindNextDescendant.

To insert new items in the Data Set, call L_DicomInsertElement or L_DicomInsertModule. To insert one or more images in a Data Element of type TAG_PIXEL_DATA, use L_DicomInsertImage or L_DicomInsertImageList.

To copy a Data Set, call L_DicomCopyDS or L_DicomCopyDSExt.

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 L_DicomDeleteElement. You can delete entire modules from the Data Set, using L_DicomDeleteModule. To delete all items in the Data Set, call L_DicomResetDS. To delete one or more images in a Data Element of type TAG_PIXEL_DATA, use L_DicomDeleteImage.

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 L_DicomSetDebugDS.

If your application consists of multiple processes as in the case of multiple DLLs, and you need to pass pointers to objects allocated inside the current DLL to other processes that will eventually free those objects, then you will need to call the L_DicomSetMemoryAllocation function with the MEMORY_GLOBAL flag (preferably at the beginning of your application) to ensure proper behavior.

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

L_DicomFreeValue

L_DicomGetAgeValue

L_DicomGetBinaryValue

L_DicomGetCharValue

L_DicomGetCountValue

L_DicomGetDateRangeValue

L_DicomGetDateTimeRangeValue

L_DicomGetDateTimeValue

L_DicomGetDateValue

L_DicomGetDoubleValue

L_DicomGetFloatValue

L_DicomGetImage

L_DicomGetImageList

L_DicomGetLongValue

L_DicomGetShortValue

L_DicomGetStringValue

L_DicomGetTimeRangeValue

L_DicomGetTimeValue

To free the memory allocated by the above functions, LEADTOOLS provides the following:

L_DicomFreeValue

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

L_DicomSetAgeValue

L_DicomSetBinaryFile

L_DicomSetBinaryStream

L_DicomSetBinaryValue

L_DicomSetImage

L_DicomSetImageList

L_DicomSetCharValue

L_DicomSetDateRangeValue

L_DicomSetDateTimeRangeValue

L_DicomSetDateTimeValue

L_DicomSetDateValue

L_DicomSetDoubleValue

L_DicomSetFloatValue

L_DicomSetImage

L_DicomSetImageList

L_DicomSetLongValue

L_DicomSetShortValue

L_DicomSetStringValue

L_DicomSetStringValue2

L_DicomSetTimeRangeValue

L_DicomSetTimeValue

To convert a value to or from a string, use L_DicomGetConvertValue or L_DicomSetConvertValue.

To determine whether you have a valid pointer to a data element, call L_DicomExistsElement.

When a function that gets a bitmap from a data set (such as L_DicomGetImage, L_DicomGetImageList or L_DicomGetImageListEx) is called, LEADTOOLS by default will pre-process the data in the bitmap handle for optimal display and image processing. To change this behavior, call the L_DicomSetKeepPixelDataIntactFlag 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 L_DicomGetKeepPixelDataIntactFlag.

LEADTOOLS provides several functions for retrieving information about the Data Set or the DICOM file. L_DicomConformanceDS determines whether the Data Set conforms to the standard. To determine the number of modules present in the entire Data Set use L_DicomGetCountModule. To determine the number of images in a specified Data Element or in the entire Data Set use L_DicomGetCountImage. To obtain information about a DICOM file, call the L_DicomGetInfoDS function. To obtain information about the image in the specified element, call the L_DicomGetInfoImage function. You can determine which level a specific element is on by calling L_DicomGetLevelElement.

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 L_DicomChangeTransferSyntax or L_DicomChangeTransferSyntax2 function.

To determine whether an element is volatile, call L_DicomIsVolatileElement.

Finally, for getting and setting the contents of the Preamble, LEADTOOLS provides L_DicomGetPreamble and L_DicomSetPreamble.

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.

Help Version 22.0.2022.12.7
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS DICOM C API Help
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.