htmldriver(1grass)

📦
version 8.5.0 · 13 versions
, in ubuntu stonking

💅 HTML DISPLAY DRIVER

okay bestie, so htmldriver(1grass) — it's the GRASS User's Manual page for the HTML display driver, and it's literally the thing that makes clickable image maps out of your vector polygons. no cap. ✨

🌸 DESCRIPTION

okay so. the HTML driver lets you generate HTML image maps for area vector data. 🗺️ and like, what even is an HTML image map? it's when you take an image and give different portions of that image their own unique URL targets. iconic behavior honestly. and this driver can make both flavors:

  • client-side image maps, embedded right into HTML files, and
  • server-side image maps, the kind web server software uses.

now. the fine print, and you're gonna wanna hear this:

Polygons can have at most 100 vertices. this limit is not me being dramatic, it's imposed by HTML image map formats — peep GRASS_RENDER_HTMLMAXPOINTS below. 📌

the driver will try to trim polygons that have more than 100 vertices by removing the vertices with the least amount of angle to the next vertice. so it's out here doing triage. also, any polygon that's entirely bounded by another polygon? discarded. gone. not invited to the function. 💀

text written to the driver before the polygons are used as the HREF tag for all subsequent polygons written. so like, one text line sets the URL, everything after it points there. and every single polygon that exists in a vector map will have the same HREF tag. no mixing, no matching. 🎀

The only GRASS display commands that should be used with this driver are:

  • d.text — pass href information for resulting image maps.
  • d.vect — draw polygons from a vector map.

that's the whole list. don't bring other commands to this party, they're not on the guest list. 🙈

🛠️ USAGE

🦋 Environment variables

you turn the HTML driver on by setting the GRASS_RENDER_IMMEDIATE variable, like so:

export GRASS_RENDER_IMMEDIATE=html

and then there's a whole squad of environment variables that change how the HTML driver behaves:

  • GRASS_RENDER_WIDTH=xxx — the width of the image map (default is 640). 📐
  • GRASS_RENDER_HEIGHT=yyy — the height of the image map (default is 480).
  • GRASS_RENDER_HTMLTYPE=type — the type of image map to create (default is CLIENT). the options are:
    • CLIENT — Netscape/IE client-side image map (NAME="map").
    • APACHE — Apache/NCSA server-side image map.
    • RAW — Raw url and polygon vertices (url x1 y1 x2 y2 .....), suitable for conversion to CERN server format, or any other format with user supplied conversion program.
  • GRASS_RENDER_FILE=filename — specifies the resulting file to store the html image map, default is htmlmap. files without absolute path names are written in the current directory where the driver was started.
⚠️ Any existing file of the same name is overwritten without warning. she does not check. she does not ask. she does not care. 💀
  • GRASS_RENDER_HTMLMINDIST=n — 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 2, 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. 🌸
  • GRASS_RENDER_HTMLMINBBOX=n — specifies the minimum bounding box dimensions to record a polygon as a clickable area. the default is 2, 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. (yes, "polygons than are a point or line" — we're quoting the original lore bestie. 📝)
  • GRASS_RENDER_HTMLMAXPOINTS=n — specifies the maximum number of vertices included in a polygon's clickable area. the default is 99. 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. 👑

🎀 Example

Start up the driver:

g.region vector=zipcodes_wake
d.mon start=html

Display text strings (HREF's) and polygons:

echo "https://en.wikipedia.org/wiki/Raleigh,_North_Carolina" | d.text
d.vect map=zipcodes_wake where="ZIPNAME = ’RALEIGH’"
echo "https://en.wikipedia.org/wiki/Cary,_North_Carolina" | d.text
d.vect map=zipcodes_wake where="ZIPNAME = ’CARY’" fill_color=180:200:210

Stop the driver once all polygon have been displayed. This will create a file named 'htmlmap' in your current directory:

d.mon stop=html

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. The following example is somewhat out of date and refers to options available in GRASS 5.

# using previous GRASS_RENDER_WIDTH & 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

# 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 <alien.ppm |  ppmtogif >alien.gif

# assemble some html with the image and the image map
echo ’<html><body><img src="alien.gif" usemap="#map">’ >alien.html
cat htmlmap                                           >>alien.html
echo ’</body></html>’                                 >>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 &

like, imagine forgetting to reset your region after all that. couldn't be you. 🫶

📝 NOTES

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:

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 map. A small sed script can easily change the map name:

sed -e ’s/NAME="map"/NAME="foomap"/’ < htmlmap > foomap.html

so basically if you've got multiple maps fighting over the same name, that one-liner is your bestie. 💖

👀 SEE ALSO

Cairo driver, PNG driver, HTML driver, variables

d.rast, d.vect, d.mon, d.erase, d.redraw

👑 AUTHOR

Glynn Clements

🌈 SOURCE CODE

Available at: HTML DISPLAY DRIVER source code (history)

Accessed: Tuesday Sep 08 11:53:12 2026

Main index | Topics index | Keywords index | Graphical index | Full index

and that's the whole page, periodt. 💅✨

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual — this was htmldriver(1grass) from GRASS 8.5.0, mwah, slay, go make some clickable maps bestie 🎀🦋

📦 where this page comes from