Locative Tech Maps Documentation
Written by Schuyler Erle <schuyler@geocoder.us>
Last updated 13 Apr 2005
Overview
The Locative Tech Map Service lives at http://geocoder.us/surfer/surfer.cgi. Called without options, the Map Service returns a JavaScript-driven interface with a map of the world based on VMap0.
Examples
- http://geocoder.us/surfer/surfer.cgi
With no options, the default map is shown.
- http://geocoder.us/surfer/surfer.cgi?size=375+175
The default map shown at half size. (Due to the size of the map control
icons, it would probably be preferable to reduce the number of zoom levels if a
map this size were to be used in earnest.)
- http://geocoder.us/surfer/surfer.cgi?marker=40.755932,-73.986508,capital,,,Times+Square
A map showing a single marker.
- http://geocoder.us/surfer/surfer.cgi?zoom=5¢er=40.755932+-73.986508&marker=40.755932,-73.986508,capital,,,Times+Square
The same map, zoomed in to level 5 (out of 8).
- http://geocoder.us/surfer/surfer.cgi?marker_url=http://geocoder.us/surfer/cities.txt
A marker file read from an HTTP URL.
- http://geocoder.us/surfer/docs/iframe.html
Example of the map service embedded in a page via an IFrame. View
source to see how this is used.
Usage
The Map Service supports the following optional URL query string
arguments for controlling the map output:
| Name | Value | Notes |
|---|
| mode |
[ normal | map | overview ] |
In normal mode, the entire map UI is loaded in the browser.
The JavaScript UI then uses the map and overview modes
internally to load the main and overview maps, based on user input. Normal
mode is the default, so you should almost never have to use this option.
|
| extent |
minx miny maxx maxy |
The extents of the image, given in the current projection.
Defaults to the entire world. |
| size |
width height |
Map size in pixels. Should be approximately 2:1. Defaults to
750 x 355 pixels. |
| zoom |
zoom_level [center_x center_y] |
If provided, the returned map is zoomed to the given zoom level,
centered on the image x and y coordinates, based on the
current map extents. |
| center |
lat lon |
If provided, the map is centered on the given lat/lon (and
the center_x and center_y params given to zoom are
ignored). |
| marker |
lat,lon,symbol,color,size,name,font,link |
The format of the marker specification is described below. More than one marker can be
specified in a single URL. |
| marker_url |
url |
The URL of a text file, containing marker specifications (as described
below), one per line. Although only
one marker_url can be specified per request, the
marker_url and marker options can be combined. |
Marker Specification
A marker specification is used to determine the look and behavior of each
supplied marker. The marker specification takes the form of a list of
comma-separated fields in the following order:
| Name | Value | Required? | Default |
|---|
| lat |
Latitude of the marker point. |
Yes |
None |
| lon |
Longitude of the marker point. |
Yes |
None |
| symbol |
Name of the marker symbol. |
Yes |
None |
| color |
Six-digit hex RGB color value, with leading hash mark. |
No |
#FF0000 |
| size |
Size of the marker in pixels. |
No |
20 |
| name |
Text label for the marker. |
No |
None |
| font |
Font to be used for the label, if provided. |
No |
univers |
| link |
URL to link the symbol to. If no URL is provided, the
marker is plotted but not hyperlinked. |
No |
None |
Any optional marker specification field can be left blank if
desired. If the remainder of the options in a given marker spec are
unused, the line can be truncated after the last option used. The label
is presently rendered at a font size half that of the marker.
Symbol Table
The following symbols are taken from TrueType cartography fonts and are
shown at 32 pixels wide, although they can be rendered at any size. More
symbols can be added or replaced on request. A maximum of 60 symbols can be
defined. An additional symbol, 'solid', is supported if a simple colored
dot is required.
| triangle |  |
diamond |  |
octagon |  |
| explosion |  |
ruins |  |
lighthouse |  |
| mine |  |
battle |  |
diving |  |
| snow |  |
church |  |
city |  |
| star |  |
hiking |  |
airport |  |
| oilrig |  |
radioactive |  |
bank |  |
| capital |  |
wildlife |  |
major_city |  |
| waypoint |  |
pedestrian |  |
skiing |  |
| cemetary |  |
camping |  |
star2 |  |
| port |  |
courthouse |  |
capital2 |  |
| wildlife2 |  |
major_city2 |  |
school |  |
| hospital |  |
info |  |
pedxing |  |
| diamond2 |  |
triangle2 |  |
fish |  |
| forest |  |
star4 |  |
microwave |  |
| picnic |  |
crosshair |  |
post |  |
| bicycle |  |
airport2 |  |
star3 |  |
| x |  |
crosshair2 |  |
x2 |  |
| farm |  |
Available Fonts
The following TrueType fonts are supported, but more can be added easily.
| denmark |  |
| pavilion |  |
| persans |  |
| tube |  |
| univers |  |
| univers2 |  |
| univers3 |  |
| universcondensed |  |
Technical Details
Under the hood, the surfer.cgi script makes use of the
MapScript-driven mapserv.py module in the same directory.
The strictly necessary files in that directory include:
| File | Purpose |
|---|
| mapserv.py |
This python module does all the heavy lifting, providing the
mapserv.Map class as a wrapper around mapscript.mapObj. See the
internal documentation and MapScript API docs
for more details. |
| surfer.cgi |
This Python CGI script calls mapserv.py with a pointer to the
MapFile configuration, the Cheetah UI template, and the
number of zoom levels to use. |
| surfer.html |
The template for the DHTML UI. See the Cheetah
users' guide for more information on how this template is
constructed. |
| surfer.map |
This file contains the current MapFile definition used by
the map service, which controls the appearance and contents of
the generated maps. See the MapServer
MapFile reference for more details. |
| nav/ |
The nav/ directory contains all of the images used in the UI
controls. |
| symbolset.txt |
This text file contains the symbol definitions used by the map service,
as described in the MapServer
MapFile reference. |
| fonts.txt |
This text file contains the TrueType font definitions, one per line. |
The following files are optional, but potentially useful:
| mkfontstxt |
This shell script can be used to regenerate the fonts.txt ffile. |
| blue_marble.gif |
A nice base image for a reference map, if we ever add one. |
| iframe.html |
An IFrame usage example for embedding the map inside another
page. |
| cities.txt |
An example marker file. |
The data, including several gigs of tiled VMap0 vectors in ESRI Shapefile
format, live in /www/gisdata. PostGIS is currently not
needed for this application.
One final technical note is that image tiles will pile up in the
/www/html/mstmp directory and need to be removed periodically.
A simple cron job has been installed in the root user's crontab on that
machine to accomplish this on a nightly basis:
05 01 * * * find /www/html/mstmp -ctime +1 | xargs rm