****************************************************************** * * * How to Use the AGD Server * * ========================= * * * ****************************************************************** 1. The AGD Server: ------------------ The AGD server (agd_server) is an executable program that allows to run all AGD algorithms from the command line. The program reads the input graph in GML or GraphWin format (see file graphformats.txt) from a given file and loads the corresponding options from a second file. It runs the selected algorithm and writes the result back to the input graph file. If an error occurs (e.g., if a precondition of the selected algorithm is violated) a diagnostic message is written to the input graph file. The program recognizes a special "list" parameter that prints a list of all available algorithms together with their default options. This command can be used to create an initial option file. The option file format is based on the GML format. The output of the list command for the current AGD server version (1.4) can be found in file default_server_options.gml. The main reason for developing the AGD server program was to create a file or socket interface that allows applications implemented on different platforms (,e.g., not based on LEDA or not written in C++) to use the algorithms of the AGD library. Such a client application can easily contact the AGD server by writing the graph to be drawn to a temporary file (either in GraphWin or GML format), running the AGD server with appropriate options on this file, and reading the result from the same file. The application may ask for the list of all available AGD algorithms and their options (,e.g., for building a corresponding pull-down menu) by using the list command of the server. LEDA's graph editor GraphWin uses this method to incorporate the graph drawing algorithms of AGD. 2. The GraphWin Client: ----------------------- This client for agd_server is integrated in LEDA's graph editor GraphWin. It looks for agd_server in the user's command search path and, if successful, includes a sub-menu containing the names of all available AGD algorithms into the main layout menu. Now, these algorithms can easily be applied to the current graph by clicking on the corresponding menu item. This kind of interface is very flexible. In particular, if a new AGD version is installed on the system the client automatically updates the list of algorithms and the corresponding menu of the editor. To install agd_server for GraphWin simply copy the agd_server to a directory in your command search path or set the environment variable AGD_SERVER to the complete path name of the server. 3. The Command Line: -------------------- The command line agd_server list [optfile] writes the list of AGD algorithms available in the agd_server and their default options in GML format to file optfile or the standard output stream (if optfile is missing). The command line to draw a graph using the agd_server has the following form. agd_server alg gfile optfile iform oform It reads a graph in format "iform" from file "gfile", applies algorithm "alg" to it using the options from file "optfile", and writes the result in format "oform" back to gfile. There are two possible file formats for iform and oform: "gw" for the GraphWin file format (see Section 6) and "gml" for the GML format (see Section 7). A default options file can be created by calling "agd_server list optfile" (see above) and edited as needed (see Section 5). Example: Let "graph.gw" contain the graph we want to draw using the agd_server in GraphWin file format. Suppose we want to use the Sugiyama algorithm with the options in the standard options file optfile. Then the corresponding command line looks as follows. agd_server Sugiyama graph.gw optfile gw gw If everything worked correctly the file "graph.gw" contains the resulting layout of our input graph. If an error occured a diagnostic message is written to the file "graph.gw" . 4. Algorithms: -------------- Currently the following algorithms are available in the AGD Server and can be used as parameter "alg". "de Fraysseix et al." Schnyder Convex ConvexDraw PlanarStraight PlanarDraw Mixed-Model PureOrthogonal QuasiOrthogonalLayout OrthogonalLayout TreeLayout Sugiyama Planarization "Spring Embedder" Tutte "Visibility Representation" To use the algorithm "de Fraysseix et al." on the graph graph.gml in GML Format with the options file "optfile" write: agd_server "de Fraysseix et al." graph.gml optfile gml gml 5. The Options File: -------------------- The command agd_server list optfile generates an initial options file optfile. The contents of this file (for the current version of agd_server) can be found in the AGD manual. The file is in GML format. An input in GML format is a list of GML objects. Each object consists of a key word and a value. A value may have one out of four possible types, an integer, a double, a string, or a list of GML objects. Since a value can be a list of objects, we get a tree structure on the input. Lists of GML objects start with [ and end with ]. The options file for the AGD server consists of four GML objects: * Creator with string value "AGD_SERVER" * Version with double value 1.4 * AGD_function_list with a list of available algorithms (cf. Section 4) * AGD_option_list with a list of available options for each algorithm and the corresponding standard values A detailed description of the various options of the algorithms can be found in the corresponding AGD manual page. To change an option for a layout algorithm do the following: i) Find the algorithm in AGD_option_list ii) Find the option you want to modify iii) Change the option to the desired value with an ordinary text editor. Example: Suppose you want to use the Sugiyama algorithm with DFS ranking, Greedy Insert, node_distance 5.0, and level distance 7.0. The corresponding part of the standard options file looks as follows: ... function "Sugiyama" [ ranking [ ranking_wahl 0 ranking_lst [ lst "Hierarchical" lst "DFS" ] ] heuristic [ heuristic_wahl 0 heuristic_lst [ lst "Split" lst "Barycenter" lst "Median" lst "Greedy Insert" lst "Greedy Switch" ] ] fixed_level_distance "false" node_distance 3.00000 level_distance 3.00000 work_infos "false" infos [ name: "Sugiyama" author: "K. Sugiyama, S. Tagawa, M. Toda" Implementation: "C. Gutwenger, M. Krger" date: "March 1998" version: "2.0" ] ] ... To use your parameters you simply change that part to: function "Sugiyama" [ ranking [ ranking_wahl 1 ranking_lst [ lst "Hierarchical" lst "DFS" ] ] heuristic [ heuristic_wahl 3 heuristic_lst [ lst "Split" lst "Barycenter" lst "Median" lst "Greedy Insert" lst "Greedy Switch" ] ] fixed_level_distance "false" node_distance 5.00000 level_distance 7.00000 work_infos "false" infos [ name: "Sugiyama" author: "K. Sugiyama, S. Tagawa, M. Toda" Implementation: "C. Gutwenger, M. Krger" date: "March 1998" version: "2.0" ] ]