patchwork(1)

1PATCHWORK(1)                General Commands Manual               PATCHWORK(1)
2
3
4

NAME

6       patchwork - filter for drawing clustered graphs as treemaps
7

SYNOPSIS

9       patchwork  [-(G|N|E)name=value]  [-Tlang]  [-llibfile] [-ooutfile] [-O]
10       [-P] [-v] [-V] [files]
11

DESCRIPTION

13       patchwork draws clustered graphs using a squarified treemap layout.  As
14       input,  it  takes any graph in the dot format. Each cluster is given an
15       area based on the areas specified by the clusters  and  nodes  it  con‐
16       tains.  The  areas  of nodes and empty clusters can be specified by the
17       area attribute.  The default value is 1.
18
19       The root graph is laid out as a square. Then, recursively,  the  region
20       of  a  cluster  or  graph  is partitioned among its top-level nodes and
21       clusters, with each given a roughly square subregion with its specified
22       area.
23

OUTPUT FORMATS

25       Patchwork uses an extensible plugin mechanism for its output renderers,
26       so to see what output formats your installation of  patchwork  supports
27       you  can  use ``patchwork -Txxx'' (where xxx is an unlikely format) and
28       check the warning message.  Also, The plugin mechanism supports  multi‐
29       ple  implementations  of  the output formats.  To see what variants are
30       available, use, for example: ``patchwork -Tpng:'' and to force  a  par‐
31       ticular variant, use, for example: ``patchwork -Tpng:gd''
32
33       Traditionally,  patchwork  supports  the  following: -Tps (PostScript),
34       -Tsvg -Tsvgz (Structured Vector Graphics), -Tfig (XFIG graphics), -Tmif
35       (FrameMaker  graphics),  -Thpgl  (HP pen plotters), and -Tpcl (Laserjet
36       printers), -Tpng -Tgif (bitmap graphics), -Tdia (GTK+ based  diagrams),
37       -Timap (imagemap files for httpd servers for each node or edge that has
38       a non‐null "href" attribute.), -Tcmapx (client‐side imagemap for use in
39       html and xhtml).  Additional less common or more special‐purpose output
40       formats  can  be  found  at   http://www.graphviz.org/cvs/doc/info/out‐
41       put.html.)
42
43       Alternative  plugins providing support for a given output format can be
44       found from the error message resulting from appending a ':' to the for‐
45       mat. e.g. -Tpng: The first plugin listed is always the default.
46

GRAPH FILE LANGUAGE

48       Here  is  a  synopsis  of  the  graph file language, normally using the
49       extension .gv, for graphs:
50
51       [strict] (graph|digraph) name { statement‐list }
52       Is the top level graph. If the graph is strict then multiple edges  are
53       not  allowed  between  the  same  pairs  of nodes.  If it is a directed
54       graph, indicated by digraph, then the edgeop must be "->". If it is  an
55       undirected graph then the edgeop must be "--".  Statements may be:
56
57       name=val;
58       node [name=val];
59       edge [name=val];
60       Set  default graph, node, or edge attribute name to val.  Any subgraph,
61       node, or edge appearing after this inherits the new default attributes.
62
63       n0 [name0=val0,name1=val1,...]; Creates node n0 (if it does not already
64       exist) and sets its attributes according to the optional list.
65
66       n0 edgeop n1 edgeop ... edgeop nn [name0=val0,name1=val1,...];
67       Creates  edges  between nodes n0, n1, ..., nn and sets their attributes
68       according to the optional list.  Creates nodes as necessary.
69
70       [subgraph name] { statement‐list }
71       Creates a subgraph.  Subgraphs may be used in place of n0, ...,  nn  in
72       the  above statements to create edges.  [subgraph name] is optional; if
73       missing, the subgraph is assigned an internal name.
74
75       Comments may be /*C‐like*/ or //C++‐like.
76
77
78       Attribute names and values are ordinary (C‐style) strings.  The follow‐
79       ing sections describe attributes that control graph layout.
80
81

GRAPH ATTRIBUTES

