Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/graph/doc/write-graphviz.html @ 47

Last change on this file since 47 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 11.5 KB
Line 
1<HTML>
2
3<!--
4  -- Copyright (c) Lie-Quan Lee and Jeremy Siek 2000, 2001
5  --
6  -- Distributed under the Boost Software License, Version 1.0.
7  -- (See accompanying file LICENSE_1_0.txt or copy at
8  -- http://www.boost.org/LICENSE_1_0.txt)
9  -->
10<Head>
11<Title>Boost Graph Library: write graphviz</Title>
12<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b" 
13        ALINK="#ff0000"> 
14<IMG SRC="../../../boost.png" 
15     ALT="C++ Boost" width="277" height="86"> 
16
17<BR Clear>
18
19<H1><A NAME="sec:write-graphviz">
20<TT>write_graphviz</TT>
21</H1>
22
23
24<pre>
25// Output graph structure without properties.
26template &lt; typename VertexListGraph &gt;
27void
28write_graphviz(std::ostream&amp; out, const VertexListGraph&amp; g);
29
30// Graph structure with customized property output
31template &lt; typename VertexListGraph, typename VertexPropertyWriter &gt;
32void
33write_graphviz(std::ostream&amp; out, const VertexListGraph&amp; g,
34               VertexPropertyWriter vpw);
35
36template &lt; typename VertexListGraph, typename VertexPropertyWriter,
37           typename EdgePropertyWriter &gt;
38void
39write_graphviz(std::ostream&amp; out, const VertexListGraph&amp; g,
40               VertexPropertyWriter vpw, EdgePropertyWriter epw);
41
42template &lt; typename VertexListGraph, typename VertexPropertyWriter,
43           typename EdgePropertyWriter, typename GraphPropertyWriter &gt;
44void
45write_graphviz(std::ostream&amp; out, const VertexListGraph&amp; g,
46               VertexPropertyWriter vpw, EdgePropertyWriter epw,
47               GraphPropertyWriter gpw);
48
49template &lt; typename VertexListGraph, typename VertexPropertyWriter,
50           typename EdgePropertyWriter, typename GraphPropertyWriter,
51           typename VertexID &gt;
52void
53write_graphviz(std::ostream&amp; out, const VertexListGraph&amp; g,
54               VertexPropertyWriter vpw, EdgePropertyWriter epw,
55               GraphPropertyWriter gpw, VertexID vertex_id);
56
57// Graph structure with dynamic property output
58template&lt;typename Graph&gt;
59void
60write_graphviz(std::ostream&amp; out, const Graph&amp; g,
61               const dynamic_properties&amp; dp,
62               const std::string&amp; node_id = "node_id");
63
64template&lt;typename Graph, typename VertexID&gt;
65void
66write_graphviz(std::ostream&amp; out, const Graph&amp; g,
67               const dynamic_properties&amp; dp, const std::string&amp; node_id,
68               VertexID vertex_id);
69</pre>
70
71<p>
72This is to write a BGL graph object into an output stream in graphviz
73dot format so that users can make use of <a href="http://www.research.att.com/sw/tools/graphviz/">AT&amp;T graphviz</a> to draw a
74picture with nice layout.
75<p>
76The first version with two parameters will write the graph into a
77<tt>std::ostream</tt> where each vertex is represented by its numerical vertex
78ID. If users have either interior or exterior properties for each vertex
79in the graph, the second version above provides a way to print those
80properties into the graphviz format file. For example, if each vertex
81in the graph has its label through property map object <tt>name</tt>,
82users can use the second version:
83<pre>
84  write_graph(out, g, make_label_writer(name));
85</pre>
86The utility function <tt>make_label_writer</tt> returns a predefined
87<a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> for
88vertex labels.  Similarly, the third
89version and fourth version require vertex
90<a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a>, edge
91<a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a>, and graph
92<a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a>,
93respectively.
94
95<p> The final two overloads of <code>write_graphviz</code> will emit
96all of the properties stored in the <a
97href="../../property_map/doc/dynamic_property_map.html"><code>dynamic_properties</a></code>
98object, thereby retaining the properties that have been read in
99through the dual function <a
100href="read_graphviz.html"><code>read_graphviz</code></a>. With these
101overloads, <code>node_id</code> is the name of the property map that
102stores the IDs of each node for use in the output (if it is stored in
103the <code>dynamic_properties</code> structure); alternatively, one may
104provide an arbitrary property map for <code>vertex_id</code> giving the
105vertex identifiers.</p>
106
107<H3>Where Defined</H3>
108
109<P>
110<a href="../../../boost/graph/graphviz.hpp"><TT>boost/graph/graphviz.hpp</TT></a>
111
112<h3><A NAME="concept:PropertyWriter">
113<tt>PropertyWriter</tt>
114</h3>
115
116PropertyWriter is used in the <tt>write_graphviz</tt> function to
117print properties of vertex, edge or graph. There are two types of
118PropertyWriter. One is for a vertex or edge. The other is for a graph.
119Thus, users could easily extend the <tt>write_graphviz</tt> function
120by creating their own <a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> only.
121<p>
122A <a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> 
123for vertices or edges is a functor which can be called with two parameters:
124<tt>std::ostream</tt> and either a vertex or an edge descriptor. It should output a
125pair of brackets with a series of assigments &quot;name=value&quot; inside.
126Each assignment should be separated either with space, with comma, or with semicolon.
127The following functor, provided by BGL, is the example of PropertyWriter for
128vertices or edges.  It is used to print the label of each vertex or edge.
129<pre>
130  template < class Name >
131  class label_writer {
132  public:
133    label_writer(Name _name) : name(_name) {}
134    template <class VertexOrEdge>
135    void operator()(std::ostream& out, const VertexOrEdge& v) const {
136      out << "[label=\"" << name[v] << "\"]";
137    }
138  private:
139    Name name;
140  };
141</pre>
142
143<p>
144A function to conveniently create this writer is provided:
145<pre>
146template &lt; class Name &gt;
147label_writer&lt;Name&gt;
148make_label_writer(Name n);
149</pre>
150
151<p>
152A <a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> 
153for graphs is a functor which is called with one parameter of type
154<tt>std::ostream</tt> and should print a series of graph properties. The following
155code excerpt is an example of a PropertyWriter for a graph.
156<pre>
157  struct sample_graph_writer {
158    void operator()(std::ostream& out) const {
159      out << "graph [bgcolor=lightgrey]" << std::endl;
160      out << "node [shape=circle color=white]" << std::endl;
161      out << "edge [style=dashed]" << std::endl;
162    }
163  };
164}
165</pre>
166
167<p>
168There exists a class <tt>default_writer</tt>, which can be used as both
169vertex/edge and graph property writer, and does nothing. It comes handy when
170only edge properties must be written, but function interface requries to pass
171vertex property writer as well.
172
173<h3>Parameters</h3>
174 OUT: <tt>std::ostream&amp; out</tt>
175<blockquote>
176  A standard <tt>std::ostream</tt> object.
177</blockquote> 
178
179 IN: <tt>VertexListGraph&amp; g</tt>
180<blockquote>
181  A directed or undirected graph.  The graph's type must be a model of
182  <a href="./VertexListGraph.html">VertexListGraph</a>. Also the graph
183  must have an internal <tt>vertex_index</tt> property map.
184</blockquote> 
185
186 IN: <tt>VertexPropertyWriter vpw</tt>
187<blockquote>
188  A functor that models <a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> concept to print
189  properties of a vertex.<br>
190<b>Default</b>: <tt>default_writer()</tt>
191</blockquote> 
192
193 IN: <tt>EdgePropertyWriter epw</tt>
194<blockquote>
195  A functor that models <a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> concept to print
196  properties of an edge.<br>
197<b>Default</b>: <tt>default_writer()</tt>
198</blockquote> 
199
200 IN: <tt>GraphPropertyWriter epw</tt>
201<blockquote>
202  A functor that models <a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> concept to print
203  properties of a graph.<br>
204<b>Default</b>: <tt>default_writer()</tt>
205</blockquote>
206
207IN: <tt>dynamic_properties& dp</tt>
208<blockquote>
209  Contains all of the vertex and edge properties that should be
210  emitted by the GraphViz writer.
211</blockquote>
212
213IN: <tt>const std::string& node_id</tt>
214<blockquote>
215  The name of the property map that provides identifiers for the
216  vertices in the graph.<br>
217<b>Default</b>: <tt>"node_id"</tt>
218</blockquote>
219
220IN: <tt>VertexID vertex_id</tt>
221<blockquote>
222  A property map that models <a href="../../property_map/ReadablePropertyMap.html">Readable Property Map</a> whose key type is the vertex descriptor of the graph and whose value type can be written to a stream. The value should be a unique descriptor that can be used to name a node in a Graphviz file (so it should not, for instance, have any spaces in it).<br>
223<b>Default</b>: If no <code>dynamic_properties</code> object is provided, <tt>get(vertex_index, g)</tt>. Otherwise, a dynamic property map that accesses the property map named <code>node_id</code>.
224</blockquote>
225<H3>
226Example
227</H3>
228
229This example demonstrates using BGL-graphviz interface to write
230a BGL graph into a graphviz format file.
231
232<pre>
233#include &lt;boost/graph/graphviz.hpp&gt;
234
235enum files_e { dax_h, yow_h, boz_h, zow_h, foo_cpp,
236               foo_o, bar_cpp, bar_o, libfoobar_a,
237               zig_cpp, zig_o, zag_cpp, zag_o,
238                 libzigzag_a, killerapp, N };
239const char* name[] = { "dax.h", "yow.h", "boz.h", "zow.h", "foo.cpp",
240                       "foo.o", "bar.cpp", "bar.o", "libfoobar.a",
241                       "zig.cpp", "zig.o", "zag.cpp", "zag.o",
242                       "libzigzag.a", "killerapp" };
243
244int main(int,char*[])
245{
246   
247  typedef pair&lt;int,int&gt; Edge;
248  Edge used_by[] = {
249    Edge(dax_h, foo_cpp), Edge(dax_h, bar_cpp), Edge(dax_h, yow_h),
250    Edge(yow_h, bar_cpp), Edge(yow_h, zag_cpp),
251    Edge(boz_h, bar_cpp), Edge(boz_h, zig_cpp), Edge(boz_h, zag_cpp),
252    Edge(zow_h, foo_cpp),
253    Edge(foo_cpp, foo_o),
254    Edge(foo_o, libfoobar_a),
255    Edge(bar_cpp, bar_o),
256    Edge(bar_o, libfoobar_a),
257    Edge(libfoobar_a, libzigzag_a),
258    Edge(zig_cpp, zig_o),
259    Edge(zig_o, libzigzag_a),
260    Edge(zag_cpp, zag_o),
261    Edge(zag_o, libzigzag_a),
262    Edge(libzigzag_a, killerapp)
263  };
264  const int nedges = sizeof(used_by)/sizeof(Edge);
265  int weights[nedges];
266  std::fill(weights, weights + nedges, 1);
267
268  using namespace boost;
269
270  typedef adjacency_list< vecS, vecS, directedS, 
271      property< vertex_color_t, default_color_type >,
272      property< edge_weight_t, int >
273    > Graph;
274  Graph g(used_by, used_by + nedges, weights, N);
275
276  write_graphviz(std::cout, g, make_label_writer(name));
277}
278</pre>
279
280The output will be:
281<pre>
282digraph G {
2830 -> 4;
2840 -> 6;
2850 -> 1;
2860 [label="dax.h"];
2871 -> 6;
2881 -> 11;
2891 [label="yow.h"];
2902 -> 6;
2912 -> 9;
2922 -> 11;
2932 [label="boz.h"];
2943 -> 4;
2953 [label="zow.h"];
2964 -> 5;
2974 [label="foo.cpp"];
2985 -> 8;
2995 [label="foo.o"];
3006 -> 7;
3016 [label="bar.cpp"];
3027 -> 8;
3037 [label="bar.o"];
3048 -> 13;
3058 [label="libfoobar.a"];
3069 -> 10;
3079 [label="zig.cpp"];
30810 -> 13;
30910 [label="zig.o"];
31011 -> 12;
31111 [label="zag.cpp"];
31212 -> 13;
31312 [label="zag.o"];
31413 -> 14;
31513 [label="libzigzag.a"];
31614;
31714 [label="killerapp"];
318edge[style="dotted"];
3196 -> 0;
320}
321</pre>
322
323<p>The examples directory contains an <a
324href="../example/graphviz.cpp">example using
325<code>dynamic_properties</code></a>.</p>
326
327<h3>See Also</h3>
328
329<a href="./read_graphviz.html"><tt>read_graphviz</tt></a>
330
331<h3>Notes</h3>
332Note that you can use Graphviz dot file write facilities
333without the library <tt>libbglviz.a</tt>.
334
335<br>
336<HR>
337<TABLE>
338<TR valign=top>
339<TD nowrap>Copyright &copy 2000-2001</TD><TD>
340<A HREF="../../../people/liequan_lee.htm">Lie-Quan Lee</A>, Indiana University (<A HREF="mailto:llee@cs.indiana.edu">llee@cs.indiana.edu</A>)<br>
341<A HREF="../../../people/jeremy_siek.htm">Jeremy Siek</A>, Indiana University (<A HREF="mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</A>)
342</TD></TR></TABLE>
343
344</BODY>
345</HTML> 
Note: See TracBrowser for help on using the repository browser.