IDLffDicomEx::GetPixelData

Medical Imaging in IDL: IDL DICOM Reference

IDLffDicomEx::GetPixelData

Syntax | Return Value | Arguments | Keywords | Examples | Version History

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.

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

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

When accessing pixel data, the following tags (also exposed as properties) are used in the construction of the array of pixel data:

Table 3-8: DICOM Attributes Queried to Determine the Pixel Data Array 

 

Table 3-8: DICOM Attributes Queried to Determine the Pixel Data Array  DICOM Attribute Description BITS_ALLOCATED Determines the width of the elements in the returned array. Typical values are 8 bits or 16 bits. If this tag is missing an error is issued. SAMPLES_PER_PIXEL Typical values are 1 for monochrome frames and 3 or 4 for RGB frames. If this tag is missing, an error is issued. ROWS Number of horizontal lines in a frame. If this tag is missing an error is issued COLUMNS Number of vertical lines in a frame. If this tag is missing an error is issued PIXEL_REPRESENTATION Determines how to return the data in the correct format for images with greater than 8 bit signed or unsigned data. The GetPixelData method will use a value of 0 if this tag is not present. PLANAR_CONFIGURATION Determines how the ORDER keyword operates on the pixel data. This tag is required for non-monochrome images. The GetPixelData method will use a value of 0 if this tag is not present. NUMBER_OF_FRAMES Determines the frames component of a multi-frame image array and is required for multi-frame images. This tag is only allowed in SOP Classes that support multi-frame images. The GetPixelData method will use a value of 1 if this tag is not present.

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.

 

Table 3-9: Pixel Data Array Possibilities 

 

Table 3-9: Pixel Data Array Possibilities  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.

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

Example Code
The code for filter_clonedicom_doc.pro is provided in the IDL distribution, in the examples/doc/dicom subdirectory of the main IDL directory. You can run the example code directly by entering filter_clonedicom_doc at the IDL prompt.

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 BEGINoImg->GetProperty, NUMBER_OF_FRAMES=frameFRAME = frame - 1; Otherwise, set FRAME to 0 indicating is is a single frame; image. ORDER is set for IDL consistency.ENDIF ELSE BEGINFRAME = 0ENDELSEORDER = 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 BEGINvFilterArr = INTARR([rows,cols,frame+1])ENDIF ELSE BEGINvFilterArr = BYTARR([rows,cols,frame+1])ENDELSE; Filter each frame of data or the single frame.IF frame GT 0 THEN BEGINFOR n = 1, frame+1 DO BEGINvFilterPixels = ROBERTS(vPixels[*,*,n-1])vFilterArr[*,*,n-1] = vFilterPixelsENDFORENDIF ELSE BEGINvFilterArr = 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 BEGINvFilterArr = BYTE(vFilterArr)End; 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 BEGINTVSCL, vPixels[*,*,i-1], 0, ORDER = orderTVSCL, vfilterarr[*,*,i-1], 1, ORDER = orderWAIT, 1ENDFOR; 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_NONEXISTENTEND

Version History

 

6.1 Introduced

 

 

  IDL Online Help (March 06, 2007)