The XINTERANIMATE procedure is a utility for displaying an animated sequence of images using off-screen pixmaps or memory buffers. The speed and direction of the display can be adjusted using the widget interface.

Note: On Microsoft Windows systems, the number of pixmap windows that can be created (and thus the number of images in an animation sequence) is limited by system GDI resources. The number of pixmap windows IDL can create is constrained by the total amount of GDI memory, the amount of GDI memory used by other applications, and the size of the IDL pixmap windows.

Only a single copy of XINTERANIMATE can run at a time. If you need to run multiple instances of the animation widget concurrently, use the CW_ANIMATE compound widget.

MPEG Support

MPEG animation files can be created either programmatically using keywords to open and save a file, or interactively using the widget interface. Note that the MPEG standard does not allow movies with odd numbers of pixels to be created.

Note: MPEG support in IDL requires a special license. For more information, contact your NV5 Geospatial Solutions sales representative or technical support.

The IDLffMJPEG2000 object creates and reads Motion JPEG2000 (MJ2) files, and provides more functionality than the MPEG_* routines. No special license is required and animations can consist of monochrome, RGB or multi-component frames that display individual components, tiles or regions.

This routine is written in the IDL language. Its source code can be found in the file xinteranimate.pro in the lib/utilities subdirectory of the IDL distribution.

Using XINTERANIMATE

Displaying an animated series of images using XINTERANIMATE requires at least three calls to the routine: one to initialize the animation widget, one to load images, and one to display the images. When initialized using the SET keyword, XINTERANIMATE creates an approximately square pixmap or memory buffer, large enough to contain the requested number of frames of the requested size. Images are loaded using the IMAGE and FRAME keywords. Finally, images are displayed by copying them from the pixmap or memory buffer to the visible draw widget.

Examples

Enter the following commands to open the file ABNORM.DAT (a series of images of a human heart) and animate the images it contains using XINTERANIMATE.

OPENR, unit, FILEPATH('abnorm.dat', $
   SUBDIR=['examples','data']), /GET_LUN
H = BYTARR(64, 64, 16, /NOZERO) 
READU, unit, H 
CLOSE, unit 
; Read the images into variable H:
H = REBIN(H, 128, 128, 16)
; Initialize XINTERANIMATE:
XINTERANIMATE, SET=[128, 128, 16], /SHOWLOAD
; Load the images into XINTERANIMATE:
FOR I=0,15 DO XINTERANIMATE, FRAME = I, IMAGE = H[*,*,I]
; Play the animation:
XINTERANIMATE, /KEEP_PIXMAPS

Note: Since the KEEP_PIXMAPS keyword was supplied, the same animation can be replayed (after the animation widget has been destroyed) with the single command XINTERANIMATE.

Syntax

XINTERANIMATE [, Rate]

Keywords for initialization: [, SET=[sizex, sizey, nframes]] [, /BLOCK] [, /CYCLE] [, GROUP=widget_id] [, /MODAL] [, MPEG_BITRATE=value] [, MPEG_FORMAT=value] [, MPEG_IFRAME_GAP=integer value] [, MPEG_MOTION_VEC_LENGTH={1 | 2 | 3}] [, /MPEG_OPEN, MPEG_FILENAME=string] [ MPEG_QUALITY=value{0 to 100}] [, /SHOWLOAD] [, /TRACK] [, TITLE=string]

Keywords for loading images: [, FRAME=value{0 to (nframes‑1)} [, IMAGE=value]] [, /ORDER] [, WINDOW=[window_num [, x0, y0, sx, sy]]]

Keywords for running animations: [, /CLOSE] [, /KEEP_PIXMAPS] [, /MPEG_CLOSE] [, XOFFSET=pixels] [, YOFFSET=pixels]

Arguments

Rate

A value between 0 and 100 that represents the speed of the animation as a percentage of the maximum display rate. The fastest animation is with a value of 100 and the slowest is with a value of 0. The default animation rate is 100. The animation must be initialized using the SET keyword before calling XINTERANIMATE with a rate value.

Keywords

The following keywords are segmented into three categories:

Keywords: Initialization

The following keywords are used to initialize the animation display. The SET keyword must be provided. Other keywords described in this section are optional; note that they work only when SET is specified.

SET

Set this keyword to a three-element vector [Sizex, Sizey, Nframes] to initialize XINTERANIMATE. Sizex and Sizey represent the width and height of the images to be displayed, in pixels. Nframes is the number of frames in the animation sequence. Note that Nframes must be at least 2 frames.

BLOCK

Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting BLOCK=1 will cause all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER.

Note: Only the outermost call to XMANAGER can block. Therefore, to have XINTERANIMATE block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example.

CYCLE

Normally, frames are displayed going either forward or backwards. If the CYCLE keyword is set, the animation reverses direction after the last frame in either direction is displayed.

GROUP

Set this keyword to the widget ID of the widget that calls XINTERANIMATE. When GROUP is specified, the death of the calling widget results in the death of XINTERANIMATE.

MODAL

