IDLffMJPEG2000::GetData

The IDLffMJPEG::GetData function method returns data for a specified frame (or component, tile or region of a frame) from an MJ2 file. This method does not return until the requested data has been decompressed. It will throw an error if the decompression fails. A CATCH statement can be used to trap such an error.

To playback a large number of frames in a sequential manner, consider using the StartSequentialReading method, which includes a built-in background processing thread for file decompression.

Note: You can use the WAIT procedure, a widget timer, or a IDLitWindow timer mechanism to control the rate at which random frames are retrieved if needed.

Note: If PERSISTENT = 0 (the default) when the IDLffMJPEG2000 object was created, only one GetData call can be made per frame when reading individual components, tiles or regions. PERSISTENT must be set on Init in order to access tiled data.

Syntax

Result = Obj->[IDLffMJPEG2000::]GetData(FrameNumber [, COMPONENT=value] [, DISCARD_LEVELS=value] [, MAX_LAYERS=value] [, N_COMPONENTS=value] [, /ORDER] [, REGION=value] [, /RGB] [, TILE_INDEX=value])

Return Value

Returns a two- or three-dimensional array containing the frame data that corresponds to the specified frame number. The exact dimensions are based on keyword values:

Keyword	Condition and Result
RGB	Set—array dimensions are [3, width, height].
RGB	Not set—array dimensions are [nComponents, width, height] where nComponents, the number of bands or channels of data, depends on the COMPONENT and N_COMPONENTS keyword settings. If COMPONENT is not set, nComponents equals the number of components in the frame. If a starting COMPONENT is set, nComponents equals the number of components requested in N_COMPONENTS unless the frame has only one component. In this case the array dimensions are [width, height]. If a starting COMPONENT is set, but N_COMPONENTS is not set, nComponents equals all available components from the starting component.
REGION	If set, the array width and height are determined by the width and height values in the 4-element REGION vector [startX, startY, width, height].
TILE_INDEX	If set, the array width and height equal the dimensions of a single tile, defined in the TILE_DIMENSIONS property value.

The data type of the result is automatically determined using the BIT_DEPTH and SIGNED properties of the returned components as follows;

Data Properties	Result
BIT_DEPTH ≤ 8 or RGB is set	Byte
BIT_DEPTH ≥9 or ≤16	Integer or unsigned integer
BIT_DEPTH >16	Long or unsigned long

Note: All components in the MJ2 file must have the same bit depth and be either signed or unsigned. Components with different bit depths or a mixture of signed and unsigned data are not supported.

Arguments

FrameNumber

A long value specifying the number of the frame from which data is to be retrieved. Allowable values range from 0 to the total number of frames (the N_FRAMES property value) - 1.

Keywords

COMPONENT

An integer value indicating the zero-based index number of the first component to be returned. The total number of components returned depends upon this keyword and the value of N_COMPONENTS as follows:

If this keyword is set and N_COMPONENTS is not set, it returns all the components from the starting COMPONENT
If this keyword is set and N_COMPONENTS is set, it returns the number of components specified by N_COMPONENTS from the starting COMPONENT

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 ... 2³²-2, and width and height must be in the range 1 ... 2³²-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 the 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.
Yes	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 GetData.
No	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.

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 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.

Version History

6.3	Introduced