source: TI02-CSML/trunk/services/3rdParty/tilecache-1.4/README @ 2202

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI02-CSML/trunk/services/3rdParty/tilecache-1.4/README@2202
Revision 2202, 10.1 KB checked in by lawrence, 13 years ago (diff)

Adding tilecache to the "interesting" OGC services already implemented
in python.

Line 
1---------
2TileCache
3---------
4
5TileCache is a BSD licensed tile caching mechanism.  The goal is to make it
6easy to set up a WMS or TMS frontend to any backend data services you might be
7interested in, using a pluggable caching and rendering mechanism.
8
9This implements the WMS-C server recommendation, as defined by
10http://wiki.osgeo.org/index.php/WMS_Tiling_Client_Recommendation and the Tiled
11Map Service specification, available at
12http://wiki.osgeo.org/index.php/Tile_Map_Service_Specification
13
14TileCache will run under Python CGI or mod_python.
15
16Backend rendering can be powered by remote, or cascading, WMS requests, or by
17MapServer rendering via python-mapscript. Support for other rendering engines
18can be added with the implementation of a single function.
19
20Caches can be maintained on disk, or via the memcached memory-based LRU caching
21daemon. 
22
23TileCache was developed by MetaCarta Labs and released to the public under a
24BSD license. For updates on tools released by MetaCarta Labs, you can subscribe
25to the Labs Announce list, available at
26http://labs.metacarta.com/mailman/listinfo/announce .
27
28The TileCache was designed as a companion to OpenLayers, the BSD licensed web
29mapping interface. For help with setting up TileCache for use with OpenLayers,
30please feel free to stop by #openlayers, on irc.freenode.net, or to send email
31to labs@metacarta.com.
32
33To set up a TileCache under CGI
34===============================
35
36 * Extract the code to some web directory (e.g. in /var/www).
37 * Edit tilecache.cfg to point the DiskCache to the location you wish
38   to cache tiles, and the layers to point to the map file or WMS
39   server you wish to cache
40 * Permit CGI execution in the TileCache directory.
41   For example, if TileCache is to be run with Apache, the
42   following must be added in your Apache configuration:
43     <Directory /var/www/tilecache>
44          AddHandler cgi-script .cgi
45          Options +ExecCGI
46     </Directory>
47   where /var/www/tilecache is the directory resulting from
48   the code extraction.
49 * Visit:
50   
51   http://example.com/yourdir/tilecache.cgi?LAYERS=basic&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&SRS=EPSG:4326&BBOX=-180,-90,0,90&WIDTH=256&HEIGHT=256
52   or:
53   http://example.com/yourdir/tilecache.cgi/1.0.0/basic/0/0/0.png
54
55 * If you see a tile you have set up your configuration correctly. Congrats!
56
57Windows users: If you are using Windows, you should change the first line
58of tilecache.cgi to read:
59
60#!C:/Python/python.exe -u
61
62C:/Python should match the location Python is installed under on your
63system. In Python 2.5, this location is C:/Python25 by default. 
64
65To set up a TileCache under mod_python
66======================================
67
68 * Extract the code to some web directory (e.g. /var/www).
69 * Edit tilecache.cfg to point the DiskCache to the location you wish
70   to cache tiles, and the layers to point to the map file or WMS
71   server you wish to cache
72 * Add the following to your Apache configuration, under a <Directory> heading:
73       AddHandler python-program .py
74       PythonHandler TileCache.Service
75       PythonOption TileCacheConfig /path/to/tilecache.cfg
76   An example might look like:
77     <Directory /var/www/tilecache/>
78         AddHandler python-program .py
79         PythonHandler TileCache.Service
80         PythonOption TileCacheConfig /var/www/tilecache/tilecache.cfg
81     </Directory>
82   where /var/www/tilecache is the directory resulting from
83   the code extraction.
84 * Visit one of the URLs described above, replacing tilecache.cgi with
85   tilecache.py
86 * If you see a tile you have set up your configuration correctly. Congrats!
87
88To set up a TileCache under a standalone HTTP Server
89====================================================
90
91TileCache as of version 1.4 comes with a standalone HTTP server which uses
92the WSGI handler. This implementation depends on Python Paste, which can be
93downloaded from:
94 
95  http://cheeseshop.python.org/pypi/Paste
96
97For versions of Python earlier than 2.5, you will also need to install
98wsgiref:
99
100  http://cheeseshop.python.org/pypi/wsgiref
101
102Once you have all the prerequisites installed, simply run:
103
104  python tilecache_http_server.py
105
106This will start a webserver listening on port 8080, after which you should
107be able to open:
108
109  http://hostname:8080/1.0.0/basic/0/0/0.png
110
111to see your first tile.
112
113To set up a TileCache under FastCGI
114===================================
115
116TileCache as of version 1.4 comes with a fastcgi implementation. In
117order to use this implementation, you will need to install flup, available
118from:
119 
120  http://trac.saddi.com/flup
121
122This implementation also depends on Python Paste, which can be downloaded
123from:
124 
125  http://cheeseshop.python.org/pypi/Paste
126
127Once you have done this, you can configure your fastcgi server to use
128tilecache.fcgi.
129
130Configuring FastCGI is beyond the scope of this documentation.
131
132To set up a TileCache under IIS
133===============================
134
135Installing TileCache for use with IIS requires some additional configuration.
136
137 * Install Python for Windows
138 * Follow "Using Python Scripts with IIS" to setup Python CGI for IIS.
139   http://support.microsoft.com/kb/276494
140 * Edit metabase.xml to get correct Security Permissions for IIS 6.0.
141   http://blogs.msdn.com/david.wang/archive/2005/04/20/IIS6-CGI-Web-Service-Extension.aspx
142 * Edit tilecache.cgi to specify your configuration file explicitly:
143     
144    svc = Service.load("C:\\TileCache\\tilecache.cfg")
145
146Configuration
147-------------
148TileCache is configured by a config file, defaulting to tilecache.cfg.
149There are several parameters to control TileCache layers that are applicable
150to all layers:
151
152  bbox -- The bounding box of the Layer. The resolutions array defaults
153          to having resolutions which are equal to the bbox divided by
154          512 (two standard tiles).
155  debug -- Whether to send debug output to the error.log. Defaults to "yes",
156           can be set to "no"
157  description -- Layer description, used in some metadata responses. Default
158                 is blank.
159  extension -- File extension of the layer. Used to request images from
160               WMS servers, as well as when writing cache files.
161  layers -- A string used to describe the layers. Typically passed directly
162            to the renderer. The WMSLayer sends this in the HTTP request,
163            and the MapServerLayer chooses which layer to render based on
164            this string. If no layer is provided, the layer name is used
165            to fill this property.
166  levels -- An integer, describing the number of 'zoom levels' or
167            scales to support. Overridden by resolutions, if passed.       
168  mapfile -- The absolute file location of a mapfile. Required for
169             MapServer and Mapnik layers.
170  maxResolution -- The maximum resolution. If this is set, a resolutions
171                   array is automatically calculated up to a number of
172                   levels controlled by the 'levels' option.
173  metaTile -- set to "yes" to turn on metaTiling. This will request larger
174              tiles, and split them up using the Python Imaging library.
175              Defaults to "no".
176  metaBuffer -- an integer number of pixels to request around the outside
177                of the rendered tile. This is good to combat edge effects
178                in various map renderers. Defaults to 10.
179  metaSize -- A comma seperated pair of integers, which is used to
180              determine how many tiles should be rendered when using
181              metaTiling. Default is 5,5.
182  resolutions -- Comma seperate list of resolutions you want the TileCache
183                 instance to support.
184  size -- Comma seperated set of integers, describing the width/height
185          of the tiles. Defaults to 256,256
186  srs -- String describing the SRS value. Default is "EPSG:4326"         
187  type -- The type of layer. Options are:
188            * WMSLayer
189            * MapnikLayer
190            * MapServerLayer
191  url -- URL to use when requesting images from a remote WMS server. Required
192         for WMSLayer.
193
194OpenLayers with TileCache
195=========================
196
197To run OpenLayers with TileCache the URL passed to the OpenLayers.Layer.WMS
198constructor must point to the TileCache script, i.e. tilecache.cgi or
199tilecache.py. As an example see the index.html file included in the TileCache
200distribution.
201
202Note: index.html assumes TileCache is set up under CGI (see above). If you set
203up TileCache under mod_python you'd need to slighly modify index.html: the URL
204passed to the OpenLayers.Layer.WMS constructor must point to the mod_python
205script as opposed to the CGI script, so replace tilecache.cgi with
206tilecache.py. Similarly, you would need to edit this URL if you were to use
207TileCache with the standalone HTTP Server or FastCGI.
208
209The most important thing to do is to ensure that the OpenLayers Layer
210has the same resolutions and bounding box as your TileCache layer. You can define
211the resolutions in OpenLayers via the 'resolutions' option or the 'maxResolution'
212option on the layer. The maxExtent should be defined to match the bbox parameter
213of the TileCache layer.
214
215If you are using TileCache for overlays, you should set the 'reproject' option
216on the layer to 'false'.
217
218To use TileCache to seed your cache
219===============================
220
221 * Set up the tilecache.cfg if you have not already done so in one of the
222   above configurations
223
224 * In /var/www/tilecache/TileCache,  where /var/www/tilecache is the
225   directory resulting from the code extraction.
226
227 * The syntax is in the form of;
228<path to>python ./Client.py <url> <layer> <zoom start> <zoom stop> <bbox>
229
230   where:
231
232   url -- http://example.com/yourdir/tilecache.cgi? or
233          http://example.com/yourdir/tilecache.py
234   layer -- same layer name that is in the tilecache.cfg
235   zoom start -- Zoom level to start the process
236   zoom end -- Zoom level to end the process
237   bbox -- The bounding box (see the *** note *** above)
238
239  An example with zoom levels 5 through 12 would be like;
240/usr/bin/python ./Client.py "http://example.com/yourdir/tilecache.cgi?"
241     Zip_Codes 5 12 "-118.12500,31.952162238,-116.015625,34.3071438563"
242
243  The bbox can be dropped and defaults to world lonlat(-180,-90,180,90)
244
245/usr/bin/python ./Client.py "http://example.com/yourdir/tilecache.cgi?"
246     Zip_Codes 0 9
247
248=30=
Note: See TracBrowser for help on using the repository browser.