java -jar PlanetlabDesktop.jar
When the program is running, there is a list of views at the top of the window. You can choose to look at any view by selecting it from the list and clicking the "Update image" button. The button will become disabled while the program is creating the map. After it has finished, it will display the map in a new window. If the map contains any nodes, move the mouse over a node to see what city it's in. If you click on a node, the program will attempt to contact that node and, if it is successful, a window containing the node's properties will appear. The map window also gives you the option of saving the map to disk in JPEG format.
The other main feature of PlanetlabDesktop is the ability to customize existing views without touching the view files. This allows the user to experiment with different drawing parameters and even make changes to a Sophia query (see the View files section). To customize a view, choose a view from the list and click the "Customize view" button. A customization window opens with four tabs and a custom view is added to the dropdown list in the main window. There can only be one customized view at a time, so customizing another view will replace the previous customized view.
The first tab in the customization window allows the user to modify parts of the node and edge queries. You can fill in the blanks on the left with values according to the description on the right. Each blank starts out containing its default value, which is used if you don't change it.
The second and third tabs allow you to change the colors and sizes of the nodes and edges on the map. Again, the view file can provide default values, but you're free to modify them. If a view does not contain nodes or edges, the corresponding tabs will be disabled. The left list in the customization window contains ranges that specify colors and the right list contains ranges that specify sizes. Use the add, edit, and remove buttons to create as many ranges as you like. Each range specifies a range of weights, which are gathered from the queries (or data), and assigns a color or size to it. The color ranges and the size ranges might not refer to the same property of the nodes or edges. In parentheses above each list of ranges there should be a short description of what property of the nodes or edges that range corresponds to. There will not be a short description if the view file does not specify one. Read the View files section for more information.
The fourth tab gives you information about the view that you're customizing, including the queries, image parameters, and description.
PlanetlabDesktop allows you to automatically update the image with the checkbox in the main window.
The program writes the description of the image to standard out in the following format: if an error occurs, only the error is printed. Otherwise, the string "success" is printed on the first line, the image file to use is printed on the second line, the map description is printed on the lines following, then the string "drawing_start" on its own line, then one line for each node or edge to be drawn. A line for a node looks like this:
node red green blue size id cityName x-coord y-coord
and a line for an edge looks like this:
edge red green blue size x-coord1 y-coord1 x-coord2 y-coord2
To generate the map, planetlabMap.php executes generateMap.php. generateMap.php uses session variables set by planetlabMap.php to obtain the information necessary for generating the map. If you click on a node on the map, planetlabMap.php runs nodeInfo.php, which in turn executes PlanetlabNode and displays the node's properties in a new window.
A view file is split up into several sections, each of which is described in detail below. A section in a view file starts when the name of that section is on a line by itself. The sections are description, node_query, node_data, edge_query, edge_data, node_parameters, edge_parameters, and image_parameters. The sections can appear in any order. Any line in a view file beginning with the character "#" is a comment and is ignored. Whitespace at the beginning and end of lines is also ignored. View files must have the suffix ".in" and must be in the provided views directory to be usable in the GUI programs (PlanetlabDesktop and PlanetlabDisplayWall). There are plenty of examples of view files included with the PlanetLab Visualizer software.
It's useful to include a color and size key in the description section. The colors and sizes of nodes and edges can represent different properties of the PlanetLab network, so the description should describe how to interpret the map. The description section is optional.
The node_query section begins when the string "node_query" appears on a line by itself and ends when another section begins. Every line in the node query section is either a part of the query, specifies node query variables, or specifies the timeout value.
If a line begins with the string "timeout:" then the number following the colon is used as the timeout value for this query. If multiple timeout values are specified, the the last on that appears in the node_query section is used as the timeout value for the query. A timeout value for the node_query is the number of seconds that the visualizer will wait for the data to be returned from Sophia before giving up and not drawing any nodes. A default of 30 seconds is used if no value is specified.
Any line beginning with a "$" and then a number declared a variable in a query. A variable in a query is the part of a query that can be customized through PlanetlabDesktop by users. Variables are declared by specifying three arguments. The first is the variable name and is a dollar sign followed by a whole number. Two variables cannot share a name. The following two arguments specify the default value of the variable and the variable description. Arguments containing whitespace must be enclosed in quotes.
Here are a few examples of query variables:
$1 4 "Load upper boundary" means that the variable $1 starts out with the value of "4" and "Load upper boundary" describes the variable.
$2 "Princeton Node" nodename means that the variable $2 starts out with the value of "Princeton Node" and "nodename" describes the variable.
The general format for specifying variables is $number default_value variable_description
All of the lines not beginning with a "$" or a "timeout:" in the node_query section are appended together to form the query itself.
The query is a Prolog command (or group of commands) that is sent to Sophia to retrieve node data. Sophia sensors and specifications are on the Sophia sensors site.
In order for a valid map to be drawn, the Sophia node_query must return data as a set of node ids, latitudes, longitudes, color weights, and size weights. Color weights and size weights are values that will be used in node_parameters to determine the node's color and size, respectively. For example, the query:
eval(setof([Node, Lat, Long, Load, Uptime], (node(Node), eval(position(node(Node), latitude(Lat), longitude(Long))), eval(node(Node), load(Load)), eval(node(Node), uptime(Uptime))), Vs)).
will return a set of nodes, latitudes, longitudes, loads (to be used as the weights for the color parameters), and uptimes (to be used as weights for size parameters).
Both color and size weights must be numerical data, such that the data are able to be used in specifying ranges (see the node_parameters section). Thus, it is not valid for either of those fields to take on values as iphost or update, while querying for data like localtime or iplatency is perfectly valid.
For help on constructing Sophia queries, visit the Sophia sample queries site.
Also, variables can appear in the query section. For example the variable $20 0 "Lower bound on uptime" could appear in the Prolog query as follows:
eval(setof([Node, Lat, Long, Load, Uptime], (node(Node), eval(position(node(Node), latitude(Lat), longitude(Long))), eval(node(Node), load(Load)), eval(node(Node), uptime(Uptime)), Uptime > $20), Vs)).
When sent to Sophia, the $20 is replaced by the default value, 0, or by the value customized by the users in PlanetlabDesktop.
If a view file contains this section, it cannot contain a node_data section. If a view file contains a node_data section, then it cannot contain the node_query section.
This section can also contain a timeout value and variables like the node_query section.
If a view file contains this section, it cannot contain an edge_data section. If a view file contains an edge_data section, then it cannot contain the edge_query section.
Data in this section can appear in two formats. The first is a result from a valid Sophia node query. Saved results from Sophia queries can be pasted into the node_data section.
If the node data are not obtained from Sophia, then they are to appear in the following format:
[[node1 id, node1 latitude, node1 longitude, node1 color weight, node1 size weight], [node2 id, node2 latitude, node2 longitude, node2 color weight, node2 size weight], ..., [noden id, noden latitude, noden longitude, noden color weight, noden size weight]].
Both color and size weights must be numerical data, such that the data are able to be used in specifying ranges (see node_parameters).
If a view file contains this section, it cannot contain a node_query section. If a view file contains a node_query section, then it cannot contain the node_data section.
[[edge1 begin latitude, edge1 begin longitude, edge1 end latitude, edge1 end longitude, edge1 color weight, edge1 size weight], [edge2 begin latitude, edge2 begin longitude, edge2 end latitude, edge2 end longitude, edge2 color weight, edge2 size weight], ..., [edgen begin latitude, edgen begin longitude, edgen end latitude, edgen end longitude, edgen color weight, edgen size weight]].
If a view file contains this section, it cannot contain an edge_query section. If a view file contains a edge_query section, then it cannot contain the edge_data section.
(lower_bound, upper_bound, color)
That line is translated into English as "draw all nodes with a color weight greater than or equal to lower_bound and less than upper_bound with the color color." The color must be in the standard RGB hex format, and must be represented by six hexadecimal digits. The lower bound, instead of being a number, can be the string "infinity" to represent negative infinity. Likewise, the string "infinity" for the upper_bound represents positive infinity. For example, the line
(infinity, 10.5, ff0000)
means "all nodes with a color weight between negative infinity and 10.5 should be drawn red."
The color subsection can contain an arbitrary number of color ranges. It can also contain a line that specifies how to draw nodes with "invalid" color weights (meaning that Sophia could not retrieve the requested value from a node) with the line
invalid: color
To specify what color all other nodes should be drawn, use the line
else: color
If there is no else line, any node that has a color weight that does not fit into any of the ranges will not be drawn.
You can also specify what the color is describing at the beginning of the color section by putting a description right after the word "color" that begins this section. For example, "color load" means that the colors represent the loads. This description appears in the PlanetlabDesktop customizer.
The size subsection (which begins with the string "size" on its own line, along with an optional description) works exactly the same way as the color subsection except that it specifies the size of the nodes instead of the color. The syntax is exactly the same except that the colors are replaced by positive integer sizes.
image_name: name
image_size: (width, height)
latitude_range: (lower, upper)
longitude_range: (lower, upper)
where the image name is the path to the JPEG image relative to the view file, image size is the size of that image, latitudes can range from -90 to 90, and longitudes can range from -180 to 180.
The node input file can also contain the line
timeout: seconds
to change the timeout time from the default of 10 seconds. If the timeout value is exceeded while querying for any one property in the file, PlanetlabNode and PlanetlabDesktop will report an error.
latitude longitude cityname
where latitudes range from -90 to 90, latitudes range from -180 to 180, and the city name may contain whitespace characters. The supplied city input file, called cityinputfile, contains over 35,000 cities around the world and probably does not have to be modified unless a more exact location for a node needs to be added.
The source code for all PlanetLab Visualizer classes is available through the main PlanetLab Visualizer page, and is included with the software.
DataGatherer - The DataGatherer class serves as a connection to Sophia. Its methods allow the client to send queries to Sophia and to retrieve the results. A query must be set before it is executed and a query must be executed before its result can be seen.
DisplayRanges - The DisplayRanges class contains ranges that specify how nodes and edges are drawn on the map. The ranges specify boundary values that define a numerical range. They can also specify how to draw invalid map components and map components that don't fit into any of the other ranges.
DrawingParameters - The DrawingParameters class contains information on how to draw a component on the map, independent of the nodes and edges themselves. It contains ranges for specifying the colors and sizes of the components.
GenerateMap - The abstract class GenerateMap generates a map according to the specifications implemented the methods of its subclasses, which define how to create the map and the nodes and edges on it.
ImageParameters - The ImageParameters class contains information about the map image on which to draw nodes and edges. This includes its size, file location, and the latitude and longitude ranges that the map spans.
InputFileParser - The InputFileParser class parses the view file used by the Visualizer class and provides methods for extracting the sections of the file.
Map - The Map class stores a collection of nodes and edges representing properties of the PlanetLab network. This class contains methods that receive information from the DataGatherer and store it as nodes and edges.
QueryDescription - The QueryDescription class parses the view file query given to it by the InputFileParser and provides methods for extracting the query sections of the file.
Visualizer - The Visualizer class reads in a view file and runs the GenerateMap that is passed to it in order to create the map object.
Second, the PlanetLab Visualizer might in the future display the data with the image, so that users would not have to click on individual nodes to see their properties, but would be able to see the queried properties while dragging the mouse over the nodes, just like they do with the city names.
Third, PlanetlabDisplayWall currently uses a PHP layer to create the images. It would be a better implementation to do this entirely through a Java program, as is done in PlanetlabDesktop. Unfortunately, since the Java Virtual Machine only allocates 64 MB to the program when it runs, there is not enough memory to uncompress and manipulate the 6000 by 3000 pixel image files. To circumvent this problem, PlanetlabDisplayWall executes a PHP script called planetlabDisplayWall.php to update the image. This program, in turn, runs PlanetlabDescription and uses its output to generate the image and write it to disk with the name planetlab.jpg. PlanetlabDisplayWall then executes three commands on the display wall control computer to put the image on the wall:
invalidate wall-24 current_directory\planetlab.jpg
index current_directory\planetlab.jpg
imgctrl draw wall-24 current_directory\planetlab.jpg 0 0 0 0 0 0
The first command clears the wall's cache so it doesn't remember the previous version of planetlab.jpg. The second command looks at the image so that the control computer can send the image to the display wall more efficiently. The third command displays the image on the wall.
There is probably a way to increase the memory allocated to PlanetlabDisplayWall, thus making it possible to bypass the PHP layer.
Because the program must execute the mentioned commands specific to the display wall, obviously these commands cannot change. If the interface commands to the display wall change, the commands in PlanetlabDisplayWall.java must reflect the change.
Fourth, the website might also want to completely bypass PHP by eventually switching to JSP. Currently the PHP layer must generate the image to prevent writing an image to disk. A JSP layer could create the image in memory using the PlanetLab Visualizer tools and place it directly into the page.