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.
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.
You must call the IDLffDicomEx::Commit method to write any changes to the DICOM file.
Always use the IDLffDicomEx::SetPixelData method to alter pixel data. Do not use the SetValue method.
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).
Strings which have trailing spaces may have those spaces ignored. Leading spaces are considered significant and are preserved.
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.
|
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::]SetValue, DicomTag, VR, Value [, SEQID=integer] [, /CLEAR] [, /REMOVE]
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.
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 VR Conversion Table for how values are converted. See Value Representations for a descriptive VR list.
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.
Note: See the VR Conversion Table for the conversions used per VR type.
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 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.
Some attributes are required in a valid DICOM file. You should always replace any mandatory attributes that you remove 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.
For an example that adds groups of repeating tags to a sequence, see the “Examples” section of IDLffDicomEx::AddGroup.
This example does not write the cloned file to memory. To do so, use the IDLffDicomEx::Commit method.
PRO dicom_addpublicattributes_doc
sFile = DIALOG_PICKFILE( $
PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $
TITLE='Select DICOM Patient File', FILTER='*.dcm', $
GET_PATH=path)
oImg = OBJ_NEW('IDLffDicomEx', path + 'aImgClone.dcm', $
CLONE=sfile, /NON_CONFORMING)
vRootSeq = oImg->AddSequence('0054,0016')
oImg->SetValue, '0018,1071', 'DS', '0', SEQID=vRootSeq
vNestSeq = oImg->AddSequence('0054,0300', PARENTSEQID=vRootSeq)
oImg->SetValue, '0008,0100', 'SH', 'Tc-99m', SEQID=vNestSeq
oImg->SetValue, '0008,0102', 'SH', '99SDM', SEQID=vNestSeq
vTags = oImg->EnumerateTags(COUNT=vTagCnt, $
START_TAG='0054,0000', STOP_TAG='0056,0000')
PRINT, FORMAT= $
'(%"%-12s, %3s, %5s, %31s, %10s")', $
'TAG', 'VR', 'SEQID', $
'DESCRIPTION', 'VALUE'
FOR xx = 0, vTagCnt-1 DO BEGIN
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 (vTags[xx].GroupNum GT 0) THEN BEGIN
PRINT, FORMAT='(%"%15s, %1d")', 'Group', vTags[xx].GroupNum
ENDIF
PRINT, FORMAT = $
'(%"%-12s, %3s, %5d, %31s, %10s")', $
vtg, vTags[xx].VR, vTags[xx].SeqId, $
vTags[xx].Description, vTags[xx].Value
ENDFOR
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
PRINT, FORMAT= $
'(%"%3s, %2s, %-12s, %3s, %7s, %3s, %5s, %30s, %10s")', $
'IDX', 'LVL', 'TAG', 'VR', 'LEN', 'CNT', 'SEQID', $
'DESCRIPTION', 'VALUE'
FOR xx = 0, vTagCnt-1 DO BEGIN
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 (vTags[xx].GroupNum GT 0) THEN BEGIN
PRINT, FORMAT='(%"%15s, %1d")', 'Group', vTags[xx].GroupNum
ENDIF
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
sFile = DIALOG_PICKFILE( $
PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $
TITLE='Select DICOM Patient File', FILTER='*.dcm', $
GET_PATH=path)
oImg = OBJ_NEW('IDLffDicomEx', path + 'aImgClone.dcm', $
CLONE=sfile, /NON_CONFORMING)
oImg->SetValue, '0054,0400', 'SH', 32
vRootSeq = oImg->AddSequence('0054,0016')
oImg->SetValue, '0018,1071', 'DS', '0', SEQID=vRootSeq
vNestSeq = oImg->AddSequence('0054,0300', PARENTSEQID=vRootSeq)
oImg->SetValue, '0008,0100', 'SH', 'Tc-99m', SEQID=vNestSeq
oImg->SetValue, '0008,0102', 'SH', '99SDM', SEQID=vNestSeq
vTags = oImg->EnumerateTags(COUNT=vTagCnt, $
START_TAG='0054,0000', STOP_TAG='0056,0000')
print_tags_doc, vTags, vTagCnt
oImg->SetValue, '0054,0400', /CLEAR
vSeqId = oImg->GetValue('0054,0016')
oImg->SetValue, '0054,0300', SEQID=vSeqId, /REMOVE
oImg->SetValue, '0018,1071', 'DS', 55, SEQID=vSeqID
PRINT, '******************* Modified Values *******************
vTags = oImg->EnumerateTags(COUNT=vTagCnt, $
START_TAG='0054,0000', STOP_TAG='0056,0000')
print_tags_doc, vTags, vTagCnt
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