Adding Data to MJ2 Animations

The source of the data for the MJ2 file can be existing data or incremental captures from data processing or data display. Regardless of the source of the data to be added to the MJ2 file, you will need to call the IDLffMJPEG2000::SetData method multiple times (minimally, once for each frame of the animation). Each SetData call adds the data to the frame buffer where it is compressed by a background processing thread. This processing thread is automatically started with the first SetData call. After all of the data has been added to the file, you must call the IDLffMJPEG2000::Commit method to stop the processing thread and close the file.

The first call to the IDLffMJPEG2000::SetData property is key. If you have not previously defined a number of object properties (noted in Creating a Motion JPEG2000 Animation), then the values are taken from the dimensions of the data that is passed in during the first SetData call. For example, if you pass in three arrays (data1, data2 and data3) in the first SetData call, the COLOR_SPACE property will automatically be set to sRGB. If you are passing in three monochrome data arrays, this property would need to be set to sLUM prior to the first call to SetData to avoid unexpected results.

Note
It is possible to call SetData faster than the background processing thread can compress the data and write it to a file. If this is an issue, see High Speed MJ2 Reading and Writing for additional file creation options.

When creating a new MJ2 file you can choose from the following options:

Animating Existing Data — add frames, components or tiles of data to the MJ2 file

Animating Screen Captures — add the contents of an object graphics animation to the MJ2 file

Animating Data Captures—add newly created data to the MJ2 file

Note
The following examples use a simple WAIT statement mechanism for controlling the playback rate. In reality, you will likely use a more robust mechanism. See Controlling the Playback Rate for options and information about a related example.

These examples, which are comparatively short and simple, use the GetData method instead of the group of methods described in Sequential Motion JPEG2000 Playback. Examples showing the use of the sequential playback methods are located in Controlling the Playback Rate and the Examples section of "IDLffMJPEG2000::GetSequentialData" (IDL Reference Guide).

Animating Existing Data

The IDLffMJPEG2000 object stores entire frames of data as well as bands or channels of frame data (components) or frame tiles. The new MJ2 file can contain a series of images, components, or tiles as long as the dimensions and numbers of components are the same for each element. Examples of animating existing data include:

MJ2 Monochrome Frame Animation

MJ2 Animation of an Image with a Palette

MJ2 RGB Tile Animation

The following examples write MJ2 files to your temporary directory. Use PRINT, FILEPATH(' ', /TMP) to display this location.

MJ2 Monochrome Frame Animation

The following simple example creates a short animation from a series of MRI frames of data contained in a binary file. An animation consisting of all available quality layers for a dozen frames is then displayed.

PRO mj2_frames_doc 
 
; Read image data, which contains 57 frames. 
nFrames = 57 
head = READ_BINARY( FILEPATH('head.dat', $ 
  SUBDIRECTORY=['examples','data']), $ 
  DATA_DIMS=[80,100, 57]) 
 
; Create new MJ2 file in the temporary directory. 
file = FILEPATH("mj2_frames_ex.mj2",/TMP) 
 
; Create an IDLffMJPEG2000 object. 
oMJ2write=OBJ_NEW('IDLffMJPEG2000', file, /WRITE, /REVERSIBLE, $ 
   N_LAYERS=10) 
 
; 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 access 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], TITLE="MJ2 Layers" 
 
; Display all quality layers (j) of a dozen frames (i). 
FOR i=25, 36 DO BEGIN 
   ; Return data and display magnified version. Pause 
   ; between each frame for visibility. Unless a timer 
   ; is used in conjunction with the FRAME_PERIOD and 
   ; TIMESCALE properties, playback will occur as fast 
   ; as the frames can be decompressed.  
   FOR j=0, 10 DO BEGIN 
      data = oMJ2read->GetData(i, MAX_LAYERS=j) 
      TVSCL, CONGRID(data, 2*dims[0], 2*dims[1]) 
      WAIT, 0.1 
   ENDFOR 
ENDFOR 
 
; Cleanup. 
OBJ_DESTROY, oMJ2read 
 
End

