sfgraph/hypersfg/hypercube.1

.TH HYPERCUBE 1 "2014-02-14" "1.6.0"
.SH NAME
Hypercube \- Graph visualization tool
.SH SYNOPSIS
.B hypercube\-cli
.RI [ OPTIONS ]
.I FILE
.br
.B hypercube
.RI [ FILE... ]
.SH DESCRIPTION
Hypercube draws text based graph representations as vector images. A simulated
annealing based algorithm allowing layout parametrization is used to lay out
the graph.
.B hypercube-cli
is a command line utility version of Hypercube,
.B hypercube
a GUI application.
.PP
Graphs can be represented as DOT files, GML files, GraphML files, GXL files,
edge lists or adjancency matrixes and can be visualized to SVG or EPS images.
For info on the file formats, see the
.B INPUT FORMATS
section.
.SH OPTIONS
.SS "Generic Program Information"
.TP
.BR \-h
Print a short usage info and exit.
.TP
.BR \-v
Print the program version and exit.
.SS "Input and Output Control"
.TP
.BI \-o " FILE"
Set output file to
.IR FILE .
If no output file name is set, it is generated from the input file by replacing
its suffix with the output format suffix.
.TP
.BI \-f " FORMAT"
Set output format to
.IR FORMAT .
Supported formats are
.B svg
and
.BR eps .
Default format is svg.
.TP
.BI \-e " ENCODING"
Set input file encoding to
.IR ENCODING .
Supported encodings are
.B iso\-8859\-1\fR, \fPiso\-8859\-2\fR, \fPiso\-8859\-5\fR,
.B iso\-8859\-7\fR, \fPwindows\-1250\fR, \fPwindows\-1251\fR,
.B windows\-1252\fR, \fPwindows\-1253\fR, \fPkoi8\-r\fR, \fPkoi8\-u\fR
and
.BR utf\-8 .
Default encoding is iso\-8859\-1.
.TP
.BI \-va " ATTRIBUTE"
Use vertex
.IR ATTRIBUTE
for vertex labels. Usable only with file formats, that support vertex
attributes. If no attribute is set, the first available attribute is used.
.TP
.BI \-ea " ATTRIBUTE"
Use edge
.IR ATTRIBUTE
for edge labels. Usable only with file formats, that support edge attributes.
If no attribute is set, the first available attribute is used.
.SS "Graph Appearance"
.TP
.BI \-s " SIZE"
Set image size to
.IR SIZE .
The image size is expected as
.BR width,height .
.TP
.BR \-d
Directed graph \- the graph edges are drawn as arrows displaying the edge
orientation. If set, overrides the type given in the graph source file.
.TP
.BR \-u
Undirected graph. If set, overrides the type given in the graph source file.
.TP
.BI \-vc " COLOR"
Set vertex color to
.IR COLOR .
The color format is
.BR #RRGGBB .
.TP
.BI \-ec " COLOR"
Set edge color to
.IR COLOR .
The color format is
.BR #RRGGBB .
.TP
.BI \-vs " SIZE"
Set vertex size to
.IR SIZE .
.TP
.BI \-es " SIZE"
Set edge size to
.IR SIZE .
.TP
.BI \-vf " SIZE"
Set vertex ID font size to
.IR SIZE .
To disable showing vertex IDs, set their font size to 0.
.TP
.BI \-ef " SIZE"
Set edge value font size to
.IR SIZE .
To disable showing edge values, set their font size to 0.
.TP
.BR \-c
Colorize graph. Asign a unique color to every uniqe edge value. When this option
is set, the
.B \-ec
option is ommited.
.TP
.BI \-l " SIZE"
Show edge color legend with font size
.IR SIZE .
Implies the
.B \-c
option.
.PP
All sizes are given in output format units \- pixels for SVG and points for EPS.
.SS "Graph Layout"
.TP
.BI \-nd " DIST"
Set node distribution factor to
.IR DIST .
.TP
.BI \-el " LENGTH"
Set edge length factor to
.IR LENGTH .
.TP
.BI \-cr " CROSSINGS"
Set edge crossings factor to
.IR CROSSINGS .
.SS "Algorithm Settings"
.TP
.BI \-it " TEMP"
Set initial temerature to
.IR TEMP .
.TP
.BI \-ft " TEMP"
Set final temerature to
.IR TEMP .
.TP
.BI \-cf " FACTOR"
Set cooling factor to
.IR FACTOR .
.TP
.BI \-ns " STEPS"
Set number of iteration steps to
.IR STEPS .
.SH "INPUT FORMATS"
.SS "DOT"
DOT file format as described in the official Graphviz documentation. Hypercube
parses the complete language, but the only used attribute is the label attribute
(for both edges and nodes).
.PP
.nf
Digraph {
    0 -> 1 [label = 1];
    0 -> 3 [label = 2];
    0 -> 5 [label = 3];
    1 -> 2 [label = 4];
    1 -> 6 [label = 5];
    2 -> 3 [label = 6];
    2 -> 7 [label = 7];
    3 -> 4 [label = 8];
    4 -> 5 [label = 9];
    4 -> 7 [label = 10];
    5 -> 6 [label = 11];
    6 -> 7 [label = 12];
}
.fi
.SS "GML"
GML file format as described in the official documentation. The attributes
(keys) used for vertex/edge labels can be set using the
.B \-va
and
.B \-ea
parameters.
.PP
.nf
graph [
  directed 1

  node [id 0]
  node [id 1]
  node [id 2]
  node [id 3]
  node [id 4]
  node [id 5]
  node [id 6]
  node [id 7]

  edge [label "1" source 0 target 1]
  edge [label "2" source 0 target 3]
  edge [label "3" source 0 target 5]
  edge [label "4" source 1 target 2]
  edge [label "5" source 1 target 6]
  edge [label "6" source 2 target 3]
  edge [label "7" source 2 target 7]
  edge [label "8" source 3 target 4]
  edge [label "9" source 4 target 5]
  edge [label "10" source 4 target 7]
  edge [label "11" source 5 target 6]
  edge [label "12" source 6 target 7]
]
.fi
.SS "GraphML"
GraphML file format as given by the specification. Hypercube does not support
nested graphs, hyperedges and ports. The attributes (data elements) used for the
vertex/edge labels can be set using the
.B \-va
and
.B \-ea
parameters. If there is no appropriate attribute, the vertex/edge id is used as
the label.
.PP
The input encoding is always taken from the xml declaration (with UTF\-8 as the
default), setting the encoding using the
.B \-e
parameter is pointless for GraphML files.
.PP
.nf
<?xml version="1.0" encoding="UTF-8"?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns"  
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns
     http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
  <graph id="G" edgedefault="directed">
    <node id="0"/>
    <node id="1"/>
    <node id="2"/>
    <node id="3"/>
    <node id="4"/>
    <node id="5"/>
    <node id="6"/>
    <node id="7"/>
    <edge source="0" target="1" id="1"/>
    <edge source="0" target="3" id="2"/>
    <edge source="0" target="5" id="3"/>
    <edge source="1" target="2" id="4"/>
    <edge source="1" target="6" id="5"/>
    <edge source="2" target="3" id="6"/>
    <edge source="2" target="7" id="7"/>
    <edge source="3" target="4" id="8"/>
    <edge source="4" target="5" id="9"/>
    <edge source="4" target="7" id="10"/>
    <edge source="5" target="6" id="11"/>
    <edge source="6" target="7" id="12"/>
  </graph>
