The IDLffJPEG2000::SetData procedure method writes data to the IDLffJPEG2000 object.

Syntax

Obj->[IDLffJPEG2000::]SetData, P1, ..., Pn [, COMPONENT=value] [, /ORDER] [, TILE_INDEX=value]

Arguments

P1, ... , Pn

Arguments may be one or more arrays containing the image components or tile components to be written to the JPEG2000 object. The arrays may have either two or three dimensions. Two-dimensional arrays contain one image or tile component with the dimensions of width and height. Three-dimensional arrays are dimensioned [nComponents, width, height]. All parameters must have the same width and height.

The array parameters are converted to byte data type if the bit-depth for the corresponding component is less than or equal to 8; to signed or unsigned integer, depending on the signed setting, for bit-depths from 9 - 16; and to signed or unsigned long integers, depending on the signed setting for bit-depths over 16.

Note: The bit depths used for output are determined from the BIT_DEPTH property, and not from the data type of the input arguments. If you are writing out short or long integer data, you should set the BIT_DEPTH property before calling SetData.

Note: The SIGNED property determines whether the data are written out using signed or unsigned integers, and is not affected by the data type of the input arguments. If you are writing out signed integer data, you may wish to set the SIGNED property before calling SetData.

Image Dimensions, Tile Dimensions, and Component Number

Images may be written using multiple calls to SetData with each call transferring one or more tile components. A tile component contains one image component for a given tile and is the smallest unit of data that can be supplied to SetData. The dimensions of the entire image and tiles, plus the number of components are determined the first time they are specified to Init or SetProperty, and may not be changed once established. If the dimensions or number of components are not specified explicitly they are inferred from the image parameters supplied in the first call to SetData.

If transferring an image with multiple calls to SetData, try to supply the data to SetData in a manner consistent with the progression setting of PROGRESSION to ensure optimum performance and minimize memory requirements.

Note: If you do not complete writing all of the tiles or components, or your array dimensions are not the same as the overall image dimensions, then the library will be unable to complete the code stream. In this case, reading the data back in may result in unexpected or incorrect values.

Note: If the YCC property is set (indicating that you want the library to convert from RGB to YCC before compressing the data), then you must supply all three image components in the same call to SetData (either the entire image or one tile at a time). If the components are provided in separate calls to SetData, the YCC conversion is not performed.

Keywords

COMPONENT

Set this keyword to be the index of the first component to be written by this call to SetData. Default is 0.

ORDER

JPEG2000 images are assumed to be stored in top-to-bottom order, while IDL usually assumes images are in bottom-to-top order. By default (ORDER = 0), SetData will automatically flip the input arrays to match JPEG2000's top-to-bottom order. Setting ORDER to a nonzero value will save the image directly to the JPEG2000 file without doing the vertical flip.

TILE_INDEX

Set this keyword to specify the index of the first tile to be written. JPEG2000 tiles are numbered in raster scan fashion, starting from 0. The default value for this keyword is 0. The tile indices must range from 0 to one less than the number of tiles in the image file, which is determined by the tile dimensions and image dimensions.

Examples

Write a one-component image:

;Open file to write
jp2 = OBJ_NEW('IDLffJPEG2000', 'test.jp2', /WRITE)
 
;Write the image
jp2->SetData, BYTSCL(DIST(400,300))
 
OBJ_DESTROY, jp2

Read a one-component image:

;Open file to read
jp2_in = OBJ_NEW('IDLffJPEG2000', 'test.jp2')
 
img = jp2_in->GetData() ; Read the file.
 
OBJ_DESTROY, jp2_in

Write an indexed-color image with a palette:

;Load IDL color table #5, this example assumes we have 256 colors.
LOADCT, 5
 
;Read color tables
TVLCT, /GET, Red, Green, Blue
 
;Open file to write
jp2 = OBJ_NEW('IDLffJPEG2000', 'test.jp2', /WRITE, /JP2, $
   PALETTE=[[Red], [Green], [Blue]])
 
;Write the image with the palette
jp2->SetData, BYTSCL(DIST(400,300))
OBJ_DESTROY, jp2

Read the above image and palette:

;Open file to read
jp2_in = OBJ_NEW('IDLffJPEG2000', 'test.jp2')
 
jp2_in->GetProperty, PALETTE=palette
 
;Read without RGB keyword. img is a 400 by 300 byte image.
img = jp2_in->GetData()
 
;With the RGB keyword, the image is now [3, 400, 300]
img3d = jp2_in->GetData(/RGB)
 
OBJ_DESTROY, jp2_in

Show the images:

TVLCT, palette[*, 0], palette [*, 1], palette[*, 2]
DEVICE, DECOMPOSED = 0
TV, img
DEVICE, DECOMPOSED = 1
TV, img3d, TRUE=1

Write a 100 component file, one component at a time:

j2k = OBJ_NEW('IDLffJPEG2000', 'test.j2k', /WRITE,    N_COMPONENTS=100)
FOR i = 0, 99 DO j2k_in->SetData, $
   replicate(byte(i), 200, 300), COMPONENT = i
OBJ_DESTROY, j2k_in

Read the above file:

j2k_in = obj_new('IDLffJPEG2000', 'test.j2k')
 
;b is a [200, 300] array
b = j2k_in->GetData(COMPONENT=30)
 
;b is a [5, 200, 300] array
b = j2k_in->GetData(COMPONENT=50, N_COMPONENT = 5)
 
OBJ_DESTROY, j2k_in

Version History

6.1

Introduced