210 lines
6.8 KiB
Plaintext
210 lines
6.8 KiB
Plaintext
@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 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,
|
|
|
|
@node Animation interface
|
|
@section Animation interface
|
|
|
|
The animation interface uses underlying ns-3 trace sources to construct
|
|
a timestamped ASCII file that can be read by a standalone animator.
|
|
The animation interface in ns-3 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.
|
|
|
|
@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
|