1OSAGE(1) General Commands Manual OSAGE(1)
2
6 osage - filter for drawing clustered graphs
7
9 osage [-(G|N|E)name=value] [-Tlang] [-llibfile] [-ooutfile] [-O] [-P]
10 [-v] [-V] [files]
11
13 osage draws clustered graphs. As input, it takes any graph in the dot
14 format. It draws the graph recursively. At each level, there will be a
15 collection of nodes and a collection of cluster subgraphs. The inter‐
16 nals of each cluster subgraph are laid out, then the cluster subgraphs
17 and nodes at the current level are positioned relative to each other,
18 treating each cluster subgraph as a node.
19 At each level, the nodes and cluster subgraphs are viewed as rectangles
21 to be packed together. At present, edges are ignored during packing.
22 Packing is done using the standard packing functions. In particular,
23 the graph attributes pack and packmode control the layout. Each graph
24 and cluster can specify its own values for these attributes. Remember
25 also that a cluster inherits its attribute values from its parent
26 graph.
27 After all nodes and clusters, edges are routed based on the value of
29 the splines attribute.
30
32 Osage uses an extensible plugin mechanism for its output renderers, so
33 to see what output formats your installation of osage supports you can
34 use ``osage -Txxx'' (where xxx is an unlikely format) and check the
35 warning message. Also, The plugin mechanism supports multiple imple‐
36 mentations of the output formats. To see what variants are available,
37 use, for example: ``osage -Tpng:'' and to force a particular variant,
38 use, for example: ``osage -Tpng:gd''
39 Traditionally, osage supports the following: -Tps (PostScript), -Tsvg
41 -Tsvgz (Structured Vector Graphics), -Tfig (XFIG graphics), -Tmif
42 (FrameMaker graphics), -Thpgl (HP pen plotters), and -Tpcl (Laserjet
43 printers), -Tpng -Tgif (bitmap graphics), -Tdia (GTK+ based diagrams),
44 -Timap (imagemap files for httpd servers for each node or edge that has
45 a non‐null "href" attribute.), -Tcmapx (client‐side imagemap for use in
46 html and xhtml). Additional less common or more special‐purpose output
47 formats can be found at http://www.graphviz.org/cvs/doc/info/out‐
48 put.html.)
49 Alternative plugins providing support for a given output format can be
51 found from the error message resulting from appending a ':' to the for‐
52 mat. e.g. -Tpng: The first plugin listed is always the default.
53
55 Here is a synopsis of the graph file language, traditionally using the
56 extension .gv or .dot, for graphs:
57 [strict] (graph|digraph) name { statement‐list }
59 Is the top level graph. If the graph is strict then multiple edges are
60 not allowed between the same pairs of nodes. If it is a directed
61 graph, indicated by digraph, then the edgeop must be "->". If it is an
62 undirected graph then the edgeop must be "--". Statements may be:
63 name=val;
65 node [name=val];
66 edge [name=val];
67 Set default graph, node, or edge attribute name to val. Any subgraph,
68 node, or edge appearing after this inherits the new default attributes.
69 n0 [name0=val0,name1=val1,...]; Creates node n0 (if it does not already
71 exist) and sets its attributes according to the optional list.
72 n0 edgeop n1 edgeop ... edgeop nn [name0=val0,name1=val1,...];
74 Creates edges between nodes n0, n1, ..., nn and sets their attributes
75 according to the optional list. Creates nodes as necessary.
76 [subgraph name] { statement‐list }
78 Creates a subgraph. Subgraphs may be used in place of n0, ..., nn in
79 the above statements to create edges. [subgraph name] is optional; if
80 missing, the subgraph is assigned an internal name.
81 Comments may be /*C‐like*/ or //C++‐like.
83 Attribute names and values are ordinary (C‐style) strings. The follow‐
86 ing sections describe attributes that control graph layout.
87
90 size="x,y" sets bounding box of drawing in inches.
91 page="x,y" sets the PostScript pagination unit.
93 ratio=f sets the aspect ratio to f which may be a floating point num‐
95 ber, or one of the keywords fill, compress, or auto.
96 pagedir=[TBLR][TBLR] sets the major and minor order of pagination.
98 rotate=90 sets landscape mode. (orientation=land is backward compati‐
100 ble but obsolete.)
101 center=n a non‐zero value centers the drawing on the page.
103 layers="id:id:id:id" is a sequence of layer identifiers for overlay
105 diagrams. The PostScript array variable layercolorseq sets the assign‐
106 ment of colors to layers. The least index is 1 and each element must be
107 a 3‐element array to be interpreted as a color coordinate.
108 color=colorvalue sets foreground color (bgcolor for background).
110 href="url" the default url for image map files; in PostScript files,
112 the base URL for all relative URLs, as recognized by Acrobat Distiller
113 3.0 and up.
114 URL="url" ("URL" is a synonym for "href".)
116 stylesheet="file.css" includes a reference to a stylesheet in -Tsvg and
118 -Tsvgz outputs. Ignored by other formats.
119 splines. If set to true, edges are drawn as splines. If set to poly‐
121 line, edges are drawn as polylines. If set to ortho, edges are drawn
122 as orthogonal polylines. In all of these cases, the nodes may not
123 overlap. If splines=false or splines=line, edges are drawn as line
124 segments. The default is false.
125
128 height=d or width=d sets minimum height or width. Adding fixed‐
129 size=true forces these to be the actual size (text labels are ignored).
130 shape=record polygon epsf builtin_polygon
132 builtin_polygon is one of: plaintext ellipse oval circle egg triangle
133 box diamond trapezium parallelogram house hexagon octagon note tab
134 box3d component. (Polygons are defined or modified by the following
135 node attributes: regular, peripheries, sides, orientation, distortion
136 and skew.) epsf uses the node's shapefile attribute as the path name
137 of an external EPSF file to be automatically loaded for the node shape.
138 label=text where text may include escaped newlines \n, \l, or \r for
140 center, left, and right justified lines. The string '\N' value will be
141 replaced by the node name. The string '\G' value will be replaced by
142 the graph name. Record labels may contain recursive box lists delim‐
143 ited by { | }. Port identifiers in labels are set off by angle brack‐
144 ets < >. In the graph file, use colon (such as, node0:port28).
145 fontsize=n sets the label type size to n points.
147 fontname=name sets the label font family name.
149 color=colorvalue sets the outline color, and the default fill color if
151 style=filled and fillcolor is not specified.
152 fillcolor=colorvalue sets the fill color when style=filled. If not
154 specified, the fillcolor when style=filled defaults to be the same as
155 the outline color.
156 fontcolor=colorvalue sets the label text color.
158 A colorvalue may be "h,s,v" (hue, saturation, brightness) floating
160 point numbers between 0 and 1, or an X11 color name such as white black
161 red green blue yellow magenta cyan or burlywood, or a "#rrggbb" (red,
162 green, blue, 2 hex characters each) value.
163 style=filled solid dashed dotted bold invis or any Postscript code.
165 layer=id or id:id or "all" sets the node's active layers. The empty
167 string means no layers (invisible).
168 The following attributes apply only to polygon shape nodes:
170 regular=n if n is non‐zero then the polygon is made regular, i.e. sym‐
172 metric about the x and y axis, otherwise the polygon takes on the
173 aspect ratio of the label. builtin_polygons that are not already regu‐
174 lar are made regular by this attribute. builtin_polygons that are
175 already regular are not affected (i.e. they cannot be made asymmet‐
176 ric).
177 peripheries=n sets the number of periphery lines drawn around the poly‐
179 gon. This value supersedes the number of periphery lines of
180 builtin_polygons.
181 sides=n sets the number of sides to the polygon. n<3 results in an
183 ellipse. This attribute is ignored by builtin_polygons.
184 orientation=f sets the orientation of the first apex of the polygon
186 counterclockwise from the vertical, in degrees. f may be a floating
187 point number. The orientation of labels is not affected by this
188 attribute. This attribute is added to the initial orientation of
189 builtin_polygons.
190 distortion=f sets the amount of broadening of the top and narrowing of
192 the bottom of the polygon (relative to its orientation). Floating
193 point values between -1 and +1 are suggested. This attribute is
194 ignored by builtin_polygons.
195 skew=f sets the amount of right‐displacement of the top and left‐dis‐
197 placement of the bottom of the polygon (relative to its orientation).
198 Floating point values between -1 and +1 are suggested. This attribute
199 is ignored by builtin_polygons.
200 href="url" sets the url for the node in imagemap, PostScript and SVG
202 files. The substrings '\N' and '\G' are substituted in the same manner
203 as for the node label attribute. Additionally the substring '\L' is
204 substituted with the node label string.
205 URL="url" ("URL" is a synonym for "href".)
207 target="target" is a target string for client‐side imagemaps and SVG,
209 effective when nodes have a URL. The target string is used to deter‐
210 mine which window of the browser is used for the URL. Setting it to
211 "_graphviz" will open a new window if it doesn't already exist, or re‐
212 use it if it does. If the target string is empty, the default, then no
213 target attribute is included in the output. The substrings '\N' and
214 '\G' are substituted in the same manner as for the node label
215 attribute. Additionally the substring '\L' is substituted with the
216 node label string.
217 tooltip="tooltip" is a tooltip string for client‐side imagemaps and
219 SVG, effective when nodes have a URL. The tooltip string defaults to
220 be the same as the label string, but this attribute permits nodes with‐
221 out labels to still have tooltips thus permitting denser graphs. The
222 substrings '\N' and '\G' are substituted in the same manner as for the
223 node label attribute. Additionally the substring '\L' is substituted
224 with the node label string.
225
229 label=text where text may include escaped newlines \n, \l, or \r for
230 centered, left, or right justified lines. If the substring '\T' is
231 found in a label it will be replaced by the tail_node name. If the
232 substring '\H' is found in a label it will be replaced by the head_node
233 name. If the substring '\E' value is found in a label it will be
234 replaced by: tail_node_name->head_node_name If the substring '\G' is
235 found in a label it will be replaced by the graph name. or by:
236 tail_node_name--head_node_name for undirected graphs.
237 fontsize=n sets the label type size to n points.
239 fontname=name sets the label font family name.
241 fontcolor=colorvalue sets the label text color.
243 style=solid dashed dotted bold invis
245 color=colorvalue sets the line color for edges.
247 color=colorvaluelist a ':' separated list of colorvalue creates paral‐
249 lel edges, one edge for each color.
250 dir=forward back both none controls arrow direction.
252 tailclip,headclip=false disables endpoint shape clipping.
254 href="url" sets the url for the node in imagemap, PostScript and SVG
256 files. The substrings '\T', '\H', '\E' and '\G' are substituted in the
257 same manner as for the edge label attribute. Additionally the sub‐
258 string '\L' is substituted with the edge label string.
259 URL="url" ("URL" is a synonym for "href".)
261 target="target" is a target string for client‐side imagemaps and SVG,
263 effective when edges have a URL. If the target string is empty, the
264 default, then no target attribute is included in the output. The sub‐
265 strings '\T', '\H', '\E' and '\G' are substituted in the same manner as
266 for the edge label attribute. Additionally the substring '\L' is sub‐
267 stituted with the edge label string.
268 tooltip="tooltip" is a tooltip string for client‐side imagemaps effec‐
270 tive when edges have a URL. The tooltip string defaults to be the same
271 as the edge label string. The substrings '\T', '\H', '\E' and '\G' are
272 substituted in the same manner as for the edge label attribute. Addi‐
273 tionally the substring '\L' is substituted with the edge label string.
274 arrowhead,arrowtail=none, normal, inv, dot, odot, invdot, invodot, tee,
276 empty, invempty, open, halfopen, diamond, odiamond, box, obox, crow.
277 arrowsize (norm_length=10,norm_width=5,
279 inv_length=6,inv_width=7,dot_radius=2)
280 headlabel,taillabel=string for port labels. labelfontcolor,labelfont‐
282 name,labelfontsize for head and tail labels. The substrings '\T',
283 '\H', '\E' and '\G' are substituted in the same manner as for the edge
284 label attribute. Additionally the substring '\L' is substituted with
285 the edge label string.
286 headhref="url" sets the url for the head port in imagemap, PostScript
288 and SVG files. The substrings '\T', '\H', '\E' and '\G' are substi‐
289 tuted in the same manner as for the edge label attribute. Additionally
290 the substring '\L' is substituted with the edge label string.
291 headURL="url" ("headURL" is a synonym for "headhref".)
293 headtarget="headtarget" is a target string for client‐side imagemaps
295 and SVG, effective when edge heads have a URL. The headtarget string
296 is used to determine which window of the browser is used for the URL.
297 If the headtarget string is empty, the default, then headtarget
298 defaults to the same value as target for the edge. The substrings
299 '\T', '\H', '\E' and '\G' are substituted in the same manner as for the
300 edge label attribute. Additionally the substring '\L' is substituted
301 with the edge label string.
302 headtooltip="tooltip" is a tooltip string for client‐side imagemaps
304 effective when head ports have a URL. The tooltip string defaults to
305 be the same as the headlabel string. The substrings '\T', '\H', and
306 '\E' are substituted in the same manner as for the edge label
307 attribute. Additionally the substring '\L' is substituted with the
308 edge label string.
309 tailhref="url" sets the url for the tail port in imagemap, PostScript
311 and SVG files. The substrings '\T', '\H', '\E' and '\G' are substi‐
312 tuted in the same manner as for the edge label attribute. Additionally
313 the substring '\L' is substituted with the edge label string.
314 tailURL="url" ("tailURL" is a synonym for "tailhref".)
316 tailtarget="tailtarget" is a target string for client‐side imagemaps
318 and SVG, effective when edge tails have a URL. The tailtarget string
319 is used to determine which window of the browser is used for the URL.
320 If the tailtarget string is empty, the default, then tailtarget
321 defaults to the same value as target for the edge. The substrings
322 '\T', '\H', '\E' and '\G' are substituted in the same manner as for the
323 edge label attribute. Additionally the substring '\L' is substituted
324 with the edge label string.
325 tailtooltip="tooltip" is a tooltip string for client‐side imagemaps
327 effective when tail ports have a URL. The tooltip string defaults to
328 be the same as the taillabel string. The substrings '\T', '\H', '\E'
329 and '\G' are substituted in the same manner as for the edge label
330 attribute. Additionally the substring '\L' is substituted with the
331 edge label string.
332 labeldistance and port_label_distance set distance; also labelangle (in
334 degrees CCW)
335 decorate draws line from edge to label.
337 samehead,sametail aim edges having the same value to the same port,
339 using the average landing point.
340 layer=id or id:id or "all" sets the edge's active layers. The empty
342 string means no layers (invisible).
343 (neato‐specific attributes)
346 w=f sets the weight (spring constant) of an edge to the given floating
347 point value. The default is 1.0; greater values make the edge tend
348 more toward its optimal length.
349 len=f sets the optimal length of an edge. The default is 1.0.
351
353 -G sets a default graph attribute.
354 -N sets a default node attribute.
355 -E sets a default edge attribute. Example: -Gsize="7,8" -Nshape=box
356 -Efontsize=8
357 -lfile loads custom PostScript library files. Usually these define
359 custom shapes or styles. If -l is given by itself, the standard
360 library is omitted.
361 -Tlang sets the output language as described above.
363 -O automatically generate output filenames based on the input filename
365 and the -T format.
366 -v (verbose) prints various information useful for debugging.
368 -V (version) prints version information and exits.
370 -? prints the usage and exits.
372
374 digraph test123 {
375 pack=8
376 subgraph cluster0 {
377 packmode=array
378 x y x0 y0 x1
379 subgraph cluster1 {
380 m n
381 }
382 }
383 b [shape=box];
384 c [label="hello\0orld",color=blue,fontsize=24,
385 fontname="Palatino-Italic",fontcolor=red,style=filled];
386 a -> z
387 x -> z
388 a -> b -> c;
389 a -> {x y};
390 edge [style=dashed,color=red];
391 b -> x;
392 }
393
395 Emden R. Gansner <erg@research.att.com>
396
398 This man page contains only a small amount of the information related
399 to the Graphviz layout programs. The most complete information can be
400 found at http://www.graphviz.org/Documentation.php, especially in the
401 on‐line reference pages. Most of these documents are also available in
402 the doc and doc/info subtrees in the source and binary distributions.
403 dot(1)
405 27 May 2009 OSAGE(1)