OLD | NEW |
1 @node Animation | 1 @node Animation |
2 @chapter Animation | 2 @chapter Animation |
3 | 3 @anchor{chap:Animation} |
4 @cartouche | 4 |
5 Placeholder chapter | 5 @menu |
6 @end cartouche | 6 * Animation interface:: |
7 | 7 * NetAnim:: |
8 This wiki page: @* | 8 @end menu |
9 @uref{http://www.nsnam.org/wiki/index.php/NetAnim,,http://www.nsnam.org/wiki/ind
ex.php/NetAnim} | 9 |
10 contains information about the animator support that has been added to ns-3.6. | 10 Animation is an important tool for network simulation. While ns-3 does· |
11 | 11 not contain a graphical animation tool, it does provide an animation interface· |
12 Another Python-based animator is available (ns-3-pyviz) but is not | 12 for use with stand-alone animators. Currently, the animation· |
13 documented. | 13 interface only supports point-to-point links; however, we hope |
| 14 to support other link types such as CSMA and wireless in the near future. |
| 15 The animation interface in ns-3 allows the generation of a custom trace· |
| 16 file to be used by an animation program. |
| 17 |
| 18 An existing stand-alone program, NetAnim, uses these custom traces to· |
| 19 graphically display the simulation. NetAnim depicts packets traveling· |
| 20 on point-to-point links as they travel from node to node. |
| 21 |
| 22 @node Animation interface |
| 23 @section Animation interface |
| 24 |
| 25 The animation interface in ns-3 currently only supports point-to-point· |
| 26 links and can generate a custom trace file for use by an animation· |
| 27 program. A snippet from a sample trace file is shown below. |
| 28 |
| 29 @verbatim |
| 30 0.0 N 0 4 5.5 |
| 31 0.0 N 1 7 5.5 |
| 32 0.0 N 2 2.5 2.90192 |
| 33 |
| 34 ... |
| 35 |
| 36 0.0 L 0 1 |
| 37 0.0 L 0 2 |
| 38 0.0 L 0 3 |
| 39 |
| 40 ... |
| 41 |
| 42 Running the simulation |
| 43 0.668926 P 11 1 0.66936 0.669926 0.67036 |
| 44 0.67036 P 1 0 0.670794 0.67136 0.671794 |
| 45 0.671794 P 0 6 0.672227 0.672794 0.673227 |
| 46 |
| 47 ... |
| 48 @end verbatim |
| 49 |
| 50 The tracefile describes where nodes and links should be placed at· |
| 51 the top of the file. Following this placement, the packet events· |
| 52 are shown. The format for node placement, link placement and· |
| 53 packet events is shown below. |
| 54 |
| 55 @itemize @bullet |
| 56 @item Node placement: <time of placement> <N for node> <node id>· |
| 57 <x position> <y position> |
| 58 @item Link placement: <time of placement> <L for link> <node1 id>· |
| 59 <node2 id> |
| 60 @item Packet events: <time of first bit tx> <P for packet>· |
| 61 <source node> <destination node>· |
| 62 <time of last bit tx>· |
| 63 <time of first bit rx>· |
| 64 <time of last bit rx> |
| 65 @end itemize |
| 66 |
| 67 To get started using the animation interface, several example scripts· |
| 68 have been provided to show proper use. These examples can be found· |
| 69 in examples/animation. The example scripts use the animation interface· |
| 70 as well as topology helpers in order to automatically place the nodes· |
| 71 and generate the custom trace. It is important to note that if a· |
| 72 topology helper is not used with its provided BoundingBox method,· |
| 73 which automatically calculates the nodes' cavas positions, the nodes· |
| 74 must be placed manually by aggregating a CanvasLocation to the node.· |
| 75 An example use of CanvasLocation can be found in any of the topology· |
| 76 helpers. Additionally, a simple example of placing a node is shown below: |
| 77 |
| 78 @verbatim |
| 79 // assuming a node container m_hub exists and· |
| 80 // contains at least one node. |
| 81 // we grab this node and associate a· |
| 82 // CanvasLocation to it, in order for the· |
| 83 // animation interface to place the node |
| 84 Ptr<Node> hub = m_hub.Get (0); |
| 85 Ptr<CanvasLocation> hubLoc = hub->GetObject<CanvasLocation> (); |
| 86 if (hubLoc == 0) |
| 87 { |
| 88 hubLoc = CreateObject<CanvasLocation> (); |
| 89 hub->AggregateObject (hubLoc); |
| 90 } |
| 91 Vector hubVec (5, 7); |
| 92 hubLoc->SetLocation (hubVec); |
| 93 @end verbatim |
| 94 |
| 95 Finally, after the simulation has been set up and the nodes have been· |
| 96 placed, the animation interface is used to start the animation, which· |
| 97 writes the custom trace file. Below is an example of how to set· |
| 98 up and start the animation interface. |
| 99 |
| 100 @verbatim |
| 101 AnimationInterface anim; |
| 102 // the animation interface can be set up to write· |
| 103 // to a socket, if a port > 0 is specified |
| 104 // see doxygen for more information |
| 105 if (port > 0) |
| 106 { |
| 107 anim.SetServerPort (port); |
| 108 } |
| 109 else if (!animFile.empty ()) |
| 110 { |
| 111 // if a file name is specified,· |
| 112 // the trace is written to the file. |
| 113 // otherwise, it is directed to stdout |
| 114 anim.SetOutputFile (animFile); |
| 115 } |
| 116 anim.StartAnimation (); |
| 117 @end verbatim |
| 118 |
| 119 @node NetAnim |
| 120 @section NetAnim |
| 121 |
| 122 NetAnim is a stand-alone program which uses the custom trace files· |
| 123 generated by the animation interface to graphically display the· |
| 124 simulation. NetAnim is based on the multi-platform· |
| 125 @uref{http://www.qtsoftware.com/products/,,Qt4 GUI toolkit}. A· |
| 126 screenshot of the NetAnim GUI is shown below. |
| 127 |
| 128 @float Figure,fig:anim-dumbbell |
| 129 @caption{NetAnim GUI with dumbbell animation.} |
| 130 @image{figures/animation-dumbbell, 4in} |
| 131 @end float |
| 132 |
| 133 The NetAnim GUI provides play, pause, and record buttons. Play and· |
| 134 pause start and stop the simulation. The record button starts a series· |
| 135 of screenshots of the animator, which are written to the directory in· |
| 136 which the trace file was run. Two slider bars also exist. The top· |
| 137 slider provides a "seek" functionality, which allows a user to skip to· |
| 138 any moment in the simulation. The bottom slider changes the granularity· |
| 139 of the time step for the animation. Finally, there is a quit button to· |
| 140 stop the simulation and quit the animator. |
| 141 |
| 142 @subsection Prerequisites |
| 143 |
| 144 The animator requires the Qt4 development packages. If you are using a· |
| 145 Debian or Ubuntu Linux distribution, you can get the following package:· |
| 146 qt4-dev-tools· |
| 147 |
| 148 This should install everything you need to compile and build NetAnim.· |
| 149 If you are using an Red Hat based distribution, look for similar qt4· |
| 150 packages (or libqt4*) and install these using yum. Mac users should· |
| 151 install the binaries: http://www.qtsoftware.com/downloads/mac-os-cpp |
| 152 |
| 153 Make sure to download the binary package; look for a link to something· |
| 154 without the word "src" or "debug" in the download filename. These will· |
| 155 be the library binaries you need. |
| 156 |
| 157 @subsection Downloading NetAnim |
| 158 |
| 159 The tarball of the source code for NetAnim is available here:· |
| 160 @uref{http://www.nsnam.org/~jpelkey3/NetAnim.tar.gz,,http://www.nsnam.org/~jpelk
ey3/NetAnim.tar.gz}.· |
| 161 Download it, then untar it:· |
| 162 |
| 163 @verbatim |
| 164 tar -xzvf NetAnim.tar.gz |
| 165 @end verbatim |
| 166 |
| 167 @subsection Building NetAnim |
| 168 |
| 169 NetAnim uses a Qt4 build tool called qmake; this is similar to the· |
| 170 configure script from autotools in that it generates the Makefile,· |
| 171 which make then uses to build the project. qmake is different on· |
| 172 different versions of Qt, so we'll provide some additional information· |
| 173 that is system dependent. You can check your default version of qmake: |
| 174 |
| 175 @verbatim |
| 176 qmake --version |
| 177 Qmake version: 1.07a (Qt 3.3.8b) |
| 178 Qmake is free software from Trolltech ASA. |
| 179 @end verbatim |
| 180 |
| 181 If you see something like the above, where it says Qt 3.x.x, find the· |
| 182 qt4 version of qmake on your system and explicitly call it instead. |
| 183 |
| 184 In general, |
| 185 |
| 186 @verbatim |
| 187 cd NetAnim |
| 188 qmake |
| 189 make |
| 190 @end verbatim |
| 191 |
| 192 On Mac OSX, |
| 193 |
| 194 @verbatim |
| 195 cd NetAnim |
| 196 /usr/local/Trolltech/Qt-4.x.y/bin/qmake |
| 197 make |
| 198 @end verbatim |
| 199 |
| 200 Note that above, the x.y is the specific version of Qt4 you are running.· |
| 201 As of April 1st 2009, the latest version is 4.5.0, although you might· |
| 202 have an older version already installed.· |
| 203 |
| 204 On Ubuntu/Debian with Qt3 AND Qt4, |
| 205 |
| 206 @verbatim |
| 207 cd NetAnim |
| 208 qmake-qt4 |
| 209 make |
| 210 @end verbatim |
OLD | NEW |