Debian Codegraph @

lib/htmldriver/htmldriver.html

raw
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 map to create
54 (default is CLIENT):
55 <dl>
56 <dd><code><b>CLIENT</b></code> &nbsp;&nbsp; Netscape/IE client-side
57 image map (NAME="map").</dd>
58 <dd><code><b>APACHE</b></code> &nbsp;&nbsp; Apache/NCSA server-side image
59 map.</dd>
60 <dd><code><b>RAW</b></code>
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 <code>htmlmap</code>. 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 <code>2</code>, 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 <code>2</code>, 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 <code>99</code>. 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 g.region vector=zipcodes_wake
104 d.mon start=html
105 </pre></div>
106
107 Display text strings (HREF's) and polygons
108
109 <div class="code"><pre>
110 echo "https://en.wikipedia.org/wiki/Raleigh,_North_Carolina" | d.text
111 d.vect map=zipcodes_wake where="ZIPNAME = 'RALEIGH'"
112 echo "https://en.wikipedia.org/wiki/Cary,_North_Carolina" | d.text
113 d.vect map=zipcodes_wake where="ZIPNAME = 'CARY'" fill_color=180:200:210
114 </pre></div>
115
116 Stop the driver once all polygon have been displayed. This will create
117 a file named 'htmlmap' in your current directory:
118
119 <div class="code"><pre>
120 d.mon stop=html
121 </pre></div>
122
123 You will also want to create an image for your image map. Use the PNG
124 driver and other utilities to create .gif or .jpg files.
125 <i>The following example is somewhat out of date and refers to options
126 available in GRASS 5.</i>
127
128 <div class="code"><pre>
129 # using previous GRASS_RENDER_WIDTH &amp; GRASS_RENDER_HEIGHT
130 d.mon start=png
131 d.rast map=terrain
132 d.vect map=area51 fillcolor=white linecolor=blue
133 d.vect map=roswell fillcolor=yellow linecolor=blue
134 d.vect map=states color=green
135 d.vect map=roads color=black
136 d.mon stop=png
137
138 <!-- ???? FIXME and the ppm stuff looks overly complicated -->
139 # make the region the same as the newly created cell for ppm export
140 g.region save=saved.reg
141 g.region raster=D_cell
142 r.out.ppm -q input=D_cell output=alien.ppm
143
144 # use the netpbm utilities to create a gif (quantize if needed)
145 ppmquant 128 &lt;alien.ppm | ppmtogif &gt;alien.gif
146
147 # assemble some html with the image and the image map
148 echo '&lt;html&gt;&lt;body&gt;&lt;img src="alien.gif" usemap="#map"&gt;' &gt;alien.html
149 cat htmlmap &gt;&gt;alien.html
150 echo '&lt;/body&gt;&lt;/html&gt;' &gt;&gt;alien.html
151
152 # don't forget to reset your region
153 g.region region=saved.reg
154
155 # take a look and test it out
156 netscape file:`pwd`/alien.html &amp;
157 </pre></div>
158
159 <h2>NOTES</h2>
160
161 HTML was adapted from the CELL driver in GRASS 4.3.
162 Point-in-polygon test code was lifted from Randolph Franklin's web
163 page, see
164
165 <ul>
166 <li><a href="http://www.ecse.rpi.edu/Homepages/wrf/">http://www.ecse.rpi.edu/Homepages/wrf/</a>
167 </li>
168 <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>
169 </li>
170 </ul>
171
172 <p>If you create an HTML file with two or more images and image maps, you
173 will need to edit the map names. The HTML driver creates its map
174 with the name
175 <code>map</code>. A small sed script can easily change the map name:
176
177 <div class="code"><pre>
178 sed -e 's/NAME="map"/NAME="foomap"/' &lt; htmlmap &gt; foomap.html
179 </pre></div>
180
181 <h2>SEE ALSO</h2>
182
183 <em>
184 <a href="cairodriver.html">Cairo driver</a>,
185 <a href="pngdriver.html">PNG driver</a>,
186 <a href="htmldriver.html">HTML driver</a>,
187 <a href="variables.html">variables</a>
188 </em>
189 <br><br>
190 <em>
191 <a href="d.rast.html">d.rast</a>,
192 <a href="d.vect.html">d.vect</a>,
193 <a href="d.mon.html">d.mon</a>,
194 <a href="d.erase.html">d.erase</a>,
195 <a href="d.redraw.html">d.redraw</a>
196 </em>
197
198 <h2>AUTHOR</h2>
199
200 Glynn Clements