Open Graph Drawing Framework
current version:
v.2015.05 (Baobab)

gml2pic Tutorial

Remarks: For ease of notation, we assume the following:

  • The directory containing the gml2pic executable is in the file search path, so that we can call the program by simply typing gml2pic.
  • The current directory contains the GML examples from the examples subdirectory of gml2pic's installation directory; make sure that you have write permission in the current directory!

Jump start

Let's start by a simple example using the example GML files coming with gml2pic. If you type

gml2pic data-flow.gml

this call creates a PNG file data-flow.png; by default the file name of the created image file is derived from the input file name, simply by changing the file extensions (usually from .gml) to the file extensions of the output graphics file format (in this case .png). If you want a different output file name, you can use the -o option:

gml2pic -o layout.png data-flow.gml

We obtained a PNG file, since this image format is gml2pic's default format. Of course, you can easily select a different image format. This is done by adding the -pic option with the required image format; possible values are PNG, JPEG, TIFF, SVG, PDF, and EPS (these values are case-insensitive, so you can also type png etc.). For creating a PDF file, simply type:

gml2pic -pic pdf data-flow.gml

For the vector graphics formats (SVG, PDF, EPS), gml2pic produces true vector graphics (and not just an encapsulated bitmap file); it also sets a correct bounding box, which is handy when including figures in publications (e.g., LaTeX documents). Sometimes, you may want to have an additional margin around the drawing (instead of a tight bounding box). You can specify this margin with the -margin option. The size of the margin must be given with respect to GML coordinates; that means, e.g., if our nodes have a width of 40 and we specify a margin of 40, we get a margin around the drawing which is as large as the width of the nodes, independent of any scaling. As an example, we create a PDF of power-supply.gml with a small extra margin, since this makes it easier to see the objects at the edge of the drawing:

gml2pic -pic pdf -margin 10 power-supply.gml

There are further options that influence what is shown in the resulting picture. E.g., you might want to create a picture without edge arrows at all, or you GML file specifies that edges have no arrows, but you want to see the edge directions. This can be adjusted with the -arrows option. E.g.,

gml2pic -arrows none data-flow.gml

will omit the arrow heads in the produced picture. You can also use the values last to show always arrow heads at the edge target, first to show arrow heads at the edge source, or both to show arrow heads at both ends; the default value is gml which uses the attribute for each edge from the GML file. Sometimes, it is useful to omit node or cluster labels, e.g., if you want to draw large graphs. This can be achieved by using the options -no-node-labels and -no-cluster-labels.

Bitmap graphics

For bitmap graphics (PNG, JPEG, TIFF), there are some special options. The first (-bg) specifies the background of the image. By default, the background is white, but you can also specify any other background color including transparent background. A color is specified by a string as used by Qt's QColor::setNamedColor() method. Here are some examples:

  • -bg transparent
    sets the background to transparent.
  • -bg greenyellow
    sets the background color to the SVG color greenyellow; you can use any of the SVG color keyword names.
  • -bg #FFA500
    sets the background color to the RGB-value (255,165,0), which is orange; the RGB components must be given in hexadecimal form, e.g., 165 is hexadecimal A5.

A drawing with orange background can be obtained with the following call:

gml2pic -bg orange -margin 10 power-supply.gml

The size of the created bitmap is determined from the size of the bounding box of the graph layout, where 1 unit in GML coordinates corresponds to 1 pixel. This might be inappropriate for your GML, therefore there are several ways to adjust this. First, you can directly specify the width or height of the bitmap in pixels. You can also specify both width and height, in which case the aspect ratio of the drawing might not be preserved. A simple example is:

gml2pic -width 1280 data-flow.gml

The second alternative is to specify a scaling factor, e.g.,

gml2pic -scale 2 data-flow.gml

scales the drawing by a factor of 2, so that it has twice the width and height. Please note that you cannot specify a scale factor if you specify a fixed width or height.

You can also adjust the compression level used for creating PNG and JPEG files. By default, gml2pic uses the highest compression level for PNG files (resulting in smallest files size), since PNG uses lossless compression; for JPEG files, the smallest compression level is used resulting in larger file size but best quality. To adjust the compression level, use the -compression level option, where level is a value between 0..100 (100 results in smallest files size). If you want to speed-up the computation of PNG files, you can decrease the compression level a bit, e.g.:

gml2pic -compression 70 data-flow.gml

Curved edges

gml2pic can automatically generate curved edges like Bézier curves from the simple polylines defined in the GML file. You can choose between cubic (cubic) or quadratic (quadratic) Bézier curves and circular arcs (arc). As a simple example, we can generate a drawing of unix-history-time.gml with cubic Bézier curves as follows:

gml2pic -curve cubic unix-history-time.gml

In the resulting PNG, the bend points of edges are smoothened using cubic Bézier curves. In fact, gml2pic only changes the routing of edges (using smooth curves) in a small area around each bend point; the other parts are routed as for the actual polyline. We do not change the routing of edges too much because we want to avoid overlaps caused by changing the edge routing. If you want to decrease (because of overlaps) or increase this area (for getting nicer edge routing), you can adjust it with the option -curvedLength len. Its parameter len specifies the part of the edge that is rerouted, that is, the part of the edge with a distant of at most len from the bend point. The default value for len depends on which type of curves we use, e.g., for cubic Bézier curves it is 40. We can decrease this to 20 in our example by typing:

gml2pic -curve cubic -curvedLength 20 unix-history-time.gml

Further information

You can get a list of all available options with gml2pic -help. There is also a slightly more detailed documentation online.

project/gml2pic-tutorial.txt · Last modified: 2014/12/16 12:20 (external edit)
This page is driven by DokuWiki