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:
† 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
sFile = DIALOG_PICKFILE(/MUST_EXIST, $
TITLE = 'Select an Image File', $
FILTER = ['*.bmp', '*.jpg', '*.png', $
'*.ppm', '*.srf', '*.tif'], $
GET_PATH=path)
IF (sFile EQ '') THEN RETURN
vOpenStatus = QUERY_IMAGE(sFile, vQueryInfo)
IF (vOpenStatus NE 1) THEN RETURN
vNumSamples = vQueryInfo.channels
vCols = vQueryInfo.dimensions[0]
vRows = vQueryInfo.dimensions[1]
vImgSize = vQueryInfo.dimensions
vNumFrames = vQueryInfo.num_images
vPixelType = vQueryInfo.pixel_type
If vNumSamples EQ 1 THEN BEGIN
CASE vPixelType of
1: BEGIN
vBitsAlloc = 8
vPixelRep = 0
vPhotoInterp = 'MONOCHROME2'
END
2: BEGIN
vBitsAlloc = 10
vPixelRep = 1
vPhotoInterp = 'MONOCHROME2'
END
12: BEGIN
vBitsAlloc = 16
vPixelRep = 0
vPhotoInterp = 'MONOCHROME2'
END
ENDCASE
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
oImg = OBJ_NEW('IDLffDicomEx', $
path+PATH_SEP()+'aNewMonoImg.dcm', $
SOP_CLASS = 'STANDARD_MR', /NON_CONFORMING, /CREATE)
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
oImg->Commit
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 (vNumSamples EQ 3) THEN BEGIN
vDataSize = SIZE(vPixelData, /DIMENSIONS)
vInterleave = WHERE((vDataSize NE vCols) AND $
(vDataSize NE vRows))
IF (vInterleave[0] EQ 1) THEN RETURN
IF (vInterleave[0] EQ 0) THEN vPlanarConfig = 0 $
ELSE vPlanarConfig = 1
vBitsAlloc = 8
vPhotoInterp = 'RGB'
vPixelRep = 0
vPixelData = READ_IMAGE(sFile)
oImg = OBJ_NEW('IDLffDicomEx', $
path+PATH_SEP()+'aNewRBGImg.dcm', $
SOP_CLASS = 'STANDARD_US', /NON_CONFORMING, /CREATE)
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
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
OBJ_DESTROY, [oImg]
FILE_DELETE, path+PATH_SEP()+'aNewMonoImg.dcm', /ALLOW_NONEXISTENT
FILE_DELETE, path+PATH_SEP()+'aNewRBGImg.dcm', /ALLOW_NONEXISTENT
END
Version History