This package can be used to put clickable, zoomable, maps on the web.
For an example of an online map that uses this software, see

 Campgrounds in the San Francisco Bay Area
 http://maps.openspacecouncil.org/cgi-bin/zoom/Land/camp  

The software in this distribution takes an existing image, slices it
into panels at various levels of magnification.  This is done once
when the map is created.  Then, a CGI script lets the user pan and
zoom from panel to panel.  The map images must be provided as GIF
files, and can be created through various means, for example with
drawing software such as Adobe Illustrator, or from a GIS database
using software such as ArcInfo/ArcView.  Because this system is based
on static panels, rather than images dynamically generated from a GIS
database, it does not give the user infinite control over the area
shown, layers shown, and so on.  If you want to create maps
dynamically from GIS data, the mapserver project is a good
alternative.
 http://mapserver.gis.umn.edu
However, one advantage to using static images is that you have more
control over what they look like, and the system responds faster for
the user.

This package allows you to make certain regions clickable as
links to other web pages.  It adjusts the clickable regions
on each panel automatically.  Clickable regions can be 
created from points, lines, or polygons in a GIS shapefile.

To get started with this package:

- download mapzoom.tar.gz, unzip, and unpack with tar.

- type "make" to compile the C programs.

- move everything under the cgi-bin directory into a directory 
  on your web server where you can execute CGI program.

- move the Map directory, where the images are stored, into a
  directory accessible from your web server,
  edit the zoom.cgi script to set $filepath to this directory.
  Set the $urlpath to this directory's name as accessed
  in urls.  For example, $filepath might be /usr/local/httpd/docs,
  and $urlpath might be empty, or $filepath might be 
  /home/joeuser/public_html/Test and $urlpath might be
  /~joeuser/Test, if you access this directory as 
  http://www.mydomain.com/~joeuser/Test/.

- run makemap.pl on the file Map/Land/camp, and you should
  be able to access this sample map as  
   http://www.mydomain.com/~joeuser/cgi-bin/zoom.cgi/Land/camp
  if you have installed zoom.cgi under 
   http://www.mydomain.com/~joeuser/cgi-bin/


The process for creating a new map goes as follows:

- Create the images, using drawing software or a GIS package.
  You must create one GIF image for each level of magnification
  that the user will have access to, typically two to four levels.
  You can show more detail in the more magnified images, for
  example leaving text off the zoomed out image that would
  not be readable.

- Run makemap.pl to slice the images into static panels.

- Create a imagemap file, if you want clickable regions.
  If you are creating your map from an ESRI shapefile
  produced by ArcView or compatiable software, you can
  translate lines, points, or regions from your shapefile
  into an imagemap using the shp2imagemap.pl script.

- edit the mapname.db file to customize the map title, 
  move everything into the appropirate directories on 
  your web server, and you're off!






This distribution contains code for 

- zoom.cgi - main interactive cgi program

- mapscan - called by zoom.cgi to check whether point
	clicked on by user in part of a linked area

- scale - cgi program, generates scale bar of appropriate
	length dynamically

The above three programs are used at run time (while browing
the map) and must be executable on your web server.  The following
programs are used while creating the map:

- makemap.pl - cuts large gif images into individual panels
	for each level

- crop - called by makemap.pl, cuts the map into panels. 

- drawmap - draws outline of linked regions from an imagemap
	file onto the gif image.  Useful for checking
	that the co-ordinate transformation from the original
	GIS file was done correctly.

- shp2imagemap.pl - convert shapefile from GIS software into
        an imagemap file used by zoom.cgi to define clickable
        regions on the map.

- dbf2html.pl - makes a html file for each entry in your 
	shapefile, listing all database fields and their
	values.  This is an easy way to create web pages
	to link to for clickable maps, though you will
	probably want to customize their contents and appearance.

- dump-shp.pl - a utility for examining the contents of 
	shapefiles.  prints out co-ordinates for each shape
	together with contents of each database record.

