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), -Timap (imagemap files for
44 httpd servers for each node or edge that has a non‐null "href" attri‐
45 bute.), -Tcmapx (client‐side imagemap for use in html and xhtml). Ad‐
46 ditional less common or more special‐purpose output formats can be
47 found at https://www.graphviz.org/doc/info/output.html.)
48 Alternative plugins providing support for a given output format can be
50 found from the error message resulting from appending a ':' to the for‐
51 mat. e.g. -Tpng: The first plugin listed is always the default.
52
54 Here is a synopsis of the graph file language, normally using the ex‐
55 tension .gv, for graphs:
56 [strict] (graph|digraph) name { statement‐list }
58 Is the top level graph. If the graph is strict then multiple edges are
59 not allowed between the same pairs of nodes. If it is a directed
60 graph, indicated by digraph, then the edgeop must be "->". If it is an
61 undirected graph then the edgeop must be "--". Statements may be:
62 name=val;
64 node [name=val];
65 edge [name=val];
66 Set default graph, node, or edge attribute name to val. Any subgraph,
67 node, or edge appearing after this inherits the new default attributes.
68 n0 [name0=val0,name1=val1,...]; Creates node n0 (if it does not already
70 exist) and sets its attributes according to the optional list.
71 n0 edgeop n1 edgeop ... edgeop nn [name0=val0,name1=val1,...];
73 Creates edges between nodes n0, n1, ..., nn and sets their attributes
74 according to the optional list. Creates nodes as necessary.
75 [subgraph name] { statement‐list }
77 Creates a subgraph. Subgraphs may be used in place of n0, ..., nn in
78 the above statements to create edges. [subgraph name] is optional; if
79 missing, the subgraph is assigned an internal name.
80 Comments may be /*C‐like*/ or //C++‐like.
82 Attribute names and values are ordinary (C‐style) strings. The follow‐
85 ing sections describe attributes that control graph layout.
86
89 size="x,y" sets bounding box of drawing in inches.
90 page="x,y" sets the PostScript pagination unit.
92 ratio=f sets the aspect ratio to f which may be a floating point num‐
94 ber, or one of the keywords fill, compress, or auto.
95 pagedir=[TBLR][TBLR] sets the major and minor order of pagination.
97 rotate=90 sets landscape mode. (orientation=land is backward compati‐
99 ble but obsolete.)
100 center=n a non‐zero value centers the drawing on the page.
102 layers="id:id:id:id" is a sequence of layer identifiers for overlay di‐
104 agrams. The PostScript array variable layercolorseq sets the assign‐
105 ment of colors to layers. The least index is 1 and each element must be
106 a 3‐element array to be interpreted as a color coordinate.
107 color=colorvalue sets foreground color (bgcolor for background).
109 href="url" the default url for image map files; in PostScript files,
111 the base URL for all relative URLs, as recognized by Acrobat Distiller
112 3.0 and up.
113 URL="url" ("URL" is a synonym for "href".)
115 stylesheet="file.css" includes a reference to a stylesheet in -Tsvg and
117 -Tsvgz outputs. Ignored by other formats.
118 splines. If set to true, edges are drawn as splines. If set to poly‐
120 line, edges are drawn as polylines. If set to ortho, edges are drawn
121 as orthogonal polylines. In all of these cases, the nodes may not
122 overlap. If splines=false or splines=line, edges are drawn as line
123 segments. The default is false.
124
127 height=d or width=d sets minimum height or width. Adding fixed‐
128 size=true forces these to be the actual size (text labels are ignored).
129 shape=record polygon epsf builtin_polygon
131 builtin_polygon is one of: plaintext ellipse oval circle egg triangle
132 box diamond trapezium parallelogram house hexagon octagon note tab
133 box3d component. (Polygons are defined or modified by the following
134 node attributes: regular, peripheries, sides, orientation, distortion
135 and skew.) epsf uses the node's shapefile attribute as the path name
136 of an external EPSF file to be automatically loaded for the node shape.
137 label=text where text may include escaped newlines \n, \l, or \r for
139 center, left, and right justified lines. The string '\N' value will be
140 replaced by the node name. The string '\G' value will be replaced by
141 the graph name. Record labels may contain recursive box lists delim‐
142 ited by { | }. Port identifiers in labels are set off by angle brack‐
143 ets < >. In the graph file, use colon (such as, node0:port28).
144 fontsize=n sets the label type size to n points.
146 fontname=name sets the label font family name.
148 color=colorvalue sets the outline color, and the default fill color if
150 style=filled and fillcolor is not specified.
151 fillcolor=colorvalue sets the fill color when style=filled. If not
153 specified, the fillcolor when style=filled defaults to be the same as
154 the outline color.
155 fontcolor=colorvalue sets the label text color.
157 A colorvalue may be "h,s,v" (hue, saturation, brightness) floating
159 point numbers between 0 and 1, or an X11 color name such as white black
160 red green blue yellow magenta cyan or burlywood, or a "#rrggbb" (red,
161 green, blue, 2 hex characters each) value.
162 style=filled solid dashed dotted bold invis or any Postscript code.
164 layer=id or id:id or "all" sets the node's active layers. The empty
166 string means no layers (invisible).
167 The following attributes apply only to polygon shape nodes:
169 regular=n if n is non‐zero then the polygon is made regular, i.e. sym‐
171 metric about the x and y axis, otherwise the polygon takes on the as‐
172 pect ratio of the label. builtin_polygons that are not already regular
173 are made regular by this attribute. builtin_polygons that are already
174 regular are not affected (i.e. they cannot be made asymmetric).
175 peripheries=n sets the number of periphery lines drawn around the poly‐
177 gon. This value supersedes the number of periphery lines of
178 builtin_polygons.
179 sides=n sets the number of sides to the polygon. n<3 results in an el‐
181 lipse. This attribute is ignored by builtin_polygons.
182 orientation=f sets the orientation of the first apex of the polygon
184 counterclockwise from the vertical, in degrees. f may be a floating
185 point number. The orientation of labels is not affected by this attri‐
186 bute. This attribute is added to the initial orientation of
187 builtin_polygons.
188 distortion=f sets the amount of broadening of the top and narrowing of
190 the bottom of the polygon (relative to its orientation). Floating
191 point values between -1 and +1 are suggested. This attribute is ig‐
192 nored by builtin_polygons.
193 skew=f sets the amount of right‐displacement of the top and left‐dis‐
195 placement of the bottom of the polygon (relative to its orientation).
196 Floating point values between -1 and +1 are suggested. This attribute
197 is ignored by builtin_polygons.
198 href="url" sets the url for the node in imagemap, PostScript and SVG
200 files. The substrings '\N' and '\G' are substituted in the same manner
201 as for the node label attribute. Additionally the substring '\L' is
202 substituted with the node label string.
203 URL="url" ("URL" is a synonym for "href".)
205 target="target" is a target string for client‐side imagemaps and SVG,
207 effective when nodes have a URL. The target string is used to deter‐
208 mine which window of the browser is used for the URL. Setting it to
209 "_graphviz" will open a new window if it doesn't already exist, or re‐
210 use it if it does. If the target string is empty, the default, then no
211 target attribute is included in the output. The substrings '\N' and
212 '\G' are substituted in the same manner as for the node label attri‐
213 bute. Additionally the substring '\L' is substituted with the node la‐
214 bel string.
215 tooltip="tooltip" is a tooltip string for client‐side imagemaps and
217 SVG, effective when nodes have a URL. The tooltip string defaults to
218 be the same as the label string, but this attribute permits nodes with‐
219 out labels to still have tooltips thus permitting denser graphs. The
220 substrings '\N' and '\G' are substituted in the same manner as for the
221 node label attribute. Additionally the substring '\L' is substituted
222 with the node label string.
223
227 label=text where text may include escaped newlines \n, \l, or \r for
228 centered, left, or right justified lines. If the substring '\T' is
229 found in a label it will be replaced by the tail_node name. If the
230 substring '\H' is found in a label it will be replaced by the head_node
231 name. If the substring '\E' value is found in a label it will be re‐
232 placed by: tail_node_name->head_node_name If the substring '\G' is
233 found in a label it will be replaced by the graph name. or by:
234 tail_node_name--head_node_name for undirected graphs.
235 fontsize=n sets the label type size to n points.
237 fontname=name sets the label font family name.
239 fontcolor=colorvalue sets the label text color.
241 style=solid dashed dotted bold invis
243 color=colorvalue sets the line color for edges.
245 color=colorvaluelist a ':' separated list of colorvalue creates paral‐
247 lel edges, one edge for each color.
248 dir=forward back both none controls arrow direction.
250 tailclip,headclip=false disables endpoint shape clipping.
252 href="url" sets the url for the node in imagemap, PostScript and SVG
254 files. The substrings '\T', '\H', '\E' and '\G' are substituted in the
255 same manner as for the edge label attribute. Additionally the sub‐
256 string '\L' is substituted with the edge label string.
257 URL="url" ("URL" is a synonym for "href".)
259 target="target" is a target string for client‐side imagemaps and SVG,
261 effective when edges have a URL. If the target string is empty, the
262 default, then no target attribute is included in the output. The sub‐
263 strings '\T', '\H', '\E' and '\G' are substituted in the same manner as
264 for the edge label attribute. Additionally the substring '\L' is sub‐
265 stituted with the edge label string.
266 tooltip="tooltip" is a tooltip string for client‐side imagemaps effec‐
268 tive when edges have a URL. The tooltip string defaults to be the same
269 as the edge label string. The substrings '\T', '\H', '\E' and '\G' are
270 substituted in the same manner as for the edge label attribute. Addi‐
271 tionally the substring '\L' is substituted with the edge label string.
272 arrowhead,arrowtail=none, normal, inv, dot, odot, invdot, invodot, tee,
274 empty, invempty, open, halfopen, diamond, odiamond, box, obox, crow.
275 arrowsize (norm_length=10,norm_width=5,
277 inv_length=6,inv_width=7,dot_radius=2)
278 headlabel,taillabel=string for port labels. labelfontcolor,labelfont‐
280 name,labelfontsize for head and tail labels. The substrings '\T',
281 '\H', '\E' and '\G' are substituted in the same manner as for the edge
282 label attribute. Additionally the substring '\L' is substituted with
283 the edge label string.
284 headhref="url" sets the url for the head port in imagemap, PostScript
286 and SVG files. The substrings '\T', '\H', '\E' and '\G' are substi‐
287 tuted in the same manner as for the edge label attribute. Additionally
288 the substring '\L' is substituted with the edge label string.
289 headURL="url" ("headURL" is a synonym for "headhref".)
291 headtarget="headtarget" is a target string for client‐side imagemaps
293 and SVG, effective when edge heads have a URL. The headtarget string
294 is used to determine which window of the browser is used for the URL.
295 If the headtarget string is empty, the default, then headtarget de‐
296 faults to the same value as target for the edge. The substrings '\T',
297 '\H', '\E' and '\G' are substituted in the same manner as for the edge
298 label attribute. Additionally the substring '\L' is substituted with
299 the edge label string.
300 headtooltip="tooltip" is a tooltip string for client‐side imagemaps ef‐
302 fective when head ports have a URL. The tooltip string defaults to be
303 the same as the headlabel string. The substrings '\T', '\H', and '\E'
304 are substituted in the same manner as for the edge label attribute.
305 Additionally the substring '\L' is substituted with the edge label
306 string.
307 tailhref="url" sets the url for the tail port in imagemap, PostScript
309 and SVG files. The substrings '\T', '\H', '\E' and '\G' are substi‐
310 tuted in the same manner as for the edge label attribute. Additionally
311 the substring '\L' is substituted with the edge label string.
312 tailURL="url" ("tailURL" is a synonym for "tailhref".)
314 tailtarget="tailtarget" is a target string for client‐side imagemaps
316 and SVG, effective when edge tails have a URL. The tailtarget string
317 is used to determine which window of the browser is used for the URL.
318 If the tailtarget string is empty, the default, then tailtarget de‐
319 faults to the same value as target for the edge. The substrings '\T',
320 '\H', '\E' and '\G' are substituted in the same manner as for the edge
321 label attribute. Additionally the substring '\L' is substituted with
322 the edge label string.
323 tailtooltip="tooltip" is a tooltip string for client‐side imagemaps ef‐
325 fective when tail ports have a URL. The tooltip string defaults to be
326 the same as the taillabel string. The substrings '\T', '\H', '\E' and
327 '\G' are substituted in the same manner as for the edge label attri‐
328 bute. Additionally the substring '\L' is substituted with the edge la‐
329 bel string.
330 labeldistance and port_label_distance set distance; also labelangle (in
332 degrees CCW)
333 decorate draws line from edge to label.
335 samehead,sametail aim edges having the same value to the same port, us‐
337 ing the average landing point.
338 layer=id or id:id or "all" sets the edge's active layers. The empty
340 string means no layers (invisible).
341 (neato‐specific attributes)
344 w=f sets the weight (spring constant) of an edge to the given floating
345 point value. The default is 1.0; greater values make the edge tend
346 more toward its optimal length.
347 len=f sets the optimal length of an edge. The default is 1.0.
349
351 -G sets a default graph attribute.
352 -N sets a default node attribute.
353 -E sets a default edge attribute. Example: -Gsize="7,8" -Nshape=box
354 -Efontsize=8
355 -lfile loads custom PostScript library files. Usually these define
357 custom shapes or styles. If -l is given by itself, the standard li‐
358 brary is omitted.
359 -Tlang sets the output language as described above.
361 -O automatically generate output filenames based on the input filename
363 and the -T format.
364 -ofile write output to file.
366 -x reduce graph.
368 -Lg don't use grid.
370 -LO use old attractive force.
372 -Lni set number of iterations to i.
374 -LUi set unscaled factor to i.
376 -LCv set overlap expansion factor to v.
378 -LT[*]v set temperature (temperature factor) to v.
380 -v (verbose) prints various information useful for debugging.
382 -V (version) prints version information and exits.
384 -? prints the usage and exits.
386
388 digraph test123 {
389 pack=8
390 subgraph cluster0 {
391 packmode=array
392 x y x0 y0 x1
393 subgraph cluster1 {
394 m n
395 }
396 }
397 b [shape=box];
398 c [label="hello\nworld",color=blue,fontsize=24,
399 fontname="Palatino-Italic",fontcolor=red,style=filled];
400 a -> z
401 x -> z
402 a -> b -> c;
403 a -> {x y};
404 edge [style=dashed,color=red];
405 b -> x;
406 }
407
409 Emden R. Gansner <erg@research.att.com>
410
412 This man page contains only a small amount of the information related
413 to the Graphviz layout programs. The most complete information can be
414 found at https://www.graphviz.org/documentation/, especially in the on‐
415 line reference pages. Most of these documents are also available in the
416 doc and doc/info subtrees in the source and binary distributions.
417 dot(1)
419 27 May 2009 OSAGE(1)