IDLffMJPEG2000::StartSequentialReading

The IDLffMJPEG2000::StartSequentialReading function method initiates a sequential playback of a large number of frames. This method lets you configure what data is to be decompressed from each frame of the MJ2 file (the entire frame or a component, tile or region of the frame).

Internally, this method starts a background processing thread that decompresses frames into a frame buffer. This background thread allows the UI to remain active as described in About Processing Threads).

The StartSequentialReading, GetSequentialData, ReleaseSequentialData and StopSequentialReading methods are used with a timer mechanism to create a sequential playback.

Note: Always use a widget timer or IDLitWindow timer mechanism to control the playback rate. Avoid using the WAIT procedure with sequential playback methods as the interaction between the procedure and the background processing thread will cause adverse side effects on UNIX platforms.

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

Syntax

Result = Obj->[IDLffMJPEG2000::]StartSequentialReading ([, COMPONENT=value] [, DISCARD_LEVELS=value] [, MAX_LAYERS=value] [, N_COMPONENTS=value] [, /ORDER] [, REGION=vector] [, /RGB] [, START_FRAME_NUMBER=value] [, STOP_FRAME_NUMBER=value] [, TILE_INDEX=value] )

Return Value

Returns an integer value indicating success (1) or failure (0).

Arguments

None

Keywords

COMPONENT

An integer value indicating the zero-based index number of the first component to be returned as follows:

If this keyword is not set, all the components are returned. The default is 0.

DISCARD_LEVELS

An integer value specifying the number of resolution levels to be excluded from the result starting with the highest resolution level. For example, given a full-resolution frame that is 1024 by 1024 pixels:

Value

Description

0

The default. No data is discarded.

1

Discard 1 level, the highest resolution data (e.g. discard the 1024 by 1024 level, leaving the 512 by 512 data)

2

Discard 2 levels of data (e.g. discard the 1024 by 1024 and 512 by 512 levels, leaving the 256 by 256 data)

Determine the number of resolution levels by checking the N_LEVELS property.

MAX_LAYERS

An integer value specifying the maximum number of quality layers to be read. Each layer contains the information required to represent the image at a higher quality, given the information from all the previous layers. A value of 0, the default, means all available layers should be returned. If MAX_LAYERS is 3, data from the first, second and third quality layers will be combined in the returned data. Determine the number of quality layers in a file by checking the value of the N_LAYERS property.

N_COMPONENTS

An integer value specifying the number of components to return from the starting component specified by the COMPONENT keyword. If this keyword is set, but COMPONENT is not set, the default COMPONENT value (0) will be used.

ORDER

An integer value specifying the order in which to return 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 IDL's bottom-to-top order. Setting ORDER to a nonzero value will return the Motion JPEG2000 frames without doing the vertical flip.

REGION

A four-element long vector containing the rectangular region of the frame to read. The region is specified as [startX, startY, width, height], where startX and startY must be in the range 0 ... 232-2, and width and height must be in the range 1 ... 232-1. The region must contain at least some portion of the frame, or an error will occur. If the region is larger than the frame, or extends beyond the frame, only that portion that lies within the frame will be returned. This keyword, in combination with the COMPONENT keyword, lets you access any region from a particular component.

RGB

If set, the resulting data stream will be interpreted as RGB frames. The returned array will always have three components (red, green, and blue) with the dimensions [3, width, height]. See the following table for information on what data will be read if fewer than or more than 3 components are specified, or if the keyword is not set.

Note: The Motion JPEG2000 standard allows a decorrelating color transformation to be applied to the first three image components. This transformation is identical or similar to the conventional YCbCr color transformation. To determine if this transform has been applied, examine the YCC property.

RGB Set?

Number of Components

Outcome

Yes

More than 3

Only the first three components are returned.

Less than 3

An error is thrown.

No

3

If a color transformation has been applied to the input stream, the three components which are encoded as YCC will automatically be converted to RGB. To avoid this conversion you must transfer more than or fewer than three components when using StartSequentialReading.

Not equal to 3

Each component in the data stream will be placed in the result without interpretation. Result will have dimensions: [N_COMPONENTS, width, height].

You cannot specify RGB and COMPONENT or N_COMPONENTS at the same time. An error will be thrown in such cases.

START_FRAME_NUMBER

A long value specifying the frame index with which to start the sequential playback. If not set, the default value, 0, will be used.

STOP_FRAME_NUMBER

A long value specifying the frame index with which to stop the sequential playback. If not set, the stop frame will be the last frame in the file.

TILE_INDEX

An integer value specifying the index of the tile to return. Tiles are numbered in raster scan fashion (from left to right starting at the top-left corner) starting with an index value of 0. This keyword, in combination with the COMPONENT keyword, lets you access any tile from a particular component. When this keyword is set, the REGION keyword is ignored.

Examples

See the Examples section of IDLffMJPEG2000::GetSequentialData for a simple example that uses the four sequential playback methods.

Version History

6.3

Introduced