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. Nodes  shar‐
24       ing the same cluster attribute value will be put into the same cluster.
25       N.B. For the cluster attribute to be used, all nodes must have a  valid
26       value.
27
28       If  the  input  specifies the desired clustering as described above, it
29       can also specify a desired coloring by having some node in each cluster
30       provide  a  clustercolor attribute. N.B. Unless one specifies -c0, only
31       the clustercolor of the last node in a cluster has an effect. In  addi‐
32       tion, unless one uses -O, gvmap may permute the given colors.
33

OPTIONS

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

EXAMPLES

122       Given  a  graph  foo.gv, one way to generate a layout and highlight the
123       clusters is to first select a layout engine  with  a  suitable  overlap
124       removal  method,  then feed the output to gvmap, and finally render the
125       map using specific graphics format. For example, the following pipeline
126       creates  a map with edges in semi-transparent light gray and nodes laid
127       out using sfdp:
128
129       sfdp -Goverlap=prism foo.gv | gvmap -e |  neato  -n2  -Ecolor=#55555522
130       -Tpng > foo.png
131
132       The  shell script gvmap.sh provides a shorthand for such pipelines. For
133       example, the above pipeline can be achieved using
134
135       gvmap.sh -Ae -Ecolor=#55555522 -Tpng foo.gv > foo.png
136
137
138

AUTHOR

140       Yifan Hu <yifanhu@research.att.com>
141

SEE ALSO

143       gvmap.sh(1), sfdp(1), neato(1), gvpr(1)
144
145       E. R. Gansner, Y. Hu, S. G. Kobourov,  "GMap:  Visualizing  graphs  and
146       clusters as maps," Proc. Pacific Vis. 2010, pp. 201‐208.
147
148
149
150                                 3 March 2011                         GVMAP(1)
Impressum