Working with DICOM Waveforms

The DICOM standard supports waveform storage and communication: this includes hemodynamic curve data, cardiac electrophysiology, electrocardiography (ECG) and audio signals (WAV files). A waveform consists of one or more multiplex groups, each encoded into an item in the "Waveform Sequence" (5400,0100). All channels within a multiplex group are synchronously digitized at a common sampling frequency. The waveform samples can be 8 or 16 bit, with data representation as signed, unsigned, mu-law or A-law. DICOM also supports waveform annotations, which are typically generated as part of the data acquisition process, such as waveform maxima and minima, or the labeling of particular stimuli.

LEADTOOLS waveform support is comprehensive and handles the various features supported by the standard. The L_DicomWaveGrpxxx functions can be used to manage multiplex groups (the building block for waveforms in DICOM), while the L_DicomChannelxxxfunctions can be used to create and manipulate waveform channels. On the dataset level, the toolkit provides four simple, yet powerful functions for using waveforms:

The L_DicomAddWaveformGroup function, which you use to create a new waveform group.

The L_DicomDeleteWaveformGroup, which you use to delete an existing waveform group.

The L_DicomGetWaveformGroupCount, which you use to get the number of waveform groups.

The L_DicomGetWaveformGroup function, which you use to extract a waveform group from a dataset.

Waveform groups

The functionality offered by the LEADTOOLS to manage Waveform groups can be divided into four main categories:

Creating and Freeing
Channel Manipulation
Audio Support
Management of Waveform Group Attributes

More information is provided in the following sections.

Creating and Freeing

To create and manage Waveform groups, you must begin by allocating the memory required for the waveform group. This is accomplished by calling L_DicomWaveGrpCreate. This function returns a handle to the waveform group, which is required for all the functions used with waveform groups.

Once you have finished with the waveform group, you must free the memory that was allocated for the waveform group by calling L_DicomWaveGrpFree.

Channel Manipulation

At the heart of any waveform support is the creation and management of channels. To create a new channel, use the L_DicomWaveGrpAddChannel function. To get an existing one use the L_DicomWaveGrpGetChannel function. The following functions can also be used to manage channels:

L_DicomWaveGrpDeleteChannel

L_DicomWaveGrpGetNumberOfChannels

L_DicomWaveGrpGetNumberOfSamplesPerChannel

L_DicomWaveGrpSetNumberOfSamplesPerChannel

Audio Support

LEADTOOLS waveform support includes support for audio data. To load a wave file into a waveform group, use the L_DicomWaveGrpLoadAudio function. This function is very useful when creating DICOM objects of type "Basic Voice Audio" (1.2.840.10008.5.1.4.1.1.9.4.1), which is typically used for report dictation.

To create a wave file from the channels in a waveform group, use the L_DicomWaveGrpSaveAudio function. This function is very useful when extracting audio (wave) data from a DICOM object of type "Basic Voice Audio" (1.2.840.10008.5.1.4.1.1.9.4.1)

Management of Waveform Group Attributes

LEADTOOLS waveform support includes comprehensive support for the management of the attributes of a waveform group.

In DICOM it is mandatory to specify the waveform's originality (that is, whether the waveform data is original (source) data, or derived data), as well as its sampling frequency. Consequently it is important to call L_DicomWaveGrpSetOriginality and L_DicomWaveGrpSetSamplingFrequency and set these values in order to create a proper waveform group.

If the acquisition equipment adds padding values, DICOM makes it mandatory to set the value by calling L_DicomWaveGrpSetPaddingValue. For more information, refer to the "Waveform Padding Value" (5400,100A) element in the DICOM standard.

The following functions are other functions that can be used to set and get the different attributes of a waveform group:

L_DicomWaveGrpGetMultiplexGroupLabel

L_DicomWaveGrpGetMultiplexGroupTimeOffset

L_DicomWaveGrpGetSampleInterpretation

L_DicomWaveGrpGetSamplingFrequency

L_DicomWaveGrpGetTriggerSamplePosition

L_DicomWaveGrpGetTriggerTimeOffset

L_DicomWaveGrpGetOriginality

L_DicomWaveGrpGetPaddingValue

L_DicomWaveGrpSetMultiplexGroupLabel

L_DicomWaveGrpSetMultiplexGroupTimeOffset

L_DicomWaveGrpSetSampleInterpretation

L_DicomWaveGrpSetTriggerSamplePosition

L_DicomWaveGrpSetTriggerTimeOffset

L_DicomWaveGrpSetOriginality

L_DicomWaveGrpSetPaddingValue

Working with DICOM Waveform Channels

LEADTOOLS waveform channel support can be divided into the following categories:

Creating and Freeing
Setting/Getting Channel Samples
Setting/Getting Channel Source
Setting/Getting Channel Sensitivity
Adding/Managing Waveform Annotations
Setting/Getting Other WaveformChannel Attributes

More information is provided in the following sections.

Creating and Freeing

To create and manipulate Waveform channels you must begin by allocating the memory required for the waveform channel. To do this, call L_DicomChannelCreate. This function returns a handle to the waveform channel, which is required for all the functions used with waveform channels.

Once you have finished with the waveform channel, you must free the memory that was allocated for the waveform channel by calling L_DicomChannelFree.

Setting/Getting Channel Samples

Before setting channel data be sure to call the L_DicomWaveGrpSetSampleInterpretation function to set the sample interpretation. To set the data for an 8-bit channel use the L_DicomChannelSetSamples8 function. Use the L_DicomChannelSetSamples16 function to set the data for a 16-bit one. Use the L_DicomChannelSetSamples32 function if you want to set the channel data and have the toolkit automatically convert it for you based on the "Waveform Sample Interpretation" (5400,1006). Data representation for 8-bit channels can be signed, unsigned, mu-law or A-law, while the data representation for 16-bit channels can be signed or unsigned. To get the data for a channel call the L_DicomChannelGetSamples function.

Setting/Getting Channel Source

In DICOM, it is mandatory to specify the source for a channel. For this reason it is important to call the L_DicomChannelSetSource function to create a proper waveform channel. If you want to get a channel source, call the L_DicomChannelGetSource function.

Setting/Getting Channel Sensitivity

In DICOM, it is mandatory to specify the channel sensitivity if the channel samples represent defined (not arbitrary) units. Since this is almost always the case, it is important to call L_DicomChannelSetSensitivity to create a proper waveform channel. The members of the pChannelSensitivityUnits structure can be managed using the functions offered by the context groups functions (L_DicomxxxContextGroup and L_DicomxxxCodedConcept). For more information about these functions and the use of Coded Concepts in DICOM, please refer to Working with Context Groups.

To get the channel sensitivity call the L_DicomChannelGetSensitivity function.

Adding/Managing Waveform Annotations

To get the number of annotations call the L_DicomChannelGetAnnotationCount function. To create a new annotation, call the L_DicomChannelAddAnnotation function, while you call the L_DicomChannelGetAnnotation function to get an existing one. To delete an annotation call L_DicomChannelDeleteAnnotation.

Setting/Getting Other Waveform Channel Attributes

The following functions are other functions that can be used to set and get the different attributes of a waveform channel:

L_DicomChannelGetLabel

L_DicomChannelGetMaximumValue

L_DicomChannelGetMinimumValue

L_DicomChannelGetOffset

L_DicomChannelGetSampleSkew

L_DicomChannelGetStatus

L_DicomChannelGetTimeSkew

L_DicomChannelGetFilterHighFrequency

L_DicomChannelGetFilterLowFrequency

L_DicomChannelGetIndex