IDLffDicomEx::CopyTags

Syntax | Arguments | Keywords | Example | Version History

The IDLffDicomEx::CopyTags procedure method copies all the tags from the source object to the destination object beginning with the DICOM attribute tag specified by the Start_Tag and copying up to the Stop_Tag. This method does a deep copy of a tag, which means it copies all sub-items, even sequences that contain nested sequences and multiple repeating groups.

Note
This method is intended to copy small blocks of tags from one DICOM file to another DICOM file. This method is not intended to be used to copy entire DICOM files. To clone an existing DICOM file, use the IDLffDicomEx::Init method with the CLONE keyword set to copy an entire DICOM file.

Note
If you are copying non-standard tags to a destination object (as defined by its SOP Class definition), open the destination object with the IDLffDicomEx::Init method NON_CONFORMING keyword to avoid errors.

Note
In rare instances the values of copied tags are changed when they are added to the destination file. If you are copying multiple private block code tags that are not numbered sequentially by 1, they will be numbered in this manner when they are copied into the destination file.

Specifying Start and Stop Tags

The Start_Tag and Stop_Tag don't have to be precise tags. For example, suppose you provide '0010,0000' as the Start_Tag or Stop_Tag argument. If the specified tag does not exist in the file, copying will start with the next element after that one or stop on the element right before that one. While the Start_Tag and Stop_Tag arguments can be loosely defined, the definitions must adhere to the following guidelines:

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.

When copying private DICOM attributes (those with an odd group number) it is necessary to start at the beginning of a private block. An error will be issued if you attempt to copy tags from the middle of a private sequence or private group. For example 0055,0010 is a tag that starts a new private block of tags. Attempting to copy tags beginning with 0055,1013, which exists inside a private block, would generate an error.

Note
If you are copying a block of tags that includes multiple private blocks, each block must be copied independently as shown in the following "Example" section.

The DICOM attributes specified for the start and stop tags cannot be set to `0000,0000'.

Note
Tags 0002,0003 (Media Storage SOP Instance tag) and 0008,0018 (SOP Instance tag) are not copied from one file to another. This avoids overwriting the unique instance identifiers for a file and prevents identical identifiers from existing in two unique files.

Note
Use the IDLffDicomEx::EnumerateTags method to view all attributes in a DICOM file.

Syntax

Obj->[IDLffDicomEx::]CopyTags, DestinationObject, Start_Tag, Stop_Tag

Arguments

DestinationObject

An IDLffDicomEx object reference to the file to which the specified tags will be copied.

Start_Tag

A string identifying a DICOM attribute in the form 'XXXX,XXXX' that specifies the first tag to be copied. A Start_Tag value of '0000,0000' is not valid. See Specifying Start and Stop Tags for more information. See DICOM Attributes for a list of tags.

Stop_Tag

A string identifying a DICOM attribute in the form 'XXXX,XXXX' that specifies the last tag to be copied. A Stop_Tag value of '0000,0000' is not valid. See Specifying Start and Stop Tags for more information. See DICOM Attributes for a list of tags.

Keywords

None

Example

The following example adds a number of private tags to a clone of the first selected image and then copies these blocks of private tags to a clone of the second selected file using the CopyTags method. The new tags and copied tags are displayed in the Output Log window.

Note
If you are copying a block of tags that include multiple private blocks, each block must be copied independently as shown in the following example.

Note
To avoid errors encountered when attempting to overwrite an existing file, neither cloned image is saved to disk. To do so, call the IDLffDicomEx::Commit method.

PRO print_tags_doc, vTags, vTagCnt 
 
; Format the output. 
PRINT, FORMAT= $ 
   '(%"%3s, %2s, %-12s, %3s, %5s, %12s, %15s")', $ 
   'IDX', 'LVL', '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 = $ 
      '(%"%3d, %2d, %-12s, %3s, %5s, %12s, %15s")', $ 
       xx, vTags[xx].Level, vtg, vTags[xx].VR, $ 
       vTags[xx].SeqId, vTags[xx].Description, $ 
       vTags[xx].Value 
 
ENDFOR 
 
END 
 
PRO dicom_tagcopyexample_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.  
 oCloneImg= OBJ_NEW('IDLffDicomEx', path + 'aImgClone.dcm', $ 
    CLONE=sfile, /NON_CONFORMING) 
     
; Add private tags. The following are hypothetical. 
; Create a multi-valued tag at the root level. 
arr = [1, 2, 3, 4] 
oCloneImg->SetPrivateValue, 'Private Test', '0053', '00', 'SS', $ 
   arr 
 
; Create a sequence at the root level. 
vSeqId = oCloneImg->AddPrivateSequence('VOI Min,Max', '0055', $ 
   '12') 
 
; Add items to the sequence, specifying SQ identifier returned by  
; AddPrivateSequence. 
oCloneImg->SetPrivateValue, 'VOI Min,Max', '0055', '13', 'IS', $ 
   '215', SEQID=vSeqID 
oCloneImg->SetPrivateValue, 'VOI Min,Max', '0055', '14', 'IS', $ 
   '234', SEQID=vSeqID 
 
; Print a range including the new tags to  
; the Output Log window. 
vTags = oCloneImg->EnumerateTags(COUNT=vTagCnt, $ 
   START_TAG='0053,0000', STOP_TAG='0057,0000') 
print_tags_doc, vTags, vTagCnt 
 
; Open a second file and copy tags to this file. 
; Select a DICOM file. 
sFile1 = 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.  
 oDestImg = OBJ_NEW('IDLffDicomEx', path + 'aDestImg.dcm', $ 
    CLONE=sfile1, /NON_CONFORMING) 
     
; Copy the private tags to the second file. Each block is copied 
; independently. 
oCloneImg->CopyTags, oDestImg, '0053,0000', '0055,0000' 
oCloneImg->CopyTags, oDestImg, '0055,0000', '0057,0000' 
 
; Print a range including the new tags to  
; the Output Log window. 
PRINT, 'Tags copied to aDestImg file.' 
vTags = oDestImg->EnumerateTags(COUNT=vTagCnt, $ 
   START_TAG='0053,0000', STOP_TAG='0057,0000') 
print_tags_doc, vTags, vTagCnt 
 
; Clean up references. 
OBJ_DESTROY, [oCloneImg, oDestImg] 
 
END

Version History


6.1	Introduced