Class DicomDataset

A collection of DicomItem.

Inheritance

Object

DicomDataset

DicomFileMetaInformation

DicomDirectoryRecord

FilmBox

FilmSession

ImageBox

PresentationLut

DicomCodeItem

DicomMeasuredValue

DicomReferencedSOP

Implements

IEnumerable<DicomItem>

IEnumerable

Inherited Members

Object.Equals(Object)

Object.Equals(Object, Object)

Object.ReferenceEquals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Namespace: Dicom

Assembly: cs.temp.dll.dll

Syntax

public class DicomDataset : IEnumerable<DicomItem>, IEnumerable

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
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
Boolean

InternalTransferSyntax

Gets the DICOM transfer syntax of this dataset.

Declaration

public DicomTransferSyntax InternalTransferSyntax { get; }

Property Value

Type	Description
DicomTransferSyntax

Methods

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
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
IEnumerable<DicomItem>	items	Collection of DICOM items to add.

Returns

Type	Description
DicomDataset	The dataset instance.

Exceptions

Type	Condition
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
ArgumentException	If tag already exists in dataset.

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

Add single DICOM item given by tag and values.

Declaration

public DicomDataset Add<T>(DicomTag tag, Encoding encoding, params T[] values)

Parameters

Type	Name	Description
DicomTag	tag	DICOM tag of the added item.
Encoding	encoding	Encoding to be applied when adding item to the dataset.
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
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
ArgumentException	If tag already exists in dataset.

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

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

Declaration

public DicomDataset Add<T>(DicomVR vr, DicomTag tag, Encoding encoding, 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.
Encoding	encoding	Encoding to be applied when adding item to the dataset.
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
ArgumentException	If tag already exists in dataset.

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
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>(DicomTag, Encoding, T[])

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

Declaration

public DicomDataset AddOrUpdate<T>(DicomTag tag, Encoding encoding, params T[] values)

Parameters

Type	Name	Description
DicomTag	tag	DICOM tag of the added item.
Encoding	encoding	Encoding to be applied when adding item to the dataset.
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.

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

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

Declaration

public DicomDataset AddOrUpdate<T>(DicomVR vr, DicomTag tag, Encoding encoding, 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.
Encoding	encoding	Encoding to be applied when adding item to the dataset.
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.

AddOrUpdatePixelData(DicomVR, IByteBuffer, DicomTransferSyntax)

Add or update the image pixel data element in the dataset

Declaration

[Obsolete("Use DicomPixelData.AddFrame(IByteBuffer) to add pixel data to underlying dataset.")]
public DicomDataset AddOrUpdatePixelData(DicomVR vr, IByteBuffer pixelData, DicomTransferSyntax transferSyntax = null)

Parameters

Type	Name	Description
DicomVR	vr	DICOM vr of the image pixel. For a PixelData element this value should be either DicomVR.OB or DicomVR.OW DICOM VR.
IByteBuffer	pixelData	An that holds the image pixel data
DicomTransferSyntax	transferSyntax	A DicomTransferSyntax object of the pixelData parameter. If parameter is not provided (null), then the default TransferSyntax "ExplicitVRLittleEndian" will be applied to the dataset

Returns

Type	Description
DicomDataset	The dataset instance.

Remarks

Use this method whenever you are attaching an external image pixel data to the dataset and provide the proper TransferSyntax

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

Get(DicomTag, Int32)

Gets the integer element value of the specified tag, or default value if dataset does not contain tag.

Declaration

[Obsolete("Use GetValue, GetValues, GetSingleValue or GetSequence instead. See https://github.com/fo-dicom/fo-dicom/wiki/Getting-data")]
public int Get(DicomTag tag, int defaultValue)

Parameters

Type	Name	Description
DicomTag	tag	Requested DICOM tag.
Int32	defaultValue	Default value to apply if tag is not contained in dataset.

Returns

Type	Description
Int32	Element value corresponding to tag.

Exceptions

Type	Condition
DicomDataException	If the element corresponding to tag cannot be converted to an integer.

Get<T>(DicomTag, T)

Gets the item or element value of the specified tag, or default value if dataset does not contain tag.

Declaration

[Obsolete("Use GetValue, GetValues, GetSingleValue or GetSequence instead. See https://github.com/fo-dicom/fo-dicom/wiki/Getting-data")]
public T Get<T>(DicomTag tag, T defaultValue)

Parameters

Type	Name	Description
DicomTag	tag	Requested DICOM tag.
T	defaultValue	Default value to apply if tag is not contained in dataset.

Returns

Type	Description
T	Item or element value corresponding to tag.

Type Parameters

Name	Description
T	Type of the return value.

Remarks

In code, consider to use this method with implicit type specification, since T can be inferred from defaultValue, e.g. prefer

dataset.Get(tag, "Default")

over

dataset.Get<string>(tag, "Default")

.

Get<T>(DicomTag, Int32)

Gets the item or element value of the specified tag.

Declaration

[Obsolete("Use GetValue, GetValues, GetSingleValue or GetSequence instead. See https://github.com/fo-dicom/fo-dicom/wiki/Getting-data")]
public T Get<T>(DicomTag tag, int n = 0)

Parameters

Type	Name	Description
DicomTag	tag	Requested DICOM tag.
Int32	n	Item index (for multi-valued elements).

Returns

Type	Description
T	Item or element value corresponding to tag.

Type Parameters

Name	Description
T	Type of the return value.

Exceptions

Type	Condition
DicomDataException	If the dataset does not contain tag or if the specified n is out-of-range.

Get<T>(DicomTag, Int32, T)

Gets the item or element value of the specified tag, or default value if dataset does not contain tag.

Declaration

[Obsolete("Use GetValue, GetValues, GetSingleValue or GetSequence instead. See https://github.com/fo-dicom/fo-dicom/wiki/Getting-data")]
public T Get<T>(DicomTag tag, int n, T defaultValue)

Parameters

Type	Name	Description
DicomTag	tag	Requested DICOM tag.
Int32	n	Item index (for multi-valued elements).
T	defaultValue	Default value to apply if tag is not contained in dataset.

Returns

Type	Description
T	Item or element value corresponding to tag.

Type Parameters

Name	Description
T	Type of the return value.

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
IEnumerator<DicomItem>	Enumeration of DICOM items

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
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.
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
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.
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
Func<DicomItem, 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
String	A string that represents the current object.

Overrides

Object.ToString()

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
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
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.
String	stringValue	String representing the element value corresponding to tag.

Returns

Type	Description
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.
Int32	index	Item index (for multi-valued elements).
T	elementValue	Element value corresponding to tag.

Returns

Type	Description
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

Returns

Type	Description
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.

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

Explicit Interface Implementations

IEnumerable.GetEnumerator()

Enumerates all DICOM items.

Declaration

IEnumerator IEnumerable.GetEnumerator()

Returns

Type	Description
IEnumerator	Enumeration of DICOM items

Implements

System.Collections.Generic.IEnumerable<T>

System.Collections.IEnumerable