← Back to branch summary

~ubuntu-branches/ubuntu/vivid/grass/vivid-proposed

« back to all changes in this revision

Viewing changes to lib/htmldriver/htmldriver.html

  • Committer: Package Import Robot
  • Author(s): Bas Couwenberg
  • Date: 2015-02-20 23:12:08 UTC
  • mfrom: (8.2.6 experimental)
  • Revision ID: package-import@ubuntu.com-20150220231208-1u6qvqm84v430b10
Tags: 7.0.0-1~exp1
* New upstream release.
* Update python-ctypes-ternary.patch to use if/else instead of and/or.
* Drop check4dev patch, rely on upstream check.
* Add build dependency on libpq-dev to grass-dev for libpq-fe.h.
* Drop patches applied upstream, refresh remaining patches.
* Update symlinks for images switched from jpg to png.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/htmldriver/htmldriver.html
 
1
<!-- meta page description: HTML DISPLAY DRIVER -->
 
2
 
 
3
<em>HTML display driver</em> to create HTML image maps.
 
4
 
 
5
<h2>DESCRIPTION</h2>
 
6
 
 
7
The HTML driver allows the generation of HTML image maps for area
 
8
vector data. HTML image maps are used in conjunction with images to
 
9
provide unique URL targets for different portions of an image. The
 
10
HTML driver can create both client-side image maps embedded into HTML
 
11
files, or server-side image maps used by web server software.
 
12
 
 
13
<p>Polygons can at most have 100 vertices (this limit imposed by HTML
 
14
image map formats, see <b>GRASS_RENDER_HTMLMAXPOINTS</b> below.) The driver
 
15
will attempt to trim polygons that have more that 100 vertices by
 
16
removing vertices with the least amount of angle to the next
 
17
vertice. Also, any polygon that is entirely bounded by another polygon
 
18
will be discarded.
 
19
 
 
20
<p>Text written to the driver before polygons are used as the HREF tag
 
21
for all subsequent polygons written. All polygons that exist in a
 
22
vector map will have the same HREF tag.
 
23
 
 
24
<p>The only GRASS display commands that should be used with this driver
 
25
are:
 
26
<ul>
 
27
  <li><em><a href="d.text.html">d.text</a></em> - pass href
 
28
  information for resulting image maps.</li>
 
29
  <li><em><a href="d.vect.html">d.vect</a></em> - draw polygons from a
 
30
  vector map.</li>
 
31
</ul>
 
32
 
 
33
<h2>USAGE</h2>
 
34
 
 
35
<h3>Environment variables</h3>
 
36
 
 
37
The HTML driver can be enabled by
 
38
setting <b>GRASS_RENDER_IMMEDIATE</b> variable, eg.
 
39
 
 
40
<div class="code"><pre>
 
41
export GRASS_RENDER_IMMEDIATE=html
 
42
</pre></div>
 
43
 
 
44
Several environment variables affect the operation of the HTML driver:
 
45
 
 
46
<ul>
 
47
  <li><b>GRASS_RENDER_WIDTH=xxx</b><br>
 
48
     the width of the image map (default is 640).
 
49
  </li>
 
50
  <li><b>GRASS_RENDER_HEIGHT=yyy</b><br>
 
51
    the height of the image map (default is 480).
 
52
  </li>
 
53
  <li><b>GRASS_RENDER_HTMLTYPE=type</b><br> type of image mape to create
 
54
    (default is CLIENT):
 
55
    <dl>
 
56
      <dd><tt><b>CLIENT</b></tt> &nbsp;&nbsp; Netscape/IE client-side
 
57
        image map (NAME="map").</dd>
 
58
      <dd><tt><b>APACHE</b></tt> &nbsp;&nbsp; Apache/NCSA server-side image 
 
59
        map.</dd>
 
60
      <dd><tt><b>RAW</b></tt>
 
61
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Raw url and polygon
 
62
        vertices (<i>url&nbsp; x1&nbsp; y1&nbsp; x2&nbsp; y2&nbsp;
 
63
        .....</i>), suitable for conversion to CERN server format, or
 
64
        any other format with user supplied conversion program.</dd>
 
65
    </dl>
 
66
  </li>
 
67
  <li><b>GRASS_RENDER_FILE=filename</b><br>
 
68
    specifies the resulting file to store the html image map, default
 
69
    is <tt>htmlmap</tt>. Files without absolute path names are written
 
70
    in the current directory where the driver was started.
 
71
    <br>
 
72
    <em>Any existing file of the same name is overwritten without
 
73
      warning.</em>
 
74
  </li>
 
75
  <li><b>GRASS_RENDER_HTMLMINDIST=n</b><br>
 
76
    specifies the minimum distance in pixels that a point must change
 
77
    from the previous point to keep in the list of vertices for a
 
78
    polygon.  The default is <tt>2</tt>, which means that a point's x
 
79
    and y difference from the previous point must change by a number
 
80
    of pixels greater than this value.  This parameter helps to
 
81
    eliminate closely spaced points.
 
82
  </li>
 
83
  <li><b>GRASS_RENDER_HTMLMINBBOX=n</b><br>
 
84
    specifies the minimum bounding box dimensions to record a polygon
 
85
    as a clickable area.  The default is <tt>2</tt>, which means that a
 
86
    polygon with a bounding box of less than this value is not
 
