Class DicomDataset

A collection of DICOM items.

Inheritance
System.Object
DicomDataset
DicomFileMetaInformation
DicomDirectoryRecord
FilmBox
FilmSession
ImageBox
PresentationLut
DicomCodeItem
DicomMeasuredValue
DicomReferencedSOP
Implements
System.Collections.Generic.IEnumerable<DicomItem>
System.Collections.IEnumerable
System.IEquatable<DicomDataset>
Inherited Members
System.Object.Equals(System.Object, System.Object)
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
Namespace: FellowOakDicom
Assembly: fo-dicom.core.dll
Syntax
public class DicomDataset : IEnumerable<DicomItem>, IEnumerable, IEquatable<DicomDataset>

Constructors

DicomDataset()

Initializes a new instance of the DicomDataset class with InternalTransferSyntax set to Explicit VR Little Endian (DICOM default transfer syntax).

Declaration
public DicomDataset()

DicomDataset(DicomItem[])

Initializes a new instance of the DicomDataset class.

Declaration
public DicomDataset(params DicomItem[] items)
Parameters
Type Name Description
DicomItem[] items

An array of DICOM items.

DicomDataset(DicomTransferSyntax)

Initializes a new instance of the DicomDataset class.

Declaration
public DicomDataset(DicomTransferSyntax internalTransferSyntax)
Parameters
Type Name Description
DicomTransferSyntax internalTransferSyntax

Internal transfer syntax representation of the dataset.

DicomDataset(IEnumerable<DicomItem>)

Initializes a new instance of the DicomDataset class.

Declaration
public DicomDataset(IEnumerable<DicomItem> items)
Parameters
Type Name Description
System.Collections.Generic.IEnumerable<DicomItem> items

A collection of DICOM items.

Properties

AutoValidate

Gets or sets if the content of DicomItems shall be validated as soon as they are added to the DicomDataset

Declaration
[Obsolete("Use this property with care. You can suppress validation, but be aware you might create invalid Datasets if you need to set this property.", false)]
public bool AutoValidate { get; set; }
Property Value
Type Description
System.Boolean

CompareInstancesByContent

Gets or sets how two DicomDatasets are compared if dataset1 == dataset2 is called If this property is true, then all items are iterated and the content is compared. Then two DicomDatasets are equal if the content is equal. If this property is false, then the equalitycheck tests if the DicomDatasets are the same instance.

Declaration
public static bool CompareInstancesByContent { get; set; }
Property Value
Type Description
System.Boolean

InternalTransferSyntax

Gets the DICOM transfer syntax of this dataset.

Declaration
public DicomTransferSyntax InternalTransferSyntax { get; }
Property Value
Type Description
DicomTransferSyntax

Methods

Add(DicomItem)

Adds a DICOM item to the dataset.

Declaration
public DicomDataset Add(DicomItem item)
Parameters
Type Name Description
DicomItem item

DICOM item to add.
Returns
Type Description
DicomDataset

The dataset instance.
Exceptions
Type Condition
System.ArgumentException

If tag of added item already exists in dataset.

Add(DicomItem[])

Add a collection of DICOM items to the dataset.

Declaration
public DicomDataset Add(params DicomItem[] items)
Parameters
Type Name Description
DicomItem[] items

Collection of DICOM items to add.
Returns
Type Description
DicomDataset

The dataset instance.
Exceptions
Type Condition
System.ArgumentException

If tag of added item already exists in dataset.

Add(IEnumerable<DicomItem>)

Add a collection of DICOM items to the dataset.

Declaration
public DicomDataset Add(IEnumerable<DicomItem> items)
Parameters
Type Name Description
System.Collections.Generic.IEnumerable<DicomItem> items

Collection of DICOM items to add.
Returns
Type Description
DicomDataset

The dataset instance.
Exceptions
Type Condition
System.ArgumentException

If tag of added item already exists in dataset.

Add<T>(DicomTag, T[])

Add single DICOM item given by tag and values.

Declaration
public DicomDataset Add<T>(DicomTag tag, params T[] values)
Parameters
Type Name Description
DicomTag tag

DICOM tag of the added item.
T[] values

Values of the added item.
Returns
Type Description
DicomDataset

The dataset instance.
Type Parameters
Name Description
T

Type of added values.
Exceptions
Type Condition
System.ArgumentException

If tag already exists in dataset.

Add<T>(DicomVR, DicomTag, T[])

Add single DICOM item given by vr, tag and values.

Declaration
public DicomDataset Add<T>(DicomVR vr, DicomTag tag, params T[] values)
Parameters
Type Name Description
DicomVR vr

DICOM vr of the added item. Use when setting a private element.
DicomTag tag

DICOM tag of the added item.
T[] values

