pointMapper Manual

For an introduction to pointMapper, see "what is pointMapper?" nearby.

The pointMapper API

The following functions make up the API:

Loading and zooming on maps

pm_loadMap(mapUrl)

loads a new map into pointMapper. Example:

pm_loadMap("../basemaps/croppedworld.0.xml");

loads the world map described by croppedworld.0.xml This XML file specifies image and projection data in the RDFMap format. The path to the XML file should given be relative to the versioned pointmapper directory (pointmapper/1.6). XML descriptions in this format come with all maps from Map Bureau, and are listed with each map in the map catalog.

You can also use your own SWF or non-progressive JPG files as maps in pointMapper. To do this, create an RDFMap file with the relevant parameters as described in the RDFMap documentation.

pm_zoomLatLong(latmin,latmax,longmin,longmax)

Zooms to the given range in latitude and longitude. For example

pm_zoomLatLong(-58,13,-86,-30);

zooms to South America and

pm_zoomLatLong(46.174568,46.179023,-123.828308,-123.823365);

zooms to Shively Park in the town of Astoria, Oregon. Of course, the former zoom would be useful only on a map at world scale, and the latter only on map of much more local extent.

Displaying a single point

pm_setLatLong(lat,long)

moves a dot called "the indicator" to the given latitude and longitude. When the indicator is moved, an animated burst effect appears at the dot. The indicator, which is hidden before it is moved somewhere by pm_setLatLong or pm_setXY, is useful displaying one point at a time.

pm_setXY(lat,long)

moves the indicator to the given image coordinates.

pm_hideIndicator()

hides the indicator.

Displaying multiple points

pm_loadPoints(url)

loads a collection of points from an external XML file. The format of the file is illustrated by 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:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
xmlns:pm="http://www.mapbureau.com/pointmapper/vocabulary/"
>

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>
<pm:rollover> Astoria, Oregon</pm:rollover>
</geo:Point>

or by canvas coordinates (aka "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). The optional pm:rollover element specifies text that will pop up as the mouse rolls over the point. This text can be specified in HTML, suitably encoded for appearance within an XML file as in:

<pm:rollover>
&lt;font face="arial" size="-1" color="#333333"&gt;Battery Park &lt;/font&gt;
</pm:rollover>

pm_setPoints(pnts)

provides a way of displaying multiple points in pointMapper directly from the API without recourse to an external XML file. The argument pnts should be an array of JavaScript objects, each of which has properties specifying a position, a name, and an optional rollover. 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. Finally, the point may have a rollover property, corresponding to the <pm:rollover> element. Here is an example:

function GeoPoint(lat,lon,id,rollover)
{
  this . lat = lat;
  this . lon = lon;
  this . id = id;
  this . rollover = rollover;
}

var pnts = new Array(
new GeoPoint(46.179842,-123.825828,"astoria","Astoria, Oregon"),
new GeoPoint(40.700633,-74.014816,"Battery Park")
);

pm_setPoints(pnt);

pm_loadPoints, rather than pm_setPoints, should be used for large point sets (hundreds rather than dozens).

pm_highlight(id)

highlights the point with the given identifier.

pm_unhighlight(id)

removes the highlight from the point with the given identifier; if the point was not previously highlighted, the operation has no effect.

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.

The Locator

pm_setLocatorCallback(fn)

sets a callback which is invoked when the user clicks using the locator tool:

The callback takes three arguments. The first is a string indicating whether the remaining arguments supply latitude and longitude or image coordinates. This argument has two possible values: "latitude_longitude" or "x_y". (Latitude and longitude will always be supplied if the map description includes projection information.) The second argument is the latitude or image x coordinate, and the third the longitude or image y. If no callback is installed, locator click coordinates are reported in a small window that is popped for the purpose.

This allows pointMapper to be used to develop interfaces where the user enters location information by clicking on maps.