Animation


This document was published with and applies to ArcGIS 9.3.
A 10 version also exists.
Supported with:
Library dependencies: System, SystemUI, Geometry, Display, Server, Output, Geodatabase, GISClient, ArcWeb, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, DataSourcesNetCDF, GeoDatabaseDistributed, GeoDatabaseExtensions, Carto, NetworkAnalysis, Location, GeoAnalyst

Additional library information: Contents, Object Model Diagram

The Animation library contains objects to work with animations in map, scene, and globe. In ArcGIS 9.2, with ArcGIS Desktop, the animation functionality is available in the ArcMap, ArcScene, and ArcGlobe applications. However, when working with ArcGIS Engine, animation functionality is not available for the Map control. It is only available for the Scene and Globe controls, which are supported with the 3D Analyst extension.
 
An animation can be thought of as a visualization of the changes to the properties of one object (such as a layer or a camera) or a set of objects (such as multiple layers). Examples include changes over time, the navigation of a camera through a scene or globe, changes to the display extent of a map, and changes to the transparency and visibility of a layer.
 
An animation is composed of animation tracks (AGAnimationTracks), which are further composed of keyframes (AGAnimationKeyframes) of the same type. Each keyframe stores properties of the animation objects. When an animation is played, keyframes are interpolated, and the interpolated properties are then applied to the animated objects to create the dynamic visual effect.

The objects that implement this functionality are grouped into a number of library subsystems. These library subsystems are:

ArcMap

The following are the out-of-the-box animation types for ArcMap: AnimationTypeTimeLayer, AnimationTypeMapView, and AnimationTypeMapLayer. Each animation type corresponds to a type of keyframe.
 
The following are the types of keyframes in the Animation library: TimeLayerKeyframe, MapViewKeyframe, and MapLayerKeyframe.
 
The following illustration shows the relationship among the animation components in the Animation library that can be used to create the different types of animations in ArcMap: 
 

ArcScene

The following are the out-of-the-box animation types for ArcScene: AnimationTypeCamera, AnimationTypeLayer, AnimationTypeScene, and AnimationTypeTimeLayer. Each animation corresponds to a type of keyframe: Bookmark3D (for creating camera keyframes), LayerKeyframe, SceneKeyframe, and TimeLayerKeyframe.

The following illustration shows the relationship among the animation components in the 3D Analyst library that can be used to create the different types of animations in ArcScene:
 
 

ArcGlobe

The following are the out-of-the-box animation types for ArcGlobe: AnimationTypeGlobeCamera, AnimationTypeGlobeLayer, and AnimationTypeTimeLayer. Each animation corresponds to a type of keyframe: GlobeCameraKeyframe, GlobeLayerKeyframe, and TimeLayerKeyframe.

The following illustration shows the relationship among the animation components in the GlobeCore library, which can be used to create the different types of animations in ArcGlobe:
 
 
 
The Animation library can be extended by creating custom animation types.
 

AnimationExtension

The AnimationExtension object is the access point for other animation objects in ArcMap, ArcScene, and ArcGlobe. Typically, when you work with animation objects, the AnimationExtension object needs to be obtained as the first step before other actions are performed. The animation environment and animation track container objects can be accessed through the IAnimationExtension interface.
 
The following code example shows how to find the animation extension from a ArcScene object:

[Java]
public IAnimationExtension FindAnimationExtension(IScene scene)
{
    IBasicScene2 basicScene2 = (IBasicScene2)scene;
    IAnimationExtension animExt = basicScene2.getAnimationExtension();
    return animExt;
}
The following code example shows how to find the animation extension from a GlobeBean:

[Java]
IScene scene = getGlobeBean().getGlobeDisplay().getScene();
IBasicScene2 basicScene2 = (IBasicScene2)scene;
IAnimationExtension animExt = basicScene2.getAnimationExtension();

AGAnimationTrackContainer

An AGAnimationTrackContainer object is conceptually a container for animation tracks. The IAGAnimationTracks interface provides methods and properties to manage animation tracks. The animation track container can contain more than one animation track so that many animation tracks can be animated simultaneously. An IAGAnimationTracks object can be accessed through the AnimationExtension object.
 
