Documentation Open Graph Markup Language (OGML)

Transcription

1 Documentation Open Graph Markup Language (OGML) Version: July 10, 2012 Fakultät für Informatik Algorithm Engineering (Ls11) Technische Universität Dortmund

2 2

3 Contents 1 Introduction 5 2 Design and Design Goals 7 3 Specication Structure Node Edge Layout Node styling Edge styling Ports Examples 17 3

4 4 Contents

5 Chapter 1 Introduction OGML, the Open Graph Markup Language, is an XML based le format for the storage of graphs and their associated data. It is tailored towards the use for graph drawing, i.e. for the specication of data needed for the visualization of graphs and networks, and designed to be both exible and human readable. Development and specication of OGML was started within the OGDF project [1], but OGML is an independent open language that is not restricted for use with or within the Open Graph Drawing Framework. Much of the data needed for graph drawing, e.g. layout information, is modelled explicitly by corresponding language elements, but there are also means to store additional extensions or unspecied data associated with graph elements. This allows easy interpretation of the core elements needed for visualization purposes, while also allowing persistent storage of application specic data like e.g. experimental results. OGML therefore can be used both for pure Graph Drawing research purposes, where mainly standard information like graph structure and layout is of interest, as well as for real world applications, where additional associated data like condence values or text labels may be of interest for storage. OGML was designed to cover most of the relevant structural information needed for graph drawing, but is also extensible to cope with less common structural features. 5

6 6 Chapter 1. Introduction

7 Chapter 2 Design and Design Goals The design of OGML targets at making it an extensible open storage and exchange le format for graphs from a variety of application areas. An OGML le should be human readable, and allow easy parsing, exchange, and transformation. In addition, there should be specic elements to model the layout-associated information needed for graph visualization, e.g. object positions or ports, without however an overly complex specication. XML is ideally suited as the base for a corresponding le format, and the wide availability of tools like XML parsers and the transformation language XSLT facilitate handling of documents in that format. The basic underlying data model is a graph structure, i.e. a set of nodes and a set of edges that connect the nodes. The graph might be directed, undirected, or partially directed. In addition, further structural information like clusters, compounds, or hyperedges can be expressed in OGML. Layout information like object positions, but also layout specications like for example layout constraints can be specied with OGML. 7

8 8 Chapter 2. Design and Design Goals

9 Chapter 3 Specication Every OGML-le contains only one ogml-tag, which represents the root of the xmldocument tree. There can be only a single graph stored per OGML le. The main structure of an OGML le is divided into two main blocks, graph and data, see Listing 3.1. Within the graph block, there are two main parts, the structure block that species the graph objects that the graph is composed of, and the layout block that species the layout, i.e. location and appearance of the node and edge objects. Style templates can be dened to dene a standard appearance for groups of objects. An additional data block allows to store data that does not represent visual properties or cannot specied in advance, like for example experimental data. Listing 3.1: Basic structure 1 2 <?xml version="1.0" encoding="utf-8"?> 3 <!-- root element --> 4 <ogml> 5 6 <!-- Specification of the graph structure --> 7 <graph> <!-- Structural information --> 10 <structure> 11 <node /> <edge /> </structure> 16 <!-- Layout information --> 17 <layout> <!-- Style-Templates --> 20 <styletemplates>

10 10 Chapter 3. Specication 22 </styletemplates> 23 <!-- Individual formatting of structural elements --> 24 <styles> </styles> 27 <!-- Constraints --> 28 <constraints> </constraints> 31 </layout> 32 </graph> <!-- Additional data annotations --> 35 <data> </data> 38 </ogml> 3.1 Structure Node Each node of the graph is represented by a <node> element with a unique id value. <node> elements can be nested to represent inclusion structures like for example compounds or clusters Edge Each edge of the graph is represented by an <edge> element with a unique id value. The end objects of the edge, i.e. usually its end nodes, are represented by <source> and target elements. The direction of an edge is modelled by the number of <source> and <target> elements stored within the <edge> element. For an undirected edge, only <source> elements are given. For a bidirectional edge, only <target> elements are given. For a directed edge, one <source> and one <target> element are given for the start and end vertex, respectively. Edges may also end at other edges, represented by using an edge id instead of a node id in the start or end elements.

11 3.2. Layout Layout Node styling Edge styling Edges are drawn as straight lines between the centers of two nodes by default. You have the possibility to override this default behavior in several ways. It is possible to specify the line type, the appearance of the start- and endpoint(s) and the shape of an edge. Additionally there is no default drawing of a hyperedge. In this case you need to specify the shape to get a well dened drawing of a graph. A complete list of all possible elements can found in Table 3.1. As for nodes you have the possibility to use a template (see subsection 3.2.1). element type min occurrence max occurrence data data.type 0 template template.type 0 1 line line.type 0 1 sourcestyle sourcetargetstyle.type 0 1 targetstyle sourcetargetstyle.type 0 1 hypernode hypernode.type 0 segment segment.type 0 Table 3.1: Edge style specication Source and target styling In many cases it may be important to have a style for the endpoints of an edge. The most common use case may be a directed graph. The target should have an arrow or a similar symbol to indicate the direction of an edge. For a sourcetargetstyle element you can specify the type (i.e. endpoint style), color and size. Possible endpoint styles are listed in Table 3.2. Hypernodes and hyperedges A hyperedge can be represented by a hypernode and normal edges between the nodes and hypernodes. Because a hypernode is only visual and does not reect the graph structure it is only specied as a layout element. Therefore the edge between hypernodes and a node or hypernode is also only visual and not represented by an edge. You can visually connect hypernodes to nodes or hypernodes with segments (refer to section 3.2.2). A hypernode is simply specied by is coordinates as a normal node.

