@node Animation
@chapter Animation
@anchor{chap:Animation}

@menu
* Animation interface::
* NetAnim::
@end menu

Animation is an important tool for network simulation. While ns-3 does 
not contain a graphical animation tool, it does provide an animation interface 
for use with stand-alone animators. Currently, the animation 
interface only supports point-to-point links; however, we hope
to support other link types such as CSMA and wireless in the near future.
The animation interface in ns-3 allows the generation of a custom trace 
file to be used by an animation program.

An existing stand-alone program, NetAnim, uses these custom traces to 
graphically display the simulation. NetAnim depicts packets traveling 
on point-to-point links as they travel from node to node.

@node Animation interface
@section Animation interface

The animation interface in ns-3 currently only supports point-to-point 
links and can generate a custom trace file for use by an animation 
program.  A snippet from a sample trace file is shown below.

@verbatim
0.0 N 0 4 5.5
0.0 N 1 7 5.5
0.0 N 2 2.5 2.90192

...

0.0 L 0 1
0.0 L 0 2
0.0 L 0 3

...

Running the simulation
0.668926 P 11 1 0.66936 0.669926 0.67036
0.67036 P 1 0 0.670794 0.67136 0.671794
0.671794 P 0 6 0.672227 0.672794 0.673227

...
@end verbatim

The tracefile describes where nodes and links should be placed at 
the top of the file. Following this placement, the packet events 
are shown. The format for node placement, link placement and 
packet events is shown below.

@itemize @bullet
@item Node placement: <time of placement> <N for node> <node id> 
                      <x position> <y position>
@item Link placement: <time of placement> <L for link> <node1 id> 
                      <node2 id>
@item Packet events:  <time of first bit tx> <P for packet> 
                      <source node> <destination node> 
                      <time of last bit tx> 
                      <time of first bit rx> 
                      <time of last bit rx>
@end itemize

To get started using the animation interface, several example scripts 
have been provided to show proper use.  These examples can be found 
in examples/animation. The example scripts use the animation interface 
as well as topology helpers in order to automatically place the nodes 
and generate the custom trace. It is important to note that if a 
topology helper is not used with its provided BoundingBox method, 
which automatically calculates the nodes' canvas positions, the nodes 
must be placed manually by aggregating a CanvasLocation to the node. 
An example use of CanvasLocation can be found in any of the topology 
helpers. Additionally, a simple example of placing a node is shown below:

@verbatim
  // assuming a node container m_hub exists and 
  // contains at least one node.
  // we grab this node and associate a 
  // CanvasLocation to it, in order for the 
  // animation interface to place the node
  Ptr<Node> hub = m_hub.Get (0);
  Ptr<CanvasLocation> hubLoc =  hub->GetObject<CanvasLocation> ();
    if (hubLoc == 0)
      {
        hubLoc = CreateObject<CanvasLocation> ();
        hub->AggregateObject (hubLoc);
      }
  Vector hubVec (5, 7);
  hubLoc->SetLocation (hubVec);
@end verbatim

Finally, after the simulation has been set up and the nodes have been 
placed, the animation interface is used to start the animation, which 
writes the custom trace file.  Below is an example of how to set 
up and start the animation interface.

@verbatim
  AnimationInterface anim;
  // the animation interface can be set up to write 
  // to a socket, if a port > 0 is specified
  // see doxygen for more information
  if (port > 0)
    {
      anim.SetServerPort (port);
    }
  else if (!animFile.empty ())
    {
      // if a file name is specified, 
      // the trace is written to the file.
      // otherwise, it is directed to stdout
      anim.SetOutputFile (animFile);
    }
  anim.StartAnimation ();
@end verbatim

@node NetAnim
@section NetAnim

NetAnim is a stand-alone program which uses the custom trace files 
generated by the animation interface to graphically display the 
simulation.  NetAnim is based on the multi-platform 
@uref{http://www.qtsoftware.com/products/,,Qt4 GUI toolkit}. A 
screenshot of the NetAnim GUI is shown below.

@float Figure,fig:anim-dumbbell
@caption{NetAnim GUI with dumbbell animation.}
@image{figures/animation-dumbbell, 4in}
@end float

The NetAnim GUI provides play, pause, and record buttons.  Play and 
pause start and stop the simulation.  The record button starts a series 
of screenshots of the animator, which are written to the directory in 
which the trace file was run.  Two slider bars also exist.  The top 
slider provides a "seek" functionality, which allows a user to skip to 
any moment in the simulation.  The bottom slider changes the granularity 
of the time step for the animation. Finally, there is a quit button to 
stop the simulation and quit the animator.

@subsection Prerequisites

The animator requires the Qt4 development packages. If you are using a 
Debian or Ubuntu Linux distribution, you can get the following package: 
qt4-dev-tools 

This should install everything you need to compile and build NetAnim. 
If you are using an Red Hat based distribution, look for similar qt4 
packages (or libqt4*) and install these using yum. Mac users should 
install the binaries: http://www.qtsoftware.com/downloads/mac-os-cpp

Make sure to download the binary package; look for a link to something 
without the word "src" or "debug" in the download filename. These will 
be the library binaries you need.

@subsection Downloading NetAnim

The tarball of the source code for NetAnim is available here: 
@uref{http://www.nsnam.org/~jpelkey3/NetAnim.tar.gz,,http://www.nsnam.org/~jpelkey3/NetAnim.tar.gz}. 
Download it, then untar it: 

@verbatim
tar -xzvf NetAnim.tar.gz
@end verbatim

@subsection Building NetAnim

NetAnim uses a Qt4 build tool called qmake; this is similar to the 
configure script from autotools in that it generates the Makefile, 
which make then uses to build the project. qmake is different on 
different versions of Qt, so we'll provide some additional information 
that is system dependent. You can check your default version of qmake:

@verbatim
qmake --version
Qmake version: 1.07a (Qt 3.3.8b)
Qmake is free software from Trolltech ASA.
@end verbatim

If you see something like the above, where it says Qt 3.x.x, find the 
qt4 version of qmake on your system and explicitly call it instead.

In general,

@verbatim
cd NetAnim
qmake
make
@end verbatim

On Mac OSX,

@verbatim
cd NetAnim
/usr/local/Trolltech/Qt-4.x.y/bin/qmake
make
@end verbatim

Note that above, the x.y is the specific version of Qt4 you are running. 
As of April 1st 2009, the latest version is 4.5.0, although you might 
have an older version already installed. 

On Ubuntu/Debian with Qt3 AND Qt4,

@verbatim
cd NetAnim
qmake-qt4
make
@end verbatim