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 LDicomWaveformGroup class encapsulates the attributes of a multiplex group (the building block for waveforms in DICOM), while the LDicomWaveformChannel class provides functions to create and manipulate waveform channels. On the dataset level, the toolkit provides four simple, yet powerful functions for using waveforms:

The LDicomDS::AddWaveformGroup function, which you use to create a new waveform group.

The LDicomDS::DeleteWaveformGroup, which you use to delete an existing waveform group.

The LDicomDS::GetWaveformGroupCount, which you use to get the number of waveform groups.

The LDicomDS::GetWaveformGroup function, which you use to extract a waveform group from a dataset

The LDicomWaveformGroup Class

The functionality offered by the LDicomWaveformGroup class can be divided into three main categories:

Channel Manipulation

Audio Support

Management of Waveform Group Attributes

More information is provided in the following sections.

Channel Manipulation

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

LDicomWaveformGroup::DeleteChannel

LDicomWaveformGroup::GetNumberOfChannels

LDicomWaveformGroup::GetNumberOfSamplesPerChannel

LDicomWaveformGroup::SetNumberOfSamplesPerChannel

Audio Support

LEADTOOLS waveform support includes support for audio data. To load a wave file into a waveform group, use the LDicomWaveformGroup::LoadAudio 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 LDicomWaveformGroup::SaveAudio 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 LDicomWaveformGroup::SetWaveformOriginality and LDicomWaveformGroup::SetSamplingFrequency 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 LDicomWaveformGroup::SetWaveformPaddingValue value. 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:

LDicomWaveformGroup::GetMultiplexGroupLabel

LDicomWaveformGroup::GetMultiplexGroupTimeOffset

LDicomWaveformGroup::GetSampleInterpretation

LDicomWaveformGroup::GetSamplingFrequency

LDicomWaveformGroup::GetTriggerSamplePosition

LDicomWaveformGroup::GetTriggerTimeOffset

LDicomWaveformGroup::GetWaveformOriginality

LDicomWaveformGroup::GetWaveformPaddingValue

LDicomWaveformGroup::SetMultiplexGroupLabel

LDicomWaveformGroup::SetMultiplexGroupTimeOffset

LDicomWaveformGroup::SetSampleInterpretation

LDicomWaveformGroup::SetTriggerSamplePosition

LDicomWaveformGroup::SetTriggerTimeOffset

LDicomWaveformGroup::SetWaveformOriginality

LDicomWaveformGroup::SetWaveformPaddingValue

The LDicomWaveformChannel Class

The LDicomWaveformChannel class provides functionality that can be divided into the following five categories:

1.	Setting/Getting Channel Samples
2.	Setting/Getting Channel Source
3.	Setting/Getting Channel Sensitivity
4.	Adding/Managing Waveform Annotations
5.	Setting/Getting Other WaveformChannel Attributes

More information is provided in the following sections.

Setting/Getting Channel Samples

Before setting channel data be sure to call the LDicomWaveformGroup::SetSampleInterpretation function to set the sample interpretation. To set the data for an 8-bit channel use the LDicomWaveformChannel::SetChannelSamples8 function. Use the LDicomWaveformChannel::SetChannelSamples16 function to set the data for a 16-bit one. 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 LDicomWaveformChannel::GetChannelSamples 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 LDicomWaveformChannel::SetChannelSource function to create a proper waveform channel. If you want to get a channel source, call the LDicomWaveformChannel::GetChannelSource 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 LDicomWaveformChannel::SetChannelSensitivity to create a proper waveform channel. The members of the pChannelSensitivityUnits structure can be managed using the functions offered by the LDicomContextGroup class. For more information about this class and the use of Coded Concepts in DICOM, please refer to Working with Context Groups.

To get the channel sensitivity call the LDicomWaveformChannel::GetChannelSensitivity function.

Adding/Managing Waveform Annotations

To get the number of annotations call the LDicomWaveformChannel::GetAnnotationCount function. To create a new annotation, call the LDicomWaveformChannel::AddAnnotation function, while you call the LDicomWaveformChannel::GetAnnotation function to get an existing one. To delete an annotation call LDicomWaveformChannel::DeleteAnnotation.

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:

LDicomWaveformChannel::GetChannelLabel

LDicomWaveformChannel::GetChannelMaximumValue

LDicomWaveformChannel::GetChannelMinimumValue

LDicomWaveformChannel::GetChannelOffset

LDicomWaveformChannel::GetChannelSampleSkew

LDicomWaveformChannel::GetChannelStatus

LDicomWaveformChannel::GetChannelTimeSkew