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 |