87
    included. This parameter helps to eliminate polygons than are a
 
88
    point or line.
 
89
  </li>
 
90
  <li><b>GRASS_RENDER_HTMLMAXPOINTS=n</b><br>
 
91
    specifies the maximum number of vertices included in a polygon's
 
92
    clickable area.  The default is <tt>99</tt>. Some browsers can only
 
93
    accommodate polygons of 100 vertices or less. The HTMLMAP driver
 
94
    automatically ensures that a polygon is closed by making the last
 
95
    point the same as the first point.</li>
 
96
</ul>
 
97
 
 
98
<h3>Example</h3>
 
99
 
 
100
Start up the driver
 
101
 
 
102
<div class="code"><pre>
 
103
d.mon start=html
 
104
</pre></div>
 
105
 
 
106
Display text strings (HREF's) and polygons
 
107
 
 
108
<div class="code"><pre>
 
109
echo "http://www.no-such-place.net/area51/" | d.text
 
110
d.vect map=area51
 
111
echo "http://www.roswell-nm.net/little/green/men.html" | d.text
 
112
d.vect map=roswell
 
113
</pre></div>
 
114
 
 
115
Stop the driver when all polygon have been displayed. This will cause
 
116
a file named 'htmlmap' to be created in your current directory.
 
117
 
 
118
<div class="code"><pre>
 
119
d.mon stop=html
 
120
</pre></div>
 
121
 
 
122
You will also want to create an image for your image map. Use the PNG 
 
123
driver and other utilities to create .gif or .jpg files.
 
124
<i>The following example is somewhat out of date and refers to options
 
125
  available in GRASS 5.</i>
 
126
 
 
127
<div class="code"><pre>
 
128
# using previous GRASS_RENDER_WIDTH &amp; GRASS_RENDER_HEIGHT
 
129
d.mon start=png
 
130
d.rast map=terrain
 
131
d.vect map=area51  fillcolor=white  linecolor=blue
 
132
d.vect map=roswell fillcolor=yellow linecolor=blue
 
133
d.vect map=states  color=green
 
134
d.vect map=roads   color=black
 
135
d.mon stop=png
 
136
 
 
137
<!-- ????  FIXME and the ppm stuff looks overly complicated -->
 
138
# make the region the same as the newly created cell for ppm export
 
139
g.region save=saved.reg
 
140
g.region raster=D_cell
 
141
r.out.ppm -q input=D_cell output=alien.ppm
 
142
 
 
143
# use the netpbm utilities to create a gif (quantize if needed)
 
144
ppmquant 128 &lt;alien.ppm |  ppmtogif &gt;alien.gif 
 
145
 
 
146
# assemble some html with the image and the image map
 
147
echo '&lt;html&gt;&lt;body&gt;&lt;img src="alien.gif" usemap="#map"&gt;' &gt;alien.html
 
148
cat htmlmap                                           &gt;&gt;alien.html
 
149
echo '&lt;/body&gt;&lt;/html&gt;'                                 &gt;&gt;alien.html
 
150
        
 
151
# don't forget to reset your region
 
152
g.region region=saved.reg
 
153
 
 
154
# take a look and test it out
 
155
netscape file:`pwd`/alien.html &amp;
 
156
</pre></div>
 
157
 
 
158
<h2>NOTES</h2>
 
159
 
 
160
HTML was adapted from the CELL driver in GRASS 4.3.
 
161
Point-in-polygon test code was lifted from Randolph Franklin's web
 
162
page, see
 
163
 
 
164
<ul>
 
165
  <li><a href="http://www.ecse.rpi.edu/Homepages/wrf/">http://www.ecse.rpi.edu/Homepages/wrf/</a>
 
166
  </li>
 
167
  <li><a href="http://www.ecse.rpi.edu/Homepages/wrf/research/geom/pnpoly.html">http://www.ecse.rpi.edu/Homepages/wrf/research/geom/pnpoly.html</a>
 
168
  </li>
 
169
</ul>
 
170
 
 
171
<p>If you create an HTML file with two or more images and image maps, you
 
172
will need to edit the map names. The HTML driver creates its map
 
173
with the name
 
174
<tt>map</tt>. A small sed script can easily change the map name:
 
175
 
 
176
<div class="code"><pre>
 
177
sed -e 's/NAME="map"/NAME="foomap"/' &lt; htmlmap &gt; foomap.html
 
178
</pre></div>
 
179
 
 
180
<h2>SEE ALSO</h2>
 
181
 
 
182
<em>
 
183
  <a href="cairodriver.html">Cairo driver</a>,
 
184
  <a href="pngdriver.html">PNG driver</a>,
 
185
  <a href="htmldriver.html">HTML driver</a>,
 
186
  <a href="variables.html">variables</a>
 
187
  <br><br>
 
188
  <a href="d.rast.html">d.rast</a>,
 
189
  <a href="d.vect.html">d.vect</a>,
 
190
  <a href="d.mon.html">d.mon</a>,
 
191
  <a href="d.erase.html">d.erase</a>,
 
192
  <a href="d.redraw.html">d.redraw</a>
 
193
</em>
 
194
 
 
195
<p>
 
196
<i>Last changed: $Date: 2014-12-09 18:31:29 +0100 (Tue, 09 Dec 2014) $</i>