Quick Reference Guide for GraphViz 20 February 2002 Command-line Invocation ------------------------------------------------------------------------ All GraphViz programs have a similar invocation: cmd [ flags ] [ input files ] If no input files are supplied, the program reads from stdin. Flags -Gname=value Set a graph attribute. -Nname=value Set a default node attribute. -Ename=value Set a default edge attribute. -Tformat Set output language to one of the supported formats. By default, attributed dot is produced. -V Emit version information and exit. -llibfile User-supplied, device-dependent library files. Multiple libraries may be given. These names are passed to the code generator at the beginning of output. -n[num] Sets no-op flag in neato. If set, neato assumes nodes have already been positioned and have a pos attribute giving this position. It then just computes the edge layouts and emits the graph in the appropriate format. If num is supplied and > 1, neato checks for previously positioned edges, with control points provided in the pos attribute. It uses these if given; otherwise, it computes the edge layout. -ooutfile Write output to file outfile. By default, output goes to stdout. -s[scale] Set input scale to scale. If this value is omitted, 72.0 is used. This number is used to convert the point coordinate units used in the pos attribute into inches. For example, dot -Tdot produces pos values in points, with 72 per inch. Thus, to use this output as input to neato -n, one needs -s (equivalently, -s72). -v Verbose mode -x In neato, on input, prune isolated nodes and peninsulas. This removes uninteresting graph structure and produces a less cluttered drawing. Note that the file contents override the -G, -N and -E flags. In addition, these flags cause the related attributes to be permanently attached to the graph. Thus, if attributed dot is used for output, the graph will have these attributes. ------------------------------------------------------------------------ The DOT Language ------------------------------------------------------------------------ digraph G {foo -> bar; ... } or graph G { foo -- bar; ...} To connect all pairs: {foo bar}->{baz bart} To make a chain of links: foo->bar->baz Commas inside [...] and semicolons inside {...} are optional. Quotes are needed on attribute values to protect spaces, commas, periods, etc. // C++ like comment: to end of line /* C-like comment: between delimiters */ For a complete language description, see http://www.research.att.com/~erg/graphviz/info/lang.html ------------------------------------------------------------------------ Attributes ------------------------------------------------------------------------ Name Used By Type Default Minimum Notes Damping G double 0.99 0.0 neato only Epsilon G double (.0001 * # nodes) neato only URL ENGC string arrowhead E arrowType normal arrowsize E double 1.0 0.0 arrowtail E arrowType normal bb G rect write-only bgcolor G color bottomlabel N string "" center G bool false clusterrank G clusterMode local dot only color ENC color black comment ENG string "" compound G bool false dot only concentrate G bool false dot only constraint E bool true dot only decorate E bool false dir E dirType forward(directed) none(undirected) distortion N double 0.0 -100.0 fillcolor NC color lightgrey(nodes) black(clusters) fixedsize N bool false fontcolor ENGC color black fontname ENGC string "Times-Roman" fontpath G string "" fontsize ENGC double 14.0 1.0 group N string "" dot only headURL E string "" headlabel E string "" headport E portPos center height N double 0.5 0.02 label ENGC string "" "\N" (nodes) labelangle E double -25.0 -180.0 labeldistance E double 1.0 0.0 labelfloat E bool false labelfontcolor E color black labelfontname E string "Times-Roman" labelfontsize E double 11.0 1.0 labeljust C string "" dot only labelloc GC string "t"(clusters) dot only "b"(root graphs) layer EN layerRange "" layers G layerList "" len E double 1.0 neato only lhead E string "" dot only lp EGC point write-only ltail E string "" dot only margin G double pointf maxiter G int MAXINT neato only mclimit G double 1.0 dot only minlen E int 1 0 dot only model G string "" neato only nodesep G double 0.25 0.02 dot only normalize G bool false neato only nslimit nslimit1 G double dot only ordering G string "" dot only orientation N double 0.0 360.0 orientation G string "" overlap G string "" neato only bool page G pointf pagedir G pagedir BL peripheries N int 0 pin N bool neato only pos EN point splineType quantum G double 0.0 0.0 rank S rankType dot only rankdir G rankdir TB dot only ranksep G double 0.5 0.02 ratio G double rects N rect write-only regular N bool false remincross G bool false dot only rotate G int 0 samehead E string "" dot only sametail E string "" dot only samplepoints G int 8 searchsize G int 30 dot only sep G double 0.01 neato only shape N shape ellipse shapefile N string "" showboxes ENG int 0 0 dot only sides N int 4 0 size G pointf skew N double 0.0 -100.0 splines G bool false neato only start G string "" neato only int style ENC style styleheet G style tailURL E string "" taillabel E string "" tailport E portPos center toplabel N string "" vertices N pointfList write-only voro_margin G double 0.05 0.0 neato only w E double 1.0 neato only weight E double 1.0 0(dot) 1(neato) width N double 0.75 0.01 z N double 0.0 -MAXFLOAT -1000 ------------------------------------------------------ For the bool type, TRUE values are represented by "true" (case-insensitive) and any non-zero integer, and FALSE values by "false" (case-insensitive) and zero. In the Used By field, the characters E, N, G and C represent edges, nodes, the root graph and cluster subgraphs, respectively. This field indicates which graph component uses the attribute. ------------------------------------------------------------------------ Attribute Descriptions Damping Factor damping force motions. On each iteration, a nodes movement is limited to this factor of its potential motion. By being less than 1.0, the system tends to ``cool'', thereby preventing cycling. Epsilon Terminating condition. If the length squared of all energy gradients are < Epsilon, the algorithm stops. URL Incorporated into device-dependent output. At present, used for ps2, i*map and svg. For ps2, URLs can be attached to nodes and the root graph. When distilled to PDF, such nodes are active links and the graph URL can be used as a base URL. For i*map, URLs can be attached to nodes, edges and the root graph. If the node or edge URL contains "\N", this is replaced by the object's name. For svg, URLs can be attached to nodes, edges and clusters, with "\N" replacement done for all three. arrowhead Style of arrowhead on head of edge. arrowsize Multiplicative scale factor for arrowheads. arrowtail Style of arrowhead on tail of edge. bb Bounding box of drawing in integer points. bgcolor Color used as background for canvas, plus initial fill color. bottomlabel Additional label near bottom of nodes of shape M*. center If true, the drawing is centered in the output canvas. clusterrank Mode used for handling clusters. If clusterrank is "local", a subgraph whose name begins with "cluster" is given special treatment. The subgraph is laid out separately, and then integrated as a unit into its parent graph, with a bounding rectangle drawn about it. If the cluster has a label parameter, this label is displayed within the rectangle. Note also that there can be clusters within clusters. At present, the modes "global" and "none" appear to be identical, both turning off the special cluster processing. color Basic drawing color for graphics. comment Comments are inserted into output. Device-dependent compound If true, allow edges between clusters. (See lhead and ltail below.) concentrate If true, use edge concentrators. constraint If false, the edge is not used in ranking the nodes. For example, in the graph digraph G { a -> c; a -> b; b -> c [constraint=false]; } the edge b -> c does not add a constraint during rank assignment, so the only constraints are that a be above b and c. decorate If true, attach edge label to edge by a 2-segment polyline, underlining the label, then going to the closest point of spline. dir Set edge type for drawing arrowheads. distortion Distortion factor for shape=polygon. Positive values cause top part to be larger than bottom; negative values do the opposite. fillcolor If fillcolor is not defined, color is used. If this is not defined, the default is used, except for shape=point or when the output format is MIF, which use black by default. fixedsize If true, the node size is kept fixed and not expanded to contain the text label. fontcolor Color used for text. fontname Font used for text. fontpath Directory list used by libgd to search for bitmap fonts. If fontpath is not set, the environment variable DOTFONTPATH is checked. If that is not set, GDFONTPATH is checked. If not set, libgd uses its compiled-in font path. fontsize Font size, in points, used for text. group If the end points of an edge belong to the same group, i.e., have the same group attribute, parameters are set to avoid crossings and keep the edges straight. headURL For the output format imap, or cmap, if headURL is defined, it is output as part of the head label of the edge. If headURL contains "\N", this will be replaced by the head label text. headlabel Text label to be placed near head of edge. headport Indicates where on the head node to attach the head of the edge. In the default case, the edge is aimed towards the center of the node, and then clipped at the node boundary. height Height of node, in inches. label Text label attached to objects. The escape sequences "\n", "\l" and "\r" divide the label into lines, centered, left-justified and right-justified, respectively. The escape sequence "\N" represents a node's name. If a node's shape is record, then the label can have a special format which describes the record layout. labelangle Angle, in degrees, that the headlabel(taillabel) is rotated from the angle the edge makes incident with the head(tail) node, respectively. labeldistance Multiplicative scaling factor adjusting the distance that the headlabel(taillabel) is the from head(tail) node. labelfloat If true, allows edge labels to be less constrained in position. In particular, it may appear on top of other edges. labelfontcolor Color used for headlabel and taillabel. labelfontname Font used for headlabel and taillabel. labelfontsize Font size, in points, used for headlabel and taillabel. labeljust Justification for cluster labels. If "r", the label is right-justified within bounding rectangle; otherwise, left-justified. labelloc Top/bottom placement of graph and cluster labels. If the attribute is "t", place label at the top; if the attribute is "b", place label at the bottom. By default, root graph labels go on the bottom and cluster labels go on the top. layer Specifies layers in which the node or edge is present. layers Specifies a linearly ordered list of layer names attached to the graph The graph is then output in separate layers. Only those components belonging to the current output layer appear. For more information, see the page How to use drawing layers (overlays). len Preferred edge length, in inches. lhead Logical head of an edge. When compound is true, if lhead is defined and is the name of a cluster containing the real head, the edge is clipped to the boundary of the cluster. lp Label position, in points. ltail Logical tail of an edge. When compound is true, if ltail is defined and is the name of a cluster containing the real tail, the edge is clipped to the boundary of the cluster. margin Set x and y margins of canvas, in inches. In first case, both margins are set equal to the given value. maxiter Sets the number of iterations used. mclimit Multiplicative scale factor used to alter the MinQuit (default = 8) and MaxIter (default = 24) parameters used during crossing minimization. These correspond to the number of tries without improvement before quitting and the maximum number of iterations in each pass. minlen Minimum edge length (rank difference between head and tail). model If "circuit", use circuit resistance model to compute dissimilarity values; otherwise, use shortest path model. nodesep Minimum space between two adjacent nodes in the same rank, in inches. normalize If set, normalize coordinates of final layout so that the first point is at the origin, and then rotate the layout so that the first edge is horizontal. nslimit , nslimit1 Used to set number of iterations in network simplex applications. nslimit is used in computing node x coordinates, nslimit1 for ranking nodes. If defined, # iterations = nslimit(1) * # nodes; otherwise, # iterations = MAXINT. ordering If "out" for a graph G, and n is a node in G, then edges n->* appear left-to-right in the same order in which they are defined. orientation Angle, in degrees, used to rotate node shapes. orientation If "[lL]*", set graph orientation to landscape Used only if rotate is not defined. overlap If "scale", remove node overlaps by scaling; if converts to false, remove node overlaps by the Voronoi technique; otherwise, leave overlaps. page Width and height of output pages, in inches. If this is set and is smaller than the size of the layout, a rectangular array of pages of the specified page size is overlaid on the layout, with origins aligned in the lower-left corner, thereby partitioning the layout into pages. The pages are then produced one at a time, in pagedir order. pagedir If the page attribute is set and applicable, this attribute specifies the order in which the pages are emitted. This is limited to one of the 8 row or column major orders. peripheries Set number of peripheries used in polygonal shapes. pin If true and the node has a pos attribute on input, neato prevents the node from moving from the input position. This property can also be specified in the pos attribute itself (cf. the point type). pos Position of node, or spline control points, in points. In neato, pos can be used to set initial position of a node. Concerning this, see the -s command line flag. quantum If quantum > 0.0, node label dimensions will be rounded to integral multiples of the quantum. rank Rank constraints on the nodes in a subgraph. If rank="same", all nodes are placed on the same rank. If rank="min", all nodes are placed on the minimum rank. If rank="source", all nodes are placed on the minimum rank, and the only nodes on the minimum rank belong to some subgraph whose rank attribute is "source" or "min". Analogous criteria hold for rank="max" and rank="sink". (Note: the minimum rank is topmost or leftmost, and the maximum rank is bottommost or rightmost.) rankdir Sets direction of graph layout. If rankdir="LR", the graph is laid out from left to right, i.e., directed edges tend to go from left to right. By default, graphs are laid out from top to bottom. ranksep In dot, this the gives desired rank separation, in inches. This is the minimum vertical distance between the bottom of the nodes in one rank and the tops of nodes in the next. If the value contains "equally", the centers of all ranks are spaced equally apart. Note that both settings are possible, e.g., ranksep = "1.2 equally". In twopi, specifies radial separation of ranks. ratio Sets the aspect ratio (drawing height/drawing width) for the drawing. Note that this is adjusted before the size attribute constraints are enforced. If ratio is numeric, it is taken as the desired aspect ratio. Then, if the actual aspect ratio is less than the desired ratio, the drawing height is scaled up to achieve the desired ratio; if the actual ratio is greater than that desired ratio, the drawing width is scaled up. If ratio = "fill" and the size attribute is set, the drawing is scaled to achieve the aspect ratio implied by size. As size is set, when the drawing is later scaled to fit that rectangle, the resulting picture will fill the rectangle. If ratio = "compress" and the size attribute is set, dot attempts to compress the initial layout to fit in the given size. This achieves a tighter packing of nodes but reduces the balance and symmetry. If ratio = "auto", the page attribute is set and the graph cannot be drawn on a single page, then size is set to an ``ideal'' value. In particular, the size in a given dimension will be the smallest integral multiple of the page size in that dimension which is at least half the current size. The two dimensions are then scaled independently to the new size. rects Rectangles for fields of records, in points. regular If true, force polygon to be regular. remincross If true and there are multiple clusters, run cross minimization a second time. rotate If 90, set drawing orientation to landscape. samehead Edges with the same head and the same samehead value are aimed at the same point on the head. sametail Edges with the same tail and the same sametail value are aimed at the same point on the tail. samplepoints If the input graph defines the vertices attribute, and output is plain* or attributed dot, this give the number of points used to represent circles and ellipses. It plays the same role in neato, when adjusting the layout to avoid overlapping nodes. searchsize During network simplex, maximum number of edges with negative cut values to search when looking for one with minimum cut value. sep Fraction to increase polygons (multiply coordinates by 1 + sep) for purposes of determining overlap. Guarantees a minimal non-zero distance between nodes. shape Set shape of node. shapefile For output format is ps* or svg*, if non-empty, taken as a filename containing a device-dependent description of a node's shape. showboxes Print guide boxes in PostScript at the beginning of routesplines if 1, or at the end if 2. (Debugging) sides Number of sides if shape=polygon. size Maximum width and height of drawing, inches. If defined and the drawing is too large, the drawing is uniformly scaled down so that it fits within the given size. Note that there is some interaction between the size and ratio attributes. skew Skew factor for shape=polygon. Positive values skew top of polygon to right; negative to left. splines If true, draw edges as splines. This requires non-overlapping nodes (cf. overlap). start Parameter used to determine the initial layout of nodes. By default, nodes are randomly placed in a square whose sides have length (# nodes). The same seed is always used for the random number generator, so the initial placement is repeatable. If start converts to an integer, this is used as a seed value for the random number generator. If start is "regular", the nodes are placed regularly about a circle. Finally, if start is defined but is not one of the above cases, the current time is used to pick a seed. style Set style for node or edge. For cluster subgraph, if "filled", the cluster box's background is filled. stylesheet The URL of a CSS stylesheet to be referenced from the output file. Relevant only for SVG output. tailURL When the output format is imap, or cmap, if tailURL is defined, it is output as part of the tail label of the edge. If tailURL contains "\N", this will be replaced by the tail label text. taillabel Text label to be placed near tail of edge. tailport Indicates where on the tail node to attach the tail of the edge. toplabel Additional label near top of nodes of shape M*. vertices If the input graph defines this attribute, the node is polynomial, and output is plain* or attributed dot, this attribute provides the coordinates of the vertices of the node's polynomial, in points. If the node is an ellipse or circle, the samplepoints attribute affects the output. voro_margin Factor to scale up drawing to allow margin for expansion in Voronoi technique. dim' = (1+2*margin)*dim. w Redundant definition of weight in neato, cf. bug 9. weight Weight of edge. Usually, the heavier the weight, the shorter (and, in dot, straighter and more vertical) an edge is. width Width of node, in inches. z Provides z coordinate for the node when output format is VRML. ------------------------------------------------------------------------ Attribute Type Descriptions arrowType "normal" "inv" "dot" "invdot" "odot" "invodot" "none" clusterMode "local","global","none" color "#%2x%2x%2x" RGB "#%2x%2x%2x%2x"RGBA "%lf,%lf,%lf" HSV 0.0 <= values <= 1.0 string color name dirType For an edge T -> H; "forward" "back" "both" "none" For undirected edges T -- H;, one of the nodes, usually the righthand one, is treated as the head for the purpose of interpreting "forward" and "back". layerList list of strings separated by colons, tabs or spaces, defining layer names and implicitly numbered 1,2,... layerRange layerId or layerId[:\t ]layerId, where layerId = "all", decimal integer or layer name. (An integer i corresponds to layer i.) pagedir "BL", "BR", "TL", "TR", "RB", "RT", "LB", "LT". These specify the 8 row or column major orders for traversing a rectangular array, the first character corresponding to the major order and the second to the minor order. Thus, for "BL", the major order is from bottom to top, and the minor order is from left to right. This means the bottom row is traversed first, from left to right, then the next row up, from left to right, and so on, until the topmost row is traversed. point "%d,%d"('!') representing the point (x,y). The optional '!' indicates the node position should not change (input-only). pointf "%lf,%lf" representing the point (x,y). pointfList list of pointf, separated by spaces. portPos "n","ne","e","se","s","sw","w","nw" These correspond to the obvious compass points on the node. rankType "same", "min", "source", "max", "sink" rankdir "LR". Any other value corresponds to a top-down layout. rect "%d,%d,%d,%d" The rect llx,lly,urx,ury gives the coordinates, in points, of the lower-left corner (llx,lly) and the upper-right corner (urx,ury). shape A string specifying the shape of a node. There are three main types of shapes : polygon-based, record-based and PostScript-based. splineType spline ( ';' spline )* where spline= (endp)? (startp)? point (triple)]* and triple = point point point and endp = "e,%d,%d" and startp = "s,%d,%d" If a spline has points p1 p2 p3 ... pn, (n = 1 (mod 3)), the points correspond to the control points of a B-spline from p1 to pn. If startp is given, it touches one node of the edge, and the arrowhead goes from p1 to startp. If startp is not given, p1 touches a node. Similarly for pn and endp. style styleItem ( ',' styleItem )* where styleItem= name or name'('args')' and args = name ( ',' name )* and name = [^)(, ][^)(,]* At present, the recognized style names comprise "dashed", "dotted", "solid", "invis" and "bold" for nodes and edges, and "filled", "diagonals" and "rounded" for nodes only. Additional styles are available in device-dependent form. Style lists are passed to device drivers, which can use this to generate appropriate output. Note that, at present, "rounded" cancels "filled", except for circles and ellipses. This holds for the Mrecord shape, which is rounded by definition. ------------------------------------------------------------------------ Output Formats ------------------------------------------------------------------------ The output format is specified with the -Tlang flag on the command line, where lang is one of the following: Command-line parameter Format canon cmap Client-side imagemap dot DOT fig FIG gd gd2 GD/GD2 formats gif GIF hpgl HP-GL/2 imap Server-side imagemap ismap Server-side imagemap (deprecated) jpg jpeg JPEG mif FrameMaker MIF format mp MetaPost pcl PCL pic PIC plain plain-ext Simple text format png Portable Network Graphics format ps PostScript ps2 PostScript for PDF svg svgz Scalable Vector Graphics vrml VRML vtx Visual Thought format wbmp Wireless BitMap format ------------------------------------------------------------------------ Format Descriptions canon , dot These two formats produce output in variations of the dot language. Using canon produces a prettyprinted version of the input, with no layout performed. dot corresponds to attributed dot, and is the default output format. It reproduces the input, along with layout information for the graph. In particular, a bb attribute is attached to the graph, specifying the bounding box of the drawing. If the graph has a label, its position is specified by the lp attribute. Each node gets pos, width and height attributes. If the node is a record, the record rectangles are given in the rects attribute. If the node is a polygon and the vertices attribute is defined, this attribute contains the vertices of the node. Every edge is assigned a pos attribute, and if the edge has a label, the label position is given in lp. fig Outputs graphs in the FIG graphics language. gd , gd2 Output images in the GD and GD2 format. These are the internal formats used by the gd library. The latter is compressed. gif Outputs GIF bitmap images. hpgl Produces output in the HP-GL/2 vector graphic printer language. imap cmap Produces map files for server-side and client-side image maps, respectively. These can be used in a web page with a graphical form of the output, e.g. in JPEG or GIF format, to attach links to nodes and edges. For example, given the dot file /* x.dot */ digraph G { URL="http://www.research.att.com/"; command [URL="command.html"]; command -> output [URL="colors.html"]; } this can be processed twice: dot -Timap > x.map dot -Tgif > x.gif and then be referred to in a web page, such as URLs can be attached to the root graph, nodes and edges. If the URL of a node contains the escape sequence "\N", it will be replaced by the node's name. If an edge has a URL, various points along the edge (but not the head or tail) will link to it. In addition, if the edge has a label, that will link to the URL. As for the head of the edge, this is linked to the headURL, if set. Otherwise, it is linked to the edge's URL if that is defined. If the headURL contains the escape sequence "\N", it will be replaced by the headlabel, if defined. The analogous description holds for the tail, tailURL and taillabel. ismap Produces HTML image map files. This is a predecessor (circa 1994) of the IMAP format. Most servers now user the latter. URLs can be attached to the root graph, nodes and edges. Since edge links are attached to edge labels, an edge must have a label for its URL to be used. For both nodes and edges, if the URL has the escape sequence "\N" embedded in its string, this will be replaced with the node or edge name. jpg , jpeg Output JPEG compressed image files. This format relies on the installation having the JPEG library. mif Generates Frame Maker MIF files. mp Produces MetaPost output. pcl Produces output in the PCL printer language. HP-GL is a subset of PCL, so that PCL output is the same as HP-GL, wrapped with some initial and final commands to set the printer to and from HP-GL mode. pic Outputs in PIC, the picture description language in the troff-family plain , plain-ext The plain and plain-ext formats produce output using a simple, line-based language. The latter format differs in that, on edges, it provides port names on head and tail nodes when applicable. There are four types of statements. graph scale width height node name x y width height label style shape color fillcolor edge tail head n x1 y1 .. xn yn [label xl yl] style color stop graph The width and height values give the width and height of the drawing. The lower left corner of the drawing is at the origin. The scale value indicates how the drawing should be scaled if a size attribute was given and the drawing needs to be scaled to conform to that size. If no scaling is necessary, it will be set to 1.0. Note that all graph, node and edge coordinates and lengths are given unscaled. node The name value is the name of the node, and x and y give the node's position. The width and height are the width and height of the node. The label, style, shape, color and fillcolor give the node's label, style, shape, color and fillcolor, respectively, using attribute default values where necessary. If the node does not have a style attribute, "solid" is used. edge The tail and head values give the names of the head and tail nodes. n is the number of control points defining the B-spline forming the edge. This is followed by 2*n numbers giving the x and y coordinates of the control points in order from tail to head. If the edge has a label, this comes next followed by the x and y coordinates of the label's position. The edge description is completed by the edge's style and color. As with nodes, if a style is not defined, "solid" is used. The output consists of one graph line, a sequence of node lines, one per node, a sequence of edge lines, one per edge, and a final stop line. All units are in inches, represented by a floating point number. png Produces output in the PNG (Portable Network Graphics) format. PNG relies on having libz and the PNG library. ps Produces PostScript output. ps2 Produces PostScript output with PDF notations. It is assumed the output will be directly converted into PDF format. The notations include PDF bounding box information, so that the resulting PDF file can be correctly used with pdf tools, such as pdflatex. In addition, if a node has a URL attribute, this gets translated into PDF code such that the node, when viewed in a PDF-viewer, e.g., acroread, is a link to the given URL. If a URL is attached to the graph, this serves as a base, such that relative URLs on nodes are derived from it. svg , svgz Produce SVG output, the latter in compressed format. SVG relies on having libz. vrml Outputs graphs in the VRML format. VRML relies on having the PNG library. vtx Generates graph diagrams in the format for Confluents's Visual Thought. wbmp Produces output in the Wireless BitMap (WBMP) format, optimized for mobile computing. ------------------------------------------------------------------------