This example is also available in the IDL distribution.

Example Code
This example, mj2_frames_doc.pro, is located in the examples/doc/objects subdirectory of the IDL distribution. Run this example procedure by entering mj2_frames_doc at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT mj2_frames_doc.pro.

MJ2 Animation of an Image with a Palette

The following example accesses the palette associated with a PNG file and assigns the values to the IDLffMJPEG2000 object PALETTE property. The image data is then modified in such a way that the resulting animation appears to be a shrinking view of the image. However, the shrunken image is padded to maintain the original image dimensions, which is a requirement of SetData. Each frame must have the same dimensions.

The following lines, abstracted from the entire example, show accessing the palette from the PNG file and assigning it to the new MJ2 file.

; Access image data and associated palette. 
world = READ_PNG (FILEPATH ('avhrr.png', $ 
   SUBDIRECTORY = ['examples', 'data']), R, G, B) 
;... 
; Create an MJ2 file in the temporary directory. Assign the  
; palette arrays to the PALETTE property. 
file =FILEPATH("mj2_palette_ex.mj2", /TMP) 
oMJ2write = OBJ_NEW('IDLffMJPEG2000', file, /WRITE, $ 
   PALETTE=[[R], [G], [B]])

See the following for the complete program.

Example Code
This example mj2_palette_doc.pro, is located in the examples/doc/objects subdirectory of the IDL distribution. Run this example procedure by entering mj2_palette_doc at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT mj2_palette_doc.pro.

MJ2 RGB Tile Animation

The following example creates a tiled, RGB JPEG2000 image from a 5,000 by 5,0000 pixel JPEG image. The JPEG2000 image tile data is then written to a Motion JPEG2000 image file. As shown in the following code, a smaller version of each tile is extracted from the MJ2 file and displayed sequentially in a window.

; Create object to read new MJ2 file. Set PERSISTENT to access 
; tiled data. Set DISCARD_LEVELS to display smaller versions of 
; the tiles. 
oMJ2read = OBJ_NEW('IDLffMJPEG2000', file, /PERSISTENT) 
oMJ2read->GetProperty, N_TILES=nTiles, TILE_DIMENSIONS=tileDims 
WINDOW, 0, XSIZE=625, YSIZE=625 
For j=0, nTiles-1 DO BEGIN 
   data = oMJ2read->GetData(0, DISCARD_LEVELS=3, $ 
      TILE_INDEX=j, /RGB) 
   TVSCL, data, j, TRUE=1 
   WAIT, 0.3 
ENDFOR

See the following for the complete program. A noticeable amount of time will be required the first time you run the example as several large files must be created.

Example Code
This example mj2_tile_doc.pro, is located in the examples/doc/objects subdirectory of the IDL distribution. Run this example procedure by entering mj2_tile_doc at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT mj2_tile_doc.pro.

Animating Screen Captures

You can capture the visible contents of an IDLgrWindow using the IDLgrWindow IMAGE_DATA property. The captured data can then be passed to the MJ2 file via the IDLffMJPEG2000::SetData method. This method of MJ2 creation is useful for recording an existing animation. For information on creating animations in an object graphics window see Animating Objects (Object Programming). For an example that creates an MJ2 file using this method, see Sample Motion JPEG2000 Player and Writer, which describes the example, mj2_writer_rgb.pro, located in the IDL_DIR\examples\mjpeg2000 directory.

A timer mechanism can be used to control the rate of the animation and the rate at which data is captured and written to an MJ2 file. See Timer Mechanisms for more information.

Animating Data Captures

In addition to adding existing data to an MJ2 file, you can also add incremental data captures - snapshots of data at specified intervals. Data captured at any point during program execution can be added as long as each element passed to SetData has the same dimensions. The following example captures the incremental application of a thinning operator to an image, creating an animation that shows the changes to the original data.

Example Code
This example mj2_morphthin_doc.pro, is located in the examples/doc/objects subdirectory of the IDL distribution. Run this example procedure by entering mj2_morphthin_doc at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT mj2_morphthin_doc.pro.