The IDLffDicomEx::AddPrivateSequence function method creates a new private sequence. When calling AddPrivateSequence the PrivateCode, Group, and Element arguments identify the characteristics and placement of the private sequence.

The optional PARENTSEQID keyword can be used to create a nested sequence, placing the new private 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::AddPrivateSequence or IDLffDicomEx::GetPrivateValue. Once the sequence has been created, member items can be added via the IDLffDicomEx::SetPrivateValue method using the return value from this method, the identifier of the new sequence.

The new sequence is not written to the DICOM file until you call the IDLffDicomEx::Commit method. When you commit changes, the sequence identifier is invalidated. You need to call IDLffDicomEx::GetPrivateValue to re-access the sequence identifier.

Syntax

Result = Obj->[IDLffDicomEx::]AddPrivateSequence (PrivateCode, Group, Element [, 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::GetPrivateValue and IDLffDicomEx::SetPrivateValue methods.

Arguments

PrivateCode

A string identification code that identifies the private block of data. Within a given private group PrivateCode labels are stored sequentially in the element addresses ranging from '0010' to '00FF'. For example, the string value stored at DICOM tag address '0029,0010' is the PrivateCode for the block of data tagged at '0029,1000' ‑ '0029,10FF'. The label stored at '0029,0011' would be the PrivateCode for the data in tags '0029,1100' - '0029,11 FF'.

Group

A string identifying the group tag number of the private attribute (the first four digits of a DICOM tag). This must be an odd number and in the form 'XXXX'. If this does not reference an existing sequence, then a new private sequence is created.

Element

A string identifying the last two digits of the element associated with the private attribute. This must be in the form 'XX'. Valid values are 10 - FF.

The first two digits of the Element are implicit in the PrivateCode argument.

If the PrivateCode differs, but the Group, Element combination of arguments already exists, the Element value will be internally incremented to avoid overwriting the existing sequence. To modify existing sequences, use the IDLffDicomEx::SetPrivateValue method.

Keywords

PARENTSEQID

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

  • If set to a non-zero value, then the sequence will be added as a member item to the private sequence associated with this parent sequence identifier. This sequence identifier may have been returned via a previous call to the IDLffDicomEx::AddPrivateSequence method.
  • If set to 0 or not specified, then the sequence is added to a private sequence at the root level of the DICOM file. This is the default value.

Example

The following example adds a private attribute to the root level of the DICOM file, a private sequence, and two items in the private sequence. This example shows how to add private attributes, but does not write the tags to the cloned file. The new private attributes are printed to the Output Log window.

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

PRO dicom_setprivate_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).
 oImg = OBJ_NEW('IDLffDicomEx', path + 'aImgClone.dcm', $
    CLONE=sfile)
 
; Add private tags. The following are hypothetical.
; Create a multi-valued tag at the root level.
arr = [1, 2, 3, 4]
oImg->SetPrivateValue, 'Private Test', '0053', '10', 'SS', arr
 
; Create a sequence at the root level.
vSeqId = oImg->AddPrivateSequence('VOI Min,Max', '0055', '12')
 
; Add items to the sequence, specifying the sequence identifier 
; returned by AddPrivateSequence.
oImg->SetPrivateValue, 'VOI Min,Max', '0055', '13', 'IS', '215', $
   SEQID=vSeqID
oImg->SetPrivateValue, 'VOI Min,Max', '0055', '14', 'IS', '234', $
   SEQID=vSeqID
 
; Print a range including the new tags to
; the Output Log window.
vTags = oImg->EnumerateTags(COUNT=vTagCnt, $
   START_TAG='0053,0000', STOP_TAG='0057,0000')
 
; Format the output.
PRINT, FORMAT= $
   '(%"%3s, %2s, %12s, %3s, %12s, %20s")', $
   'IDX', 'LVL', 'TAG',  'VR', '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 = $
      '(%"%3d, %2d, %-12s, %3s, %12s, %20s")', $
       xx, vTags[xx].Level, vtg, vTags[xx].VR, $
       vTags[xx].Description, vTags[xx].Value
 
ENDFOR
 
; Clean up references.
OBJ_DESTROY, oImg
 
END

This example creates the following output.

IDX, LV,          TAG,  VR,  DESCRIPTION,                VALUE
  0,  0, 0053,0010   ,  LO,             ,         Private Test
  1,  0, 0053,1010   ,  SS,             ,              1\2\3\4
  2,  0, 0055,0010   ,  LO,             ,          VOI Min,Max
  3,  0, 0055,1012   ,  SQ,             ,                     
  4,  1, >0055,0010  ,  LO,             ,          VOI Min,Max
  5,  1, >0055,1013  ,  IS,             ,                  215
  6,  1, >0055,1014  ,  IS,             ,                  234

Version History

6.1

Introduced