The IDLffDicomEx::SetPrivateValue procedure method allows you to add and alter private attributes including items contained in sequences. When modifying the value of an existing private tag that is contained in a sequence, you must supply a SEQID keyword value. Use the IDLffDicomEx::AddPrivateSequence method or the IDLffDicomEx::GetPrivateValue method to return the SEQID keyword value.

Use IDLffDicomEx::AddPrivateSequence to create the sequence, and then call SetPrivateValue, using the returned SEQID from the AddPrivateSequence call, to add private attributes to the sequence.

This method allows you to:

  • Modify existing private attributes, those that exist at the root level of a file, and those contained within sequences.
  • Add a private attribute (with or without a value) to the root level of a file, or as an item in a sequence. Use the VR argument to determine the Value Representation of the value. The value passed in will be converted to the specified VR as shown in the VR Conversion Table section.
  • Clear single or multiple values from an attribute at the root level or within a sequence using the CLEAR keyword. The private attribute will exist but will not have any associated value.
  • Remove a single attribute from the root level or from within a sequence using the REMOVE keyword. When you specify the REMOVE keyword in conjunction with a private sequence attribute (SQ), this removes all attributes in the sequence, including all nested sequences and all repeating groups of tags. You can also remove a block of private tags using the BLOCKREMOVE keyword. Once any change has been committed, attempting to re-access a value that has been removed will fail.

You must call the IDLffDicomEx::Commit method to write any changes to the DICOM file.

VR Conversion Table

A private tag can have a single value or a tag can have multiple values. Correspondingly, the Value argument consists of either a single value or an array of values. The VR argument determines the Value Representation of the associated value(s). The VR types that can be used in SetPrivateValue are listed in the following table. These are the same VR types described in Value Representations. When SetPrivateValue is called to add or modify an attribute value, the conversions listed in the following table are applied to the data values specified in the Value argument. This lets you pass in values of one type and if possible the values will be converted according to the VR argument.

Value Representation

Conversion

AE (Application Entity)

AS (Age String)

CS (Code String)

DA (Date)

DS (Decimal String)

DT (Date Time)

IS (Integer String)

LO (Long String)

LT (Long Text)

PN (Patient Name)

SH (Short String)

ST (Short Text)

TM (Time)

UI (Unique Identifier)

UT (Unlimited Text)

STRING

SS (Signed Short)

FIX

US (Unsigned Short)

UINT

SL (Signed Long)

LONG

UL (Unsigned Long)

AT (Attribute Tag)

ULONG

FL (Floating Point Single)

FLOAT

FD (Floating Point Double)

DOUBLE

SQ (Sequence)

No conversion. SQ can only specified for removal. To add a sequence, use the AddSequence method.

OB (Other Byte)

No conversion.

OW (Other Word)

No conversion.

OF (Other Float)

FLT

Syntax

Obj->[IDLffDicomEx::] SetPrivateValue, PrivateCode, Group, Element, VR [, Value] [, SEQID=integer] [, /CLEAR] [, /REMOVE] [, / BLOCKREMOVE]

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.

This argument is ignored when the BLOCKREMOVE keyword is set. All private attributes associated with the block of attributes identified by the Group and PrivateCode arguments will be removed.

VR

A two-character string of the attribute, indicating the Value Representation of the supplied Value argument. This argument is required even when removing an attribute. When adding an attribute value, the data specified in the Value argument is converted to the data type defined by this argument. See the VR Conversion Table for how values are converted. See Value Representations for descriptive VR list.

Value

A private attribute can have a single value or multiple values. Set this argument to a single value or array of value(s) to store in the attribute as follows:

  • Set a single value to a tag by specifying a single value for the tag being written. This value matches the VR type specified in the VR argument.
  • Set multiple values into a tag by specifying an array of values for the tag being written; values in the array match the VR type specified in the VR argument.

If the Value argument is null, the value of the tag being written is set to null (the tag will not have a value). When the REMOVE or BLOCKREMOVE keywords are set the Value argument is ignored.

Keywords

SEQID

Set this keyword only if setting the value of an attribute that exists within a sequence. Use this keyword to specify a sequence identifier as follows:

  • Set to a non-zero value (a sequence identifier) indicating the sequence in which the value is contained. This sequence identifier may have been returned via a previous call to the IDLffDicomEx::AddPrivateSequence or IDLffDicomEx::GetPrivateValue method.
  • Set to 0 or do not specify this keyword to indicate the attribute exists at the root level of the DICOM file. This is the default.

CLEAR

Set this keyword to remove all values from the private attribute.

REMOVE

Set this keyword to remove the private attribute from the DICOM file. If the private attribute is a sequence then the sequence and all of the private attributes included in the sequence are removed.

BLOCKREMOVE

Set this keyword to remove an entire block of private attributes from the DICOM file. The private block is identified by the PrivateCode and Group arguments.

Note: When this keyword is set the Element and Value arguments are ignored.

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. To persist any changes, call the IDLffDicomEx::Commit method. The new private attributes are printed to the Output Log window. Then the CLEAR and BLOCKREMOVE keywords are used to clear the value of the multi-valued attribute and delete the group of attributes containing the private sequence. 

PRO print_tags_doc, vTags, vTagCnt
 
; Format the output.
PRINT, FORMAT= $
   '(%"%3s, %2s, %-12s, %3s, %7s, %3s, %5s, %15s")', $
   'IDX', 'LVL', 'TAG',  'VR', 'LEN', 'CNT', 'SEQID', $
   '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, %7d, %3d, %5d, %15s")', $
       xx, vTags[xx].Level, vtg, vTags[xx].VR, vTags[xx].Length, $
       vTags[xx].ValueCount, vTags[xx].SeqId, $
       vTags[xx].Value
 
ENDFOR
 
END
 
PRO dicom_setprivate_remove_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 tag at the root level.
arr = [1, 2, 3, 4]
oImg->SetPrivateValue, 'Private Test', '0053', '12', 'SS', arr
 
; Create a sequence at the root level.
vSeqId = oImg->AddPrivateSequence('VOI Min,Max', '0055', '12')
 
; Add items to the sequence, specifying SQ 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
 
; Return and 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')
 
print_tags_doc, vTags, vTagCnt
 
; Clear the values from the multi-valued private attribute.
oImg->SetPrivateValue, 'Private Test', '0053', '12', 'SS', arr, $
   /CLEAR
 
; Remove the block of private attributes containing the 
; private sequence.
oImg->SetPrivateValue, 'VOI Min,Max', '0055', '12', 'LO', 'x', $
   /BLOCKREMOVE
 
; Print tag modifications.
PRINT, 'Modified tags'
vTags = oImg->EnumerateTags(COUNT=vTagCnt, $
   START_TAG='0053,0000', STOP_TAG='0057,0000')
 
print_tags_doc, vTags, vTagCnt
 
END

The following output is printed to the IDL Output Log window. Notice how using BLOCKREMOVE deletes all attributes with a group value of ‘0055’, including the block length tag, (0055,0010).

Version History

6.1

Introduced