Values of the added item.
Returns
Type Description
DicomDataset

The dataset instance.
Type Parameters
Name Description
T

Type of added values.
Remarks

No validation is performed on the vr matching the element tag This method is useful when adding a private tag and need to explicitly set the VR of the created element.

Exceptions
Type Condition
System.ArgumentException

If tag already exists in dataset.

AddOrUpdate(DicomItem)

Add a DICOM item to the dataset. Update existing items.

Declaration
public DicomDataset AddOrUpdate(DicomItem item)
Parameters
Type Name Description
DicomItem item

DICOM item to add.
Returns
Type Description
DicomDataset

The dataset instance.

AddOrUpdate(DicomItem[])

Add a collection of DICOM items to the dataset. Update existing items.

Declaration
public DicomDataset AddOrUpdate(params DicomItem[] items)
Parameters
Type Name Description
DicomItem[] items

Collection of DICOM items to add.
Returns
Type Description
DicomDataset

The dataset instance.

AddOrUpdate(IEnumerable<DicomItem>)

Add a collection of DICOM items to the dataset. Update existing items.

Declaration
public DicomDataset AddOrUpdate(IEnumerable<DicomItem> items)
Parameters
Type Name Description
System.Collections.Generic.IEnumerable<DicomItem> items

Collection of DICOM items to add.
Returns
Type Description
DicomDataset

The dataset instance.

AddOrUpdate<T>(DicomTag, T[])

Add or update a single DICOM item given by tag and values.

Declaration
public DicomDataset AddOrUpdate<T>(DicomTag tag, params T[] values)
Parameters
Type Name Description
DicomTag tag

DICOM tag of the added item.
T[] values

Values of the added item.
Returns
Type Description
DicomDataset

The dataset instance.
Type Parameters
Name Description
T

Type of added values.

AddOrUpdate<T>(DicomVR, DicomTag, T[])

Add or update a single DICOM item given by vr, tag and values.

Declaration
public DicomDataset AddOrUpdate<T>(DicomVR vr, DicomTag tag, params T[] values)
Parameters
Type Name Description
DicomVR vr

DICOM vr of the added item. Use when setting a private element.
DicomTag tag

DICOM tag of the added item.
T[] values

Values of the added item.
Returns
Type Description
DicomDataset

The dataset instance.
Type Parameters
Name Description
T

Type of added values.
Remarks

No validation is performed on the vr matching the element tag This method is useful when adding a private tag and need to explicitly set the VR of the created element.

Clear()

Removes all items from the dataset.

Declaration
public DicomDataset Clear()
Returns
Type Description
DicomDataset

Current Dataset

Contains(DicomTag)

Checks the DICOM dataset to determine if the dataset already contains an item with the specified tag.

Declaration
public bool Contains(DicomTag tag)
Parameters
Type Name Description
DicomTag tag

DICOM tag to test
Returns
Type Description
System.Boolean

True if a DICOM item with the specified tag already exists.

CopyTo(DicomDataset)

Copies all items to the destination dataset.

Declaration
public DicomDataset CopyTo(DicomDataset destination)
Parameters
Type Name Description
DicomDataset destination

Destination Dataset
Returns
Type Description
DicomDataset

Current Dataset

CopyTo(DicomDataset, DicomMaskedTag)

Copies tags matching mask to the destination dataset.

Declaration
public DicomDataset CopyTo(DicomDataset destination, DicomMaskedTag mask)
Parameters
Type Name Description
DicomDataset destination

Destination Dataset
DicomMaskedTag mask

Tags to copy
Returns
Type Description
DicomDataset

Current Dataset

CopyTo(DicomDataset, DicomTag[])

Copies tags to the destination dataset.

Declaration
public DicomDataset CopyTo(DicomDataset destination, params DicomTag[] tags)
Parameters
Type Name Description
DicomDataset destination

Destination Dataset
DicomTag[] tags

Tags to copy
Returns
Type Description
DicomDataset

Current Dataset

Equals(DicomDataset)

Declaration
public bool Equals(DicomDataset other)
Parameters
Type Name Description
DicomDataset other
Returns
Type Description
System.Boolean

Equals(Object)

Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
System.Object obj
Returns
Type Description
System.Boolean
Overrides
System.Object.Equals(System.Object)

FunctionalGroupValues(Int32)

Returns a DicomDataset, that contains all Tags accumulated from the Shared Functional Group Sequence and the Per-Frame Functional Group Sequence.

Declaration
public DicomDataset FunctionalGroupValues(int frame)
Parameters
Type Name Description
System.Int32 frame

Zero-based frame index.
Returns
Type Description
DicomDataset
Exceptions
Type Condition
DicomDataException

GetCodeItem(DicomTag)