The following code example shows how to get the animation track container in an application:

[Java]
IScene scene = getGlobeBean().getGlobeDisplay().getScene();
IBasicScene2 basicScene2 = (IBasicScene2)scene;
IAnimationExtension animExt = basicScene2.getAnimationExtension();
IAGAnimationTracks tracks = animExt.getAnimationTracks();

AGAnimationEnvironment

An AGAnimationEnvironment object represents the animation environment, which stores the animation state and playing options, such as animation duration, playing interval, playing mode, and so on. Also, these settings are used when exporting animations as video files.
 
These settings are persisted with the ArcMap, ArcScene, and ArcGlobe document when the document is saved, or with an animation file when the animation is saved as a file (.ama, .asa, or .aga for ArcMap, ArcScene, and ArcGlobe respectively). The animation environment object can be accessed through the AnimationExtension object.
 
The following code example shows how to access the animation environment in an application:

[Java]
IScene scene = getGlobeBean().getGlobeDisplay().getScene();
IBasicScene2 basicScene2 = (IBasicScene2)scene;
IAnimationExtension animExt = basicScene2.getAnimationExtension();
IAGAnimationEnvironment env = animExt.getAnimationEnvironment();

AGAnimationTrack

An AGAnimationTrack object represents an animation track, which assembles one or more similar animation keyframes. In a typical animation, more than one keyframe is needed to create an animation that will show change.
 
The IAGAnimationTrack interface provides access to animation track properties, such as track name, animation type, attached objects, and so on. The IAGAnimationTrackKeyframes interface provides methods and properties to manage keyframes in a track, such as get a keyframe at the given index, remove keyframes, sort keyframes, and so on.

AGAnimationKeyframe 

AGAnimationKeyframe is the base class for the three types of keyframes in ArcMap: MapLayerKeyframe, MapViewKeyframe, and TimeLayerKeyframe. Keyframes are snapshots of an object's properties at certain times. The interface IAGKeyframe contains methods to set these properties and apply them directly to the object. 

MapLayerKeyframe

This is the coclass used to define a map layer keyframe. A map layer keyframe is a snapshot of the layer transparency and visibility at a given moment. It stores two property values of a layer; visibility and transparency.

MapViewKeyframe

This is the coclass used to define a map view keyframe. A map view keyframe represents the snapshot of the map display extent at a given moment. It stores the view extent property value of the map.

TimeLayerKeyframe

This is the coclass used to define a time layer keyframe. A time layer keyframe represents a snapshot of the state of a layer or table at a given time. A time layer keyframe stores the time, interval, and units properties of the animation object.
 
The following code example shows how to create a time layer keyframe in ArcScene and ArcGlobe:

[Java]
//Create a time layer keyframe.
IAGKeyframe pKeyframe = new TimeLayerKeyframe();
pKeyframe.setTimeStamp(0.0);
pKeyframe.setName("Timelayerkeyframe1");
pKeyframe.setPropertyValue(0, new java.util.Date(strTime)); 
    // Set the time property.
pKeyframe.setPropertyValue(1, timeInterval); // Set the interval property.
pKeyframe.setPropertyValue(2, timeUnit); // Set the time unit property.

AGAnimationType 

AGAnimationType is an abstract class and derives animation type classes in ArcMap: AnimationTypeMapLayer, AnimationTypeMapView, and AnimationTypeTimeLayer.
 
Through the IAGAnimationType interface, an animation type object provides necessary information about a given type of animation, such as the animated property names, types, and so on. For each animation track, an animation type object must be specified.

AnimationTypeMapLayer 

AnimationTypeMapLayer allows you to animate a map layer. A map layer animation type supports the animation of two map layer properties; layer transparency and layer visibility.

AnimationTypeMapView

AnimationTypeMapView allows you to animate the display extent of a map. The property supported by a map view animation type is the map display extent. Changes to the map display extent include zooming in and out and panning the map in the display window.

AnimationTypeTimeLayer

