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:
For maneuvering through the Data Set use the following functions:
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.
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.
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:
To free the memory allocated by the above functions, LEADTOOLS provides the following:
To set values stored in the Value Field of the Data Element use the following:
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 is called, such as L_DicomGetImage or L_DicomGetImageList, LEADTOOLS, by default will pre-process the data in the bitmap handle for optimum 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 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.