Added support for GraphML input format
[hypercube:hypercube.git] / hypercube.1
1 .TH HYPERCUBE 1 "2012-11-10" "1.0.4"
2 .SH NAME
3 Hypercube \- Graph visualization tool
4 .SH SYNOPSIS
5 .B hypercube\-cli
6 .RI [ OPTIONS ]
7 .I FILE
8 .br
9 .B hypercube
10 .RI [ FILE... ]
11 .SH DESCRIPTION
12 Hypercube draws text based graph representations as vector images. A simulated
13 annealing based algorithm allowing layout parametrization is used to lay out
14 the graph.
15 .B hypercube-cli
16 is a command line utility version of Hypercube,
17 .B hypercube
18 a GUI application.
19 .PP
20 Graphs can be represented as DOT files, GML files, edge lists or adjancency
21 matrixes and can be visualized to SVG or EPS images. For info on the file
22 formats, see the
23 .B INPUT FORMATS
24 section.
25 .SH OPTIONS
26 .SS "Generic Program Information"
27 .TP
28 .BR \-h
29 Print a short usage info and exit.
30 .TP
31 .BR \-v
32 Print the program version and exit.
33 .SS "Input and Output Control"
34 .TP
35 .BI \-o " FILE"
36 Set output file to
37 .IR FILE .
38 If no output file name is set, it is generated from the input file by replacing
39 its suffix with the output format suffix.
40 .TP
41 .BI \-f " FORMAT"
42 Set output format to
43 .IR FORMAT .
44 Supported formats are
45 .B svg
46 and
47 .BR eps .
48 Default format is svg.
49 .TP
50 .BI \-e " ENCODING"
51 Set input file encoding to
52 .IR ENCODING .
53 Supported encodings are
54 .B iso8859-1\fR,\fP iso8859-2\fR,\fP koi8-r\fR,\fP cp1250 
55 and
56 .BR utf-8 .
57 Default encoding is iso8859\-1.
58 .SS "Graph Appearance"
59 .TP
60 .BI \-s " SIZE"
61 Set image size to
62 .IR SIZE .
63 The image size is expected as
64 .BR width,height .
65 .TP
66 .BR \-d
67 Directed graph. If set the graph edges are drawn as arrows displaying the edge
68 orientation.
69 .TP
70 .BI \-vc " COLOR"
71 Set vertex color to
72 .IR COLOR .
73 The color format is
74 .BR #RRGGBB .
75 .TP
76 .BI \-ec " COLOR"
77 Set edge color to
78 .IR COLOR .
79 The color format is
80 .BR #RRGGBB .
81 .TP
82 .BI \-vs " SIZE"
83 Set vertex size to
84 .IR SIZE .
85 .TP
86 .BI \-es " SIZE"
87 Set edge size to
88 .IR SIZE .
89 .TP
90 .BI \-vf " SIZE"
91 Set vertex ID font size to
92 .IR SIZE .
93 To disable showing vertex IDs, set their font size to 0.
94 .TP
95 .BI \-ef " SIZE"
96 Set edge value font size to
97 .IR SIZE .
98 To disable showing edge values, set their font size to 0.
99 .TP
100 .BR \-c
101 Colorize graph. Asign a unique color to every uniqe edge value. When this option
102 is set, the
103 .B \-ec
104 option is ommited.
105 .PP
106 All sizes are given in output format units \- pixels for SVG and points for EPS.
107 .SS "Graph Layout"
108 .TP
109 .BI \-nd " DIST"
110 Set node distribution factor to
111 .IR DIST .
112 .TP
113 .BI \-el " LENGTH"
114 Set edge length factor to
115 .IR LENGTH .
116 .TP
117 .BI \-ec " CROSSINGS"
118 Set edge crossings factor to
119 .IR CROSSINGS .
120 .SS "Algorithm Settings"
121 .TP
122 .BI \-it " TEMP"
123 Set initial temerature to
124 .IR TEMP .
125 .TP
126 .BI \-ft " TEMP"
127 Set final temerature to
128 .IR TEMP .
129 .TP
130 .BI \-cf " FACTOR"
131 Set cooling factor to
132 .IR FACTOR .
133 .TP
134 .BI \-ns " STEPS"
135 Set number of iteration steps to
136 .IR STEPS .
137 .SH "INPUT FORMATS"
138 .SS "DOT"
139 DOT file format as described in the official Graphviz documentation. Hypercube
140 parses the complete language, but the only used attribute is the label attribute
141 (for both edges and nodes).
142 .PP
143 .nf
144 Digraph {
145     0 -> 1 [label = 1];
146     0 -> 3 [label = 2];
147     0 -> 5 [label = 3];
148     1 -> 2 [label = 4];
149     1 -> 6 [label = 5];
150     2 -> 3 [label = 6];
151     2 -> 7 [label = 7];
152     3 -> 4 [label = 8];
153     4 -> 5 [label = 9];
154     4 -> 7 [label = 10];
155     5 -> 6 [label = 11];
156     6 -> 7 [label = 12];
157 }
158 .fi
159 .SS "GML"
160 GML file format as described in the official documentation. Except the mandatory
161 keys id, target and source, the label key is also supported.
162 .PP
163 .nf
164 graph [
165   node [id 0]
166   node [id 1]
167   node [id 2]
168   node [id 3]
169   node [id 4]
170   node [id 5]
171   node [id 6]
172   node [id 7]
173
174   edge [label "1" source 0 target 1]
175   edge [label "2" source 0 target 3]
176   edge [label "3" source 0 target 5]
177   edge [label "4" source 1 target 2]
178   edge [label "5" source 1 target 6]
179   edge [label "6" source 2 target 3]
180   edge [label "7" source 2 target 7]
181   edge [label "8" source 3 target 4]
182   edge [label "9" source 4 target 5]
183   edge [label "10" source 4 target 7]
184   edge [label "11" source 5 target 6]
185   edge [label "12" source 6 target 7]
186 ]
187 .fi
188 .SS "Edge list"
189 Each line of the input file represents an edge entry. The first value is the
190 edge's start vertex ID, the second value the end vertex ID and the optional
191 third value is the edge label (value). The values are strings separated by an
192 arbitrary amount of whitespace. Quoted strings can be used, if whitespace
193 occurs in the value.
194 .PP
195 .nf
196 0 1 1
197 0 3 2
198 0 5 3
199 1 2 4
200 1 6 5
201 2 3 6
202 2 7 7
203 3 4 8
204 4 5 9
205 4 7 10
206 5 6 11
207 6 7 12
208 .fi
209 .SS "Adjacency matrix"
210 The adjacency matrix representation starts with a single number on a separate
211 line representing the number of vertexes of the graph. Starting with the next
212 line, the adjacency matrix itself follows. Numbers greater than 0 are taken as
213 edges with the given edge value.
214 .PP
215 .nf
216 8
217 0 1 0 2 0 3 0 0
218 0 0 4 0 0 0 5 0
219 0 0 0 6 0 0 0 7
220 0 0 0 0 8 0 0 0
221 0 0 0 0 0 9 0 10
222 0 0 0 0 0 0 11 0
223 0 0 0 0 0 0 0 12
224 0 0 0 0 0 0 0 0
225 .fi
226 .SH SEE ALSO
227 dot(1), eps2pdf(1), convert(1)
228 .SH AUTHOR
229 Martin Tuma (tumic@cbox.cz)