Map Bureau Home

This document concerns an early version of PointMapper. Please see the Map Bureau home page for up-to-date information about PointMapper. Thank You!

PointMapper Version 1.1[Out of date, but still supported]

PointMapper is a component for web pages that displays detailed zoomable maps, and that allows web page authors to overlay these maps with clickable dots representing points of interest. PointMapper is controlled via a simple scripting API. Included are functions to place dots at specified latitudes and longitudes, to highlight dots, to load new maps, and to set callbacks to handle clicks on dots. This allows web page authors to easily map locations of anything that interests them, and to integrate mapping into their pages as they see fit.

There is an example of PointMapper and the HTML that invokes it at the bottom of this page. Here are some others:

• Donalda's map blog
  Illustrates embedding PointMapper in a Blogger weblog.
• "Where I've Lived"
  A temporal application implemented by simple scripting.
• Jog Blog
  Illustrates integrating PointMapper with a Javascript calendar; also offers the option of displaying points on a vector map or on an aerial photo.
• Places in Astoria
  Illustrates callbacks from clicks on dots.
• Top New York Restaurants
  More points on a NYC Map; same simple structure as the example at the bottom of the page.

PointMapper displays vector maps that contain an order of magnitude more detail per kilobyte of download than the raster maps typically found on the web. Scroll to the bottom of this page to see an example map, and the very simple HTML that implements it. Note that the whole of Manhattan, with all of its streets and avenues, is present in zoomable form; the download size of this map is only 67 kilobytes.

The maps require only ordinary HTML, Javascript, and the ubiquitous Macromedia Flash player; no specialized software need be downloaded.

Although PointMapper supports map projections (allowing points to be specified in latitude and longitude) and compact vector maps, it also has options for displaying images without projection data, and images in the JPEG format (any non-progressive jpg can be used). When projection information is missing, point locations are specified by image coordinates rather than latitude and longitude. So, PointMapper can be used as an image annotation tool, as well as a mapping tool.

worldKit and Indy Junior are related mapping tools; see this comparison.

PointMapper is free for non-commercial use. Also, there is no need to download anything to use PointMapper; it can be run from Map Bureau's server. However, if you anticipate substantial traffic (or intend commercial use), please contact us, and we can provide a download. Commercial use is priced at $400/server/year, with a 30 day free trial.

Now, here are the details:

<script type="text/javascript" 
  src="http://www.mapbureau.com/pointmapper/1.1/m.php?style=width:400px;height:300px&color=00AAAA">
</script>

Alternatively size and position can be controlled via class as in:

<script type="text/javascript" 
  src="http://www.mapbureau.com/pointmapper/1.1/m.php?class=mapclass&color=00AAAA">
</script>

Usually, the script tag that instantiates PointMapper is followed immediately by initialization commands such as :

<script type="text/javascript">
   pm_loadMap("http://www.mapbureau.com/basemaps/manhattan.0.xml");
</script>

Then the coordinates of points clicked on the map will be shown at the bottom of the map, just below the map URL.

The locator is also available in PointMapper, and the API supports installing a callback for locator clicks. The callback is passed the latitude and longitude or image coordinates of the click. If no callback is installed, a report window shows the location of clicks.

Only one instance of PointMapper may appear per page, although instances can appear in multiple frames or iframes.

In addition to a set of points, PointMapper displays a moveable dot called the indicator. (Initially, before any API calls are made, the indicator is not visible.) The API functions pm_setXY and pm_setLatLong control the position of the indicator in image and geographic coordinates, respectively, and pm_hideIndicator hides it. The indicator is appropriate for applications where the only requirement is to indicate locations, one at a time, as in the example at the bottom of this page.

The Helper File

PointMapper requires that a small html file, called the "helper", be present somewhere on the same server as files that include PointMapper. By default, PointMapper assumes that the helper is named "pm_helper-1.1.html", and is in the same directory as the file hosting PointMapper. Here are the contents of the helper:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Pointmapper Helper File</title>
</head>
<body>
<script type="text/javascript"  src="http://www.mapbureau.com/pointmapper/1.1/h.php">
</script>
</body>
</html>

For downloading, the file can also be found at http://www.mapbureau.com/pointmapper/1.1/pm_helper-1.1.html. (Visit this page, and then use your browser's "save as" command to download)

<script type="text/javascript" 
  src="http://www.mapbureau.com/pointmapper/1.1/m.php?helper=/mydir/myhelper.html&style=width:400px;height:300px&color=00AAAA">
</script>

Tests

Although PointMapper should work with other scripting languages such as VBScript, it has only been tested with Javascript.

PointMapper has been tested (and works) on the following browsers:

The API

pm_setLatLong(lat,long)

moves the indicator to the given latitude and longitude. When the indicator is moved, an animated burst effect appears at the dot.

pm_setXY(x,y)

moves the indicator to the given image coordinates.

pm_hideIndicator()

hides the indicator.

pm_loadMap(mapUrl)

loads a new map into PointMapper. The argument should be the URL of an RDFMap file, or of a progressive JPEG.

pm_loadPoints(url)

loads a collection of points from an external XML file. The format of the file is illustrated by http://www.mapbureau.com/pointmapper/points.example.xml. The boilerplate at the beginning of the file:

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:geom2d="http://nurl.org/0/geom2d/1.0/"
xmlns:mapbureau="http://nurl.org/0/corporations/mapbureau/"
xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
>

brings it into compliance with the RDF standard - a format used in the semantic web project. If RDF and the semantic web are unfamiliar to you, don't worry. As long as the boilerplate is included verbatim, PointMapper will work correctly. Points within the file may be given by latitude and longitude, as in:

<geo:Point>
<geo:lat>46.179842</geo:lat>
<geo:long>-123.825828</geo:long>
<dc:identifier>astoria</dc:identifier>
</geo:Point>

or by image coordinates, illustrated by:

<geom2d:Point>
<geom2d:x>60</geom2d:x>
<geom2d:y>0</geom2d:y>
<dc:identifier>a</dc:identifier>
</geom2d:Point>

In either case, dc:identifier provides a unique name for the point. This name is used in highlighting and in the selection callback (see pm_highlight and pm_setSelectionCallback below).

pm_setPoints(pnts)

pnts should be a array of objects, each of which has properties specifying a position and name. As in the case of pm_loadPoints, positions can be given either in latitude/longitude, or in image coordinates. In the former case, the point should have properties named lat and lon (not long, since this is a Javascript keyword). In the case of image coordinates, the point should have properties named x and y. In both cases, the point should also have a property named id, which corresponds to the <dc:identifier> element, and is used in highlighting and selection callbacks.

pm_highlight(id)

highlights the point with the given identifier.

pm_setSelectionCallback(fn)

sets a callback which is invoked when the user clicks on dots. The callback should take one argument. The value passed to the callback is the id of the point clicked.

Here is the HTML for the example below:

<script type="text/javascript" 
   src="http://www.mapbureau.com/pointmapper/1.1/m.php?style=position:absolute;right:330px;width:250px;height:500px&color=FFFFFF">
</script>
<script type="text/javascript">
   pm_loadMap("http://www.mapbureau.com/basemaps/manhattan.0.xml");
</script>
<div style="float:left;width:300px">
<p>A few places in Manhattan:</p>
<a href="javascript:pm_setLatLong(40.792399,-73.952186)">The Museum of the City of New York</a><br/>
<a href="javascript:pm_setLatLong(40.768879,-73.985535)">Caribbean Cultural Center</a><br/>
<a href="javascript:pm_setLatLong(40.703597,-74.014858)">Battery Park</a><br/>
</div>