83       size="x,y" sets bounding box of drawing in inches.
84
85       page="x,y" sets the PostScript pagination unit.
86
87       ratio=f  sets  the aspect ratio to f which may be a floating point num‐
88       ber, or one of the keywords fill, compress, or auto.
89
90       pagedir=[TBLR][TBLR] sets the major and minor order of pagination.
91
92       rotate=90 sets landscape mode.  (orientation=land is backward  compati‐
93       ble but obsolete.)
94
95       center=n a non‐zero value centers the drawing on the page.
96
97       layers="id:id:id:id"  is  a  sequence  of layer identifiers for overlay
98       diagrams.  The PostScript array variable layercolorseq sets the assign‐
99       ment of colors to layers. The least index is 1 and each element must be
100       a 3‐element array to be interpreted as a color coordinate.
101
102       color=colorvalue sets foreground color (bgcolor for background).
103
104       href="url" the default url for image map files;  in  PostScript  files,
105       the  base URL for all relative URLs, as recognized by Acrobat Distiller
106       3.0 and up.
107
108       URL="url" ("URL" is a synonym for "href".)
109
110       stylesheet="file.css" includes a reference to a stylesheet in -Tsvg and
111       -Tsvgz outputs.  Ignored by other formats.
112
113       splines.  If  set to true, edges are drawn as splines.  If set to poly‐
114       line, edges are drawn as polylines.  If set to ortho, edges  are  drawn
115       as  orthogonal  polylines.   In  all  of these cases, the nodes may not
116       overlap.  If splines=false or splines=line, edges  are  drawn  as  line
117       segments.  The default is false.
118
119

NODE ATTRIBUTES

121       height=d  or  width=d  sets  minimum  height  or  width.  Adding fixed‐
122       size=true forces these to be the actual size (text labels are ignored).
123
124       shape=record polygon epsf builtin_polygon
125       builtin_polygon is one of: plaintext ellipse oval circle  egg  triangle
126       box  diamond  trapezium  parallelogram  house  hexagon octagon note tab
127       box3d component.  (Polygons are defined or modified  by  the  following
128       node  attributes:  regular, peripheries, sides, orientation, distortion
129       and skew.)  epsf uses the node's shapefile attribute as the  path  name
130       of an external EPSF file to be automatically loaded for the node shape.
131
132       label=text  where  text  may include escaped newlines \n, \l, or \r for
133       center, left, and right justified lines.  The string '\N' value will be
134       replaced  by  the node name.  The string '\G' value will be replaced by
135       the graph name.  Record labels may contain recursive box  lists  delim‐
136       ited  by { | }.  Port identifiers in labels are set off by angle brack‐
137       ets < >.  In the graph file, use colon (such as, node0:port28).
138
139       fontsize=n sets the label type size to n points.
140
141       fontname=name sets the label font family name.
142
143       color=colorvalue sets the outline color, and the default fill color  if
144       style=filled and fillcolor is not specified.
145
146       fillcolor=colorvalue  sets  the  fill  color when style=filled.  If not
147       specified, the fillcolor when style=filled defaults to be the  same  as
148       the outline color.
149
150       fontcolor=colorvalue sets the label text color.
151
152       A  colorvalue  may  be  "h,s,v"  (hue, saturation, brightness) floating
153       point numbers between 0 and 1, or an X11 color name such as white black
154       red  green  blue yellow magenta cyan or burlywood, or a "#rrggbb" (red,
155       green, blue, 2 hex characters each) value.
156
157       style=filled solid dashed dotted bold invis or any Postscript code.
158
159       layer=id or id:id or "all" sets the node's active  layers.   The  empty
160       string means no layers (invisible).
161
162       The following attributes apply only to polygon shape nodes:
163
164       regular=n  if n is non‐zero then the polygon is made regular, i.e. sym‐
165       metric about the x and y axis,  otherwise  the  polygon  takes  on  the
166       aspect ratio of the label.  builtin_polygons that are not already regu‐
167       lar are made regular by  this  attribute.   builtin_polygons  that  are
168       already  regular  are  not affected (i.e.  they cannot be made asymmet‐
169       ric).
170
171       peripheries=n sets the number of periphery lines drawn around the poly‐
172       gon.    This   value  supersedes  the  number  of  periphery  lines  of
173       builtin_polygons.
174
175       sides=n sets the number of sides to the  polygon.  n<3  results  in  an
176       ellipse.  This attribute is ignored by builtin_polygons.
177
178       orientation=f  sets  the  orientation  of the first apex of the polygon
179       counterclockwise from the vertical, in degrees.  f may  be  a  floating
180       point  number.   The  orientation  of  labels  is  not affected by this
181       attribute.  This attribute is  added  to  the  initial  orientation  of
182       builtin_polygons.
183
184       distortion=f  sets the amount of broadening of the top and narrowing of
185       the bottom of the polygon  (relative  to  its  orientation).   Floating
186       point  values  between  -1  and  +1  are  suggested.  This attribute is
187       ignored by builtin_polygons.
188
189       skew=f sets the amount of right‐displacement of the top  and  left‐dis‐
190       placement  of  the bottom of the polygon (relative to its orientation).
191       Floating point values between -1 and +1 are suggested.  This  attribute
192       is ignored by builtin_polygons.
193
194       href="url"  sets  the  url for the node in imagemap, PostScript and SVG
195       files.  The substrings '\N' and '\G' are substituted in the same manner
196       as  for  the  node label attribute.  Additionally the substring '\L' is
197       substituted with the node label string.
198
199       URL="url" ("URL" is a synonym for "href".)
200
201       target="target" is a target string for client‐side imagemaps  and  SVG,
202       effective  when  nodes have a URL.  The target string is used to deter‐
203       mine which window of the browser is used for the URL.   Setting  it  to
204       "_graphviz"  will open a new window if it doesn't already exist, or re‐
205       use it if it does.  If the target string is empty, the default, then no
206       target  attribute  is  included in the output.  The substrings '\N' and
207       '\G' are  substituted  in  the  same  manner  as  for  the  node  label
208       attribute.   Additionally  the  substring  '\L' is substituted with the
209       node label string.
210
211       tooltip="tooltip" is a tooltip string  for  client‐side  imagemaps  and
212       SVG,  effective  when nodes have a URL.  The tooltip string defaults to
213       be the same as the label string, but this attribute permits nodes with‐
214       out  labels  to still have tooltips thus permitting denser graphs.  The
215       substrings '\N' and '\G' are substituted in the same manner as for  the
216       node  label  attribute.  Additionally the substring '\L' is substituted
217       with the node label string.
218
219
220

