Description of the Grav File Format

Overview

The Grav file format is a simple, text-based and line-oriented format. Each line consists of one command that begins a new graph or specifies a new node or arc in the graph.

Each command can be followed by one or more arguments (depending on the command) that specify additional attributes. The arguments must be separated by one or more whitespace characters.

File Extension

Grav files should end with the extension grav, grav.gz, grav.bz2 or grav.xz. The latter three files are compressed using the corresponding compression tool. In order for GraView to be able to read compressed files the appropriate ruby packages (gems) or the corresponding command line tools must be available.

Comments

A sharp character # introduces a comment until the end of the line. Comments as well as empty lines are ignored.

Supported Commands

Command are described in the following form:

command required [optional] ...

where command is the name of the command, required is a required argument and [optional] an optional argument. Attributes are often specified in the form key:value. Note that there must not be a space before or after the colon (which would be interpreted as attribute separator).

The following commands are supported:

1. newgraph name

   Adds a new graph with the given name. The graph starts with no nodes and arcs.

2. addgraph name

   Adds a new graph with the given name. The graph starts with all arcs and nodes contained in the previous graph. This command is great to construct an increasing sequence of graphs.

3. end

   Marks the end of a graph. This command must be the last after the sequence of nodes and arcs describing a graph and must not be omitted.

4. node id [x:NUMBER] [y:NUMBER] [weight:NUMBER] [color:R,G,B[,A]] [circ] [disc] [desc:NUMBER]

   • id is the (unique) number of the node
   • x specifies the x-coordinate where the node should be drawn
   • y specifies the y-coordinate where the node should be drawn
   • weight is the weight of the node (an arbitrary numeric attribute of the node)
   • color is color of the node given as three number between 0 and 255 for red, green and blue and an optional alpha value between 0 and 1. Note that there must not be any spaces before or after the commas
   • circ the node should be drawn as a cricle (with empty filling)
   • disc the node should be drawn as a filled circle
   • desc an additional dictionary of description strings follows this node command. The specified number is the size of the description in number of bytes (the first byte being the first character on the next line). The dictionary is specified as sequence of lines. The odd lines are the keys, the even lines the value corresponding to the key of the preceding line.

5. arc srcid snkid [flow:NUMBER] [cost:NUMBER] [color:R,G,B[,A]] [desc:NUMBER]
edge srcid snkid [flow:NUMBER] [cost:NUMBER] [color:R,G,B[,A]] [desc:NUMBER]

   The command arc denotes a directed arc (with arrow head), the command edge an undirected arc. Note that also in the case of undirected arcs, the edge (u,v) is different from the edge (v,u).

   • srcid is the id of the source node
   • snkid is the id of the sink node
   • flow a number describing the flow over this arc
   • cost a cost coefficient of the arc
   • color the color of the arc in the same format as for nodes
   • desc an additional description in the same format as for nodes

   Warning: source and sink nodes must be specified before the arc connecting them.

Default Attributes

If the commands node and arc are specified without the node id/srcid and snkid then specified attributes become default values for subsequent node and arc commands.