The IDLffDicomEx::SetPixelData function method writes pixel data to the DICOM image file. DICOM files can store pixel data for a single-frame image or a multi-frame image. This method accepts uncompressed pixel data. If the transfer syntax of the DICOM file indicates the image is to be stored in a compressed format, the data will be compressed by this method. As long as the specified pixel data array has the correct number of bytes, it can have any dimensions. See the PixelData argument for details.

Pixel data changes are written to the DICOM file only when you call the IDLffDicomEx::Commit method.

Writing Frames of Pixel Data to Lossy and Lossless Formats

When the transfer syntax indicates a lossy JPEG compression format (JPEG Baseline, JPEG Extended, or JPEG 2000), you must pass in all the pixel data for all the frames in a multi-frame image. This method does not support writing a single frame of pixel data to a multi-frame image that is stored in a lossy JPEG compression format. This is prohibited to prevent the degradation of data that occurs when a frame is uncompressed then recompressed in a lossy format.

This method does support writing a single frame of pixel data to multi-frame image stored in a lossless JPEG compression format (JPEG Lossless, JPEG 2000 Lossless). When the compression format is lossless, a frame of data can be uncompressed and recompressed without losing of data.

Specifying Pixel Data For a New Image

When assigning pixel data to a brand new image, you must set the following properties either before setting the pixel data or while setting pixel data. Once these values are set in a new image, and the SetPixelData method has been called, do not change the values as the underlying pixel data will not reflect changes to these tags.

Many other tags are needed (and specified by the DICOM standard) for the creation of a valid DICOM image for a particular SOP Class. (Complete details can be found in Digital Imaging and Communications in Medicine (DICOM) - Part 3: Information Object Definitions.) This list shows only the tags needed to permit pixel data to be added to an image.

When setting pixel data on a new image, the following attributes are required to the construct the pixel data array.

You can set these attributes using IDLffDicomEx::SetValue, IDLffDicomEx::SetProperty, or by setting keywords to this method.

DICOM Attribute

Description

BITS_ALLOCATED

Typical values are 8 bits or 16 bits. An error is issued if this is absent.

COLUMNS

Number of vertical lines in a frame. An error is issued if this is absent.

NUMBER_OF_FRAMES

This tag is required for a multi-frame image. This tag is only allowed in SOP Classes that support multi-frame images. The default value is 1.

PHOTOMETRIC_INTERPRETATION

This tag is required for RGB images, but should be set when creating a new image.

PIXEL_REPRESENTATION

This tag is not required to set pixel data, but is required to properly determine how to return the data (using the GetPixelData method) in the correct format for images with greater than 8 bit signed or unsigned data. The default value is 0.

PLANAR_CONFIGURATION

This tag is required for non-monochrome images as it is used in determining how the GetPixelData method ORDER keyword operates on the pixel data. The default value is 0.

ROWS

Number of horizontal lines in a frame. An error is issued if this is absent.

SAMPLES_PER_PIXEL

Typical values are 1 for monochrome frames and 3 for RGB frames. An error is issued if this is absent.

Typical values for attributes that are dependent upon the data type of the image are shown in the following table:

Property

UINT

INT

BYTE

RGB

BITS_ALLOCATED

16

16

8

8

BITS_STORED

10

16

8

8

HIGH_BIT

9

15

7

7

PHOTOMETRIC_INTERPRETATION

†

†

†

RGB

SAMPLES_PER_PIXEL

1

1

1

3

PIXEL_REPRESENTATION

0

1

0

0

PLANAR_CONFIGURATION

N/A

N/A

N/A

0 or 1

† MONOCHROME2

Syntax

Obj->[IDLffDicomEx::] SetPixelData, PixelData [, FRAME =integer] [, /ORDER ] [, BITS_ALLOCATED=integer] [, COLUMNS=integer] [, NUMBER_OF_FRAMES=string] [, PHOTOMETRIC_INTERPRETATION={MONOCHROME1 | MONOCHROME2 | PALETTECOLOR | RGB | HSV | CMYK}] [, PIXEL_REPRESENTATION={0 | 1}] [, PLANAR_CONFIGURATION={0 | 1}] [, ROWS=integer] [, SAMPLES_PER_PIXEL={1 | 3 | 4}]

Arguments

PixelData

The pixel data array for one frame of data or a pixel data array for all the frames.