EDGE ATTRIBUTES

222       label=text where text may include escaped newlines \n, \l,  or  \r  for
223       centered,  left,  or  right  justified lines.  If the substring '\T' is
224       found in a label it will be replaced by the  tail_node  name.   If  the
225       substring '\H' is found in a label it will be replaced by the head_node
226       name.  If the substring '\E' value is found  in  a  label  it  will  be
227       replaced  by:  tail_node_name->head_node_name  If the substring '\G' is
228       found in a label it will  be  replaced  by  the  graph  name.   or  by:
229       tail_node_name--head_node_name for undirected graphs.
230
231       fontsize=n sets the label type size to n points.
232
233       fontname=name sets the label font family name.
234
235       fontcolor=colorvalue sets the label text color.
236
237       style=solid dashed dotted bold invis
238
239       color=colorvalue sets the line color for edges.
240
241       color=colorvaluelist  a ':' separated list of colorvalue creates paral‐
242       lel edges, one edge for each color.
243
244       dir=forward back both none controls arrow direction.
245
246       tailclip,headclip=false disables endpoint shape clipping.
247
248       href="url" sets the url for the node in imagemap,  PostScript  and  SVG
249       files.  The substrings '\T', '\H', '\E' and '\G' are substituted in the
250       same manner as for the edge label  attribute.   Additionally  the  sub‐
251       string '\L' is substituted with the edge label string.
252
253       URL="url" ("URL" is a synonym for "href".)
254
255       target="target"  is  a target string for client‐side imagemaps and SVG,
256       effective when edges have a URL.  If the target string  is  empty,  the
257       default,  then no target attribute is included in the output.  The sub‐
258       strings '\T', '\H', '\E' and '\G' are substituted in the same manner as
259       for  the edge label attribute.  Additionally the substring '\L' is sub‐
260       stituted with the edge label string.
261
262       tooltip="tooltip" is a tooltip string for client‐side imagemaps  effec‐
263       tive when edges have a URL.  The tooltip string defaults to be the same
264       as the edge label string.  The substrings '\T', '\H', '\E' and '\G' are
265       substituted  in the same manner as for the edge label attribute.  Addi‐
266       tionally the substring '\L' is substituted with the edge label string.
267
268       arrowhead,arrowtail=none, normal, inv, dot, odot, invdot, invodot, tee,
269       empty, invempty, open, halfopen, diamond, odiamond, box, obox, crow.
270
271       arrowsize                                 (norm_length=10,norm_width=5,
272       inv_length=6,inv_width=7,dot_radius=2)
273
274       headlabel,taillabel=string for port labels.   labelfontcolor,labelfont‐
275       name,labelfontsize  for  head  and  tail  labels.  The substrings '\T',
276       '\H', '\E' and '\G' are substituted in the same manner as for the  edge
277       label  attribute.   Additionally the substring '\L' is substituted with
278       the edge label string.
279
280       headhref="url" sets the url for the head port in  imagemap,  PostScript
281       and  SVG  files.   The substrings '\T', '\H', '\E' and '\G' are substi‐
282       tuted in the same manner as for the edge label attribute.  Additionally
283       the substring '\L' is substituted with the edge label string.
284
285       headURL="url" ("headURL" is a synonym for "headhref".)
286
287       headtarget="headtarget"  is  a  target string for client‐side imagemaps
288       and SVG, effective when edge heads have a URL.  The  headtarget  string
289       is  used  to determine which window of the browser is used for the URL.
290       If the  headtarget  string  is  empty,  the  default,  then  headtarget
291       defaults  to  the  same  value  as target for the edge.  The substrings
292       '\T', '\H', '\E' and '\G' are substituted in the same manner as for the
293       edge  label  attribute.  Additionally the substring '\L' is substituted
294       with the edge label string.
295
296       headtooltip="tooltip" is a tooltip  string  for  client‐side  imagemaps
297       effective  when  head ports have a URL.  The tooltip string defaults to
298       be the same as the headlabel string.  The substrings  '\T',  '\H',  and
299       '\E'  are  substituted  in  the  same  manner  as  for  the  edge label
300       attribute.  Additionally the substring '\L'  is  substituted  with  the
301       edge label string.
302
303       tailhref="url"  sets  the url for the tail port in imagemap, PostScript
304       and SVG files.  The substrings '\T', '\H', '\E' and  '\G'  are  substi‐
305       tuted in the same manner as for the edge label attribute.  Additionally
306       the substring '\L' is substituted with the edge label string.
307
308       tailURL="url" ("tailURL" is a synonym for "tailhref".)
309
310       tailtarget="tailtarget" is a target string  for  client‐side  imagemaps
311       and  SVG,  effective when edge tails have a URL.  The tailtarget string
312       is used to determine which window of the browser is used for  the  URL.
313       If  the  tailtarget  string  is  empty,  the  default,  then tailtarget
314       defaults to the same value as target  for  the  edge.   The  substrings
315       '\T', '\H', '\E' and '\G' are substituted in the same manner as for the
316       edge label attribute.  Additionally the substring '\L'  is  substituted
317       with the edge label string.
318
319       tailtooltip="tooltip"  is  a  tooltip  string for client‐side imagemaps
320       effective when tail ports have a URL.  The tooltip string  defaults  to
321       be  the  same as the taillabel string.  The substrings '\T', '\H', '\E'
322       and '\G' are substituted in the same  manner  as  for  the  edge  label
323       attribute.   Additionally  the  substring  '\L' is substituted with the
324       edge label string.
325
326       labeldistance and port_label_distance set distance; also labelangle (in
327       degrees CCW)
328
329       decorate draws line from edge to label.
330
331       samehead,sametail  aim  edges  having  the same value to the same port,
332       using the average landing point.
333
334       layer=id or id:id or "all" sets the edge's active  layers.   The  empty
335       string means no layers (invisible).
336
337
338       (neato‐specific attributes)
339       w=f  sets the weight (spring constant) of an edge to the given floating
340       point value.  The default is 1.0; greater values  make  the  edge  tend
341       more toward its optimal length.
342
343       len=f sets the optimal length of an edge.  The default is 1.0.
344

