umap - a replacement for imagemap

Umap resembles in its basic functionality the imagemap program that is part of the NCSA httpd distribution; it differs from it in the syntax of the configuration file and in its ability to handle requests without coordinates, handle coordinates without corresponding document, warn about syntax errors in the configuration files, and in some of the geometry requests it understands.

The release (which you are welcome to copy and test) consists of the yacc and lex files, a Makefile, and a manual page (whose HTML equivalent is the remainder of this document.)

Synopsis

      umap/mapname?point1,point2
      umap/mapname

Description

The umap program maps a point to the URL of a document, based on geometrical regions from a description file.  It is invoked as a CGI client by a HTTP server, and responds with a redirection request.

Umap resembles in its basic functionality the imagemap program that is part of the NCSA httpd distribution; it differs from it in the syntax of the configuration file and in its ability to handle requests without coordinates, handle coordinates without corresponding document, warn about syntax errors in the configuration files, and in some of the geometry requests it understands.

Arguments

mapname
(which follows the name of the umap binary in the URL) is the virtual pathname of a description file.  It is mapped to a physical file name by the HTTP server and passed to the binary through the environment variable PATH_TRANSLATED.

?point1,point2
is appended to the the virtual pathname by bitmapped WWW clients if the URL is used as part of an anchor with the attribute ismap that encloses an inlined image, as in <a  href=url  ismap><img  src=image></a>.  point1 and point2 are the x and y coordinates, respectively, of the user's cursor position within the inlined image.  The umap program searches for a geometry that best matches this coordinate in its specification file, and then takes the action specified in that file.

Language

The description language in the umap file differs from that used in imagemap files.  Generally, expressions have the form
url geometry params ...
If the point lies within (or closest to, see below) the parametrized geometry, url is returned to the client.  Instead of prefixing multiple geometry descriptions repeatedly with the same URL, they can be enclosed in braces:
url {
geometry params ...
geometry params ...
}

URLs

URLs are strings enclosed in double quotes, or strings that don't match anything else, do not contain white space, contain at least one alphabetic character, and do not start or end with punctuation.

url
If an URL is a relative pathname without protocol prefix, it is interpreted relative to the logical pathname of the umap file.

If the URL that results from this kind of pasting, or the URL that the map file contained in the first place, is an absolute logical path name without protocol prefix, the server (at least NCSA httpd) executes the redirection within itself, with no additional traffic between client and server.

Otherwise, only a redirection (or ``Location'') request is sent back to the client; the client then reconnects and retrieves the document.

Doing the redirection within the server saves one synchroneous request.  There is one problem with this: the browser that receives the document doesn't know its URL, and will interpret relative pathnames within the document relative to the URL of the umap program.  Use a <base href=url> element in the header of the retrieved document to make sure that names are interpreted relative to url.

empty
can be specified in place of any URL to indicate that points matching this geometry shall not receive any reply.  (The status code 204 has been reserved for this purpose, and is understood by Mosaic clients since version 2.0.) Like all other keywords, this one, too, is case insensitive.  A 204 response is also returned if no other default was specified, and none of the geometry descriptions matched a user's choice.

Geometry

Geometry descriptions have the form of a case­insensitive keyword (circle, rect, point or poly) followed by a list of numeric parameters.  All numbers must be positive.  Tokens are separated by arbitrary sequences of white space, commas, and semicolons.

There are two kinds of geometry requests. The first kind, shapes like circles, rectangles, or polygons, can be decided immediately when they are encountered: either a point lies within them, or not. The first of those shapes that matches the user's point is taken as the result of the query.

The second kind, points, are considered as a whole; only if no shape matches, the closest matching point is selected. Shapes simply match; points must be closest of all possible other points to match.

The meanings and syntaxes of the individual geometries are:

point x, y
Defines a point at the coordinates x and y.  If the user did not click inside any of the bounded geometrical areas, the relevant point closest to the user's selection is chosen.  This feature probably goes back to Craig Milo Rogers' hack in July 1994.

point x, y, radius
As without radius, but do not consider the point if the user's selection is further than radius pixels away from the point.

point x, y, xR, yR
As above, but the radius is determined as the distance between xR, yR and x, y.

rect x1, y1, x2, y2
Specifies two opposite corners of a rectangle.  The URL is chosen if the point lies within the rectangle.

circle x, y, radius
Defines a circle with the center x, y and the radius radius.  A point whose distance from the center is less than or equal to the radius is considered to match the circle.

circle x, y, xR, yR
As above, but the radius is the distance between x, y and xR, yR.

