IDLffMJPEG2000

The IDLffMJPEG2000 object provides the ability to read and write Motion JPEG2000 (MJ2) files. Motion JPEG2000, like JPEG2000, uses the Discrete Wavelet Transform (DWT) to compress files. This lossless compression option permits retrieval of the original data. With lossy compression, original data is lost during compression and cannot be recovered. DWT is an excellent compression scheme for continuous tone images such as geospatial and medical imagery.

A Motion JPEG2000 (MJ2) file contains a series of frames, each of which is an independent JPEG2000 image. An MJ2 animation displays a timed sequence of frames and uses intra-frame coding, which means each frame is an independent entity. In contrast, MPEG files typically use inter-frame encoding (motion estimation)—each frame is dependent on the previous frames. Because of the intra-frame encoding, MJ2 files can support lossless compression and permit random access to individual frames. These features make the Motion JPEG2000 file format ideal for scientific applications.

Each frame of an MJ2 file (like a JPEG2000 image) may consist of one or more components (color or data bands), tiles, or regions. Using the IDLffMJPEG2000 object, you can play an animation consisting of frames, components, tiles or regions and can create a file containing frames, components, and tiles. Additionally, you can specify the number of levels (image resolutions) and quality layers when creating or playing back an MJ2 file

An IDLffMJPEG2000 object permits reading or writing an MJ2 file (based on the WRITEproperty value). However, the same IDLffMJPEG2000 object cannot be used to both write and read an MJ2 file. You can write a file with one object (where WRITE=1), but you must create a separate object (where WRITE=0, the default) in order to read or play the new MJ2 file.

Note: The rate at which the IDLffMJPEG2000 object can compress or decompress frames is affected by the contents of the individual frames being compressed or decompressed and by the processing speed of your system. The amount of compression is dependent on the contents of the frames being compressed.

About Processing Threads

Internally, several IDLffMJPEG2000 methods make use of background processing threads that allow the user interface to stay more responsive while MJ2 file data is being compressed (written) or decompressed (read). On a dual processor or multiprocessor machine the UI thread (of the main IDL process) and the background thread will typically run on separate processors allowing higher compression and decompression throughput. These threads are described in each method where appropriate.

Reading MJ2 Files

You can read or play a sequence of frames, components, tiles or regions contained in an existing MJ2 file or you can randomly access individual elements. Additionally, any element may be returned at a specified resolution (level) or quality (layer).

Tip: You can view monochrome and RGB animations in the pre-built IDL Motion JPEG2000 Player. This example code, mj2_player.pro, and a sample image, idl_mjpeg2000_example.mj2, are located in the IDL_DIR\examples\mjpeg2000 directory where IDL_DIR is the directory where you have installed IDL. If you have an MJPEG2000 codec installed, you can also play animations in other media players including the Windows Media Player.

Playback will occur as fast as the frames can be decompressed unless you implement some type of timer mechanism.

Writing MJ2 Files

You can write (create) an MJ2 file that consists of frames, components and tiles, which contain the desired number of quality levels. An MJ2 file can store multiple related or non-related images (frames) as long as each frame has the same dimensions and same number of components. Files can be written in a lossless or lossy format depending on the value of the REVERSIBLE property.

The source of frame data for the animation can be existing images, generated images, or snapshots of an IDLgrWindow display. Regardless of the source, use the SetData method to write the data to the file, and the Commit method to close the processing thread once all of the frames have been added to the animation.

For an example that adds a series of IDLgrWindow screen captures to an MJ2 file, see the mj2_writer_rgb.pro example described below.

Depending on how you pass in data, you may need to set several properties prior to the first call to SetData in order to create the expected MJ2 file.

Tip: You can use the example IDL Motion JPEG2000 Writer, mj2_writer_rgb.pro, as a template for creating an MJ2 animation. This example is located in the IDL_DIR\examples\mjpeg2000 directory where IDL_DIR is the directory where you have installed IDL. Running the example creates a new MJ2 file, which is written to your application user directory, a subdirectory of your home directory.

Note: The IDLffMJPEG2000 object supports reading and writing Motion JPEG2000 files stored in a progressive format. See the SCAN_MODE property for details.

Superclasses

None

Creation

See IDLffMJPEG2000::Init.

Properties

Objects of this class have the following properties. See IDLffMJPEG2000 Properties for details on individual properties.

BIT_DEPTH		N_LEVELS
BIT_RATE		N_TILES
COLOR_SPACE		PALETTE
COMMENT		PROGRESSION
CURRENT_FRAME		REVERSIBLE
DIMENSIONS		SCAN_MODE
DURATION		SIGNED
FILENAME		STATE
FRAME_BUFFER_LENGTH		TILE_DIMENSIONS
FRAMES_IN_BUFFER		TIMESCALE
FRAME_PERIOD		WRITE
N_COMPONENTS		XML
N_FRAMES		YCC
N_LAYERS

Methods

This class has the following methods:

Examples

The following simple example adds slices of data from an MRI of a human head to an MJ2 file to create a short animation. Each SetData call adds a single slice of data, resulting in an animation consisting of 57 frames.

PRO mj2_simple_write_read

; Read image data, which contains 57 slices.

nFrames = 57

head = READ_BINARY( FILEPATH('head.dat', $

SUBDIRECTORY=['examples','data']), $

DATA_DIMS=[80,100, 57])

; Enter new name for MJ2 file or select existing file

; to be overwritten.

file = DIALOG_PICKFILE(DEFAULT_EXTENSION="mj2", $

TITLE="Enter Name for File")

; Create an IDLffMJPEG2000 object.

oMJ2write=OBJ_NEW('IDLffMJPEG2000', file, /WRITE, /REVERSIBLE)

; Write the data of each frame into the MJ2 file.

FOR i=0, nFrames-1 DO BEGIN

data = head[*,*,i]

result = oMJ2write->SetData(data)

ENDFOR

; Commit and close the IDLffMJPEG2000 object.

return = oMJ2write->Commit(10000)

OBJ_DESTROY, oMJ2write

; Create a new IDLffMJPEG2000 object to read the MJ2 file.

oMJ2read=OBJ_NEW("IDLffMJPEG2000", file)

oMJ2read->GetProperty,N_FRAMES=nFrames, DIMENSIONS=dims

; Create a window and display simple animation.

WINDOW, 0, XSIZE=2*dims[0], YSIZE=2*dims[1]

FOR i=0, nFrames-1 DO BEGIN

; Return data and display magnified version. Use WAIT to

; pause between each frame for visibility. Unless a timer

; is used in conjunction with the FRAME_PERIOD and

; TIMESCALE properties, the default playback rate will be

; as fast as the frames can be decompressed.

data = oMJ2read->GetData(i)

TVSCL, CONGRID(data, 2*dims[0], 2*dims[1])

WAIT, 0.1