COMMAND LINE OPTIONS

346       -G sets a default graph attribute.
347       -N sets a default node attribute.
348       -E  sets  a  default edge attribute.  Example: -Gsize="7,8" -Nshape=box
349       -Efontsize=8
350
351       -lfile loads custom PostScript library  files.   Usually  these  define
352       custom  shapes  or  styles.   If  -l  is  given by itself, the standard
353       library is omitted.
354
355       -Tlang sets the output language as described above.
356
357       -O automatically generate output filenames based on the input  filename
358       and the -T format.
359
360       -v (verbose) prints various information useful for debugging.
361
362       -V (version) prints version information and exits.
363
364       -? prints the usage and exits.
365

EXAMPLES

367       graph G {
368         node[style=filled]
369         subgraph cluster0 {
370           subgraph cluster0_0 {
371             style=filled
372             fillcolor=green
373             a b[area=3 fillcolor=yellow]
374           }
375           subgraph cluster0_1 {
376              area=2
377              bgcolor=yellow
378           }
379           c [style=filled
380             fillcolor=red ]
381         }
382         subgraph cluster1 {
383           e f
384         }
385       }
386

BUGS

388       At  present,  patchwork  ignores edges, and supplies no visual clues to
389       indicate nesting.  Such clues might consist of nested boxes or  thicker
390       rectangular  outlines.  In  addition,  it would be good if some cluster
391       label could be displayed.
392
393       Patchwork has no mechanism for fitting labels within the supplied box.
394

AUTHORS

396       Emden R. Gansner <erg@research.att.com>
397       Yifan Hu <yifanhu@research.att.com>
398