poly x1, y1, x2, y2, ... xN, yN
Defines a polygon with the corners (x1,y1), (x2,y2), ... (xN,yN).  A point matches the corresponding URL if it lies within the polygon.  (Whether or not the corners and edges are considered part of the polygon is unspecified.)
In place of the geometry requests, two special requests are also accepted:
text
Matches if the client did not designate a point, e.g. if it is a text­based client such as lynx. Newer versions of lynx have now begun to send coordinates 0,0 with their map queries, which means that newer versions of umap have begun to map queries for 0,0 coordinates to text queries if the client program's name is lynx. That's progress for you.

default
Matches if nothing else (including text) matches.

Other Commands

by address
declares address to be the recipient of bug reports for the map file.  If address consists of more than one token, it must be quoted with double quotes.  If there is more than one by statement in a file, the names are concatenated into a comma­separated list when printing them.  The address can contain HTML markup and is not automatically quoted by the program; consequently, special characters such as < and & must be quoted (as &lt; and &amp;) within the map file.

# comment
Comments start with a # that is not part of an URL, and continue to the end of the line.

Installation

Once the umap executable is installed on a host, there is no further installation necessary to use it for a particular umap.  (That is, there are no global configuration files to edit, and no permissions to be granted.)  If you are allowed to write HTML documents, you are allowed to write umaps.

Example

The file sample.html contains the text: 
<html><head>
<title>Umap example</title>
</head>
<body>
<a href="http://www.cs.tu-berlin.de/cgi-bin/umap/~jutta/ht/umap/sample.umap"
><img src="sample.gif" alt="(Hit return for a text-only version.)" ismap></a>
</body></html>
The file sample.gif is a drawing of a street scene.  Umap has been installed in the virtual binary directory cgi-bin.  Since our WWW host is called www.cs.tu-berlin.de, the URL of the umap script becomes http://www.cs.tu-berlin.de/cgi-bin/umap.

After that, you see the virtual pathname of the umap description file; in my case, it is the file /~jutta/ht/umap/sample.umap in the same directory that the gif is in, namely, /~jutta/ht/umap (virtually) or /home/kbs/jutta/.public_html/ht/umap (physically). The rules that map a virtual pathname to a physical pathname are fixed by the maintainer of a server, and differ between hosts; at our site, the virtual pathname /~user leads to the directory .public_html in user's Unix home directory.

The <img> element that displays the image contains the keyword (or ``attribute'') ismap.  If a client program supports image maps, it will send the point that the user clicked on as coordinates after the URL in the anchor, preceded by a question mark.  The HTTP server will split the URL into the path of the binary to invoke, the pathname of the map file, and the query arguments; based on those arguments and the map file, umap can select an URL or document to send back.

The map file that corresponds to the image, sample.umap, looks like this: 

by "Jutta Degener &lt;jutta@cs.tu-berlin.de&gt;"

# the artist, wrapped in a thick coat,

../../me/whois.html
        circle   61,93 20       # head
../../index.html              # coat, etc.
        poly    43, 114 52, 120 49, 148 54, 174 60, 175 54, 185
                79, 187 87, 185 100, 181 99, 173 109, 170 107, 148
                91, 116 79, 106 79,  96 52, 101

# toy duck
# (No connection to Spatula city, except that I like their duck)

"http://www.wam.umd.edu/~twoflowr/index.html"
        poly  148, 165 163, 152 178, 162 202, 160 186, 190 166, 186

# the information superhighway (whole lower screen)

/~jutta/ht/index.html   rect 0,166 299,222

# a devil in the window, just to keep the conspiracy theorists
# happy
"http://www.cs.umd.edu/users/chang/poetry.html" rect 184,91 199,106

# a few evil-looking commercial (but strangely derelict) buildings
# loom in the background.


"http://marketplace.com/"       rect   93,94 130,169
"http://branch.com/"            rect  129,63 223,170
"http://storefront.xor.com/"    rect   220,143 280,175

# a sign atop of one of the building blinks ``buy! buy!''.

"http://www.directory.net/" {
        point 151,54  60
        point 200,51  60
}

sample-text.html        text
With this goes a file sample-text.html that contains a textual description of the whole street scene.  Users of character­based browsers will see the line 
     (Hit return for a text-only version.)
in place of the image, can select the link without coordinates, and receive a redirection request to the text­only file from umap.

Errors

400 umap: no map file specified.
The URL did not contain a virtual path name.

404 umap: a file name does not exist.
The map file doesn't exist. (In most cases, the user did not specify a full virtual path name, but just a local path name.)

403 umap: no permission to open map file name for reading.
The file exists, but cannot be opened; it probably has the wrong mode.

404 umap: cannot open map file name for reading (Unix errno N).
The file exists, but cannot be opened.

500 Internal error ...
The map file contains syntactical errors. Together with the error status, umap sends a list of error messages and a request for them to be forwarded to the script's author or maintainer.

See also

imagemap(1)
jutta@cs.tu-berlin.de, March 8th, 1996