Animation

Supported with:

Engine with 3D
ArcView
ArcEditor
ArcInfo
Server

Library dependencies: System, SystemUI, Geometry, GraphicsCore, Display, Server, Output, Geodatabase, GISClient, 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. 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 animating the camera through a scene or globe, changes to the display extent of a map, and changes to the transparency and visibility of a layer.

The Animation library is extensible, which means that this library can be extended by creating custom animation types.

See the following sections for more information about this namespace:

Tracks, types, and keyframes
AnimationExtension
AGAnimationTrackContainer
AGAnimationEnvironment
AGAnimationTrack
Key frames
Animation types
AGAnimationUtils
AGImportPathOptions
Exporters
Creating custom animations

Tracks, types, and keyframes

An animation is composed of animation tracks (AGAnimationTrack), 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 a dynamic visual effect.

There are three out-of-the-box animation types for ArcMap: AnimationTypeMapView, AnimationTypeMapLayer, and AnimationTypeTime. Each animation type corresponds to a type of keyframe. The three types of keyframes in the Animation library are MapViewKeyframe, MapLayerKeyframe, and TimeKeyframe.

The following diagram shows the relationship among the animation components in the Animation library, which can be used to create the three types of animations in ArcMap.

In Scene, the following types of out-of-the-box animations are available:

Each animation corresponds to a type of keyframe listed as follows:

Bookmark3D (for creating camera keyframes)
LayerKeyframe
SceneKeyframe
TimeKeyframe

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, the following types of out-of-the-box animations are available:

Each animation corresponds to a type of keyframe listed as follows:

The following diagram shows the relationship among the animation components in the GlobeCore library, which can be used to create the different types of animations in Globe:

Time Layer animations (AnimationTypeTimeLayer) created in ArcGIS 9.x are deprecated. For visualizing temporal data over time, it is recommended that you should use the time objects. Learn more about Working with time data and Displaying time-aware data. However, if you want to add other animated effects while visualizing your temporal data over time, you can choose to create a time animation (AnimationTypeTime), which can be played alongside other animation tracks. For example, if you want to create a camera flyby while visualizing your data over time, you can create a time animation track to alter the time of the display (map, scene, or globe) and a camera animation track to move the camera. These two tracks can then be played together to create a dynamic visual effect.

When opening an existing ArcGIS 9.x document with Time Layer animation tracks (AnimationTypeTimeLayer), these tracks will be automatically converted into the new Time animation tracks (AnimationTypeTime). Also, time properties of the time layer associated with the existing Time Layer track will be set automatically set.

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 ArcMap.

[C#]


            public IAnimationExtension FindAnimationExtension(IApplication mapApp)
{
    UID pUID = new UID();
    pUID.Value = "esriAnimation.AnimationExtension";
    IAnimationExtension animExt;
    animExt = (IAnimationExtension)mapApp.FindExtensionByCLSID(pUID);

    return animExt;
}

[VB.NET]


            Public Function FindAnimationExtension(ByRef mapApp As IApplication) As IAnimationExtension
    Dim pUID As New UID
    pUID.Value = "esriAnimation.AnimationExtension"
    Dim animExt As IAnimationExtension
    animExt = CType(mapApp.FindExtensionByCLSID(pUID), IAnimationExtension)
    FindAnimationExtension = animExt
End Function

In Scene and Globe, you can access the AnimationExtension property from the IBasicScene2 interface.

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;
}

[VB.NET]


            Public Function FindAnimationExtension(ByVal scene As IScene) As IAnimationExtension
    Dim basicScene2 As IBasicScene2 = CType(scene, IBasicScene2)
    Dim animExt As IAnimationExtension = basicScene2.AnimationExtension
    
    Return animExt
End Function

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;
}

[VB.NET]


            Public Function FindAnimationExtension(ByVal globe As IGlobe) As IAnimationExtension
    Dim globeDisplay As IGlobeDisplay = globe.GlobeDisplay
    Dim scene As Scene = CType(globeDisplay.Scene, Scene)
    
    Dim basicScene2 As IBasicScene2 = CType(scene, IBasicScene2)
    Dim animExt As IAnimationExtension = basicScene2.AnimationExtension
    
    Return animExt
End Function

AGAnimationTrackContainer

The 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 illustrates how to get the animation track container in ArcMap.

