- Engine with 3D Analyst
- ArcGIS for Desktop Basic
- ArcGIS for Desktop Standard
- ArcGIS for Desktop Advanced
- Server
Additional library information: Contents, Object Model Diagram
The Animation library contains objects to work with animations in Map, Scene, and Globe. With ArcGIS for 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 ArcGIS 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
- Keyframes
- 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 different types of animations in ArcMap:
In Scene, the following types of out-of-the-box animations are available:
- AnimationTypeCamera
- AnimationTypeLayer
- AnimationTypeScene
- AnimationTypeTime
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 different types of animations in Scene:
In Globe, the following types of out-of-the-box animations are available:
- AnimationTypeGlobeCamera
- AnimationTypeGlobeLayer
- AnimationTypeTime
Each animation corresponds to a type of keyframe listed as follows:
- GlobeCameraKeyframe
- GlobeLayerKeyframe
- TimeKeyframe
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 have been deprecated. To visualize temporal data over time, use the time objects. For more information, see Working with time data and Displaying time-aware data.
However, to add animated effects while visualizing your temporal data over time, you can create a time animation (AnimationTypeTime) that can be played alongside other animation tracks. For example, 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), the tracks are automatically converted to the new Time animation tracks (AnimationTypeTime). In addition, time properties of the time layer associated with the existing Time Layer track are set automatically.
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 example shows how to find the animation extension in ArcMap:
public IAnimationExtension FindAnimationExtension(IApplication mapApp)
{
UID pUID=new UID();
pUID.Value="esriAnimation.AnimationExtension";
IAnimationExtension animExt;
animExt=(IAnimationExtension)mapApp.FindExtensionByCLSID(pUID);
return animExt;
}
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 example shows how to find the animation extension in Scene:
[C#] public IAnimationExtension FindAnimationExtension(IScene scene)
{
IBasicScene2 basicScene2=(IBasicScene2)scene;
IAnimationExtension animExt=basicScene2.AnimationExtension;
return animExt;
}
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 example shows 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;
}
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 example shows how to get the animation track container in ArcMap:
//Get the animation track container in ArcMap.
IAnimationExtension animExt=FindAnimationExtension(mapApp);
IAGAnimationTracks pAnimTracks=animExt.AnimationTracks;
'Get the animation track container in ArcMap.
Dim animExt As IAnimationExtension=FindAnimationExtension(mapApp)
Dim pAnimTracks As IAGAnimationTracks=animExt.AnimationTracks
The following code example shows 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;
'Get the animation track container in Scene.
Dim animExt As IAnimationExtension=FindAnimationExtension(scene)
Dim pAnimTracks As IAGAnimationTracks=animExt.AnimationTracks
The following code example shows 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;
'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 example shows how to access the animation environment in ArcMap:
// Get the animation environment in ArcMap.
IAnimationExtension animExt=FindAnimationExtension(mapApp);
IAGAnimationEnvironment pAnimEnvironment=animExt.AnimationEnvironment;
' Get the animation environment in ArcMap.
Dim animExt As IAnimationExtension=FindAnimationExtension(mapApp)
Dim pAnimEnvironment As IAGAnimationEnvironment=animExt.AnimationEnvironment
The following code example shows how to access the animation environment in Scene:
[C#] // Get the animation environment in Scene.
IAnimationExtension animExt=FindAnimationExtension(scene);
IAGAnimationEnvironment pAnimEnvironment=animExt.AnimationEnvironment;
' Get the animation environment in Scene.
Dim animExt As IAnimationExtension=FindAnimationExtension(scene)
Dim pAnimEnvironment As IAGAnimationEnvironment=animExt.AnimationEnvironment
The following code example shows how to access the animation environment in Globe:
[C#] // Get the animation environment in Globe.
IAnimationExtension animExt=FindAnimationExtension(globe);
IAGAnimationEnvironment pAnimEnvironment=animExt.AnimationEnvironment;
' 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.
Keyframes
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.
When creating time animation, you can create a time animation track (AnimationTypeTime), which contains two or more time keyframes (TimeKeyframe). TimeLayerKeyframe has been 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.
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 example shows 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);
}
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 example shows 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);
}
'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 example shows 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);
}
'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 this, 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 are 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 (for example, 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 Component 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.