Open topic with navigation

IDLffDicomEx::SetValue

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

Note: Use IDLffDicomEx::AddSequence to create the sequence, and then call SetValue, using the returned SEQID from the AddSequence call, to add attributes to the sequence.

This method allows you to:

• Modify existing attributes, those that exist at the root level of a file, and those contained within sequences.
• Add an attribute to the root level of a file, or as an item in a sequence. Use the VR argument to assign the Value Representation of the value. The value passed in will be converted to the specified VR as shown in the following VR Conversion Table section.
• Clear single or multiple values from an attribute at the root level or contained in a sequence using the CLEAR keyword. The 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 sequence attribute (SQ), this removes all attributes in the sequence, including all nested sequences and all repeating groups of tags. Once any change has been committed, attempting to re-access a value that has been removed will fail.

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

Note: Always use the IDLffDicomEx::SetPixelData method to alter pixel data. Do not use the SetValue method.

Note: To ensure the pixel data is stored in the correct format before being further modified, use the IDLffDicomEx::ChangeTransferSyntax method to modify the compression of the pixel data. Do not use SetValue to directly modify the Transfer Syntax UID attribute (0002,0010).

VR Conversion Table

A 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 SetValue 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.

Syntax

Obj->[IDLffDicomEx::]SetValue, DicomTag, VR, Value [, SEQID=integer] [, /CLEAR ] [, /REMOVE]

Note: The VR and Value arguments are optional when the CLEAR or REMOVE keywords are set.

Arguments

DicomTag

A string that identifies the group and element of a DICOM attribute in the form 'XXXX,XXXX'. The DicomTag argument must reference a public tag. See DICOM Attributes for a list of tags.

Note: When adding a DICOM attribute, the tag must be part of the standard IOD for the image type unless the IDLffDicomEx object was initialized with the NON_CONFORMING keyword. Attempting to set an attribute that does not belong to the image type will result in an error. See IDLffDicomEx::Init for details.

VR

A two-character string of the attribute, indicating the Value Representation of the supplied Value argument. When adding an attribute value, the data specified in the Value argument is converted to the data type defined by this argument. See the IDLffDicomEx::SetPrivateValue for how values are converted. See Value Representations for a descriptive VR list.

Note: The VR argument is optional when the REMOVE or CLEAR keyword is set.

Value

An attribute can have a single value or multiple values (only a subset of standard DICOM attributes support 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 is converted to match VR type specified in the VR argument if it is not of the specified type.
• Set multiple values into a tag by specifying an array of values for the tag being written. Values in the array are converted match the VR type specified in the VR argument if they are not of the specified type.

See the IDLffDicomEx::SetPrivateValue for the conversions used per VR type.

Note: The Value argument is optional when the CLEAR or REMOVE keyword is set.

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::AddSequence or IDLffDicomEx::GetValue method.
• Set to 0 or do not set 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 attribute.

Note: Some attributes require one or more values in order to be valid. You should always replace any cleared mandatory values if you wish to maintain a valid DICOM file.

REMOVE

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

Note: Some attributes are required in a valid DICOM file. You should always replace any mandatory attributes that you remove if you wish to maintain a valid DICOM file.

Examples

Adding Attributes

The following code provides examples of:

• Adding attributes to the root level of a selected DICOM file
• Adding a sequence
• Adding attributes to the root-level sequence
• Adding a sequence nested inside the first sequence
• Adding attributes inside the nested sequence

The NON_CONFORMING keyword is set when the clone is created in order to avoid errors 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

This code produces the following output.

TAG , VR, SEQID, DESCRIPTION,    VALUE

0054,0016 , SQ, 123, Radiopharmaceutical Information,

>0018,1071 , DS, 124, Radiopharmaceutical Volume,        0

>0054,0300 , SQ, 124, Radionuclide Code Sequence,

>>0008,0100 , SH, 125, Code Value,   Tc-99m

>>0008,0102 , SH, 125, Coding Scheme Designator,    99SDM

Removing Attributes

The following example clears the value of a root-level attribute, deletes a nested sequence (and all of its items) and modifies the value of another item within a sequence. The output of the additions and modifications are printed to the Output Log window.

PRO print_tags_doc, vTags, vTagCnt

; Format the output.

PRINT, FORMAT= $

'(%"%3s, %2s, %-12s, %3s, %7s, %3s, %5s, %30s, %10s")', $

'IDX', 'LVL', 'TAG', 'VR', 'LEN', 'CNT', '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, %7d, %3d, %5d, %30s, %10s")', $

xx, vTags[xx].Level, vtg, vTags[xx].VR, vTags[xx].Length, $

vTags[xx].ValueCount, vTags[xx].SeqId, $

vTags[xx].Description, vTags[xx].Value

ENDFOR

END

PRO dicom_clearpublicattributes_doc

; Add and modify public attributes within a DICOM file.

; 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 public attribute, Image ID to the root level of the file.

; ***************************************************************

oImg->SetValue, '0054,0400', 'SH', 32

; 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')

print_tags_doc, vTags, vTagCnt

; ************** Clear Values ************************

; Clear the values from an attribute at the root level.

oImg->SetValue, '0054,0400', /CLEAR

; Retrieve the root-level sequence identifier to modify

; items within the sequence.

vSeqId = oImg->GetValue('0054,0016')

; Remove the nested sequence. This also removes all attributes

; contained within the sequence.

oImg->SetValue, '0054,0300', SEQID=vSeqId, /REMOVE

; Change the value of Radiopharmaceutical Volume from 0 to 55.

oImg->SetValue, '0018,1071', 'DS', 55, SEQID=vSeqID

; Print a range including the new tags to

; the Output Log window.

PRINT, '******************* Modified Values *******************

vTags = oImg->EnumerateTags(COUNT=vTagCnt, $

START_TAG='0054,0000', STOP_TAG='0056,0000')

print_tags_doc, vTags, vTagCnt

; Cleanup objects.

OBJ_DESTROY, oImg

END

Running this program produces the following output. the Volume attribute value is changed from 0 to 55, the Radionuclide Code sequence and all member items have been removed, and the Image ID value has been cleared.

Version History