[C#]


            //Get the animation track container in ArcMap.
IAnimationExtension animExt = FindAnimationExtension(mapApp);
IAGAnimationTracks pAnimTracks = animExt.AnimationTracks;

[VB.NET]


            'Get the animation track container in ArcMap.
Dim animExt As IAnimationExtension = FindAnimationExtension(mapApp)
Dim pAnimTracks As IAGAnimationTracks = animExt.AnimationTracks

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;

[VB.NET]


            'Get the animation track container in Scene.
Dim animExt As IAnimationExtension = FindAnimationExtension(scene)
Dim pAnimTracks As IAGAnimationTracks = 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;

[VB.NET]


            'Get the animation track container in Globe.
Dim animExt As IAnimationExtension = FindAnimationExtension(globe)
Dim pAnimTracks As IAGAnimationTracks = 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. These settings are used when exporting animations as video files. These settings are persisted with the Map, Scene, and 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 ArcMap.

[C#]


            // Get the animation environment in ArcMap.
IAnimationExtension animExt = FindAnimationExtension(mapApp);
IAGAnimationEnvironment pAnimEnvironment = animExt.AnimationEnvironment;

[VB.NET]


            ' Get the animation environment in ArcMap.
Dim animExt As IAnimationExtension = FindAnimationExtension(mapApp)
Dim pAnimEnvironment As IAGAnimationEnvironment = animExt.AnimationEnvironment

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;

[VB.NET]


            ' Get the animation environment in Scene.
Dim animExt As IAnimationExtension = FindAnimationExtension(scene)
Dim pAnimEnvironment As IAGAnimationEnvironment = 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;

[VB.NET]


            ' Get the animation environment in Globe.
Dim animExt As IAnimationExtension = FindAnimationExtension(globe)
Dim pAnimEnvironment As IAGAnimationEnvironment = 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 TimeKeyframe. Keyframes are snapshots of an object’s properties at certain times. The IAGKeyframe interface 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.

TimeKeyframe

This is the coclass used to define a time keyframe. A time keyframe represents the time of the map. A time keyframe stores three properties of the animation object: time, interval, and units.

For creating the time animation, you can create a time animation track (AnimationTypeTime), which is composed of two or more time keyframes (TimeKeyframe). TimeLayerKeyframe are deprecated post ArcGIS 9.x.

Animation types

AGAnimationType

AGAnimationType is an abstract class that derives three animation type classes in ArcMap: AnimationTypeMapLayer, AnimationTypeMapView, and AnimationTypeTime. 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.

AnimationTypeTime

AnimationTypeTime allows you to animate your display through time. In addition to IAGAnimationType and IAGAnimationTypeUI, AnimationTypeTime implements another interface—IAnimationTypeTime—that provides methods to access the time windows and the time layer track extension for a given time animation track.

AnimationTypeTimeLayer is no longer supported post ArcGIS 9.x. Time Layer animations created in ArcGIS 9.x are deprecated. For visualizing temporal data over time, it is recommended that you should use the time objects. Learn more about Working with time data and Displaying time-aware data. However, if you want to add other animated effects while visualizing your temporal data over time, you can choose to create a time animation (AnimationTypeTime), which can be played alongside other animation tracks such as a camera track.

For creating the time animation, you can create a time animation track (AnimationTypeTime), which is composed of two or more time keyframes (TimeKeyframe).

AGAnimationUtils

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

The following code illustrates how to play animations using the IAGAnimationPlayer interface.

[C#]


            public void PlayAnimation(IApplication mapApp)
{
    //Play an animation using the IAGAnimationPlayer interface. 
    IAnimationExtension pAnimExt;
    pAnimExt = FindAnimationExtension(mapApp);
    //Create the AGAnimationUtils object. 
    IAGAnimationPlayer pAnimPlayer;
    pAnimPlayer = new AGAnimationUtilsClass();
    //Play the animation. 
    pAnimPlayer.PlayAnimation(pAnimExt.AnimationTracks,
        pAnimExt.AnimationEnvironment, mapApp.StatusBar);
}

[VB.NET]


            Public Sub PlayAnimation(ByVal mapApp As IApplication)
    'Play an animation using the IAGAnimationPlayer interface.
    Dim pAnimExt As IAnimationExtension
    pAnimExt = FindAnimationExtension(mapApp)
    'Create the AGAnimationUtils object.
    Dim pAnimPlayer As IAGAnimationPlayer
    pAnimPlayer = New AGAnimationUtils
    'Play the animation.
    pAnimPlayer.PlayAnimation(pAnimExt.AnimationTracks, _
                              pAnimExt.AnimationEnvironment, mapApp.StatusBar)
End Sub

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);
}

[VB.NET]


            'Play an animation using the IAGAnimationPlayer interface in Scene.

Public Sub playAnimation(ByVal scene As IScene)
    Dim animExt As IAnimationExtension = FindAnimationExtension(scene)
    
    Dim pAnimTracks As IAGAnimationTracks = animExt.AnimationTracks
    Dim pAGAnimationEnvironment As IAGAnimationEnvironment = animExt.AnimationEnvironment
    
    Dim animUtils As IAGAnimationUtils = New AGAnimationUtilsClass()
    Dim animPlayer As IAGAnimationPlayer = New AGAnimationUtilsClass()
    
    animPlayer = CType(animUtils, IAGAnimationPlayer)
    animPlayer.PlayAnimation(pAnimTracks, pAGAnimationEnvironment, Nothing)
End Sub

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);
}

[VB.NET]


            'Play an animation using the IAGAnimationPlayer interface in Globe.

Public Sub playAnimation(ByVal globe As IGlobe)
    Dim animExt As IAnimationExtension = FindAnimationExtension(globe)
    
    Dim pAnimTracks As IAGAnimationTracks = animExt.AnimationTracks
    Dim pAGAnimationEnvironment As IAGAnimationEnvironment = animExt.AnimationEnvironment
    
    Dim animUtils As IAGAnimationUtils = New AGAnimationUtilsClass()
    Dim animPlayer As IAGAnimationPlayer = New AGAnimationUtilsClass()
    
    animPlayer = CType(animUtils, IAGAnimationPlayer)
    animPlayer.PlayAnimation(pAnimTracks, pAGAnimationEnvironment, Nothing)
End Sub

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 on the IAGAnimationUtils interface to create a flyby-from-path 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 and the 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 animation framework is 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 duration of the animation. 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 those 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, you must develop a pair of classes. One class is used to define the custom animation track, the other is used to define keyframes that can be added to the track. The custom animation track must implement the IAGAnimationType and IAGAnimationTypeUI interfaces. 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 that indicate support for ArcGIS applications, that is, ArcMap, ArcScene, or ArcGlobe.

Custom animation tracks and 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.

The esriAnimationPropertyType and esriAnimationState enumerations are located in the Animation object library.