Declaration
public DicomCodeItem GetCodeItem(DicomTag tag)
Parameters
Type Name Description
DicomTag tag
Returns
Type Description
DicomCodeItem

GetDicomItem<T>(DicomTag)

Gets the DicomItem of the specified tag.

Declaration
public T GetDicomItem<T>(DicomTag tag)
    where T : DicomItem
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
Returns
Type Description
T

Item corresponding to tag or 

null
if the tag is not contained in the instance.
Type Parameters
Name Description
T

Type of the return value. Must inherit from DicomItem.

GetEnumerator()

Enumerates all DICOM items.

Declaration
public IEnumerator<DicomItem> GetEnumerator()
Returns
Type Description
System.Collections.Generic.IEnumerator<DicomItem>

Enumeration of DICOM items

GetHashCode()

Declaration
public override int GetHashCode()
Returns
Type Description
System.Int32
Overrides
System.Object.GetHashCode()

GetMeasuredValue(DicomTag)

Declaration
public DicomMeasuredValue GetMeasuredValue(DicomTag tag)
Parameters
Type Name Description
DicomTag tag
Returns
Type Description
DicomMeasuredValue

GetPrivateTag(DicomTag)

Converts a dictionary tag to a valid private tag. Creates the private creator tag if needed.

Declaration
public DicomTag GetPrivateTag(DicomTag tag)
Parameters
Type Name Description
DicomTag tag

Dictionary DICOM tag
Returns
Type Description
DicomTag

Private DICOM tag, or null if all groups are already used.

GetReferencedSOP(DicomTag)

Declaration
public DicomReferencedSOP GetReferencedSOP(DicomTag tag)
Parameters
Type Name Description
DicomTag tag
Returns
Type Description
DicomReferencedSOP

GetSequence(DicomTag)

Gets the sequence of the specified tag.

Declaration
public DicomSequence GetSequence(DicomTag tag)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
Returns
Type Description
DicomSequence

Sequence of datasets corresponding to tag.
Exceptions
Type Condition
DicomDataException

If the dataset does not contain tag or this is not a sequence.

GetSingleValue<T>(DicomTag)

Gets the element value of the specified tag, whose value multiplicity has to be 1.

Declaration
public T GetSingleValue<T>(DicomTag tag)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
Returns
Type Description
T

Element values corresponding to tag.
Type Parameters
Name Description
T

Type of the return value. This cannot be an array type.
Exceptions
Type Condition
DicomDataException

If the dataset does not contain tag, is empty or is multi-valued.

GetSingleValueOrDefault<T>(DicomTag, T)

Gets the element value of the specified tag, whose value multiplicity has to be 1, or the provided defaultValue if the element value does not exist.

Declaration
public T GetSingleValueOrDefault<T>(DicomTag tag, T defaultValue)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
T defaultValue

Value that is returned if the requested element value does not exist.
Returns
Type Description
T
Type Parameters
Name Description
T

Type of the return value. This cannot be an array type.

GetString(DicomTag)

Gets a string representation of the value of the specified tag.

Declaration
public string GetString(DicomTag tag)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
Returns
Type Description
System.String

String representing the element value corresponding to tag.
Exceptions
Type Condition
DicomDataException

If the dataset does not contain tag.

GetValue<T>(DicomTag, Int32)

Gets the index-th element value of the specified tag.

Declaration
public T GetValue<T>(DicomTag tag, int index)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
System.Int32 index

Item index (for multi-valued elements).
Returns
Type Description
T

Element value corresponding to tag.
Type Parameters
Name Description
T

Type of the return value. This cannot be an array type.
Exceptions
Type Condition
DicomDataException

If the dataset does not contain tag or if the specified index is out-of-range.

GetValueCount(DicomTag)

Returns the number of values in the specified tag.

Declaration
public int GetValueCount(DicomTag tag)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
Returns
Type Description
System.Int32
Exceptions
Type Condition
DicomDataException

If the dataset does not contain tag.

GetValueOrDefault<T>(DicomTag, Int32, T)

Gets the index-th element value of the specified tag or the provided defaultValue if the requested value is not contained in the dataset.

Declaration
public T GetValueOrDefault<T>(DicomTag tag, int index, T defaultValue)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
System.Int32 index

Item index (for multi-valued elements).
T defaultValue

Value that is returned if the requested element value does not exist.
Returns
Type Description
T
Type Parameters
Name Description
T

Type of the return value. This cannot be an array type.

GetValues<T>(DicomTag)

Gets the array of element values of the specified tag.

Declaration
public T[] GetValues<T>(DicomTag tag)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
Returns
Type Description
T[]

Element values corresponding to tag.
Type Parameters
Name Description
T

Type of the return value. This cannot be an array type.
Exceptions
Type Condition
DicomDataException

