32.1 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.

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 ();

This document was generated on April 21, 2010 using texi2html 1.82.