182 lines
6.3 KiB
ReStructuredText
182 lines
6.3 KiB
ReStructuredText
.. include:: replace.txt
|
|
|
|
Animation
|
|
---------
|
|
|
|
Animation is an important tool for network simulation. While |ns3| does not
|
|
contain a default graphical animation tool, it does provide an animation
|
|
interface for use with stand-alone animators. One such animator called NetAnim,
|
|
presently supporting packet flow animation for point-to-point links, has been
|
|
developed. Other animators and visualization tools are in development; they may
|
|
make use of the existing animation interface or may develop new ones,
|
|
|
|
Animation interface
|
|
*******************
|
|
|
|
The animation interface uses underlying |ns3| trace sources to construct a
|
|
timestamped ASCII file that can be read by a standalone animator. The animation
|
|
interface in |ns3| currently only supports point-to-point links; however, we
|
|
hope to support other link types such as CSMA and wireless in the near future.
|
|
A snippet from a sample trace file is shown below.::
|
|
|
|
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
|
|
|
|
...
|
|
|
|
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.
|
|
|
|
* Node placement: <time of placement> <N for node> <node id> <x position> <y
|
|
position>
|
|
* Link placement: <time of placement> <L for link> <node1 id> <node2 id>
|
|
* 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>
|
|
|
|
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:::
|
|
|
|
// 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);
|
|
|
|
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.::
|
|
|
|
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 ();
|
|
|
|
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.
|
|
|
|
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://qt.nokia.com/downloads>`_.
|
|
|
|
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.
|
|
|
|
Downloading NetAnim
|
|
+++++++++++++++++++
|
|
|
|
The tarball of the source code for NetAnim is available here:
|
|
`<http://www.nsnam.org/~jpelkey3/NetAnim.tar.gz>`_. Download it, then untar
|
|
it:::
|
|
|
|
tar -xzvf NetAnim.tar.gz
|
|
|
|
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:::
|
|
|
|
qmake --version
|
|
Qmake version: 1.07a (Qt 3.3.8b)
|
|
Qmake is free software from Trolltech ASA.
|
|
|
|
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,::
|
|
|
|
cd NetAnim
|
|
qmake
|
|
make
|
|
|
|
On Mac OSX,::
|
|
|
|
cd NetAnim
|
|
/usr/local/Trolltech/Qt-4.x.y/bin/qmake
|
|
make
|
|
|
|
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,::
|
|
|
|
cd NetAnim
|
|
qmake-qt4
|
|
make
|