zoom.cgi has configuration variables at the beginning
of the script for the directory in which your maps are kept.
Please set $filepath to the correct directory name.

PER-MAP CONFIGURATION AND FILE STRUCTURE

	Certain information about each map is kept 
	in a file named <mapname>.db
	for example $filepath/Map/Land/camp.db.
	The format of map.db is colon-separated fields:
	- map directory name
	- map name
	- number of levels
	- number of panels at each level in x dimension
	- number of panels at each level in y dimension
	- for interactive maps, return first or all matches
	- for interactive maps, description of item to select
	- scale: number of pixels per mile in most zoomed-in level.
	  if specified, used to produce scale bar below map image.

	gif files at various resolutions are named, for example,
	   system-0.gif, system-1,gif, system-2.gif
	these files as well as .ps and .pdf files are
	available through the "download" link in zoom.cgi.

	The individual zoomed panels that are displayed
	are stored in a separate subdirectory for each
	map.  These sections are created by "makemap.pl".

	Legend directory is used to create legend for all maps in the
	higher-level directory.  Create a file Land/Legend/index.txt,
	for example, for all maps in the Land directory.
	Legends are separate pages linked to from the maps.
	If you legend is small, you may included it the footer
	(see below) to show it on the same page with the map.

	Footer directory is used to create footers 
	for individual maps.  A system-wide footer is specified 
	at the beginning of zoom.cgi.  If a file Land/Footer/camp.txt
	exists, for example, for the map Land/camp, it will
	be used instead.

CONVERTING GIS SHAPE FILES

The script shp2imagemap.pl can be used to convert polygons, lines,
or points from a shapfile to clickable regions on your map.  This
script requires a configuration file to determine the mapping from
the co-ordinates in the shapefile to the pixel co-ordinates on your
image.  The file should have the following format:

 2791 3979 5.9499324E+05 4.0930356E+06 "new brighton" '#12' 
 153 254 4.5561317E+05 4.2902235E+06 "gualala point" '#20' 
 2779 966 5.9443556E+05 4.2526422E+06 "neil's vineyard" "#43" 
 url=http://www.openspacecouncil.org/Camp/$HTML

The first two columns are the x and y co-ordinates of a set of points
in the GIF image used by mapzoom, at the highest level of magnification,
and the third and fourth columns give the x and y co-ordinates for 
the same points in the shapefile.  The remainder of each line is thrown
away by the shp2imagemap.pl but can be used to keep names for each
point for your convenience.  The script shp2imagemap.pl will compute
the co-ordinate transformation for all points in the shapefile from
three examples.  To create the mapping file, pick three points near
the corners of the map.  You can use dump-shp.pl to view the co-ordinate
in teh shapefile, and a GIF viewing tool such as gimp, xv, or Photoshop
to determine the co-ordinate of the corresponding points in the GIF
file.

The final line of the file above specifies the url to which the clickable
region will link.  The url is given using variables that refer to fields
in the .dbf database of the shapefile.  For example, the camp shapfile
has a field call HTML.  The polygon in the shapefile whose HTML field
contains "Costanoa.html" will link to 
 http://www.openspacecouncil.org/Camp/Costonoa.html
Field names in the url begin with a $ and include all letters, numbers,
and underscore characters following the $.

As an example, the distribution contains an example shapefile and co-ordinate
transformation file for the camping map.  You can test shp2imagemap.pl
by running the following commands:
 cd mapzoom/Map/Land/shapefile/
 ../../../bin/shp2imagemap.pl coordinate_mapping.txt 3rd_level_text > camp.map

If you want the same region to be linked on all magnification levels of
the map, create file mapname.map in the same directory as the 
master image files for the map.  To have different areas linked for
each level of magnification, create file mapname-0.map, mapname-1.map,
mapname-2.map and so on for each level.  This is the technique used
for the imagemap files camp-1.map and camp-2.map included with
the distribution.



---

Dan Gildea
gildea at cs rochester edu
