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), -Timap  (imagemap  files  for
37       httpd  servers  for each node or edge that has a non‐null "href" attri‐
38       bute.), -Tcmapx (client‐side imagemap for use in html and xhtml).   Ad‐
39       ditional  less  common  or  more  special‐purpose output formats can be
40       found at https://www.graphviz.org/doc/info/output.html.)
41
42       Alternative plugins providing support for a given output format can  be
43       found from the error message resulting from appending a ':' to the for‐
44       mat. e.g. -Tpng: The first plugin listed is always the default.
45

GRAPH FILE LANGUAGE

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

GRAPH ATTRIBUTES

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

NODE ATTRIBUTES

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

EDGE ATTRIBUTES

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

COMMAND LINE OPTIONS

344       -G sets a default graph attribute.
345       -N sets a default node attribute.
346       -E  sets  a  default edge attribute.  Example: -Gsize="7,8" -Nshape=box
347       -Efontsize=8
348
349       -lfile loads custom PostScript library  files.   Usually  these  define
350       custom  shapes  or  styles.  If -l is given by itself, the standard li‐
351       brary is omitted.
352
353       -Tlang sets the output language as described above.
354
355       -O automatically generate output filenames based on the input  filename
356       and the -T format.
357
358       -ofile write output to file.
359
360       -x reduce graph.
361
362       -Lg don't use grid.
363
364       -LO use old attractive force.
365
366       -Lni set number of iterations to i.
367
368       -LUi set unscaled factor to i.
369
370       -LCv set overlap expansion factor to v.
371
372       -LT[*]v set temperature (temperature factor) to v.
373
374       -v (verbose) prints various information useful for debugging.
375
376       -V (version) prints version information and exits.
377
378       -? prints the usage and exits.
379

EXAMPLES

381       graph G {
382         node[style=filled]
383         subgraph cluster0 {
384           subgraph cluster0_0 {
385             style=filled
386             fillcolor=green
387             a b[area=3 fillcolor=yellow]
388           }
389           subgraph cluster0_1 {
390              area=2
391              bgcolor=yellow
392           }
393           c [style=filled
394             fillcolor=red ]
395         }
396         subgraph cluster1 {
397           e f
398         }
399       }
400

BUGS

402       At  present,  patchwork  ignores edges, and supplies no visual clues to
403       indicate nesting.  Such clues might consist of nested boxes or  thicker
404       rectangular outlines. In addition, it would be good if some cluster la‐
405       bel could be displayed.
406
407       Patchwork has no mechanism for fitting labels within the supplied box.
408

AUTHORS

410       Emden R. Gansner <erg@graphviz.org>
411       Yifan Hu <yifanhu@yahoo.com>
412