</graphml>
.fi
.SS "GXL"
GXL file format as given by the specification. Hypercube does not support
hypergraphs, hyperedges and mixed graphs. The attributes used for the
vertex/edge labels can be set using the
.B \-va
and
.B \-ea
parameters. If there is no appropriate attribute, the vertex/edge id is used as
the label. Composite attribute types (seq, set, bag and tup) are serialized by
hypercube into a single string (comma delimited), the locator attribute type is
not supported.
.PP
The input encoding is always taken from the xml declaration (with UTF\-8 as the
default), setting the encoding using the
.B \-e
parameter is pointless for GXL files.
.PP
.nf
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE gxl SYSTEM "http://www.gupro.de/GXL/gxl-1.0.dtd">
<gxl>
  <graph>
    <node id="0"/>
    <node id="1"/>
    <node id="2"/>
    <node id="3"/>
    <node id="4"/>
    <node id="5"/>
    <node id="6"/>
    <node id="7"/>
    <edge from="0" to="1" id="1"/>
    <edge from="0" to="3" id="2"/>
    <edge from="0" to="5" id="3"/>
    <edge from="1" to="2" id="4"/>
    <edge from="1" to="6" id="5"/>
    <edge from="2" to="3" id="6"/>
    <edge from="2" to="7" id="7"/>
    <edge from="3" to="4" id="8"/>
    <edge from="4" to="5" id="9"/>
    <edge from="4" to="7" id="10"/>
    <edge from="5" to="6" id="11"/>
    <edge from="6" to="7" id="12"/>
  </graph>
</gxl>
.fi
.SS "Edge list"
Each line of the input file represents an edge entry. The first value is the
edge's start vertex ID, the second value the end vertex ID and the optional
third value is the edge label (value). The values are strings separated by an
arbitrary amount of whitespace. Quoted strings can be used, if whitespace
occurs in the value.
.PP
.nf
0 1 1
0 3 2
0 5 3
1 2 4
1 6 5
2 3 6
2 7 7
3 4 8
4 5 9
4 7 10
5 6 11
6 7 12
.fi
.SS "Adjacency matrix"
The adjacency matrix representation starts with a single number on a separate
line representing the number of vertexes of the graph. Starting with the next
line, the adjacency matrix itself follows. Numbers greater than 0 are taken as
edges with the given edge value.
.PP
.nf
8
0 1 0 2 0 3 0 0
0 0 4 0 0 0 5 0
0 0 0 6 0 0 0 7
0 0 0 0 8 0 0 0
0 0 0 0 0 9 0 10
0 0 0 0 0 0 11 0
0 0 0 0 0 0 0 12
0 0 0 0 0 0 0 0
.fi
.SH SEE ALSO
dot(1), eps2pdf(1), convert(1)
.SH AUTHOR
Martin Tuma (tumic@cbox.cz)