The IDLffDicomEx::AddSequence function method creates a new sequence. The DicomTag argument specifies a sequence (SQ) attribute, which must be part of the standard IOD (Information Object Definition) for the DICOM file type (unless the NON_CONFORMING keyword was set when the IDLffDicomEx object was created using the IDLffDicomEx::Init method).

The optional PARENTSEQID keyword can be used to create a nested sequence, placing the new sequence within an existing sequence. This existing sequence is identified by a sequence identifier, which may have been returned by a previous call to IDLffDicomEx::AddSequence or IDLffDicomEx::GetValue.

Once the sequence has been created, member items can be added via the IDLffDicomEx::SetValue method using the return value from this method, the identifier of the new sequence.

Changes are not written to the DICOM file until you call the IDLffDicomEx::Commit method. When you commit changes, all sequence identifiers are invalidated. You need to call IDLffDicomEx::GetValue to re-access the sequence identifiers. See Adding Groups to a Nested Sequence for an example.

Syntax

Result = Obj->[IDLffDicomEx::]AddSequence (DicomTag [, PARENTSEQID=integer] )

Return Value

Returns a long integer containing the sequence identifier for the newly created sequence. This identifier can be used by other methods that use the SEQID keyword such as IDLffDicomEx::GetValue and IDLffDicomEx::SetValue methods.

Arguments

DicomTag

A string that identifies the group and element of a DICOM sequence (SQ) attribute in the form 'XXXX,XXXX'. The DicomTag argument must reference a public tag that is part of the standard IOD for the image type and must be of the SQ VR type. See DICOM Attributes for a list of tags.

Keywords

PARENTSEQID

Set this keyword only if adding the new sequence to an existing sequence. Use this keyword to specify a parent sequence identifier to add the sequence to as follows:

  • If set to a non-zero value (a sequence identifier), then the sequence will be added to the existing, specified sequence. This sequence identifier may have been returned via a previous call to the IDLffDicomEx::AddSequence method.
  • If set to 0 or not specified, then the sequence is added to the root level of the DICOM file. This is the default.

Example

The following example adds a sequence to the root-level of a cloned DICOM file and, a nested sequence containing attributes within the first sequence. The NON_CONFORMING keyword is set when the clone is created in order to avoid errors encountered when attempting to add non-standard attributes to the selected DICOM file. The newly added attributes are printed to the IDL Output Log window.

For an example that adds groups of repeating tags to a sequence, see the “Examples” section of IDLffDicomEx::AddGroup.

This example does not write the cloned file to memory. To do so, use the IDLffDicomEx::Commit method. 

PRO dicom_addpublicattributes_doc
 
; Select a DICOM file.
sFile = DIALOG_PICKFILE($
    PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $
    TITLE='Select DICOM Patient File', FILTER='*.dcm', $
    GET_PATH=path)
 
; Create a clone (aImgClone.dcm) of the selected file (sfile).
; Set the NON_CONFORMING keyword to be able to add a public SQ
; of radiopharmaceutical items to any file.
 oImg = OBJ_NEW('IDLffDicomEx', path + 'aImgClone.dcm', $
    CLONE=sfile, /NON_CONFORMING)
 
; Add a root-level sequence (Radiopharmaceutical Information).
; **********************************************************
vRootSeq = oImg->AddSequence('0054,0016')
 
; Add an attribute within the sequence.
; *************************************
oImg->SetValue, '0018,1071', 'DS', '0', SEQID=vRootSeq
 
; Add a nested sequence (Radionuclide Code Sequence).
; ***************************************************
vNestSeq = oImg->AddSequence('0054,0300', PARENTSEQID=vRootSeq)
 
; Add two items to the nested sequence.
;**************************************
oImg->SetValue, '0008,0100', 'SH', 'Tc-99m', SEQID=vNestSeq
oImg->SetValue, '0008,0102', 'SH', '99SDM', SEQID=vNestSeq
 
; Print a range including the new tags to
; the Output Log window.
vTags = oImg->EnumerateTags(COUNT=vTagCnt, $
   START_TAG='0054,0000', STOP_TAG='0056,0000')
 
; Format the output.
PRINT, FORMAT= $
   '(%"%-12s, %3s, %5s, %31s, %10s")', $
  'TAG',  'VR', 'SEQID', $
   'DESCRIPTION', 'VALUE'
 
; Cycle through 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 = $
      '(%"%-12s, %3s, %5d, %31s, %10s")', $
       vtg, vTags[xx].VR, vTags[xx].SeqId, $
       vTags[xx].Description, vTags[xx].Value
 
ENDFOR
 
; Clean up references.
OBJ_DESTROY, oImg
 
END

Running this example generates the following output.

TAG         ,  VR, SEQID,                     DESCRIPTION,    VALUE
0054,0016   ,  SQ,   337, Radiopharmaceutical Information, 
>0018,1071  ,  DS,   338,      Radiopharmaceutical Volume,        0
>0054,0300  ,  SQ,   338,      Radionuclide Code Sequence,           
>>0008,0100 ,  SH,   339,                      Code Value,   Tc-99m
>>0008,0102 ,  SH,   339,        Coding Scheme Designator,    99SDM

Version History

6.1

Introduced