The incoming array of pixel data must be the exact size of a single frame (when setting a single frame) or of all the frames (when setting all frames). While the array can have any dimensions, it must conform to the following:

  • The format of the array must conform to the PLANAR_CONFIGURATION and PHOTOMETRIC_INTERPRETATION values of the image.
  • The size of the pixel data array must be equal to:
  SamplesPerPixel * Rows * Columns * NumFramesToWrite *
     NumBytesPerSample

where:

  • SamplesPerPixel = DICOM attribute (0028,0002)
  • Rows = DICOM attribute (0028,0010)
  • Columns = DICOM attribute (0028,0011)
  • NumFramesToWrite = 1 or DICOM attribute Number of Frames (0028,0008) in the image file
  • NumBytesPerSample = 1 when the Bits Allocated (0028,0100) is less then or equal to 8, or NumBytesPerSample = 2 when the Bits Allocated (0028,0100) is greater then 8.

Keywords

See Specifying Pixel Data For a New Image for information on keywords listed in the syntax, but not shown here.

FRAME

Set this keyword to the zero-based index of the frame of pixel data to write. Allowable values for FRAME range from 0 to NUMBER_OF_FRAMES - 1. If FRAME is not specified, the pixel data of all frames in the PixelData array are written to the image. Otherwise, only the pixel data of the one, specified frame is written.

ORDER

Set the keyword when passing in pixel data in DICOM format, where the first pixel in the array is the top left-hand pixel in the frame. The SetPixelData method will not flip the rows when writing the data. If this keyword is not set, the array is in standard IDL format, where the first pixel in the array is the bottom left-hand pixel in the frame. The SetPixelData method will flip the rows before writing the pixel data to the DICOM image.

Example

The following example allows you to select an image file of any format. Based on properties of the data, the required pixel data attributes are set. The example creates a MR file for monochrome or palette image data, or a US file for RGB data. Note that this example sets only the smallest possible number of attributes required for setting pixel data. This does not create a valid DICOM file as the other tags mandated by the SOP class have not been set as required by a the DICOM standard. (Complete details can be found in Digital Imaging and Communications in Medicine (DICOM) - Part 3: Information Object Definitions.)

The code for dicomex_importimage_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 .EDIT dicomex_importimage_doc at the IDL prompt.

By default, the transfer syntax is set to Explicit VR Little Endian when a new file is created. After pixel data has been set on the new image, you can use the IDLffDicomEx::ChangeTransferSyntax method to change the file compression.

The last few lines of the program delete the files that are created, so that the example can be run multiple times without an error occurring because you are attempting to create a file with an existing filename. Comment out these lines to retain the images. 

