The IDLffDicomEx::EnumerateTags function method returns an array of structures representing the contents of the DICOM file. Each structure contains fields relating to values within the DICOM attribute. This method allows you to access the contents of the DICOM file (specified by start and end tags) and output them to the IDL Workbench Output Log window or to a file.

If the START_TAG and STOP_TAG keywords are not specified, then the return array contains a structure for every DICOM attribute in the file. See the Examples section for sample code.

Syntax

Result = Obj->[IDLffDicomEx::]EnumerateTags ( [, START_TAG=string] [, STOP_TAG=string] [, COUNT=variable] [, FILENAME=string] [, /QUIET] )

Return Value

Returns an array of structures containing the indicated tag values. The array contains a structure for each tag enumerated by this method. Each structure has the following fields:

Field

IDL Data Type

Description

TAG

String

A nine character string containing the DICOM attribute tag (for example, ‘0080,0060’). This field always has a valid value. See DICOM AttributesDICOM Attributes for a list of tags.

DESCRIPTION

String

A description of the public tag governed by the DICOM standard. This field is not available for private tags.

VR

String

A two character string indicating the value representation of the attribute (for example, ‘LO’). This field always has a valid value. See Value Representations for more information.

LENGTH

ULong

An unsigned long value indicating the length of the value field of the DICOM attribute in bytes. If the VR field is SQ (a sequence), then the LENGTH field indicates the number of repeating groups in a sequence.

VALUECOUNT

Long

A long integer indicating the number of values in the value field of the DICOM attribute. If the attribute is multi-valued, then the individual values in the VALUE field are separated by a backslash ‘\’.

SEQID

Long

A long integer containing the sequence identifier of the DICOM attribute. This field contains a non-zero value even when the attribute is not a sequence, so that the value contained in this field can be used without error with any IDLffDicomEx method that has a SEQID keyword. Root level tags have identical valid values.

Note: All sequence identifiers are invalidated when you call the IDLffDicomEx::Commit method. You must use IDLffDicomEx::GetValue to re-access sequence identifiers if needed.

GROUPNUM

Long

A long integer containing the group number for a tag that is in a repeating group. This value can be used when formatting output to display repeating groups of tags. This value equals 0 for tags not in a repeating group.

LEVEL

Long

A long integer indicating the nesting level of an attribute. A value of 0 indicates the tag is at the root level. A value greater than one indicates the tag is not at the root level. This value can be used to indent tags so there is a visual indication of tags inside sequences or nested sequences.

VALUE

String

A string containing the value of the DICOM attribute tag with the following caveats:

  • For tags with multiple values, the values are separated by a backslash character (“\”).
  • When the VR field is OB, OW, or OF the value field is not filled in as the tag contains binary data that is not suitable for presentation in a string. Typically the OB and OW tags are used for pixel data.
  • When the VR is SQ then value is not filled in as the value field for a sequence does not contain data. The sequence identifiers for the tags in the sequence are returned in the SEQID field.

Arguments

None

Keywords

START_TAG

Set this keyword to a string that identifies the first a DICOM attribute to be enumerated. The START_TAG has the format of 'XXXX,XXXX' indicating the group and element of the attribute. A START_TAG value of '0000,0000' is valid. See DICOM Attributes for a list of tags.

Note: The DICOM attributes specified for the start and stop tags must be root level tags. These tags can be sequence tags as long as they exist at the root level, but they cannot be tags contained inside a sequence.

STOP_TAG

Set this keyword to a string that identifies the final DICOM attribute to be enumerated. STOP_TAG must have the format of 'XXXX,XXXX' indicating the group and element of the attribute. A STOP_TAG value of '0000,0000' is valid. See DICOM Attributes for a list of tags.

Note: The DICOM attributes specified for the start and stop tags must be root level tags. These tags can be sequence tags as long as they exist at the root level, but they cannot be tags contained inside a sequence.

COUNT

Set this keyword to a named variable that will contain a long integer indicating the number of structures in the array returned by this method. This equals the number of DICOM attributes for which values are enumerated.

FILENAME

Set this keyword to a string specifying name of the file to which the enumerated tags are to be written. This can either be an absolute path (‘C:\myDicomTags.txt’) or a filename (‘myDicomTags.txt’). When only a filename is provided, the file is saved in the IDL working directory.

QUIET

Set this keyword to suppress the following message in the Output Log window:

“Warning: Skipping tag, unsupported VR type (tag/vr)”

This message is displayed when the DICOM file contains a DICOM attribute that has a VR type of UN (unknown). This can happen when a vendor adds a private tag using the UN value representation. See Value Representations for more information.

Example

The following code prints all tags in the selected file to the Output Log window and to a file (dicomtags.txt) in your working directory. Set the Output Log window to a monospaced font such as Courier to display properly aligned columns. 

PRO read_dicomtags_doc
 
; Select a DICOM file to examine.
sFile = DIALOG_PICKFILE( $
    PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $
    TITLE='Select DICOM Patient File', FILTER='*.dcm')
 
; Open the selected file in read-only mode.
 oImg = OBJ_NEW('IDLffDicomEx', sfile)
 
; Use the EnumerateTags method to access the values of 
; each DICOM attribute. Do not specify start or stop 
; tag values to return all tags. Write the tags to a file
; in the IDL working directory. 
vTags = oImg->EnumerateTags(COUNT = vTagCnt, $
   FILENAME = 'dicomtags.txt')
 
; Print the tags to the Output Log window:
 
; Identify the name of the DICOM file and number of tags. 
oImg->GetProperty, FILENAME = vfilename
PRINT, ' Tags in = ', vfilename, ' tag count = ', vTagCnt
 
; Format the output.
PRINT, FORMAT= $
   '(%"%3s, %2s, %12s, %3s, %7s, %3s, %5s, %30s, %50s")', $
   'IDX', 'LVL', 'TAG',  'VR', 'LEN', 'CNT', 'SEQID', $
   'DESCRIPTION', 'VALUE'
 
; Cycle through all of the tags.
FOR xx = 0, vTagCnt-1  DO BEGIN
 
   ; If the item is nested within another item, indicate the 
   ; level using > symbol.
    IF (vTags[xx].Level GT 0) THEN BEGIN
      vLvl = STRJOIN(REPLICATE('>',vTags[xx].Level))
      vtg =  vLvl + vTags[xx].Tag
    ENDIF ELSE BEGIN
      vtg = vTags[xx].Tag
    ENDELSE
 
    ; If the tags are in a group, indicate this.
    IF (vTags[xx].GroupNum GT 0) THEN BEGIN
       PRINT, FORMAT='(%"%15s, %1d")', 'Group', vTags[xx].GroupNum
    ENDIF
 
   ; Print the fields of the structure. 
   PRINT, FORMAT= $
      '(%"%3d, %2d, %12s, %3s, %7d, %3d, %5d, %30s, %50s")', $
       xx, vTags[xx].Level, vtg, vTags[xx].VR, vTags[xx].Length, $
       vTags[xx].ValueCount, vTags[xx].SeqId, $
       vTags[xx].Description, vTags[xx].Value
 
ENDFOR
 
; Clean up references.
OBJ_DESTROY, oImg
 
END

Version History

6.1

Introduced