If the dataset does not contain tag.

Remove(DicomTag[])

Removes items for specified tags.

Declaration
public DicomDataset Remove(params DicomTag[] tags)
Parameters
Type Name Description
DicomTag[] tags

DICOM tags to remove
Returns
Type Description
DicomDataset

Current Dataset

Remove(Func<DicomItem, Boolean>)

Removes items where the selector function returns true.

Declaration
public DicomDataset Remove(Func<DicomItem, bool> selector)
Parameters
Type Name Description
System.Func<DicomItem, System.Boolean> selector

Selector function
Returns
Type Description
DicomDataset

Current Dataset

ToString()

Returns a string that represents the current object.

Declaration
public override string ToString()
Returns
Type Description
System.String

A string that represents the current object.
Overrides
System.Object.ToString()

TryGetNonEmptySequence(DicomTag, out DicomSequence)

Gets the sequence of the specified tag if it exists and is not empty.

Declaration
public bool TryGetNonEmptySequence(DicomTag tag, out DicomSequence sequence)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
DicomSequence sequence

Sequence of datasets corresponding to tag.
Returns
Type Description
System.Boolean

Returns 

true
if the tag exists and is not empty, 
false
otherwise.

TryGetSequence(DicomTag, out DicomSequence)

Gets the sequence of the specified tag.

Declaration
public bool TryGetSequence(DicomTag tag, out DicomSequence sequence)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
DicomSequence sequence

Sequence of datasets corresponding to tag.
Returns
Type Description
System.Boolean

Returns 

true
if the tag could be returned as sequence, 
false
otherwise.

TryGetSingleValue<T>(DicomTag, out T)

Tries to get the element value of the specified tag, whose value multiplicity has to be 1.

Declaration
public bool TryGetSingleValue<T>(DicomTag tag, out T value)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
T value
Returns
Type Description
System.Boolean

Returns 

true
if the element values could be exctracted, otherwise 
false
.
Type Parameters
Name Description
T

Type of the return value. This cannot be an array type.

TryGetString(DicomTag, out String)

Tries to get a string representation of the value of the specified tag.

Declaration
public bool TryGetString(DicomTag tag, out string stringValue)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
System.String stringValue

String representing the element value corresponding to tag.
Returns
Type Description
System.Boolean

Returns 

false
if the dataset does not contain the tag.

TryGetValue<T>(DicomTag, Int32, out T)

Tries to get the index-th element value of the specified tag.

Declaration
public bool TryGetValue<T>(DicomTag tag, int index, out T elementValue)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
System.Int32 index

Item index (for multi-valued elements).
T elementValue

Element value corresponding to tag.
Returns
Type Description
System.Boolean

Returns 

true
if the element value could be exctracted, otherwise 
false
.
Type Parameters
Name Description
T

Type of the return value. This cannot be an array type.

TryGetValues<T>(DicomTag, out T[])

Tries to get the array of element values of the specified tag.

Declaration
public bool TryGetValues<T>(DicomTag tag, out T[] values)
Parameters
Type Name Description
DicomTag tag

Requested DICOM tag.
T[] values

Element values corresponding to tag.
Returns
Type Description
System.Boolean

Returns 

true
if the element values could be extracted, otherwise 
false
.
Type Parameters
Name Description
T

Type of the return value. This cannot be an array type.

Validate()

Performs a validation of all DICOM items that are contained in this DicomDataset. This explicit call for validation ignores the gobal DicomValidation.AutoValidate and DicomDataset.AutoValidate property.

Declaration
public void Validate()
Exceptions
Type Condition
DicomValidationException

A exception is thrown if one of the items does not pass the valiation

ValidateTag(DicomTag)

Does nothing. Can be overwritten in derived classes to check if the tag is allowed.

Declaration
protected virtual void ValidateTag(DicomTag tag)
Parameters
Type Name Description
DicomTag tag

Operators

Equality(DicomDataset, DicomDataset)

Declaration
public static bool operator ==(DicomDataset a, DicomDataset b)
Parameters
Type Name Description
DicomDataset a
DicomDataset b
Returns
Type Description
System.Boolean

Inequality(DicomDataset, DicomDataset)

Declaration
public static bool operator !=(DicomDataset a, DicomDataset b)
Parameters
Type Name Description
DicomDataset a
DicomDataset b
Returns
Type Description
System.Boolean

Explicit Interface Implementations

IEnumerable.GetEnumerator()

Enumerates all DICOM items.

Declaration
IEnumerator IEnumerable.GetEnumerator()
Returns
Type Description
System.Collections.IEnumerator

Enumeration of DICOM items

Implements

System.Collections.Generic.IEnumerable<T>
System.Collections.IEnumerable
System.IEquatable<T>

Extension Methods