PRO dicomex_importimage_doc
  ; Import in the pixel data of an image, and
  ; then set it as the pixel data for a new Image
  ; object.
   
  ; Determine the full path to the image file.
  sFile = DIALOG_PICKFILE(/MUST_EXIST, $
           TITLE = 'Select an Image File', $
           FILTER = ['*.bmp', '*.jpg', '*.png', $
              '*.ppm', '*.srf', '*.tif'], $
          GET_PATH=path)
   
  ; If no file is selected, return to the previous
  ; level.
  IF (sFile EQ '') THEN RETURN
   
  ; Query the image file.
  vOpenStatus = QUERY_IMAGE(sFile, vQueryInfo)
   
  ; If the file cannot be openned with IDL, return
  ; to the previous level.
  IF (vOpenStatus NE 1) THEN RETURN
   
  ; Initialize some of the image parameters.
  vNumSamples = vQueryInfo.channels
  vCols = vQueryInfo.dimensions[0]
  vRows = vQueryInfo.dimensions[1]
  vImgSize = vQueryInfo.dimensions
  vNumFrames = vQueryInfo.num_images
  vPixelType = vQueryInfo.pixel_type
   
  ; Handle single channel images.
  If vNumSamples EQ 1 THEN BEGIN
     CASE vPixelType of
              1: BEGIN
                       ; Set properties for byte data.
                       vBitsAlloc = 8
        vPixelRep = 0 ; accept the default.
                       vPhotoInterp = 'MONOCHROME2'
              END
   
              2: BEGIN
                       ; Set properties for signed integer.
                       vBitsAlloc = 10
                   vPixelRep = 1
        vPhotoInterp = 'MONOCHROME2'
              END
   
              12: BEGIN
                ; Set properties for unsigned integer.
                  vBitsAlloc = 16
                       vPixelRep = 0
                       vPhotoInterp = 'MONOCHROME2'
              END
     ENDCASE
   
     ; If the file contains multiple images, access these
     ; images as multiple frames. If the file contains
     ; only one image, access just that image.
     IF (vNumFrames GT 1) THEN BEGIN
              vPixelData = MAKE_ARRAY(vCols, vRows, vNumFrames, $
                    TYPE = vPixelType)
           FOR vIndex = 0L, (vNumFrames - 1) DO $
                    vPixelData[*, *, vIndex] = READ_IMAGE(sFile, $
        IMAGE_INDEX = vIndex)
        ENDIF ELSE BEGIN
                 vPixelData = READ_IMAGE(sFile)
        ENDELSE
   
     ; Create a new DICOM file and set properties.
     oImg = OBJ_NEW('IDLffDicomEx', $
     path+PATH_SEP()+'aNewMonoImg.dcm', $
           SOP_CLASS = 'STANDARD_MR', /NON_CONFORMING, /CREATE)
   
     ; Call set pixel data with only required properties.
     oImg->SetPixelData, vPixelData, $
              BITS_ALLOCATED = vBitsAlloc, $
          COLUMNS = vCols, $
          NUMBER_OF_FRAMES = vNumFrames, $
     PHOTOMETRIC_INTERPRETATION = vPhotoInterp, $
     PIXEL_REPRESENTATION = vPixelRep, $
     ROWS = vRows, $
              SAMPLES_PER_PIXEL = vNumSamples, $
     /ORDER
   
     ; Commit the file.
     oImg->Commit
   
     ; Display monochrome image (frames).
     WINDOW, XSIZE=vcols, YSIZE=vrows, $
     TITLE = 'New Monochrome DICOM Image'
   
     FOR i = 1, vNumFrames DO BEGIN
           TVSCL, vPixelData[*,*,i-1]
           WAIT, 1
     ENDFOR
   
  ENDIF
   
  ; If it is an RGB image, determine interleaving.
  IF (vNumSamples EQ 3) THEN BEGIN
   
     ; Determine the size of all the dimensions of the pixel
     ; data array.
     vDataSize = SIZE(vPixelData, /DIMENSIONS)
   
  ; Determine the planar configuration of the image.
     vInterleave = WHERE((vDataSize NE vCols) AND $
              (vDataSize NE vRows))
   
     ; Return if line interleaved (vCols,3,vRows)
     IF (vInterleave[0] EQ 1) THEN RETURN
   
     ; If pixel interleaved (3,vCols,vRows), set to 0.
     ; If planar interleaved (vCols,vRows,3), set to 1
     IF (vInterleave[0] EQ 0) THEN vPlanarConfig = 0 $
          ELSE vPlanarConfig = 1
   
     ; Set other properties for RGB images.
     vBitsAlloc = 8
     vPhotoInterp = 'RGB'
     vPixelRep = 0
   
     ; Use READ_IMAGE to access the image array.
     vPixelData = READ_IMAGE(sFile)
   
     ; Create a new DICOM file and set properties.
     oImg = OBJ_NEW('IDLffDicomEx', $
     path+PATH_SEP()+'aNewRBGImg.dcm', $
           SOP_CLASS = 'STANDARD_US', /NON_CONFORMING, /CREATE)
   
     ; Call set pixel data with required properties
     oImg->SetPixelData, vPixelData, $
              BITS_ALLOCATED = vBitsAlloc, $
          COLUMNS = vCols, $
              NUMBER_OF_FRAMES = vNumFrames, $
              PHOTOMETRIC_INTERPRETATION = vPhotoInterp, $
     PIXEL_REPRESENTATION = vPixelRep, $
              PLANAR_CONFIGURATION = vPlanarConfig, $
     ROWS = vRows, $
     SAMPLES_PER_PIXEL = vNumSamples, $
              /ORDER
     oImg->Commit
   
     ; Display RGB image.
     WINDOW, XSIZE=vcols, YSIZE=vrows, TITLE = 'New RGB DICOM Image'
   
     IF vPlanarConfig EQ 0 THEN vTrue = 1 ELSE vTrue = 3
     TV,  vPixelData, TRUE = vTrue
   
  ENDIF
   
  ; Clean up the object references.
  OBJ_DESTROY, [oImg]
   
  ; Note: the following lines allow you to run the program
  ; multiple times without having to manually delete files.
  ; You cannot duplicate an existing file when creating or cloning
  ; a DICOM file.
  FILE_DELETE, path+PATH_SEP()+'aNewMonoImg.dcm', /ALLOW_NONEXISTENT
  FILE_DELETE, path+PATH_SEP()+'aNewRBGImg.dcm', /ALLOW_NONEXISTENT
 
END

Version History

6.1

Introduced