1GVMAP(1)                    General Commands Manual                   GVMAP(1)
2
3
4

NAME

6       gvmap  - find clusters and create a geographical map highlighting clus‐
7       ters.
8

SYNOPSIS

10       gvmap [ options ] [ -o outfile ] [ files ]
11

DESCRIPTION

13       gvmap takes as input a graph in DOT format,  finds  node  clusters  and
14       produces a rendering of the graph as a geographic-style map, with clus‐
15       ters highlighted as countries, in xdot format.
16
17       In the input graph, each node must  have  position,  width  and  height
18       information  (pos,  width and height attributes, respectively) defined,
19       and nodes must not overlap.
20
21       By default, gvmap will generate the clusters from the data. If desired,
22       the  input graph can specify cluster information by giving every node a
23       cluster attribute whose value is a small positive integer. (It is works
24       best  if cluster values are all integers in the interval [1,K] for some
25       K. Nodes sharing the same cluster attribute value will be put into  the
26       same cluster. N.B. For the cluster attribute to be used, all nodes must
27       have a valid value.
28
29       If the -D flag is used, gvmap will use the top-level cluster  subgraphs
30       to  determine  the  clustering. Any nodes not in such a cluster will be
31       put into a single catch-all cluster.
32
33       If the input specifies the desired clustering as  described  above,  it
34       can also specify a desired coloring by having some node in each cluster
35       provide a clustercolor attribute. N.B. Unless one specifies  -c0,  only
36       the  clustercolor of the last node in a cluster has an effect. In addi‐
37       tion, unless one uses -O, gvmap may permute the given colors.
38

OPTIONS

40       The following options are supported:
41
42       -a k   The integer k specifies the average number of artificial  points
43              added  along  the  bounding  box  of the labels. Such artificial
44              points are added to avoid a country boundary cutting through the
45              boundary box of the labels. Computing time is proportional to k;
46              hence, for large graphs, a small value of k is suggested. If k =
47              -1, a suitable value of k is automatically selected based on the
48              graph size. By default k = -1.
49
50       -b v   The real number v specifies the line  width  used  to  draw  the
51              polygon boundaries, with v < 0 for no line. By default v = 0.
52
53       -c k   The  integer  k  specifies  color scheme used to color the coun‐
54              tries. By default k = 1.
55
56          Acceptable values are:
57                 0 : no polygons
58                 1 : pastel
59                 2 : blue to yellow
60                 3 : white to red
61                 4 : light grey to red
62                 5 : primary colors
63                 6 : sequential single hue red
64                 7 : sequential single hue lighter red
65                 8 : light grey
66
67       -c_opacity=xy
68              Specifies a  two-character  hexadecimal  string  specifying  the
69              opacity of the polygons.
70
71       -C d   The  integer  d  specifies the maximum number of clusters (coun‐
72              tries) allowed. By default d = 0, which means that there  is  no
73              limit.
74
75       -d d   The  integer  d  specifies  the  random  seed  used during color
76              assignment optimization that maximize color  difference  between
77              neighboring countries.
78
79       -D     If  specified, the graph's cluster subgraphs are used to specify
80              the clustering.
81
82       -e     If specified, edges will be included in the final output.
83
84       -g c   Specifies the bounding box color. If not specified,  a  bounding
85              box is not drawn.
86
87       -h k   The  number  of  artificial  points  added  to maintain a bridge
88              between endpoints. By default, this is zero.
89
90       -highlight=k
91              Only draw cluster k. By default, all clusters are drawn.
92
93       -k     If specified, increases the randomness of outer boundary.
94
95       -l s   Use the string s as a label for the drawing.
96
97       -m v   Generate a margin of v points around the  drawing.  By  default,
98              this is determined by gvmap.
99
100       -O     Do  NOT  do  color  assignment optimization that maximizes color
101              differences between neighboring countries
102
103       -o<file>
104              Put output in <file>. Default output is stdout
105
106       -p k   Indicates what level of points should be shown. By  default,  no
107              points are shown.
108
109          Acceptable values are:
110                 0 : no points
111                 1 : all points
112                 2 : label points
113                 3 : random/artificial points
114
115       -Q     Use  modularity  quality  for clustering rather than the default
116              modularity clustering.
117
118       -r k   The number of random points k (integer) used to define  sea  and
119              lake boundaries. If 0, auto assigned. By default v = 0
120
121       -s v   The real number v specifies the depth of the sea and lake shores
122              in points. If 0, auto assigned. By default v = 0.
123
124       -t n   Make n attempts to improve cluster contiguity.
125
126       -v     Verbose mode.
127
128       -z c   Specified the polygon line color. Default is black.
129
130       -?     Print usage and exit.
131

EXAMPLES

133       Given a graph foo.gv, one way to generate a layout  and  highlight  the
134       clusters  is  to  first  select a layout engine with a suitable overlap
135       removal method, then feed the output to gvmap, and finally  render  the
136       map using specific graphics format. For example, the following pipeline
137       creates a map with edges in semi-transparent light gray and nodes  laid
138       out using sfdp:
139
140       sfdp  -Goverlap=prism  foo.gv  | gvmap -e | neato -n2 -Ecolor=#55555522
141       -Tpng > foo.png
142
143       The shell script gvmap.sh provides a shorthand for such pipelines.  For
144       example, the above pipeline can be achieved using
145
146       gvmap.sh -Ae -Ecolor=#55555522 -Tpng foo.gv > foo.png
147
148
149

AUTHOR

151       Yifan Hu <yifanhu@yahoo.com>
152

SEE ALSO

154       gvmap.sh(1), sfdp(1), neato(1), gvpr(1)
155
156       E.  R.  Gansner,  Y.  Hu, S. G. Kobourov, "GMap: Visualizing graphs and
157       clusters as maps," Proc. Pacific Vis. 2010, pp. 201‐208.
158
159
160
161                                 3 March 2011                         GVMAP(1)
Impressum