Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/graph/doc/write-graphviz.html @ 12

Last change on this file since 12 was 12, checked in by landauf, 18 years ago

added boost
File size: 11.8 KB
RevLine 
[12]1<HTML>
2
3<!--
4  -- Copyright (c) Lie-Quan Lee and Jeremy Siek 2000, 2001
5  --
6  -- Permission to use, copy, modify, distribute and sell this software
7  -- and its documentation for any purpose is hereby granted without fee,
8  -- provided that the above copyright notice appears in all copies and
9  -- that both that copyright notice and this permission notice appear
10  -- in supporting documentation.  Silicon Graphics makes no
11  -- representations about the suitability of this software for any
12  -- purpose.  It is provided "as is" without express or implied warranty.
13  -->
14<Head>
15<Title>Boost Graph Library: write graphviz</Title>
16<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b" 
17        ALINK="#ff0000"> 
18<IMG SRC="../../../boost.png" 
19     ALT="C++ Boost" width="277" height="86"> 
20
21<BR Clear>
22
23<H1><A NAME="sec:write-graphviz">
24<TT>write_graphviz</TT>
25</H1>
26
27
28<pre>
29// Output graph structure without properties.
30template &lt; typename VertexListGraph &gt;
31void
32write_graphviz(std::ostream&amp; out, const VertexListGraph&amp; g);
33
34// Graph structure with customized property output
35template &lt; typename VertexListGraph, typename VertexPropertyWriter &gt;
36void
37write_graphviz(std::ostream&amp; out, const VertexListGraph&amp; g,
38               VertexPropertyWriter vpw);
39
40template &lt; typename VertexListGraph, typename VertexPropertyWriter,
41           typename EdgePropertyWriter &gt;
42void
43write_graphviz(std::ostream&amp; out, const VertexListGraph&amp; g,
44               VertexPropertyWriter vpw, EdgePropertyWriter epw);
45
46template &lt; typename VertexListGraph, typename VertexPropertyWriter,
47           typename EdgePropertyWriter, typename GraphPropertyWriter &gt;
48void
49write_graphviz(std::ostream&amp; out, const VertexListGraph&amp; g,
50               VertexPropertyWriter vpw, EdgePropertyWriter epw,
51               GraphPropertyWriter gpw);
52
53template &lt; typename VertexListGraph, typename VertexPropertyWriter,
54           typename EdgePropertyWriter, typename GraphPropertyWriter,
55           typename VertexID &gt;
56void
57write_graphviz(std::ostream&amp; out, const VertexListGraph&amp; g,
58               VertexPropertyWriter vpw, EdgePropertyWriter epw,
59               GraphPropertyWriter gpw, VertexID vertex_id);
60
61// Graph structure with dynamic property output
62template&lt;typename Graph&gt;
63void
64write_graphviz(std::ostream&amp; out, const Graph&amp; g,
65               const dynamic_properties&amp; dp,
66               const std::string&amp; node_id = "node_id");
67
68template&lt;typename Graph, typename VertexID&gt;
69void
70write_graphviz(std::ostream&amp; out, const Graph&amp; g,
71               const dynamic_properties&amp; dp, const std::string&amp; node_id,
72               VertexID vertex_id);
73</pre>
74
75<p>
76This is to write a BGL graph object into an output stream in graphviz
77dot 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
78picture with nice layout.
79<p>
80The first version with two parameters will write the graph into a
81<tt>std::ostream</tt> where each vertex is represented by its numerical vertex
82ID. If users have either interior or exterior properties for each vertex
83in the graph, the second version above provides a way to print those
84properties into the graphviz format file. For example, if each vertex
85in the graph has its label through property map object <tt>name</tt>,
86users can use the second version:
87<pre>
88  write_graph(out, g, make_label_writer(name));
89</pre>
90The utility function <tt>make_label_writer</tt> returns a predefined
91<a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> for
92vertex labels.  Similarly, the third
93version and fourth version require vertex
94<a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a>, edge
95<a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a>, and graph
96<a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a>,
97respectively.
98
99<p> The final two overloads of <code>write_graphviz</code> will emit
100all of the properties stored in the <a
101href="../../property_map/doc/dynamic_property_map.html"><code>dynamic_properties</a></code>
102object, thereby retaining the properties that have been read in
103through the dual function <a
104href="read_graphviz.html"><code>read_graphviz</code></a>. With these
105overloads, <code>node_id</code> is the name of the property map that
106stores the IDs of each node for use in the output (if it is stored in
107the <code>dynamic_properties</code> structure); alternatively, one may
108provide an arbitrary property map for <code>vertex_id</code> giving the
109vertex identifiers.</p>
110
111<H3>Where Defined</H3>
112
113<P>
114<a href="../../../boost/graph/graphviz.hpp"><TT>boost/graph/graphviz.hpp</TT></a>
115
116<h3><A NAME="concept:PropertyWriter">
117<tt>PropertyWriter</tt>
118</h3>
119
120PropertyWriter is used in the <tt>write_graphviz</tt> function to
121print properties of vertex, edge or graph. There are two types of
122PropertyWriter. One is for a vertex or edge. The other is for a graph.
123Thus, users could easily extend the <tt>write_graphviz</tt> function
124by creating their own <a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> only.
125<p>
126A <a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> 
127for vertices or edges is a functor which can be called with two parameters:
128<tt>std::ostream</tt> and either a vertex or an edge descriptor. It should output a
129pair of brackets with a series of assigments &quot;name=value&quot; inside.
130Each assignment should be separated either with space, with comma, or with semicolon.
131The following functor, provided by BGL, is the example of PropertyWriter for
132vertices or edges.  It is used to print the label of each vertex or edge.
133<pre>
134  template < class Name >
135  class label_writer {
136  public:
137    label_writer(Name _name) : name(_name) {}
138    template <class VertexOrEdge>
139    void operator()(std::ostream& out, const VertexOrEdge& v) const {
140      out << "[label=\"" << name[v] << "\"]";
141    }
142  private:
143    Name name;
144  };
145</pre>
146
147<p>
148A function to conveniently create this writer is provided:
149<pre>
150template &lt; class Name &gt;
151label_writer&lt;Name&gt;
152make_label_writer(Name n);
153</pre>
154
155<p>
156A <a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> 
157for graphs is a functor which is called with one parameter of type
158<tt>std::ostream</tt> and should print a series of graph properties. The following
159code excerpt is an example of a PropertyWriter for a graph.
160<pre>
161  struct sample_graph_writer {
162    void operator()(std::ostream& out) const {
163      out << "graph [bgcolor=lightgrey]" << std::endl;
164      out << "node [shape=circle color=white]" << std::endl;
165      out << "edge [style=dashed]" << std::endl;
166    }
167  };
168}
169</pre>
170
171<p>
172There exists a class <tt>default_writer</tt>, which can be used as both
173vertex/edge and graph property writer, and does nothing. It comes handy when
174only edge properties must be written, but function interface requries to pass
175vertex property writer as well.
176
177<h3>Parameters</h3>
178 OUT: <tt>std::ostream&amp; out</tt>
179<blockquote>
180  A standard <tt>std::ostream</tt> object.
181</blockquote> 
182
183 IN: <tt>VertexListGraph&amp; g</tt>
184<blockquote>
185  A directed or undirected graph.  The graph's type must be a model of
186  <a href="./VertexListGraph.html">VertexListGraph</a>. Also the graph
187  must have an internal <tt>vertex_index</tt> property map.
188</blockquote> 
189
190 IN: <tt>VertexPropertyWriter vpw</tt>
191<blockquote>
192  A functor that models <a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> concept to print
193  properties of a vertex.<br>
194<b>Default</b>: <tt>default_writer()</tt>
195</blockquote> 
196
197 IN: <tt>EdgePropertyWriter epw</tt>
198<blockquote>
199  A functor that models <a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> concept to print
200  properties of an edge.<br>
201<b>Default</b>: <tt>default_writer()</tt>
202</blockquote> 
203
204 IN: <tt>GraphPropertyWriter epw</tt>
205<blockquote>
206  A functor that models <a href="./write-graphviz.html#concept:PropertyWriter">PropertyWriter</a> concept to print
207  properties of a graph.<br>
208<b>Default</b>: <tt>default_writer()</tt>
209</blockquote>
210
211IN: <tt>dynamic_properties& dp</tt>
212<blockquote>
213  Contains all of the vertex and edge properties that should be
214  emitted by the GraphViz writer.
215</blockquote>
216
217IN: <tt>const std::string& node_id</tt>
218<blockquote>
219  The name of the property map that provides identifiers for the
220  vertices in the graph.<br>
221<b>Default</b>: <tt>"node_id"</tt>
222</blockquote>
223
224IN: <tt>VertexID vertex_id</tt>
225<blockquote>
226  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>
227<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>.
228</blockquote>
229<H3>
230Example
231</H3>
232
233This example demonstrates using BGL-graphviz interface to write
234a BGL graph into a graphviz format file.
235
236<pre>
237enum files_e { dax_h, yow_h, boz_h, zow_h, foo_cpp,
238               foo_o, bar_cpp, bar_o, libfoobar_a,
239               zig_cpp, zig_o, zag_cpp, zag_o,
240                 libzigzag_a, killerapp, N };
241const char* name[] = { "dax.h", "yow.h", "boz.h", "zow.h", "foo.cpp",
242                       "foo.o", "bar.cpp", "bar.o", "libfoobar.a",
243                       "zig.cpp", "zig.o", "zag.cpp", "zag.o",
244                       "libzigzag.a", "killerapp" };
245
246int main(int,char*[])
247{
248   
249  typedef pair&lt;int,int&gt; Edge;
250  Edge used_by[] = {
251    Edge(dax_h, foo_cpp), Edge(dax_h, bar_cpp), Edge(dax_h, yow_h),
252    Edge(yow_h, bar_cpp), Edge(yow_h, zag_cpp),
253    Edge(boz_h, bar_cpp), Edge(boz_h, zig_cpp), Edge(boz_h, zag_cpp),
254    Edge(zow_h, foo_cpp),
255    Edge(foo_cpp, foo_o),
256    Edge(foo_o, libfoobar_a),
257    Edge(bar_cpp, bar_o),
258    Edge(bar_o, libfoobar_a),
259    Edge(libfoobar_a, libzigzag_a),
260    Edge(zig_cpp, zig_o),
261    Edge(zig_o, libzigzag_a),
262    Edge(zag_cpp, zag_o),
263    Edge(zag_o, libzigzag_a),
264    Edge(libzigzag_a, killerapp)
265  };
266  const int nedges = sizeof(used_by)/sizeof(Edge);
267  int weights[nedges];
268  fill(weights, weights + nedges, 1);
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(N, used_by, used_by + nedges, weights);
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.