Locative Tech Maps Documentation

Written by Schuyler Erle <schuyler@geocoder.us>
Last updated 13 Apr 2005

Overview - Examples - Usage - Markers - Symbols - Fonts - Technical Details

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:

NameValueNotes
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:

NameValueRequired?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:

FilePurpose
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

Overview - Examples - Usage - Markers - Symbols - Fonts - Technical Details