- Installation
- Placing pointMapper on a Web Page
- The pointMapper API
- Tiling
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/2.0). 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:geo="http://www.w3.org/2003/01/geo/wgs84_pos#" xmlns:geom="http://fabl.net/vocabularies/geometry/1.1/" xmlns:geom2d="http://fabl.net/vocabularies/geometry2d/1.1/" 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> <geom:x>60</geom:x> <geom:y>0</geom: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> <font face="arial" size="-1" color="#333333">Battery Park </font> </pm:rollover>
pm_setRolloverWidth(wd)
sets the width in image coordinates of the text box that pops up for rollovers. The default is 120. This call can be made at any time, and subsequent rollovers will appear with the specified width.
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('places',pnts);
pm_loadPoints, rather than pm_setPoints, should be used for large point sets (hundreds rather than dozens).
Point Layers
Points may be displayed as groups called "layers", which can be manipulated independently via the API. The following call creates a new point layer:
pm_createPointLayer(lynm,shp,r,g,b)
where lynm is the name of the layer, shp indicates what shape should be used to display a point (alternatives are 'circle', 'triangle', and 'square'), and r, g, b are the red, blue, and green values for the color of the shape. The color parameters r, g, b should be integers ranging from 0 to 255. For example,
pm_createPointLayer('places','triangle',0,0,255);
creates a new layer called "places"; points in this layer will be displayed as blue triangles.
The two-argument variant:
pm_loadPoints(lynm,url)
loads a collection of points from the external XML file with the given url, and with the format described above, into the layer named lynm. Similarly, the variant
pm_setPoints(lynm,pnts)
installs the given points into the specified layer.
The one-argument variants of pm_loadPoints and pm_setPoints described above utilize a predefined layer of red circles named _default_. So, for example,
pm_loadPoints("_default_","points.xml");
is equivalent to
pm_loadPoints("points.xml");
pm_setMarkScale(sc)
controls the scaling of the marks (circles, squares, or triangles) that represent points in the point layers. The default mark scale corresponds to sc = 1.0; if marks that are twice this size are desired, issue the command:
pm_setMarkScale(2);
Polyline Layers
A polyline is a line made up of straight segments. The following call creates a layer for holding a polyline:
pm_createPolylineLayer(lynm,wd,r,g,b,a)
Here, lynm is the name of the layer, wd is the line width, r, g, b are the red, blue, and green values for the line color,and a is the alpha for the line - that is, its opacity. A line with alpha 100 is fully opaque, one with alpha 0 is transparent (invisible), and lines with alpha values that are greater than 0 and less than 100 are partly transparent. As for other color related calls, the color parameters r, g, b should be integers ranging from 0 to 255. For example,
pm_createPolylineLayer('route',2,255,0,0,50);
creates a layer that will, once loaded with data, display a line whose width is 2, whose color is red, and which is semi-transparent.
pm_loadPolyline(lynm,url)
loads a collection of points from the external XML file with the given url into the polyline layer named lynm. The effect is that the series of segments joining the points, in the order in which they appear in the file, will be drawn with the width, color, and alpha assigned to the layer. The syntax of the file is identical to that employed for pm_loadPoints, but the dc:identifier and pm:rollover elements are not needed.
pm_setPolyline(lynm,pnts)
provides a way of specifying the points for a polyline directly from the API without recourse to an external XML file. The argument pnts, as in the case of pm_setPoints, should be an array of JavaScript objects, each of which has properties specifying a position. If an object represents a latitude and longitude, it should have properties lat and lon, and if it specifies image coordinates, it should have properties x and y.
pm_drawPolylineRange(lynm,m,n)
causes a subrange of the points that have been loaded into the layer to be used in generating the displayed line. Specifically, the line starting at the mth point, and terminating at the nth point, and with segments sequentially joining the points with indices between m and n, is displayed. This supports such effects as animating a route by repeated calls to pm_drawPolylineRange(lynm,m,n) with iteration of the n parameter from 0 to the length of the point set.
Polygon Layers
The following call creates a layer for holding a polygon:
pm_createPolygonLayer(nm,lwd,lr,lg,lb,la,fr,fg,fb,fa)
nm is the name of the layer.
A polygon drawn in the layer has both a linear border, and an internal "fill" - a color drawn within the polygon's area. The parameters lwd, lr,lg, lb, la specify the width, red, green, blue, and alpha of the linear boundary. If no boundary is wanted, give 0 as the value for the la (alpha) parameter.
The parameters fr, fg, fb, fa specify the red, green, blue and alpha for the fill color for the polygon.
For example,
pm_createPolygonLayer('zone',2,0,255,0,100,255,255,0,50);
specifies that a polygon on the layer will be drawn with an opaque green border line of width 2, and a half-transparent yellow fill.
pm_loadPolygon(lynm,url)
loads a collection of points from the external XML file with the given url into the polygon layer named lynm. The effect is that the series of segments joining the points, in the order in which they appear in the file, will be construed as the boundary of a polygon to be drawn as specified by the parameters with which the layer was created. If the first and last points differ, they will be joined by a boundary segment to complete the polygon.
pm_setPolygon(lynm,pnts)
is analogous in effect to pm_setPolyline, and provides a way of specifying the points for a polygon directly from the API without recourse to an external XML file. The pnts argument should be take the same form as used in connection with pm_setPolyline.
Highlighting, Selection Callbacks, Visibility
pm_highlight(lynm,id)
highlights the point with identifier id on layer lynm. The one-argument variant,
pm_highlight(id)
highlights the point with identifier id on the _default_ layer.
pm_unhighlight(lynm,id)
removes the highlight from the point with identifier id on layer lynm. If the point was not previously highlighted, the operation has no effect. The one-argument variant,
pm_unhighlight(id)
unhighlights the point with identifier id on the _default_ layer.
pm_setSelectionCallback(fn)
sets a callback which is invoked when the user clicks on points. The callback should take one or two arguments. If it takes two arguments, the values passed to the callback are the name of the layer to which the point belongs, followed by the id of the point clicked; if one argument, only the point id is passed.
pm_hideLayer(lynm)
hides the layer called lynm, and
pm_showLayer(lynm)
shows (unhides) it.
pm_resetLayer(lynm)
removes the points appearing in layer lynm.
Image Layers
The content of a layer can consist of an image specified by a swf (Flash Movie) or non-progressive jpg file, instead of a set of points.
pm_createImageLayer(lynm)
creates an image layer, and
pm_loadImage(lynm,url)
loads a swf or jpg image from url into the layer named lynm. If the layer does not yet exist, it is created.
Note: the sequence
pm_createImageLayer(lynm);pm_hideLayer(lynm);pm_loadImage(lynm,url)
allows
the contents a layer to be specified without its being initially visible.
Resets and Mapping Parameter Modifications
pm_reset()
Empties out the contents of PointMapper, and frees associated resources. This call should be made when an entirely new map or set of map layers is to be loaded.
At any time in pointMapper, a current set of map parameters is in force. These specify the cartographic projection, the coverage in latitude and longitude of image layers, and the graphical extent of those layers. It is assumed that all image layers are consistent with the current map parameters.
The map parameters are loaded from an RDFMap file either via pm_loadMap described earlier, or by the call,
pm_setMapParameters(url)
pm_setMapParameters is identical in effect to pm_loadMap except that it serves only to set parameters, and not to load a basemap image file. If the RDFMap file passed to pm_setMapParameters specifies a basemap, it is ignored.
pm_setMapParameters is typically used when multiple image layers are involved, and pm_loadMap for the single basemap case, although nothing prevents addition of image layers to a basemap loaded by the pm_loadMap call. Again, see RDFMap for details about the parameters and the format of RDFMap files.
It is assumed that the map projection parameters for every image layer agree with those specified in the last pm_setMapParameters or pm_loadMap call. When either of these calls is made, all image and tiling layers are reset, but the point layers persist; those points with lat/long coordinates are reprojected for the new parameters. This allows the same set of points to be displayed over a variety of basemaps.
Tilings
A "tiling" is a composite image layer which consists of a grid of individual image files. The motivation behind tilings is to support detailed imagery that is visible only when zoomed in closely; only those tiles visible from a close-up view are loaded. As the map is panned, tiles are loaded as needed; when zoomed out beyond a threshold depending on the tile dimensions, the tiling layer is hidden.
The following command adds a tiling described by the file at url as a layer with name lynm.
pm_createTiling(lynm,url);
See the last section of this manual for details.
The operators pm_hideLayer, pm_showLayer and pm_resetLayer apply to all three kinds of layers: point layers, image layers, and tilings.
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.
Operations Dependent on Zoom Level
pm_spanRange(lynm,minSpan,maxSpan)
causes the layer lynm to shown at a specified range of zoom levels, and hidden otherwise. The span of a map view is the distance, in projected coordinates, across the currently visible width of the territory. For example, consider the map of Portland, Oregon in the map catalog. This uses the UTM (universal transverse mercator) projection; projected coordinates are in meters. The command:
pm_spanRange('label_z1',1501,4000);
causes the labeling layer label_z1 to be visible when between 1501 and 4000 meters of territory are visible across the width of the map. Since the coverage of the map when not zoomed is approximately 36 kilometers, this means that the label_z1 layer will appear when zoomed by a factor of more than approximately 9, but less than approximately 24.
If the pm_spanRange operator is called more than once on the same layer, the effective span range is replaced by each successive call (rather than indicating additional ranges within which the layer should be visible).
Together with tiling, the pm_spanRange command enables the development of maps whose content changes appropriately with zoom level; the Portland map provides an example.
pm_markScale(sc,minSpan,maxSpan)
This three-argument variant allows the mark scale to be set in a manner dependent on the zoom level. The specified value of sc will be in force as the mark scale when the visible span lies within the specified range. Multiple calls to pm_markScale can be used to supply desired scales for a series of span ranges. Outside of all specified ranges, the mark scale will default to the value given in the one-argument variant pm_markScale(sc), or to 1.0, if no one-argument call has been issued.
Backwards Compatability
The API supported in pointMapper version 2.0 is backward compatible with version 1.6. Functions are added for layers and tilings; compatibility is maintained via the inclusion of the _default_ layer (effectively the only layer available in 1.6).
Also, the RDFMap and RDFGeom specifications have been updated since the release of pointMapper 1.6, but pointMapper 2.0 continues to support map and point files using the earlier variants.