Geografic-Information-System/lib/htmldriver/htmldriver.html

<!-- meta page description: HTML DISPLAY DRIVER -->

<em>HTML display driver</em> to create HTML image maps.

<h2>DESCRIPTION</h2>

The HTML driver allows the generation of HTML image maps for area
vector data. HTML image maps are used in conjunction with images to
provide unique URL targets for different portions of an image. The
HTML driver can create both client-side image maps embedded into HTML
files, or server-side image maps used by web server software.

<p>Polygons can at most have 100 vertices (this limit imposed by HTML
image map formats, see <b>GRASS_RENDER_HTMLMAXPOINTS</b> below.) The driver
will attempt to trim polygons that have more that 100 vertices by
removing vertices with the least amount of angle to the next
vertice. Also, any polygon that is entirely bounded by another polygon
will be discarded.

<p>Text written to the driver before polygons are used as the HREF tag
for all subsequent polygons written. All polygons that exist in a
vector map will have the same HREF tag.

<p>The only GRASS display commands that should be used with this driver
are:
<ul>
  <li><em><a href="d.text.html">d.text</a></em> - pass href
  information for resulting image maps.</li>
  <li><em><a href="d.vect.html">d.vect</a></em> - draw polygons from a
  vector map.</li>
</ul>

<h2>USAGE</h2>

<h3>Environment variables</h3>

The HTML driver can be enabled by
setting <b>GRASS_RENDER_IMMEDIATE</b> variable, eg.

<div class="code"><pre>
export GRASS_RENDER_IMMEDIATE=html
</pre></div>

Several environment variables affect the operation of the HTML driver:

<ul>
  <li><b>GRASS_RENDER_WIDTH=xxx</b><br>
     the width of the image map (default is 640).
  </li>
  <li><b>GRASS_RENDER_HEIGHT=yyy</b><br>
    the height of the image map (default is 480).
  </li>
  <li><b>GRASS_RENDER_HTMLTYPE=type</b><br> type of image mape to create
    (default is CLIENT):
    <dl>
      <dd><tt><b>CLIENT</b></tt> &nbsp;&nbsp; Netscape/IE client-side
	image map (NAME="map").</dd>
      <dd><tt><b>APACHE</b></tt> &nbsp;&nbsp; Apache/NCSA server-side image 
	map.</dd>
      <dd><tt><b>RAW</b></tt>
	&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Raw url and polygon
	vertices (<i>url&nbsp; x1&nbsp; y1&nbsp; x2&nbsp; y2&nbsp;
	.....</i>), suitable for conversion to CERN server format, or
	any other format with user supplied conversion program.</dd>
    </dl>
  </li>
  <li><b>GRASS_RENDER_FILE=filename</b><br>
    specifies the resulting file to store the html image map, default
    is <tt>htmlmap</tt>. Files without absolute path names are written
    in the current directory where the driver was started.
    <br>
    <em>Any existing file of the same name is overwritten without
      warning.</em>
  </li>
  <li><b>GRASS_RENDER_HTMLMINDIST=n</b><br>
    specifies the minimum distance in pixels that a point must change
    from the previous point to keep in the list of vertices for a
    polygon.  The default is <tt>2</tt>, which means that a point's x
    and y difference from the previous point must change by a number
    of pixels greater than this value.  This parameter helps to
    eliminate closely spaced points.
  </li>
  <li><b>GRASS_RENDER_HTMLMINBBOX=n</b><br>
    specifies the minimum bounding box dimensions to record a polygon
    as a clickable area.  The default is <tt>2</tt>, which means that a
    polygon with a bounding box of less than this value is not
    included. This parameter helps to eliminate polygons than are a
    point or line.
  </li>
  <li><b>GRASS_RENDER_HTMLMAXPOINTS=n</b><br>
    specifies the maximum number of vertices included in a polygon's
    clickable area.  The default is <tt>99</tt>. Some browsers can only
    accommodate polygons of 100 vertices or less. The HTMLMAP driver
    automatically ensures that a polygon is closed by making the last
    point the same as the first point.</li>
</ul>

<h3>Example</h3>

Start up the driver

<div class="code"><pre>
d.mon start=html
</pre></div>

Display text strings (HREF's) and polygons

<div class="code"><pre>
echo "http://www.no-such-place.net/area51/" | d.text
d.vect map=area51
echo "http://www.roswell-nm.net/little/green/men.html" | d.text
d.vect map=roswell
</pre></div>

Stop the driver when all polygon have been displayed. This will cause
a file named 'htmlmap' to be created in your current directory.

<div class="code"><pre>
d.mon stop=html
</pre></div>

You will also want to create an image for your image map. Use the PNG 
driver and other utilities to create .gif or .jpg files.
<i>The following example is somewhat out of date and refers to options
  available in GRASS 5.</i>

<div class="code"><pre>
# using previous GRASS_RENDER_WIDTH &amp; GRASS_RENDER_HEIGHT
d.mon start=png
d.rast map=terrain
d.vect map=area51  fillcolor=white  linecolor=blue
d.vect map=roswell fillcolor=yellow linecolor=blue
d.vect map=states  color=green
d.vect map=roads   color=black
d.mon stop=png

<!-- ????  FIXME and the ppm stuff looks overly complicated -->
# make the region the same as the newly created cell for ppm export
g.region save=saved.reg
g.region raster=D_cell
r.out.ppm -q input=D_cell output=alien.ppm

# use the netpbm utilities to create a gif (quantize if needed)
ppmquant 128 &lt;alien.ppm |  ppmtogif &gt;alien.gif 

# assemble some html with the image and the image map
echo '&lt;html&gt;&lt;body&gt;&lt;img src="alien.gif" usemap="#map"&gt;' &gt;alien.html
cat htmlmap                                           &gt;&gt;alien.html
echo '&lt;/body&gt;&lt;/html&gt;'                                 &gt;&gt;alien.html
	
# don't forget to reset your region
g.region region=saved.reg

# take a look and test it out
netscape file:`pwd`/alien.html &amp;
</pre></div>

<h2>NOTES</h2>

HTML was adapted from the CELL driver in GRASS 4.3.
Point-in-polygon test code was lifted from Randolph Franklin's web
page, see

<ul>
  <li><a href="http://www.ecse.rpi.edu/Homepages/wrf/">http://www.ecse.rpi.edu/Homepages/wrf/</a>
  </li>
  <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>
  </li>
</ul>

<p>If you create an HTML file with two or more images and image maps, you
will need to edit the map names. The HTML driver creates its map
with the name
<tt>map</tt>. A small sed script can easily change the map name:

<div class="code"><pre>
sed -e 's/NAME="map"/NAME="foomap"/' &lt; htmlmap &gt; foomap.html
</pre></div>

<h2>SEE ALSO</h2>

<em>
  <a href="cairodriver.html">Cairo driver</a>,
  <a href="pngdriver.html">PNG driver</a>,
  <a href="htmldriver.html">HTML driver</a>,
  <a href="variables.html">variables</a>
  <br><br>
  <a href="d.rast.html">d.rast</a>,
  <a href="d.vect.html">d.vect</a>,
  <a href="d.mon.html">d.mon</a>,
  <a href="d.erase.html">d.erase</a>,
  <a href="d.redraw.html">d.redraw</a>
</em>

<p>
<i>Last changed: $Date$</i>