IDLffMJPEG2000::SetData

The IDLffMJPEG::SetData function method starts a background processing thread and adds frame data to an MJ2 file that is being created. Each call to SetData call adds a frame to the frame buffer, which will be compressed by the processing thread. The length of the frame buffer is determined by the FRAME_BUFFER_LENGTH property.

If SetData is called faster than the background processing thread can compress the frame data, SetData will wait for an available frame buffer slot before returning.

The SetData and IDLffMJPEG2000::Commit methods are used together to create a new file. After adding all of the data to the MJ2 file using SetData, call Commit to close the file and shut down the processing thread. You can playback the new MJ2 file by creating a new Motion JPEG2000 object that opens the file for reading.

This method will throw an error if the compression fails. A CATCH statement can be used to trap these errors.

Syntax

Result = Obj->[IDLffMJPEG2000::]SetData (A₁ ...A_n [, COMPONENT=value] [, FRAME_PERIOD=value] [, /ORDER] [, TILE_INDEX=value])

Return Value

Returns a byte value indicating success (1) or failure (0).

Arguments

A₁ ...A_n

One or more arrays of data representing the component(s) or tile(s) of data associated with the single frame being written (see Writing Frames, Components and Tiles). The arrays may be 2- or 3-dimensional. A 2‑dimensional array contains one frame component or tile component, and has the dimensions [width, height]. A 3-dimensional array has the dimensions [nComponents, width, height]. All arrays must have the same width, height dimensions.

The data type of the array arguments are converted based the BIT_DEPTH and SIGNED property values as follows:

BIT_DEPTH	Converted to Data Type
≤8	Byte
≥9 or ≤16	Integer, signed or unsigned based on SIGNED property
>16	Long, signed or unsigned based on SIGNED property

Note: The data type of the input array has no effect on how the data is converted. If BIT_DEPTH and SIGNED are not set before the first call to SetData, data will be written as unsigned byte data. To write short or long integer data, or signed data, you must set the BIT_DEPTH and SIGNED properties before calling SetData.

Writing Frames, Components and Tiles

Frames may be written using multiple calls to SetData with each call transferring one or more components (channels or bands of data) or tile components. A tile component contains one frame component for a given tile and is the smallest unit of data that can be supplied to SetData.

The frame dimensions, tile dimensions and the number of components per frame are typically set prior to the first call to SetData. If they are not explicitly specified, they are inferred from the array parameters supplied in the first call to SetData. Once these properties (DIMENSIONS, TILE_DIMENSIONS, and N_COMPONENTS) are either explicitly set through Init or SetProperty, or set though the default action of SetData, they may not be changed. For example, if you pass in data arrays A₁, A₂, A₃, A₄ and A₅ in a single call to SetData, this will be interpreted as a single frame with 5 components. All subsequent frames will be expected to have the same number of components.

The frame will advance when all data for the current frame has been passed in. For example, if you pass in one frame of data at a time, each SetData call advances the frame (the N_FRAMES property value increases by 1). If you pass in individual components or tiles, multiple SetData calls may be needed to advance the frame. Suppose your frame consists of 4 components, which you are passing in one at a time. You will need to call SetData four times before the frame will advance. If you have a frame that consists of 2 components and 4 tiles, and you are passing in a single tile component in each SetData call, the frame will only advance after 8 calls.

Note: If you are writing individual components, you must set the N_COMPONENTS property for the MJ2 file before the first call to SetData. If you are writing tiled data, you must set the TILE_DIMENSIONS and DIMENSIONS properties for the file before the first call to SetData.

If a file does not contain the expected number of tiles or components, an error will be generated when you call IDLffMJPEG2000::Commit to store the data and close the file. If you do not complete writing all of the tiles or components, or if your array dimensions are not the same as the overall frame dimensions, the file storage process will not be completed. In such a case, reading the data back may result in unexpected or incorrect values.

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

Color Space and Components

If not set prior to the first call to SetData, the COLOR_SPACE property will be automatically set based on the number of components passed in during the first call to SetData as follows:

Number of Components	Color Space
3	RGB
> 3 <	LUM

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 frame components in the same call to SetData (either the entire frame or one tile at a time). If the components are provided in separate calls to SetData, the YCC conversion is not performed.

Keywords

COMPONENT

An integer value specifying the index of the component to be written in the current call to SetData. The default is 0. For example, suppose a frame consists of 4 components (N_COMPONENTS equals 4). If you pass in the first three components in one SetData call, you can pass in the fourth component in the next SetData call by setting COMPONENT equal to 3 (the zero-based index value of the fourth component). COMPONENT can only be used to write components sequentially.

You must set the N_COMPONENTS property before the first call to SetData if you are setting this keyword.

FRAME_PERIOD

A long value that indicates the duration of a frame in ticks. Each frame in an MJ2 file can be displayed a different period of time as defined by the FRAME_PERIOD. This value, in conjunction with the TIMESCALE property, determines the playback rate. See Computing Playback Rate for details.

The frame period of this frame and all subsequent frames will reflect the value set using the FRAME_PERIOD property, or set using this FRAME_PERIOD keyword.

ORDER

An integer value specifying the order in which to store data. Motion JPEG2000 frames are assumed to be stored in top-to-bottom order, while IDL usually assumes frames are in bottom-to-top order. By default (ORDER= 0), this method will automatically flip the result to match Motion JPEG2000’s top-to-bottom order. Setting ORDER to a nonzero value will save the frame directly to the file without doing the vertical flip.

TILE_INDEX

An integer value that specifies the index of the tile to be written in the current SetData call. Frame tiles are numbered in raster scan fashion (from left to right starting at the upper left corner) beginning with an index value of 0. The default value for this keyword is 0. This keyword, like the COMPONENT keyword, lets you add data sequentially in separate SetData calls.

The tile indices must range from 0 to one less than the number of tiles in the frame, which is determined by the tile dimensions (TILE_DIMENSIONS property) and frame dimensions (DIMENSIONS property). These properties must be set prior to the first call to SetData if you are setting this keyword.

Examples

Write frame components in separate SetData calls using the COMPONENT keyword. For a frame with 12 components, write the first five components in the first SetData call. Set COMPONENT to 5 (the zero-based index value of the sixth component) to add the remaining components in the next SetData call.

oMJ2write->SetProperty, N_COMPONENTS=12

result = oMJ2write->SetData(data0, data1, data2, data3, data4, $

COMPONENT=0)

result = oMJ2write->SetData(data5, data6, data7, data8, data9, $

data10, data11,COMPONENT=5)

Version History

6.3	Introduced