.. include:: replace.txt

Animation
---------

Animation is an important tool for network simulation. While |ns3| does not
contain a default graphical animation tool, we currently have two ways to provide
animation, namely using the PyViz method or the NetAnim method.
The PyViz method is described in http://www.nsnam.org/wiki/index.php/PyViz.
The NetAnim method is described in detail at http://www.nsnam.org/wiki/index.php/NetAnim.
We will describe the NetAnim method briefly here.

AnimationInterface
*******************

The class "AnimationInterface" under "src/netanim" uses underlying |ns3| trace sources 
to construct a timestamped ASCII file in XML format that can be read by a standalone animator 
named "NetAnim". 

Generating XML trace files for use in NetAnim
+++++++++++++++++++++++++++++++++++++++++++++
Apply the following statements before the "Simulator::Run ()" statement:::

  AnimationInterface anim ("animation.xml")

where "animation.xml" is any arbitrary file name.
It is important to ensure that your wscript includes the "netanim" module. 
Example as in: src/netanim/examples/wscript. Also include the header 
[#include "ns3/netanim-module.h"] in your test program

The examples under "src/netanim/examples" illustrate this. The sample wscript is at 
"src/netanim/examples/wscript".

Lets take an example: "src/netanim/examples/star-animation.cc". To run the example:::

  ./waf --run "star-animation"

This will generate an xml file "star-animation.xml" in the same directory. This XML file 
contains the information required by the standalone animator "NetAnim" to produce the required
animation.


Parts of the XML
++++++++++++++++
This is described in detail at http://www.nsnam.org/wiki/index.php/NetAnim#Parts_of_the_XML

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 `Qt4 GUI toolkit <http://qt.nokia.com/>`_.
A screenshot of the NetAnim GUI is shown below.

.. _anim-dumbbell:

.. figure:: figures/animation-dumbbell.*

    NetAnim GUI with dumbbell animation.

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.

For detailed instructions on installing "NetAnim" and loading the XML trace file 
(mentioned earlier) using NetAnim please refer:
http://www.nsnam.org/wiki/index.php/NetAnim
