Difference between revisions of "Aqua-3D dev manual"

Revision as of 14:25, 29 September 2017

Getting Started

Installation

Please see installation steps here: Installation

Running the program

Aqua3D can be started in two ways: by double-clicking on the aqua3d executable in the installation folder or by entering ./aqua3d in the console. If run from the console, there are three additional options for the program:

• -h or --help: show help options
• -v or --verbose: print verbose output to the log file
• -t <.nam trace file name> or --trace=<.nam trace file name>: immediately load the specified file on program startup
• -p or --path: load all transmission path lines immediately (option for loading a trace file, see Aqua-3D dev manual#Trace_file_load_options)
  • only applies if a trace file is also being loaded with -t
• -a of --annotation: load all annotation events immediately (option for loading a trace file, see Aqua-3D dev manual#Trace_file_load_options)
  • only applies if a trace file is also being loaded with -t

For example, the command ./aqua3d -v -t vbva.nam starts Aqua3D in verbose mode and loads the file vbva.nam immediately on startup.

Loading a file

Trace files can be loaded 2 ways:

• If running from the console, a trace file (and options) can be loaded as described above
• If started from the console only as ./aqua3d or by double-clicking on the executable, a trace file can be loaded by using one of the two methods in the File section of the top menu
  • Open Trace File (no options): immediately displays the usual file selection dialog window so a file can be chosen and loaded
    • no options are used with this method (path or annotation, see Aqua-3D dev manual#Trace_file_load_options)
  • Open Trace File (with options): opens a window that has a button to open the file selection dialog window as well as check boxes for the user to select the options with which to open the file (path or annotation, see Aqua-3D dev manual#Trace_file_load_options)

Trace file load options

A trace file can currently be loaded with the following two options:

• Load all transmission paths: Aqua3D draws the transmission paths for every hop (transmission) event that takes place, which essentially draws the network layout (see Media:General.png, the gray lines between the nodes). Normally, these lines are drawn as the hop events take place, but if this option is enabled, Aqua3D will go through the entire trace file before actually loading everything else and analyze all the hop events to get the information with which to draw all the paths immediately. The program will then start and run as usual.
• Load all annotation events: Annotation events mark specific spots in the simulation that are of particular interest to the user. They are placed in a list on the right side (see Aqua-3D_manual#Information_Window), and when the user double-clicks on one of the lines in that list, Aqua3D will "jump" to that point in the animation. So, when the user next clicks "play", the animation will start from there. These events are typically loaded like all the other events, which means users cannot see events far in the future of the simulation (see Aqua-3D#Architecture_and_Implementation). If this option is enabled, Aqua3D will go through the entire trace file (like when loading all the paths) and analyze all the annotation events to get their information and add them to the list. This way, users can see all of the annotation events immediately and be able to jump to any point of the animation right away.

Example trace files can be downloaded here. Simply load the files as described above.

Trace File Format

The file extension .nam refers to the fact that Aqua3D was originally based on the Network AniMator (NAM), which uses files with the same format. They are generated by Aqua-Sim during a simulation and include lines that initialize the network environment, such as the dimensions of the simulation space and the positions of the nodes, and of course, lines that specify the network events, such as signal transmission events. In general, a line in the trace file has the form:

<event type flag> -t <time> <other flags and attributes>

• <event type flag>: specifies what kind of network event the line represents.
• <time>: the point in the animation time that the event takes place, which is when the event‟s animation begins.

If the <time> value is a *, that means the line is an initialization line that is part of the initial setup of the environment when the trace file is first loaded. The majority of the initialization lines specify a node in the simulation, giving it its name, position, size, shape, and color. Another required initialization line specifies the dimensions of the environment. There are other initialization lines in the trace files but those have not yet been implemented in the program.
The following lines are required for the trace file to work in Aqua3D:

• Node initialization: n -t * -s <src node ID> -x <x-position> -y <y-position> -Z <z-position> -z <size> -v <shape> -c <color>
• World initialization: W -t * -x <environment width> -y <environment height> -z <environment depth>
  • -z <environment depth> is optional. Aqua3D will use the largest dimension as the depth if none is specified

The lines following the initialization lines specify the actual network events that took place in the simulation.
The following event types and flags are currently supported:

• Signal hop (transmission): h -t -s <src> -d <dest> -p <protocol/packet type> -e <packet size> -c <unused> -a <unused> -i <unused> -k <protocol/packet layer> -R <transmission range>
  • If <dest> is -1, that means the transmission is a broadcast
• Signal receive: r -t <time> -s <src> -d <dest> -p <protocol/packet type> -e <packet size> -c <unused> -a <unused> -i <unused> -k <protocol/packet layer> -R <transmission range>
• Packet enqueue: + -t <time> -s <src> -d <dest> -p <protocol/packet type> -e <packet size> -c <unused> -a <unused> -i <unused> -k <protocol/packet layer>
• Packet dequeue: - -t <time> -s <src> -d <dest> -p <protocol/packet type> -e <packet size> -c <unused> -a <unused> -i <unused> -k <protocol/packet layer>
• Packet drop: d -t <time> -s <src> -d <dest> -p <protocol/packet type> -e <packet size> -c <unused> -a <unused> -i <unused> -k <protocol/packet layer>
• Annotation: v -t <time> -e <annotation details>

More events may be added in future releases of Aqua3D.

Please refer to the following pages for more details on the meaning of the flags and their attributes:

• http://nsnam.isi.edu/nsnam/index.php/NS-2_Trace_Formats#NAM_Trace_Formats
• http://www.cubinlab.ee.unimelb.edu.au/~jrid/Docs/Manuel-NS2/node514.html
• http://isi.edu/nsnam/ns/doc-stable/node227.html

GUI Layout and Controls

General

The layout of Aqua3D's graphical user interface can be seen above.

• At the top of the GUI are the controls to play/pause the animation, a window displaying the current time of the animation, and controls to alter the speed of the animation. (see Aqua-3D_manual#Playback_Control)
• On the left side are the camera controls, which allow the user to zoom, rotate, and pan the camera as well as buttons to toggle the visibility of certain network elements like the grid lines and labels. (see Aqua-3D_manual#Camera_Controls)
• In the center of the GUI is the window displaying the visualization of the UWSN and its events.
• On the right are a number of selectable windows with details about the environment and its events. (see Aqua-3D_manual#Information_Window)

NOTE: Most of the menu options and GUI are disabled when no trace file is loaded.

Top Menu

The top menu bar currently contains the following options:

• File
  • Open Trace File (no options): see Aqua-3D dev manual#Loading_a_file
  • Open Trace File (with options): see Aqua-3D dev manual#Loading_a_file
  • Close Trace File: close the current trace file, clearing the animation and 3D environment and disabling all the environment-related GUI controls and menu options
  • Quit: exit the program
• Edit
  • Preferences: see Aqua-3D dev manual#Preferences
• View
  • Load View Settings: see Aqua-3D dev manual#Load_and_Save_View_Settings
  • Save View Settings: see Aqua-3D dev manual#Load_and_Save_View_Settings
  • Camera: change the camera angle to one of six predetermined angles to view the environment from the front, back, top, bottom, left, or right
  • Toggle: toggles various environment elements on or off (does all the same things as the buttons in the Camera Control panel (see [[Aqua-3D dev manual#Camera_Controls])
  • Reset All: resets all the camera and toggle settings to their default values
• Trace File
  • View File Details: see the file path, file name, and size of the currently loaded trace file (future plan is to include more information)
• Help
  • About: view the credits, license, and other information about the program

Playback Controls

The playback controls allow the user to pause and play the animation, view the current time progression of the animation (as well as allow the user to specify a certain time of the animation to jump to), and adjust the speed of the animation‟s time progression.

• Pause/Play button: pressing the button while the animation is currently paused will cause it to play. Pressing it again while the animation is playing will pause it
• Loop playback check box: normally, the animation will stop once it has reached the end. Checking this will cause the program to instead start the animation over from the beginning when it reaches the end
• Animation time display (time window and timeline): displays the current time progress of the animation. Clicking into the display window or the timeline will pause the animation and allow the user to specify a time in the animation to jump to (either by entering it directly into the display window, or clicking-and-dragging the timeline bar). Pressing the Play button will resume the animation at the new user specified time. The * button next to the timeline resets the animation time to the beginning (0.000000)
• Time step controls: controls the speed of the animation by adjusting its frame rate. The minimum is 1 frame/second while the maximum is 200 frames/sec. The value can either be set directly by clicking into the time step display window and typing in a new value, or by using the up (increase) and down (decrease) arrows next to the window. The * button next to the window resets the time step value to its default (20 frames/sec)
  • Do not set the frame rate too high if using a weaker machine (see Aqua-3D_manual#Warnings)

Camera Controls

The camera and toggle controls allow the user to alter their view of the environment so that they can center the camera on desired points of interest or view the animation from different angles. The user can also turn on and off various environment elements to customize their view of the 3D rendering.

• Camera Zoom: zooms the camera in and out to view the environment up close or from farther away. The * button resets the zoom to its default value
• Camera Rotate: rotates the camera around the environment to view it from different angles. The * button resets the rotation to its default value
• Camera Pan: pans the camera to center different parts of the environment on the screen. The * button resets the pan to its default value
• Toggle: toggles various elements on and off so that the user can customize their view of the environment. The elements are:
  • Surface Polygon (S): the blue (by default) rectangle at the top of the environment that represents the ocean surface
  • Floor Polygon (F): the brown (by default) rectangle at the bottom of the environment that represents the ocean floor
  • Origin Marker (O): the black marker showing where the environment origin (0, 0, 0) is located
  • Labels (L): the text labeling the axes of the origin marker (-x, +y, etc) as well as showing the names of the nodes in the environment
  • Paths (P): the transmission path lines between the nodes
  • Grid lines (G): cycles the grid lines between showing: (no lines, all lines, lines along x-axis only, along y-axis only, and along z-axis only)
• Reset All: restores all the camera and toggle settings to their default values

Environment Viewing Window

The environment viewing window displays the 3D rendering of the environment and the network event animations.

• If the mouse is over this window:
  • The scroll wheel can be used to zoom the camera in and out
  • Left-clicking-and-dragging can be used to rotate the camera
  • Right-clicking-and-dragging can be used to pan the camera
• The vertical bar separating this window from the Information window to its right is movable, allowing the user to control the size of both windows. Moving the bar to the right will expand the Environment Viewing window.

Information Window

The information window allows the user to see various sets of information related to the environment and its network events.

• The vertical bar separating this window from the Environment Viewing window to its left is movable, allowing the user to control the size of both windows. Moving the bar to the left will expand the Information window
• There are currently four information windows that are selectable by a drop down menu at the top of the panel:
  • Annotation List: displays a list of the previously encountered annotated event lines from the trace file. The user can double-click on one of the annotated events in the list to jump the animation back to that point in the file and resume animating from there
  • Event List: displays a list of events that have already been encountered as well as the next set of events that will be animated. This DOES NOT display all the events in the trace file (as loading all the events will take up a lot of memory, especially if the trace file is large). Annotated events are shown in red
  • Node Details: displays a list of all the nodes in the environment. When the user clicks on a node's name, a wireframe cube is drawn around the corresponding node in the Environment Viewing window, and if set in the Preferences, will show only that node's transmission paths. The user can click on the little triangle next to the node's name, or double-click on the node's name itself, to expand that node's branch to view addition information. The [+] button at the top of the window expands all the nodes' branches, while the [-] button at the top collapses all the nodes‟ branches. The [X] button deselects the currently selected node, removing the wireframe box from around the node in the Environment Viewing window
  • Environment Details: shows the details about the environment and animation, which currently only includes the x/y/z dimensions of the environment and the ending time of the animation

Other Controls

Preferences

There are a number of preference options available to customize the program. The preference settings are saved in an external file so that they are persistent after the program is closed and restarted. There are four main tabs in the preference window:

• Camera: adjust settings related to the camera
  • Adjust Camera Movement: change the amount that the camera zooms, rotates, and pans with each button click (affects the camera GUI controls only)
  • Invert Movement Axes: changes the direction that the camera rotates and pans when pressing one of the buttons. This essentially makes it so that it seems the controls are either moving the camera (and keeping the environment stationary) or that the controls are manipulating the environment itself (and keeping the camera stationary)
  • Choose Viewing Angle: allows the user to select the viewing angle:
    • Perspectice: 50 degree perspective angle where farther objects are smaller. This shows a true 3D view of the environment
    • Orthographic: a "flat" viewing angle where everything is the same size. This essentially shows a 2D view of the environment (there are issues with this, see Aqua-3D_manual#Warnings)
• Environment: adjust settings related to the setup of various environment elements
  • Specify Origin (0,0,0) Location: positions the origin in three predetermined locations depending on the coordinate ranges of the nodes‟ positions:
    • Surface: the origin marker is located at the “surface of the water” in the middle of the surface polygon. With this, the x- and y-coordinates of the nodes can be positive or negative while the z-axis is strictly negative (or strictly positive if the z-axis is inverted, see below)
    • Center: the origin marker is located in the exact center of the environment. With this, the x-, y-, and z-coordinates of the nodes can be positive or negative
    • Corner: the origin marker is located in the “lower-left-back corner” of the environment. Here, the x- and y-coordinates are strictly positive and the z-coordinate is strictly positive (or strictly negative if the z-axis is inverted)
  • Invert Z-Axis: by default, negative on the z-axis points down. Just in case there are trace files that have strictly positive z-coordinates, such as if the origin is on the surface (see above), setting this makes it so positive on the z-axis points down
  • Adjust Grid Spacing: adjust the amount of space between the grid lines, which also affects the number of grid lines that are drawn overall
• Animation: adjust settings related to the animation
  • Toggle Event Animations: allows the user to turn specific network event animations on or off, so that animation of no interest to the current user can be hidden
  • Toggle Transmission Paths: allows the user to customize the visibility and appearance of the transmission paths
    • Broadcast Transmission Paths: show/hide broadcast paths
    • Unicast Transmission Paths: show/hide unicast paths
    • Transmission Path Arrow Heads: show/hide the arrow heads of the paths (which indicate transmission direction)
    • Color Transmission Path Arrow Heads: if checked, arrow heads will be colored with the same color as its source node
    • Show Only Selected Node's Path: if checked, selecting a node in the Information Window's Node Details page will show only that selected node's transmission paths and hide all other paths
• Colors: adjust settings related to the colors of various environment elements
  • Adjust Environment Colors: allows the user to customize the colors of the surface polygon, floor polygon, and environment background
• Every page has a button to restore the settings to their default values

There are three buttons at the bottom of the preference window:

• Cancel: closes the window without saving any changes
• Apply: saves the current settings without closing the window
• Save: saves the current settings and closes the window

Load and Save View Settings

If a "perfect" view of the environment has been set (using the camera zoom, camera rotation, camera pan, and toggle settings), these menu options will save and load those settings to an external file so that they can be easily restored later

• View->Load View Settings: opens a file selection dialog window for the user to load an external .view file to restore a previously saved view setting
• View->Save View Settings: opens a file save dialog window for the user to save the current view settings to an external .view file

Warnings

• With very large .nam files:
  • It will take a long time to initially load the file if either the path or annotation options are used, because it has to go through the entire file to read and load all the relevant events
  • It will take a long time to reload and update the events when a time very late into the animation is selected, since the program needs to start at the beginning and go through the entire file to update everything correctly up to the selected time
• There are some issues with orthographic viewing, as the glOrtho() function skews how the environment is drawn. So, using this is currently not recommended
• On weaker machines, increasing the frame rate too high may cause the program to become unresponsive

KNOWN ISSUES

• The following may occur when trying to use Aqua3D on Ubuntu 9.04, 9.10, or 10.04 on a virtual machine such as VMWare
• Aqua3D was developed on a machine running Ubuntu 10.04 and it was installed and run successfully on another machine with Ubuntu 10.04, so these problems may be related to virtual machines specifically
• Please contact the developer at <CONTACT INFO HERE> to report:
  • Problems encountered when trying to install/run Aqua3D
  • If you encountered a problem but figured out the solution for it
  • Solutions to the two issues below

X Window System error

• Those versions of Ubuntu may require nvidia-current or nvidia-glx-<version_number> drivers to be installed for Aqua3D to run correctly
  • Otherwise, a segmentation fault will occur when attempting to loading a .nam file
• After installing the nvidia drivers, running Aqua3D with ./aqua3d and loading a trace file with the file selection window will work
• HOWEVER, running Aqua3D with ./aqua3d -t <trace_file_name> may give the following error and terminate:
  • Note: There is CURRENTLY NO FIX FOR THE PROBLEM BELOW

The program 'aqua3d' received an X Window System error.
This probably reflects a bug in the program.
The error was 'BadMatch (invalid parameter attributes)'.
  (Details: serial 3534 error_code 8 request_code 66 minor_code 0)
  (Note to programmers: normally, X errors are reported asynchronously;
   that is, you will receive the error a while after causing it.
   To debug your program, run it with the --sync command line
   option to change this behavior. You can then get a meaningful
   backtrace from your debugger if you break on the gdk_x_error() function.)

• Using ./aqua3d and opening trace files with the file selection window should suffice

extension "GLX" missing on display

• If it was necessary to install the nvidia-current or nvidia-glx-<version_number> drivers, Aqua3D should work (but with the X Window System error issue above
• HOWEVER, once the X Server is restarted (either by restarting the machine or using Ctrl+Alt+Backspace), running Aqua3D with either ./aqua3d or ./aqua3d -t <trace_file_name> will give the following error and terminate
  • Note: There is CURRENTLY NO FIX FOR THE PROBLEM BELOW

Xlib:  extension "GLX" missing on display ":0.0".
freeglut: OpenGL GLX extension not supported by display ':0.0'

• There are two workarounds:
  1. Run Aqua3D in a virtual machine with Fedora 14, Debian 5, or Ubuntu 10.10 installed
  2. remove/reinstall the nvidia driver:
     1. uninstall/remove nvidia-current or nvidia-glx-<version_number> driver
     2. restart computer (or just restart X Server with Ctrl-Alt-Backspace)
     3. reinstall nvidia-current or nvidia-glx-<version_number> driver
     4. Try running Aqua3d again. It should work
        • You will need to use ./aqua3d to start the program (as ./aqua3d -t <trace_file_name> will not work due to X Window System error issue above)