AnimationTypeTimeLayer allows you to animate your data through time. The layer's source can be a feature class, a raster catalog, or a NetCDF file. Besides IAGAnimationType and IAGAnimationTypeUI, AnimationTypeTimeLayer implements another interface—IAnimationTypeTimeLayer—that provides methods to access the time windows and the time layer track extension for a given time animation track.

AGAnimationUtils

The AnimationUtils coclass provides some utility functions for creating, saving, loading, and playing animations. These functions are organized in the following interfaces: IAGAnimationUtils and the IAGAnimationPlayer.
 
The IAGAnimationUtils interface contains utility functions to convert bookmarks to keyframes, create group animations, create flyby-from-path animations, load and save animations, and so on. The IAGAnimationPlayer interface provides utility functions to play, pause, stop, and record animations.

The following code example shows how to play animations using the IAGAnimationPlayer:

[Java]
IAGAnimationTracks animTracks = animExt.getAnimationTracks();
IAGAnimationEnvironment animationEnvironment = animExt.getAnimationEnvironment()
    ;
IAGAnimationUtils animUtils = new AGAnimationUtils();
IAGAnimationPlayer animPlayer = new AGAnimationUtils();
animPlayer = (IAGAnimationPlayer)animUtils;
animPlayer.playAnimation(animTracks, animationEnvironment, null);

AGImportPathOptions

To move the map view or scene and globe camera along a selected path (feature or graphic), create a flyby-from-path animation track. Through the IAGImportPathOptions interface, an AGImportPathOptions object provides options for creating a flyby-from-path animation track. This object must be set and passed to the CreateFlybyFromPath method (found on the IAGAnimationUtils interface) to create a flyby-from-path track.

TimeWindow

When creating a time layer animation, a TimeWindow object is used to specify the time dimension of a layer or table. Through the ITimeWindow interface, a time window object provides options to set the start time field and format and the end time field and format.
 
There is also the option to animate fields cumulatively. For each layer or table attached to a time layer animation track, there is one corresponding time window object. However, when you create a time track, you don't need to create the time window objects explicitly. This is done automatically when a layer or table is attached to the time track.
 
After the layer or table is attached, get the time window object through the GetTimeWindow() method of the IAnimationTypeTimeLayer interface and set its properties.
 
The following code example shows how to get the Time Window from a give Scene or Globe layer:

[Java]
// This function returns the time window for a layer object.
ITimeWindow timeWin = new TimeWindow();
IAnimationTypeTimeLayer pAnimTypeTimeLayer = (IAnimationTypeTimeLayer)
    animTypeTime;
pAnimTypeTimeLayer.getTimeWindow(animTrack, layer, timeWin);
timeWin.setStartField(startTimeField);
timeWin.setStartFieldFormat(startTimeFieldFormat);
timeWin.setEndField(endTimeField);
timeWin.setEndFieldFormat(endTimeFieldFormat);
timeWin.setAnimateCumulatively(bAnimCumu);

TimeLayerTrackExtension 

A TimeLayerTrackExtension object is an extension for a time layer animation track. The ITimeLayerTrackExtension interface contains methods and properties to manage time windows and time text display properties for a given time animation track. This extension can be accessed through the IAnimationTypeTimeLayer interface of an AnimationTypeTimeLayer object. It can also be accessed through the IAGAnimationTrackExtensions interface of a time layer animation track.

AnimationExporterAVI

Animations can be exported to video files. The AnimationExporterAVI object provides the method to export animations as Audio Video Interleave (*.avi) files. To do so, specify the export file name, quality and codec settings for the exporter, then call the ExportAnimation method through the IVideoExporter interface.
 
Default values for the quality and codec settings will be used if they are not specified. The default quality is 75. The default codec is Intel Indeo(R) Video R3.2 if the quality setting is below 90, and Cinepak Codec by Radius otherwise.

AnimationExporterQT

The AnimationExporterQT object allows you to export animations to QuickTime (*.mov) video files. The QuickTime player must be installed on your computer before the QuickTime video export feature is enabled. IVideoExporter, the same interface as implemented on the AnimationExporterAVI coclass, is implemented on AnimationExporterQT for QuickTime video export. To download QuickTime, see http://www.apple.com/quicktime/.