Animation

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.
 
There are three out-of-the-box animation types for ArcMap: AnimationTypeTimeLayer, AnimationTypeMapView, and AnimationTypeMapLayer. Each animation type corresponds to a type of keyframe. There are three types of keyframes in the Animation library: TimeLayerKeyframe, MapViewKeyframe, and MapLayerKeyframe.
 
The following diagram shows the relationship among the animation components in the Animation library, which can be used to create the three different types of animations in ArcMap: 
 
In Scene, there are four out-of-the-box types of animations: AnimationTypeCamera, AnimationTypeLayer, AnimationTypeScene, and AnimationTypeTimeLayer. Each animation corresponds to a type of keyframe: Bookmark3D (for creating camera keyframes), LayerKeyframe, SceneKeyframe, and TimeLayerKeyframe.
 
The following diagram shows the relationship among the animation components in the 3D Analyst library, which can be used to create the four different types of animations in Scene:
 
In Globe, there are three out-of-the-box types of animations: AnimationTypeGlobeCamera, AnimationTypeGlobeLayer, and AnimationTypeTimeLayer. Each animation corresponds to a type of keyframe: GlobeCameraKeyframe, GlobeLayerKeyframe, and TimeLayerKeyframe.
 
The following diagram shows the relationship among the animation components in the GlobeCore library, which can be used to create the three different types of animations in Globe:
 
The Animation library is extensible, which means that this library can be extended by creating custom animation types.

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

AnimationExtension
The AnimationExtension object is the access point for other animation objects in ArcMap, Scene, and Globe. 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 illustrates how to find the animation extension in an application (ArcMap, ArcScene. ArcGlobe) in VBA:

In Scene and Globe, you can access the animation extension from the IBasicScene2 object.
 
The following code illustrates how to find the animation extension in Scene:

[C#] 
  public IAnimationExtension FindAnimationExtension (IScene scene)
  {
    IBasicScene2 basicScene2 = (IBasicScene2)scene;
    IAnimationExtension animExt = basicScene2.AnimationExtension;

    return animExt;
  }
The following code illustrates how to find the animation extension in Globe:
[C#] 
  public IAnimationExtension FindAnimationExtension (IGlobe globe)
  {
    IGlobeDisplay globeDisplay = globe.GlobeDisplay;
    Scene scene = (Scene) globeDisplay.Scene;

    IBasicScene2 basicScene2 = (IBasicScene2)scene;
    IAnimationExtension animExt = basicScene2.AnimationExtension;

    return animExt;
  }

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 VBA code illustrates how to get the animation track container in an application:

The following code illustrates how to get the animation track container in Scene:
[C#] 
 //Get the animation track container in Scene
 IAnimationExtension animExt = FindAnimationExtension(scene);
 IAGAnimationTracks pAnimTracks = animExt.AnimationTracks;
The following code illustrates how to get the animation track container in Globe:
[C#] 
 //Get the animation track container in Globe
 IAnimationExtension animExt = FindAnimationExtension(globe);
 IAGAnimationTracks pAnimTracks = animExt.AnimationTracks;

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 Map/Scene/Globe document when the document is saved or with an animation file when the animation is saved as a file (.ama, .asa, or .aga file for ArcMap, Scene and Globe respectively). The animation environment object can be accessed through the AnimationExtension object.
 
The following code shows how to access the animation environment in an application:

The following code shows how to access the animation environment in Scene:
[C#] 
// Get the animation environment in Scene
 IAnimationExtension animExt = FindAnimationExtension(scene);
 IAGAnimationEnvironment pAnimEnvironment = animExt.AnimationEnvironment;
The following code shows how to access the animation environment in Globe:
[C#] 
// Get the animation environment in Globe
 IAnimationExtension animExt = FindAnimationExtension(globe);
 IAGAnimationEnvironment pAnimEnvironment = animExt.AnimationEnvironment;

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.

Key frames

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 one property value of the map, the view extent. 

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 three properties of the animation object: time, interval, and units. 
 
The following VBA code illustrates how to create a time layer keyframe: 

The following code illustrates how to create a time layer keyframe in Scene and Globe:
  

[C#] 
 //Create a time layer keyframe
 IAGKeyframe pKeyframe = new TimeLayerKeyframeClass();

 pKeyframe.TimeStamp = 0;

 pKeyframe.Name = "Timelayerkeyframe1";
 pKeyframe.set_PropertyValue(0, System.Convert.ToDateTime(strTime));  // Set the time property
 pKeyframe.set_PropertyValue(1, timeInterval); // Set the interval property
 pKeyframe.set_PropertyValue(2, timeUnit); // Set the time unit property

Animation types

AGAnimationType

AGAnimationType is an abstract class, which derives three 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--which 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 two interfaces: the IAGAnimationUtils interface and the IAGAnimationPlayer interface. 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 illustrates how to play animations using the IAGAnimationPlayer interface in VBA:

The following code illustrates how to play animations using the IAGAnimationPlayer interface in Scene:
[C#] 
 //Play an animation using the IAGAnimationPlayer interface in Scene
 public void playAnimation (IScene scene)
 {
   IAnimationExtension animExt = FindAnimationExtension(scene);

   IAGAnimationTracks pAnimTracks = animExt.AnimationTracks;
   IAGAnimationEnvironment pAGAnimationEnvironment = animExt.AnimationEnvironment;

   IAGAnimationUtils animUtils = new AGAnimationUtilsClass();

   IAGAnimationPlayer animPlayer = new AGAnimationUtilsClass();
   animPlayer = (IAGAnimationPlayer)animUtils;

   animPlayer.PlayAnimation(pAnimTracks, pAGAnimationEnvironment, null);
 }
The following code illustrates how to play animations using the IAGAnimationPlayer interface in Globe:
[C#] 
 //Play an animation using the IAGAnimationPlayer interface in Globe
 public void playAnimation (IGlobe globe)
 {
   IAnimationExtension animExt = FindAnimationExtension(globe);

   IAGAnimationTracks pAnimTracks = animExt.AnimationTracks;
   IAGAnimationEnvironment pAGAnimationEnvironment = animExt.AnimationEnvironment;

   IAGAnimationUtils animUtils = new AGAnimationUtilsClass();

   IAGAnimationPlayer animPlayer = new AGAnimationUtilsClass();
   animPlayer = (IAGAnimationPlayer)animUtils;

   animPlayer.PlayAnimation(pAnimTracks, pAGAnimationEnvironment, null);
 }

AGImportPathOptions
To move the map view or Scene/Globe camera along a selected path (feature or graphic), you need to 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 (which can be 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/format and the end time field/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, you need to get the time window object through the GetTimeWindow() method of the IAnimationTypeTimeLayer interface and set its properties. 
The following VBA code illustrates how to get the time window from a given time layer:

The following code illustrates how to get the time window from a given time layer in Scene and Globe:

[C#] 
  // This function returns the time window for a layer object
  ITimeWindow pTimeWin = new TimeWindowClass();
  IAnimationTypeTimeLayer pAnimTypeTimeLayer = pAnimTypeTime as IAnimationTypeTimeLayer;
  pAnimTypeTimeLayer.GetTimeWindow(pAnimTrack, pLayer, ref pTimeWin);
  pTimeWin.StartField = startTimeField;
  pTimeWin.StartFieldFormat = startTimeFieldFormat;
  pTimeWin.EndField = endTimeField;
  pTimeWin.EndFieldFormat = endTimeFieldFormat;
  pTimeWin.AnimateCumulatively = 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.

Exporters

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, you need to 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. QuickTime player (which can be downloaded from http://www.apple.com/quicktime) 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.

Creating custom animations

The Animations framework is very flexible in terms of allowing the creation of different types of animations. The out-of-the-box animation types use properties of different objects (Camera, Layer, Scene, Map View, and Time Layer) that can be modified to animate these objects over the animation duration. Properties include the camera’s view, a layer’s visibility, or a time layer’s interval and units. Other properties of these objects (e.g., changing the symbology of a layer or changing the properties of a layer) can also be used to create animations by defining custom animation types. These custom animations control properties of objects other than the ones predefined in the out-of-the-box animation types. In addition, it is also possible to define animation types that control objects defined externally to ArcMap, ArcScene or ArcGlobe, including common object model (COM) objects that you have implemented.
 
To customize the animation framework in ArcGIS 9.2 you must develop a pair of new classes.  One class is used to define the custom animation track and the other for defining keyframes that can be added to the track.  The custom animation track must implement the interfaces IAGAnimationType and IAGAnimationTypeUI.  Similarly, the custom keyframe must implement both IAGKeyframe and IAGKeyframeUI.  Both classes must be registered with COM and the animation track class must implement one or more of the category components which indicate support ArcGIS applications, that is, ArcMap, ArcScene or ArcGlobe. 
Custom animation tracks/keyframes developed in ArcGIS 9.1 will need to be re-engineered to support ArcGIS 9.2 library changes. Legacy code written for custom animation types will not work unless the required interfaces are implemented.
 
Besides this the  enumerations - "esriAnimationPropertyType" and “esriAnimationState” have been move from the 3D Analyst object library to the new Animation object library.  This and other modifications were made to allow developers to seamless create custom animation tracks for any (or all) ArcGIS applications.