IDLffDicomEx::AddSequence

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.

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

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

Note
This example does not write the cloned file to memory. To do so, simply 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