NCSA Imagemap Tutorial

This document is a step-by-step tutorial for designing and serving graphical maps of information resources with either the external imagemap CGI script or with the built in imagemap support in NCSA HTTPd 1.5. 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).

• Requirements
• Compiling the Imagemap Script
• Your First Imagemap
• Internal Imagemap Support
• A Complete Example
• Real-World Examples

Requirements

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

This tutorial also assumes use of a browser that supports inlined images, server side imagemapping and HTTP/1.0 URL Redirection.

Compiling the Imagemap Script

Compile the imagemap script by first changing into your ServerRoot directory, and then into the cgi-src subdirectory. Put the new imagemap.c source in place of the old one (if you have the old version of imagemap.c) and then, type make imagemap and you should be all set.

Your First Imagemap

There are a number of image creation and editing programs that will work nicely -- the one I use is called xpaint (I don't know where its home page is anymore). You can get it here. It's for UNIX systems running an X interface.

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. For instance, there is a program called mapedit that you could use.

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

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

Coordinates: 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 Local URL

ex. docs/tutorials

A Full URL

ex. http://www.yahoo.com/

coord#

Each coord entry is a coordinate, format x,y. The number depends on the method.

• 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 imagemap linked from the Mosaic Demo page. Here is what a map file looks like:

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 on UNIX 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 imagemap CGI program 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 foo 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

Or, using the internal imagemap support of NCSA HTTPd 1.5:

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

Fourth: Try it out!

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

Internal Imagemap Support

In order to enable the internal imagemap code, the server must be compiled with IMAGEMAP_SUPPORT defined. This is the default. Also, you need to add the magic mime type for the imagemap files in much the same way you would for CGI scripts:

AddType text/x-imagemap .map

Then, you can reference the map file directly in your HTML instead of through the imagemap script, ie:

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

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