12 12 Chapter 3. Specication style arrow vee tee triangle otriangle circle ocircle box obox rhomb orhomb Table 3.2: endpoint styles Segments A segment overrides the shape of an edge or visually connects hypernodes (refer to section 3.2.2) or ports (refer to subsection 3.2.3). It is possible to specify line type, start and endpoint as for an edge (refer to subsection 3.2.2, subsection 3.1.2). Additionally you can use hypernodes and ports as endpoints. In the case of dening the line type both for the edge and segment with the same endpoints (nodes and ports are equivalent), the segment line will override the edge style denition. The curve or shape of a segment can be specied by NURBS (Non-Uniform Rational B-Splines). This documentation will not give an introduction to NURBS and only cover the denition side in OGML. You can easily nd various websites for further information. The English Wikipedia gives a good introduction ( https: //en.wikipedia.org/wiki/nurbs). The key features of NURBS are that they can represent spherical curves (in contrast to a Bézier curve), are easy to implement, intuitive to use and not to complex for textual specication. NURBS can be specied by their control points inclusive their weights and a knot vector. In the OGML specication the knot vector is a list of doubles. The control points can be specied by a sequence of elements of the type control point.type. To preserve the ordering of the control points each control point has an index and the index must be unique. The other attributes of a control point are the coordinates and the weight. Note that the coordinates are not homogeneous. Therefore you need to multiply them with their weight in order to use a homogeneous NURBS formula Ports Without further specication all edges will end in the center of a node and the node is drawn above the edge. Sometimes you may want to have more control over the way edges and nodes will be visually connected. In this case you can use ports to specify the location and the appearance of a docking point. You can then connect an edge

13 3.2. Layout 13 visually to one of this ports instead of the node center. Additionally you can specify the layering of the node, port and edge. As a visual example refer to Figure 3.1. As for nodes you have the possibility to use a template (see subsection 3.2.1). Figure 3.1: Edges connected to the node center (gray) and to ports (blue) with dierent shapes. The dashed line indicates that the node is drawn above the edge. Dening ports As a port is a visual feature only (that does not change the graph structure), ports are dened in the nodestyle element. An example is given in Listing 3.2. In this example two port elements p01_01 and p01_02 for the node n01 are dened. The denition of a port element follows very close the denition of a nodestyle. The only important dierence is the positioning of the port. Therefore this section only describes the diering elements. If you want to learn more about how to style a node refer to subsection A complete list of all possible elements can found in Table 3.3. Listing 3.2: Port Example 1 <nodestyle idref="n01"> 2 <location x="1" y="1" /> 3 <shape type="rect" width="10" height="10" /> 4 <port id="p01_01"> 5 <relativelocation x="0.1" y ="0.1"/> 6 <shape type="rect"/> 7 <fill color="#000000"/> 8 </port> 9 <port id="p01_02"> 10 <polarlocation anglexy="0" dist="1" shaperelative="true"/> 11 </port> 12 </nodestyle> Location strategies As a port is closely related to a node, relative positioning is useful to avoid recalculation of all port coordinates when shifting a node. To maintain maximum exibility three dierent location strategies can be chosen:

14 14 Chapter 3. Specication element type min occurrence max occurrence data data.type 0 template template.type 0 1 shape shape.type 0 1 ll ll.type 0 1 line line.type 0 1 choice absolutelocation location.type relativelocation location.type polarlocation polarlocation.type shiftdrawing location.type 0 1 layering portlayering.type 0 1 Table 3.3: Port specication absolutelocation The absolute positioning of the port is the same as for nodes. Refer to subsection relativelocation The relative location is specied in the same way as absolute coordinates. The absolute coordinates can be computed by summing up the absolute node coordinates and the relative port coordinates. polarlocation Polar coordinates are also relative to the node. A polarlocation has the following attributes: anglexy / anglexz : The direction from the center of the node. An angle of 0 is in the direction of the x-axis. The angle is counted counterclockwise. anglexz is only used in the 3D case and is therefore optional. dist: The distance from the center of the node. shaperelative (optional): The boolean value describes the way the distance is interpreted. If it is true a distance of x means: x multiplied by the distance from the center of the node to the border of the shape. If you are human this option can make things more easy to interpret. In many cases you may want a port exactly on the shape border. This option is only available for simple shapes where the border can be crossed only once from the center of the node in any direction (e.g. circle, rectangle,..., but not a spiral). Since all edges end exactly at the center of a port you can use the element shiftdrawing to shift the drawing (but not the docking point) of the port in one direction. The semantic of the location.type is the same as in the relativelocation element, but relative to the absolute coordinates of the port. As an example refer to Figure 3.2.

15 3.2. Layout 15 Figure 3.2: The Example from Figure 3.1 with the rectangle port shifted to the left. Layering The layering element allows you to specify the layering of the port, node and edge. An port, node or edge that is above another one visually masks it. A layering can be only dened for 2 dimensional graphs. The layering element has two attributes: abovenode: If set to true the port will be drawn above the node. Defaults to true. edgeaboveport: If set to true the edge will be drawn above the port. Defaults to true. Note that the edge binds stronger to the port than to the node. This means that setting abovenode to false and edgeaboveport to true results in an edge below the node.

16 16 Chapter 3. Specication

17 Chapter 4 Examples 17

18 18 Chapter 4. Examples

19 Bibliography [1] The Open Graph Drawing Framework