Set this keyword to block processing of events from other widgets until the user quits XINTERANIMATE. A group leader must be specified (via the GROUP keyword) for the MODAL keyword to have any effect. By default, XINTERANIMATE does not block event processing.

MPEG_BITRATE

Set this keyword to a double-precision value to specify the MPEG movie bit rate. Higher bit rates will create higher quality MPEGs but will increase file size. The following table describes the valid values:

MPEG Version

Range

MPEG 1

0.1 to 104857200.0

MPEG 2

0.1 to 429496729200.0

If you do not set this keyword, IDL computes the MPEG_BITRATE value based upon the value you have specified for the MPEG_QUALITY keyword.

Note: Only use the MPEG_BITRATE keyword if changing the MPEG_QUALITY keyword value does not produce the desired results. It is highly recommended to set the MPEG_BITRATE to at least several times the frame rate to avoid unusable MPEG files or file generation errors.

MPEG_FILENAME

Set this keyword equal to a string specifying the name of the MPEG file. If no file name is specified, the default value (idl.mpg) is used.

MPEG_FORMAT

Set this keyword to a boolean value that specifies the type of MPEG encoding to use:

  • 0 = MPEG1 (the default)
  • 1 = MPEG2

MPEG_IFRAME_GAP

Set this keyword to a positive integer value that specifies the number of frames between I frames to be created in the MPEG file. I frames are full-quality image frames that may have a number of predicted or interpolated frames between them.

If you do not specify this keyword, IDL computes the MPEG_IFRAME_GAP value based upon the value you have specified for the MPEG_QUALITY keyword.

Note: Only use the MPEG_IFRAME_GAP keyword if changing the MPEG_QUALITY keyword value does not produce the desired results.

MPEG_MOTION_VEC_LENGTH

Set this keyword to an integer value specifying the length of the motion vectors to be used to generate predictive frames. Valid values include:

1

Small motion vectors

2

Medium motion vectors

3

Large motion vectors

If you do not set this keyword, IDL computes the MPEG_MOTION_VEC_LENGTH value based upon the value you have specified for the MPEG_QUALITY keyword.

Note: Only use the MPEG_MOTION_VEC_LENGTH keyword if changing the MPEG_QUALITY value does not produce the desired results.

MPEG_OPEN

Set this keyword to open an MPEG file.

MPEG_QUALITY

Set this keyword to an integer value between 0 (low quality) and 100 (high quality) inclusive to specify the quality at which the MPEG stream is to be stored. Higher quality values result in lower rates of time compression and less motion prediction which provide higher quality MPEGs but with substantially larger file size. Lower quality factors may result in longer MPEG generation times. The default is 50.

Note: Since MPEG uses JPEG (lossy) compression, the original picture quality can’t be reproduced even when setting QUALITY to its highest setting.

SHOWLOAD

Set this keyword to display each frame and update the frame slider as frames are loaded.

TRACK

Set this keyword to cause the frame slider to track the current frame when the animation is in progress. The default is not to track.

TITLE

Use this keyword to specify a string to be used as the title of the animation widget. If TITLE is not specified, the title is set to “XInterAnimate.”

Keywords: Loading Images

The following keywords are used to load images into the animation display. They have no effect when initializing or running animations.

FRAME

Use this keyword to specify the frame number when loading frames. FRAME must be set to a number in the range 0 to Nframes-1.

IMAGE

Use this keyword to specify a single image to be loaded at the animation position specified by the FRAME keyword. (FRAME must also be specified.)

ORDER

Set this keyword to display images from the top down instead of the default bottom up.

WINDOW

When this keyword is specified, an image is copied from an existing window to the animation pixmap or memory buffer. (When using some windowing systems, using this keyword is much faster than reading from the display and then calling XINTERANIMATE with a 2-D array.)

The value of this parameter is either an IDL window number (in which case the entire window is copied), or a vector containing the window index and the rectangular bounds of the area to be copied. For example: 

WINDOW = [Window_Number, X0, Y0, Sx, Sy]

Keywords: Running Animations

The following keywords are used when running the animation. They have no effect when initializing the animation or loading images.

CLOSE

Set this keyword to delete the offscreen pixmaps or buffers and the animation widget itself. This also takes place automatically when the user presses the “Done With Animation” button or closes the window with the window manager.

KEEP_PIXMAPS

If this keyword is set, XINTERANIMATE will not destroy the animation pixmaps or buffers when it is killed. Calling XINTERANIMATE again without going through the SET and LOAD steps will play the same animation without the overhead of creating the pixmaps.

MPEG_CLOSE

Set this keyword to close and save the MPEG file. This keyword has no effect if MPEG_OPEN was not used during initialization.

XOFFSET

Use this keyword to specify the horizontal offset, in pixels from the left of the frame, of the image in the destination window.

YOFFSET

Use this keyword to specify the vertical offset, in pixels from the bottom of the frame, of the image in the destination window.

Version History

Pre-4.0

Introduced

6.4

Added MPEG_FORMAT keyword.

See Also