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
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)
oImg->GetProperty, BITS_ALLOCATED = vBA, ROWS=rows, $
COLUMNS=cols, SAMPLES_PER_PIXEL=samples
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)
oImg = OBJ_NEW('IDLffDicomEx', path + 'aImgClone.dcm', $
CLONE=sfile)
ENDIF
FrameTest = oImg->QueryValue('NUMBER_OF_FRAMES')
IF FrameTest EQ 2 THEN BEGIN
oImg->GetProperty, NUMBER_OF_FRAMES=frame
FRAME = frame - 1
ENDIF ELSE BEGIN
FRAME = 0
ENDELSE
ORDER = 0
vPixels = oImg->GetPixelData(ORDER=order, COUNT=cnt)
PRINT, 'Returned pixel data for number of frames = ', cnt
IF vBA GT 8 THEN BEGIN
vFilterArr = INTARR([rows,cols,frame+1])
ENDIF ELSE BEGIN
vFilterArr = BYTARR([rows,cols,frame+1])
ENDELSE
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
IF vBA EQ 8 THEN BEGIN
vFilterArr = BYTE(vFilterArr)
ENDIF
oImg->SetPixelData, vFilterarr, ORDER=order
oImg->Commit
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
OBJ_DESTROY, oImg
FILE_DELETE, path + 'aImgClone.dcm', /ALLOW_NONEXISTENT
END
Version History