Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(847)

Unified Diff: doc/manual/animation.texi

Issue 176077: Ns-3 Net-anim Interface Documentation (Closed)
Patch Set: method typo Created 14 years, 3 months ago
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View side-by-side diff with in-line comments
Download patch
« no previous file with comments | « no previous file | doc/manual/figures/animation-dumbbell.pdf » ('j') | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
Index: doc/manual/animation.texi
===================================================================
--- a/doc/manual/animation.texi
+++ b/doc/manual/animation.texi
@@ -1,13 +1,210 @@
@node Animation
@chapter Animation
+@anchor{chap:Animation}
-@cartouche
-Placeholder chapter
-@end cartouche
+@menu
+* Animation interface::
+* NetAnim::
+@end menu
-This wiki page: @*
-@uref{http://www.nsnam.org/wiki/index.php/NetAnim,,http://www.nsnam.org/wiki/index.php/NetAnim}
-contains information about the animator support that has been added to ns-3.6.
+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.
-Another Python-based animator is available (ns-3-pyviz) but is not
-documented.
+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' cavas 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
« no previous file with comments | « no previous file | doc/manual/figures/animation-dumbbell.pdf » ('j') | no next file with comments »

Powered by Google App Engine
RSS Feeds Recent Issues | This issue
This is Rietveld f62528b