The IDLffDicomEx::GetPrivateValue function method returns the value of a private DICOM attribute using a private code defined by the author of the private tag, a group number and part of the element tag instead of a standard DICOM attribute tag.

GetPrivateValue will fail if you attempt to return a value for an attribute that does not exist, an attribute that does not have a value, or an attribute that has been removed. If you are not sure an attribute exists or has a value use IDLffDicomEx::QueryPrivateValue before calling GetPrivateValue.

In the majority of cases, IDLffDicomEx::GetValue can be used to read a private tag.

Syntax

Result = Obj->[IDLffDicomEx::]GetPrivateValue(PrivateCode, Group, Element [, SEQID=integer] [, COUNT=variable] )

Return Value

Returns one of the following:

  • A scalar value for a private attribute with one value.
  • A vector of scalar values for private attributes with multiple values.
  • A long integer if the private attribute is a sequence. This value is used as the SEQID keyword in subsequent calls to GetPrivateValue to access items contained in the sequence.
  • A vector of values when the sequence contains groups (set of repeating tags within the sequence). See the IDLffDicomEx::GetPrivateValueLength method “Example” section for code that uses such an array.

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'.

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.

Keywords

SEQID

Set this keyword only if retrieving the value of a private attribute that exists within a sequence. Use this keyword to specify 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 GetPrivateValue method.
  • Set to 0 or do not specify this keyword to indicate the private attribute exists at the root level of the DICOM file. This is the default.

COUNT

Set this keyword equal to a named variable that will contain an unsigned long value indicating the number of elements in this method’s return value. Possible values are:

  • 1 indicating the return value is a scalar value.
  • n where n is the number of elements in the returned array. This corresponds to the number of values in the multi-valued attribute.

Example

The following example uses the results of the IDLffDicomEx::GetPrivateValue method COUNT keyword to cycle through a multi-valued private attribute that has been added to a file. To avoid errors arising from attempting to write to an existing file, the cloned image is not saved to the database. To save the changes, call the IDLffDicomEx::Commit method.

PRO dicom_getprivate_value_count_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 = [11, 12, 13, 14]
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 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
 
; Get the value of a multi-valued root-level private attribute.
; Get the nubmer of items in the multi-valued attribute using 
; either the COUNT keyword to GetPrivateValue or
; GetPrivateValueCount. 
vValue = oImg->GetPrivateValue('Private Test', '0053', '10', $
   COUNT=vCount)
 
; Get the VR.
vVR = oImg->GetPrivateVR('Private Test', '0053', '10')
 
FOR i = 1, vCount DO BEGIN
   Print, 'Value number', i, + ' is ', vValue[i-1], + $
      ' and VR is ', vVR
ENDFOR  
 
; Clean up references.
OBJ_DESTROY, oImg
 
END

The following appears in the Output Log window.

Value number       1 is       11 and VR is SS
Value number       2 is       12 and VR is SS
Value number       3 is       13 and VR is SS
Value number       4 is       14 and VR is SS

Version History

6.1

Introduced