The IDLffDicomEx::GetPixelData function method returns the uncompressed pixel data from the DICOM image file. (If pixel data is stored in a compressed format, it is uncompressed before it is returned.) A DICOM file may store a single-frame image or a multiple-frame image. In the case of a multi-frame image, this method allows you to return the pixel data of all of the frames, or of a specified frame when you set the FRAME keyword. The NUMBER_OF_FRAMES property can be used to determine whether the image contains single or multiple frames. If the Number of Frames attribute does not exist in the DICOM image file, then it contains a single-frame image.

By default, GetPixelData returns the pixel data array in standard IDL format where the first pixel in the returned array is the bottom left-hand pixel in the frame. You must set the ORDER keyword to return the array DICOM format where the first pixel in the returned array is the top left-hand pixel in the frame.

If you are not sure that the image contains multiple frames, use IDLffDicomEx::QueryValue to check for Number of Frames attribute before attempting to access the value. Not all DICOM SOP classes support multi-frame pixel data. Attempting to return a property value associated with a nonexistent attribute or an attribute that does not have a value will result in an error.

Tip: Use the following settings when displaying planar pixel data (where the PLANAR_CONFIGURATION property value equals 1): set the TVSCL method TRUE keyword to 3, or set the IDLgrImage object INTERLEAVE property to 2.

Syntax


Result = Obj->[IDLffDicomEx::]GetPixelData ( [, FRAME=integer] [, /ORDER] [, COUNT=variable])

Return Value


Returns a multi-dimensional array. The data type of the array is based upon the BITS_ALLOCATED property of the DICOM file as follows:

  • Byte: The image data is 8 bits and signed or unsigned
  • Unsigned integer: The image data is greater than 8 bits and unsigned
  • Integer: The image data is greater than 8 bits and signed

The following table describes the possible arrangements of the multi-dimensional array.

Dimensions

Arrangement

Description

Two-dimensional

[columns, rows]

A single monochrome frame.

Three-dimensional

[columns, rows, frames]

Two or more monochrome frames.

[3, columns, rows]

A single RGB or HSV pixel interleaved frame.

[columns, rows, 3]

A single RGB or HSV planar interleaved frame.

[4, columns, rows]

A single CMYK pixel interleaved frame.

[columns, rows, 4]

A single CMYK planar interleaved frame.

Four-dimensional

[3, columns, rows, frames]

Two or more RGB or HSV pixel interleaved frames.

[columns, rows, 3, frames]

Two or more RGB or HSV planar interleaved frames.

[4, columns, rows, frames]

Two or more CMYK pixel interleaved frames.

[columns, rows, 4, frames]

Two or more CMYK planar interleaved frame.

Arguments


None

Keywords


FRAME

Set this keyword to a long integer to specify which frame or pixel data within a multi-frame image is to be returned. Allowable values denoted the zero-based index value of the frame, from 0 to NUMBER_OF_FRAMES -1. If not specified, the pixel data of all frames is returned.

ORDER

Set the keyword to return the pixel data in DICOM format where the first pixel in the returned array is the top left-hand pixel in the frame. If this keyword is not set, the pixel data array is returned in standard IDL format where the first pixel in the returned array is the bottom left-hand pixel in the frame.

COUNT

Set this keyword to a named variable that will contain a long integer indicating the number frames returned in the pixel data array.

Examples


Filtering Monochrome DICOM Data

The following example applies the ROBERTS edge-detection filter to every frame within a single- or multiple-frame monochrome DICOM file. Each frame is then sequentially displayed in a Direct Graphics widow.

For an example that writes RGB pixel data to an IDLffDicomEx object, see the Example section of IDLffDicomEx::SetPixelData.

The code for filter_clonedicom_doc.pro is provided in the IDL distribution, in the examples/doc/dicom subdirectory of the main IDL directory. Run the example procedure by entering filter_clonedicom at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT filter_clonedicom.pro.
PRO filter_clonedicom_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)
 
; Get image attributes.
oImg->GetProperty, BITS_ALLOCATED = vBA, ROWS=rows, $
   COLUMNS=cols, SAMPLES_PER_PIXEL=samples
 
; Allow user to select monochrome image.
IF samples gt 1 THEN BEGIN 
   v= DIALOG_MESSAGE('This application requires ' + $
      'a monochrome image.', /ERROR)
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)
ENDIF
 
; Check to see if the image has multiple frames.
; First check for the presence of the Number of Frames tag.
FrameTest = oImg->QueryValue('NUMBER_OF_FRAMES')
 
; If the tag exists and has a value, retrieve it. Pixel data 
; FRAME index is zero-based so subtract 1 from the value. 
; ORDER is set for IDL consistency.
IF FrameTest EQ 2 THEN BEGIN
   oImg->GetProperty, NUMBER_OF_FRAMES=frame
   FRAME = frame - 1
; Otherwise, set FRAME to 0 indicating is is a single frame
; image. ORDER is set for IDL consistency. 
ENDIF ELSE BEGIN
   FRAME = 0
ENDELSE
ORDER = 0
 
; Return all of the frames of pixel data by 
; not specifying a value for FRAME.
vPixels = oImg->GetPixelData(ORDER=order, COUNT=cnt)
PRINT, 'Returned pixel data for number of frames = ', cnt
 
; Initialize and array of the proper type for the 
; filtered pixel data. 
IF vBA GT 8 THEN BEGIN
    vFilterArr = INTARR([rows,cols,frame+1])
ENDIF ELSE BEGIN
    vFilterArr = BYTARR([rows,cols,frame+1])
ENDELSE
 
; Filter each frame of data or the single frame.
IF frame GT 0 THEN BEGIN 
   FOR n = 1, frame+1 DO BEGIN
      vFilterPixels = ROBERTS(vPixels[*,*,n-1])
      vFilterArr[*,*,n-1] = vFilterPixels
   ENDFOR
ENDIF ELSE BEGIN
   vFilterArr = ROBERTS(vPixels)
ENDELSE
 
; Roberts function changes byte data to integer. 
; SetPixelData requires array of original type. 
; If original array was byte (as indicated by 
; BITS_ALLOCATED = 8), change the array back to byte.
IF vBA EQ 8 THEN BEGIN
   vFilterArr = BYTE(vFilterArr)
ENDIF
 
; Set the pixel data of the frame(s) back to the image. 
oImg->SetPixelData, vFilterarr, ORDER=order
 
; Write the pixel data changes to the file.
oImg->Commit
 
; Sequentially display each frame of the original
; and filtered data. 
WINDOW, XSIZE=cols*2, YSIZE=rows, $
   TITLE = 'Original and Filtered Frames'
FOR i = 1, frame+1 DO BEGIN
   TVSCL, vPixels[*,*,i-1], 0, ORDER = order
   TVSCL, vfilterarr[*,*,i-1], 1, ORDER = order
   WAIT, 1
ENDFOR
 
; Clean up references.
OBJ_DESTROY, oImg
 
; Note: the following line allows you to run the program
; multiple times without having to manually delete the file. 
; You cannot duplicate an existing file when creating or cloning
; a DICOM file. 
FILE_DELETE, path + 'aImgClone.dcm', /ALLOW_NONEXISTENT
 
END

Version History


6.1

Introduced