NCSA Imagemap Tutorial

This is a new imagemap.c file (version 1.5 or greater) that has advantages over the old one.
The new imagemap script is being included in the latest NCSA HTTPd distribution.
Note: The new imagemap.c is backward compatible, allowing for old-style configuration via the imagemap.conf file.

This document is a step-by-step tutorial for designing and serving graphical maps of information resources with new imagemap.c. Through such a map, users can be provided with a graphical overview of any set of information resources; by clicking on different parts of the overview image, they can transparently access any of the information resources (possibly spread out all across the Internet).

What you need

Make sure you have a working NCSA HTTPd server installed and running.

This tutorial also assumes use of a browser that supports inlined GIF images and HTTP/1.0 URL redirection, which is most of them.

Compile the imagemap script

Your First Image Map

First, create an image.

There are a number of image creation and editing programs that will work nicely -- the one I use is called xpaint (you can find it on ftp.x.org in /R5contrib; here's the tar file). The important thing is that the image ends up in GIF format.

Second, create an imagemap map file.

This file maps regions to URLs for the given image.

For a list of tools that may help you create a map file, see Yahoo's Imagemap Directory.

A common scheme for an imagemap is a collection of points, polygons, rectangles and circles, each containing a short text description of some piece of information or some information server; interconnections are conveyed through lines or arcs. Try to keep the individual items in the map spaced out far enough so a user will clearly know what he or she is clicking on.

Lines beginning with # are comments. Every other non-blank line consists of the following:

method url coord1 coord2 ... coordn

coord are each coordinates, format x,y. The number depends on method.

method is one of the following:

• default

  For the default Url. Coordinates: none

• circle

  For a circle. Coordinates: center edgepoint

• poly

  For a polygon of at most 100 vertices. Each coordinate is a vertex.

• rect

  For a rectangle. Coordinates: upper-left lower-right

• point

  For closest to a point. Coordinate: thePoint

url is one of the following:

• a virtual pathname to a file on your server (i.e. a URL to your server without the http://hostname part)
• a URL

Notes:

• each method is evaluated in the order it is placed in the configuration file. If you have overlapping areas, such as a circle inside of a rectangle, you should place whichever one you want evaluated first before the other in the map file. In this case, we would put the circle before the rectangle.

• Also note that it does not make sense to use the default method with the point method because if even one point method is specified, anywhere you click will be considered close to the point and the URL specified by point will be serviced.

• If you will be serving access authentication-protected documents through your imagemap, you MUST use fully qualified URLs, for example

  http://your.server.com/path/to/protected/file.html

  otherwise access will be denied.

Here is an example image map linked from Mosaic Demo page.

default /X11/mosaic/public/none.html

rect http://cui_www.unige.ch/w3catalog    15,8    135,39
rect gopher://rs5.loc.gov/11/global       245,86  504,143  
rect http://nearnet.gnn.com/GNN-ORA.html  117,122 175,158 

The format is fairly straightforward. The first line specifies the default response (the file to be returned if the region of the image in which the user clicks doesn't correspond to anything).

Subsequent lines specify rectangles in the image that correspond to arbitrary URLs -- for the first of these lines, the rectangle specified by 15,8 (x,y of the upper-left corner, in pixels) and 135,39 (lower-right corner) corresponds to URL http://cui_www.unige.ch/w3catalog.

So, what you need to do is find the upper-left and lower-right corners of a rectangle for each information resource in your image map. A good tool to use for this is xv (also on ftp.x.org in /contrib) -- pop up the Info window and draw rectangles over the image with the middle mouse button.

It doesn't matter what you name your map file, but it does matter where you put it! Specifically, you cannot have your mapfile reside in the in the top-level of the DocumentRoot, because the imagemapping script will not see a "/" in the extra PATH_INFO that you are referencing. If this doesn't make sense to you, then just trust me: place your map file in a subdirectory.

Third, referencing your imagemap in your HTML file.

To reference your new map, you construct URLs pointing to it.

For example, if your username is newbie and you have created a sample.map file in the directory called path in your public_html home directory, and used the image sample.gif for the map, the following line of HTML will reference it:

<A HREF="http://www.school.edu/cgi-bin/imagemap/~newbie/foo/sample.map">
<IMG SRC="/~newbie/gifs/sample.gif" ISMAP>
</A>

The extra PATH_INFO after the /cgi-bin/imagemap tells the imagemap program where to find your map file. You'll note that it is possible to request the map file itself by simply requesting:

http://www.school.edu/~newbie/foo/sample.map

Fourth, try it out!

Load the HTML file, look at the inlined image, click somewhere, and see what happens.

A Complete Example

Map Configuration File

Reference the map in HTML document:

Real-World Examples

• Experimental Internet Resources Metamap at NCSA.

• University of California Museum of Paleontology.

• National Institute of Standards and Technology.

• Server map at NCHPC Information Server.

For More Information

Return to the tutorial index

Return to administration overview