Usage and documentation for source:trunk/py/ws-pinwin.py
ws-pinwin.py - an HTTP interface to the ModestMaps map tile composer
with support for rendering and plotting markers.
------------------------------------------------------------------------
EXAMPLE
------------------------------------------------------------------------
http://127.0.0.1:9999/?provider=MICROSOFT_ROAD&method=extent&bbox=45.482
882,%20-73.619899,%2045.532687,%20-73.547801&height=1024&width=1024&mark
er=roy,45.521375561025756,%20-73.57049345970154&marker=mileend,45.525825
499457,%20-73.5989034175872,600,180&marker=cherrier,45.51978191639917,-7
3.56947422027588&bleed=1
Returns a PNG file of a map of Montreal at the appropriate zoom level to
display the bounding box in a image 1024 pixels square, with (3) empty
pinwin markers.
------------------------------------------------------------------------
PARAMETERS
------------------------------------------------------------------------
* provider (required)
A valid ModestMaps map tile provider.
* method (required)
One of the following options :
* center (optional)
Render map tiles centered around a specific coordinate. If defined,
the following parameters must also be present :
* latitude (required)
A valid decimal latitude.
* longitude (required)
A valid decimal longitude.
* accuracy (required)
The zoom level / accuracy (as defined by ModestMaps rather than any
individual tile provider) of the final image.
* height (required)
The height of the final image
* width (required)
The width of the final image
* extent (optional)
Render map tiles at a suitable zoom level in order to fit a bounding
box in an image with specific dimensions. If defined, the following
parameters must also be present :
* bbox (required)
A bounding box comprised of comma-separated decimal coordinates in
the following order : SW latitude, SW longitude, NE latitude, NE
longitude
* height (required)
The height of the final image
* width (required)
The width of the final image
* bbox (optional)
Render all the map tiles necessary to display a bounding box at a
specific zoom level. If defined, the following parameters must also be
present :
* bbox (required)
A bounding box comprised of comma-separated decimal coordinates in
the following order : SW latitude, SW longitude, NE latitude, NE
longitude
* accuracy (required)
The zoom level / accuracy (as defined by ModestMaps rather than any
individual tile provider) of the final image.
* marker (optional)
Draw a pinwin-style marker at a given point. You may pass multiple
marker arguments, each of which should contain the following comma
separated values :
* label (required)
A unique string to identify the marker by
* point (required)
A comma-separated string containing the latitude and longitude
indicating the point where the marker should be placed
* dimensions (optional)
A comma-separated string containing the height and width of the marker
canvas - the default is 75 x 75
* fill (optional)
A helper argument which if present will cause each marker specified to
be filled with the contents of map for the marker's coordinates at zoom
level 15. The value should be a valid ModestMaps map tile provider.
* adjust (optional)
Adjust the size of the bounding box argument by (n) kilometers; you may
want to do this if you have markers positioned close to the sides of
your bounding box
* bleed (optional)
If true, the final image will be enlarged to ensure that all marker
canvases are not clipped
* filter (optional)
Filter the map image before any markers are applied. Valid options are
:
* atkinson (optional)
Apply the Atkinson dithering algorithm to the map image
------------------------------------------------------------------------
METADATA
------------------------------------------------------------------------
Metadata about an image is returned in HTTP headers prefixed with
'X-wscompose-'.
For example :
HTTP/1.x 200 OK
Server: BaseHTTP/0.3 Python/2.5
Date: Sun, 13 Jan 2008 01:08:37 GMT
Content-Type: image/png
Content-Length: 1946576
X-wscompose-Image-Height: 1024
X-wscompose-Image-Width: 1024
X-wscompose-Map-Zoom: 14.0
X-wscompose-Marker-mileend: 336,211,157,-131,600,180
X-wscompose-Marker-roy: 667,285,629,165,75,75
X-wscompose-Marker-cherrier: 679,312,641,192,75,75
Most headers are self-explanatory. Markers are a little more
complicated.
The string after 'X-wscompose-Marker-' is the label assigned to the
marker when the API call was made. The value is a comma separated list
interpreted as follows :
The first two numbers are the x/y coordinates for the lat/lon.
The second two are the x/y coordinates of the top left corner where the
actual pinwin content should be pasted.
The last pair are the dimensions of the pinwin content which is sort of
redundant unless you are opting for defaults and don't know what to
expect.
------------------------------------------------------------------------
ERRORS
------------------------------------------------------------------------
Errors are returned with the HTTP status code 500. Specific error codes
and messages are returned both in the message body as XML and in the
'X-ErrorCode' and 'X-ErrorMessage' headers.
------------------------------------------------------------------------
NOTES
------------------------------------------------------------------------
The shadows for the markers are stylized by design; especially when they
have been repositioned and have very long stems. Not only do they look
funny, I've decided I like that they look funny.
"Proper" shadows rendered in correct perspective are on the list and if
you want to help me with the math then they be added sooner still.
------------------------------------------------------------------------
QUESTIONS
------------------------------------------------------------------------
Is it fast?
Not really. It is designed, primarily, to be run on the same machine
that is calling the interface.
Will it ever be fast?
Sure. It is on The List (tm) to create a mod_python and/or wsgi
version. Patches are welcome.
Can I request map images asynchronously?
Not yet.
Can I get a pony?
No.
------------------------------------------------------------------------
LICENSE
------------------------------------------------------------------------
Copyright (c) 2007-2008 Aaron Straup Cope. All Rights Reserved. This is
free software. You may redistribute it and/or modify it under the same
terms the BSD license : http://www.modestmaps.com/license.txt
