OSGeo - User contributions [en]

Tile Map Service Specification

2011-06-22T08:02:16Z

Wiki-WikiAdmin:

This document is the work of a loose community of participants interested in client/server mapping solutions that use multi-resolution image pyramids. It is meant to be used as a baseline for the implementation of client/server mapping software. It is not an "official standard" nor is it endorsed by OSGeo as an official project or work product of the Foundation.

This document is version "1.0", and will not be edited further. Changes will be discussed on the [[Tile Map Service Specification Change Requests]] page.

Any new revisions will take place in a new working copy.

==Introduction==

===Document Scope===

A Tile Map Service (TMS) provides access to cartographic maps of geo-referenced data, not direct access to the data itself. This document standardizes the way in which map tiles are requested by clients, and the ways that servers describe their holdings.

===Document Form===

This document will proceed from a description of general resources provided by the server to particular resources (such as map tiles) providing examples of access URLs and return values at each stage.

==Specification==

The Tiled Web Service provides access to resources, in particular, to rendered cartographic tiles at fixed scales. Access to these resources is provided via a "REST" interface, starting with a root resource describing available layers, then map resources with a set of scales, then scales holding sets of tiles.

Each resource contains the descriptive information and links to further resources. Note that while the URLs used to access resources may appear to have internal meaning (the resource for version 1.0.0 of the service has "1.0.0" in it's URL) such structure is ''not required'' of them.

The only requirement is that the resource be referenced by a URL (<nowiki>http://tms.osgeo.org/1.0.0/ could be http://tms.osgeo.org/onepointzeropointzero or http://tms.osgeo.org/flipper.xml as long as the value appeared in the href of the <TileMapService> element</nowiki>).

The value of an "href" '''must''' be an absolute URL (starting with "http://"). For example: href="<nowiki>http://www.service.org/subdirectory/tilemap.xml</nowiki>"

===Root Resource===

The root resource describes the available versions of the <TileMapService> (and possibly other services as well).

Request:

<nowiki>http://tms.osgeo.org/</nowiki>

Response (Content-type: text/xml):

<nowiki><?xml version="1.0" encoding="UTF-8" ?>
<Services>
<TileMapService title="Example Tile Map Service" version="1.0.0" href="http://tms.osgeo.org/1.0.0/" />
<TileMapService title="New Example Tile Map Service" version="1.1.0" href="http://tms.osgeo.org/1.1.0/" />
<FancyFeatureService title="Features!" version="0.9" href="http://ffs.osgeo.org/0.9/" />
</Services></nowiki>

Request:

<nowiki>http://www.osgeo.org/services/root.xml</nowiki>

Response:

<nowiki><?xml version="1.0" ?>
<Services>
<TileMapService title="Example Static Tile Map Service" version="1.0.0" href="http://www.osgeo.org/services/tilemapservice.xml" />
</Services></nowiki>

===TileMapService Resource===

The <TileMapService> resource provides description metadata about the service and lists the available <TileMaps>.

Optional elements in the resource are called out below using the pipe character. All other elements are mandatory.

Request:

<nowiki>http://tms.osgeo.org/1.0.0/</nowiki>

Response (Content-type: text/xml):

<nowiki><?xml version="1.0" encoding="UTF-8" ?>
<TileMapService version="1.0.0" services="http://tms.osgeo.org">
<Title>Example Tile Map Service</Title>
<Abstract>This is a longer description of the example tiling map service.</Abstract>
| <KeywordList>example tile service</KeywordList>
| <ContactInformation>
| <ContactPersonPrimary>
| <ContactPerson>Paul Ramsey</ContactPerson>
| <ContactOrganization>Refractions Research</ContactOrganization>
| </ContactPersonPrimary>
| <ContactPosition>Manager</ContactPosition>
| <ContactAddress>
| <AddressType>postal</AddressType>
| <Address>300 - 1207 Douglas Street</Address>
| <City>Victoria</City>
| <StateOrProvince>British Columbia</StateOrProvince>
| <PostCode>V8W2E7</PostCode>
| <Country>Canada</Country>
| </ContactAddress>
| <ContactVoiceTelephone>12503833022</ContactVoiceTelephone>
| <ContactFacsimileTelephone>12503832140</ContactFacsimileTelephone>
| <ContactElectronicMailAddress>pramsey@refractions.net</ContactElectronicMailAddress>
| </ContactInformation>
<TileMaps>
<TileMap
title="VMAP0 World Map"
srs="EPSG:4326"
profile="global-geodetic"
href="http://tms.osgeo.org/1.0.0/vmap0" />
<TileMap
title="British Columbia Landsat Imagery (2000)"
srs="EPSG:3005"
profile="local"
href="http://tms.osgeo.org/1.0.0/landsat2000" />
</TileMaps>
</TileMapService></nowiki>

Request:

<nowiki>http://www.osgeo.org/services/tilemapservice.xml</nowiki>

Response (Content-type: text/xml):

<nowiki><?xml version="1.0" encoding="UTF-8" ?>
<TileMapService version="1.0.0" services="http://www.osgeo.org/services/root.xml">
<Title>Example Static Tile Map Service</Title>
<Abstract>This is a longer description of the static tiling map service.</Abstract>
| <KeywordList>example tile service static</KeywordList>
| <ContactInformation>
| <ContactPersonPrimary>
| <ContactPerson>Paul Ramsey</ContactPerson>
| <ContactOrganization>Refractions Research</ContactOrganization>
| </ContactPersonPrimary>
| <ContactPosition>Manager</ContactPosition>
| <ContactAddress>
| <AddressType>postal</AddressType>
| <Address>300 - 1207 Douglas Street</Address>
| <City>Victoria</City>
| <StateOrProvince>British Columbia</StateOrProvince>
| <PostCode>V8W2E7</PostCode>
| <Country>Canada</Country>
| </ContactAddress>
| <ContactVoiceTelephone>12503833022</ContactVoiceTelephone>
| <ContactFacsimileTelephone>12503832140</ContactFacsimileTelephone>
| <ContactElectronicMailAddress>pramsey@refractions.net</ContactElectronicMailAddress>
| </ContactInformation>
<TileMaps>
<TileMap
title="Vancouver Island Base Map"
srs="EPSG:26910"
profile="none"
href="http://www.osgeo.org/services/basemap.xml" />
</TileMaps>
</TileMapService></nowiki>

===TileMap Resource===

A <TileMap> is a (usually) cartographically complete map representation. Sometimes <TileMap>s are built to be used in conjunction, as a set of stacked layers, but they are generally visually complete on their own.

<TileMap>s are composed of a set of scale-appropriate cartographic renderings, each divided up into regularly spaced image tiles, called <TileSet>s. Small-scale (eg, 1:10000000) tile sets may only contain a handful of tiles. Large-scale tile sets (eg, 1:10000) may contain millions of tiles.

At a particular scale, and in a particular cartographic projection, a <TileMap> is represented by a <TileSet>, a coverage of regularly sized and spaced images that taken together form a complete visual representation of the entire area of coverage of the <TileMap>.

Request:

<nowiki>http://tms.osgeo.org/1.0.0/vmap0</nowiki>

Response (Content-type: text/xml):

<nowiki><?xml version="1.0" encoding="UTF-8" ?>
<TileMap version="1.0.0" tilemapservice="http://http://tms.osgeo.org/1.0.0">
<Title>VMAP0 World Map</Title>
<Abstract>A map of the world built from the NGA VMAP0 vector data set.</Abstract>
| <KeywordList></KeywordList>
| <Metadata type="TC211" mime-type="text/xml" href="http://www.org" />
| <Attribution>
| <Title>National Geospatial Intelligence Agency</Title>
| <Logo width="10" height="10" href="http://nga.mil/logo.gif" mime-type="image/gif" />
| </Attribution>
| <WebMapContext href="http://wms.org" />
| <Face>0</Face>
<SRS>EPSG:4326</SRS>
<BoundingBox minx="-180" miny="-90" maxx="180" maxy="90" />
<Origin x="-180" y="-90" />
<TileFormat width="256" height="256" mime-type="image/jpeg" extension="jpg" />
<TileSets profile=global-geodetic">
<TileSet href="http://tms.osgeo.org/1.0.0/vmap0/0" units-per-pixel="0.703125" order="0" />
<TileSet href="http://tms.osgeo.org/1.0.0/vmap0/1" units-per-pixel="0.3515625" order="1" />
<TileSet href="http://tms.osgeo.org/1.0.0/vmap0/2" units-per-pixel="0.17578125" order="2" />
<TileSet href="http://tms.osgeo.org/1.0.0/vmap0/3" units-per-pixel="0.08789063" order="3" />
</TileSets>
</TileMap></nowiki>

Request:

<nowiki>http://tms.osgeo.org/1.0.0/landsat2000</nowiki>

Response (Content-type: text/xml):

<nowiki><?xml version="1.0" encoding="UTF-8" ?>
<TileMap version="1.0.0" tilemapservice="http://tms.osgeo.org/1.0.0">
<Title>British Columbia Landsat Imagery (2000)</Title>
<Abstract>Landsat data collected in the year 2000 over British Columbia.</Abstract>
| <KeywordList></KeywordList>
| <Metadata type="TC211" mime-type="text/xml" href="http://www.org" />
| <Attribution>
| <Title>Government of British Columbia</Title>
| <Logo width="10" height="10" href="http://gov.bc.ca/logo.png" mime-type="image/png" />
| </Attribution>
| <WebMapContext href="http://wms.gov.bc.ca" />
<SRS>EPSG:3005</SRS>
<BoundingBox minx="100000" miny="100000" maxx="1800000" maxy="1800000" />
<Origin x="100000" y="100000" />
<TileFormat width="256" height="256" mime-type="image/png" extension="png" />
<TileSets profile="local">
<TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/2048" units-per-pixel="2048" order="0" />
<TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/1024" units-per-pixel="1024" order="1" />
<TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/512" units-per-pixel="512" order="2" />
<TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/256" units-per-pixel="256" order="3" />
<TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/128" units-per-pixel="128" order="4" />
<TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/64" units-per-pixel="64" order="5" />
</TileSets>
</TileMap></nowiki>

Request:

<nowiki>http://www.osgeo.org/services/basemap.xml</nowiki>

Response (Content-type: text/xml):

<nowiki><?xml version="1.0" encoding="UTF-8" ?>
<TileMap version="1.0.0" tilemapservice="http://www.osgeo.org/services/tilemapservice.xml">
<Title>Vancouver Island Base Map</Title>
<Abstract>A map of the Vancouver Island built from British Columbia planimetric mapping
data and digital elevation hill shading.</Abstract>
| <KeywordList></KeywordList>
| <Metadata type="TC211" mime-type="text/xml" href="http://www.org" />
| <Attribution>
| <Title>Goverment of British Columbia</Title>
| <Logo width="10" height="10" href="http://www.gov.bc.ca/logo.gif" mime-type="image/gif" />
| </Attribution>
| <WebMapContext href="http://openmaps.gov.bc.ca" />
<SRS>EPSG:26910</SRS>
| <Face>0</Face>
<BoundingBox minx="500000" miny="4800000" maxx="700000" maxy="5500000" />
<Origin x="500000" y="4800000" />
<TileFormat width="256" height="256" mime-type="image/png" extension="png" />
<TileSets profile="none">
<TileSet href="http://www.osgeo.org/services/basemap/L1" units-per-pixel="6400" order="0" />
<TileSet href="http://www.osgeo.org/services/basemap/L2" units-per-pixel="1600" order="1" />
<TileSet href="http://www.osgeo.org/services/basemap/L3" units-per-pixel="400" order="2" />
<TileSet href="http://www.osgeo.org/services/basemap/L4" units-per-pixel="100" order="3" />
<TileSet href="http://www.osgeo.org/services/basemap/L5" units-per-pixel="25" order="4" />
</TileSets>
</TileMap></nowiki>

Each <TileMap> supports one <SRS> and one image format. To support more than one SRS or image format, define extra <TileMaps> in your <TileMapService> for each combination you want.

<TileMap>s have both a <BoundingBox> and an <Origin>. The <BoundingBox> is the extent of the data of interest -- it might be used by a client to set an initial spatial extent. The <Origin> is the lower-left corner of the 0/0 tile, and the upper right corner of tile -1/-1 (if you choose to configure your service so that negative tiles are required). The <Origin> may be outside of the visual region of interest (the <BoundingBox>), for reasons of implementation convenience.

<TileMap>s may participate as a <Face> of a larger complex of <TileMap>s. The OSGPlanet and GeoFusion clients both use separate polar faces in conjuction with equatorial faces (an "earth cube") to create a single world view from multiple tile maps. See [[#Using Faces]].

<TileMap>s may implement one of three "profile"s, two global profiles in common global projections, or a local profile in an arbitrary projection. All profiles restrict the service to a fixed set of scales, to allow tilesets from different Gotomeeting services to be more easily overlaid.

===Profiles===

Using this server specification will ensure that clients can easily consume your tiled map data. However, it will not guarantee that clients can efficiently overlay your data with data from other tile map servers. In order to maximize the interoperability of your tile map with other tile maps, you must implement the a "profile" for your tile map.

The profile a <TileMap> supports is advertised in the "profile" attribute of the <TileSets> element. The "profile" will be one of:

* none
* global-geodetic
* global-mercator
* local

====global-geodetic====

If the profile type is set to "global-geodetic", the <TileMap> must meet the following requirements:

* Must use <SRS>EPSG:4326</SRS>
* Must provide <TileSet>s with units-per-pixel meeting the following formula for any integral value of "n" greater than or equal to 0: units-per-pixel = 0.703125 / 2^n
** This scaling allows an initial zoom level that consists of 2 256x256 pixel tiles covering the whole earth, with an <Origin> of (-180,-90). Other combinations of tile size and <Origin> are also possible at this scale.

<nowiki><TileSets profile="global-geodetic">
<TileSet href="http://tms.osgeo.org/1.0.0/vmap0/0" units-per-pixel="0.703125" order="0" />
<TileSet href="http://tms.osgeo.org/1.0.0/vmap0/1" units-per-pixel="0.3515625" order="1" />
<TileSet href="http://tms.osgeo.org/1.0.0/vmap0/2" units-per-pixel="0.17578125" order="2" />
<TileSet href="http://tms.osgeo.org/1.0.0/vmap0/3" units-per-pixel="0.08789063" order="3" />
</TileSets></nowiki>

====global-mercator====

If the profile type is set to "global-mercator", the <TileMap> must meet the following requirements:

* Must use <SRS>OSGEO:41001</SRS>
* Must provide <TileSet>s with units-per-pixel meeting the following formula for any integral value of "n" greater than or equal to 0: units-per-pixel = 78271.516 / 2^n
** This scaling allows an initial zoom level that consists of four 256x256 pixel tiles covering the whole earth, with an <Origin> of (-20037508.34, -20037508.34). Other combinations of tile size and <Origin> are also possible at this scale.

====local====

Unlike the global profiles, the "local" profile is built from the bottom up, starting with a smallest possible scale of one unit per pixel and compounding upwards from there. Local profiles can be in any projection, but are at a fixed set of scales.

If the profile type is set to "local", the <TileMap> must meet the following requirements:

* May use any coordinate system, and must identify that coordinate system in the <SRS>.
* Must provide <TileSet>s with units-per-pixel meeting the following formula for any integral value of "n" greater than or equal to 0: units-per-pixel = 2^n
* Must provide <TileSet> sub-directories below the <Profile> href value, using the value of "n" appropriate for that <TileSet> as the sub-directory name.

<nowiki><SRS>EPSG:3005</SRS>
<BoundingBox minx="100000" miny="100000" maxx="1800000" maxy="1800000" />
<Origin x="100000" y="100000" />
<TileSets profile="local">
<TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/6" units-per-pixel="2048" order="0" />
<TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/5" units-per-pixel="1024" order="1" />
<TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/4" units-per-pixel="512" order="2" />
<TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/3" units-per-pixel="256" order="3" />
<TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/2" units-per-pixel="128" order="4" />
<TileSet href="http://tms.osgeo.org/1.0.0/landsat2000/1" units-per-pixel="64" order="5" />
</TileSets></nowiki>

===Tile Resources===

The origin of a <TileMap> is defined in the coordinates of the spatial reference system of the <TileMap>. The x-coordinate of the tile numbers increases with the x-coordinate of the spatial reference system, and the y-coordinate of the tile numbers also increases with the y-coordinate of the spatial reference system.

Tiles are addressed under the "href" specified in the <TileSet> appending the "x" tile coordinate as a directory name and using the "y" tile coordinate as the file name, with the file "extension" from the <TileFormat>.

Example:

The tile at the origin of the tile set in the first zoom level of vmap0.
<nowiki>http://tms.osgeo.org/1.0.0/vmap0/levelzero/0/0.jpg</nowiki>

The tile near the middle of the tile set in the third zoom level of vmap0.
<nowiki>http://tms.osgeo.org/1.0.0/vmap0/leveltwo/3/4.jpg</nowiki>

The tile near the middle of the tile set in the fifth zoom level of landsat2000.
<nowiki>http://tms.osgeo.org/1.0.0/landsat2000/1/8500/8500.png</nowiki>

The tile at the origin of the tile set in the first zoom level of basemap.
<nowiki>http://www.osgeo.org/services/basemap/L1/0/0.png</nowiki>

===TileMap Diagram===

[[Image:Tms.png]]

===Error Handling===

When an error occurs in the server, it is important that the client be able easily notice that an error has occurred, and ascertain ''why'' the error occured so the user can be notified if necessary.

The tile map server uses HTTP error codes to relay the general reason for an error condition, and an XML payload to communicate the specific reason for the failure in human readable language.

Only HTTP error codes given in this specification should be used to return errors to the client.

* The client requests a nonexistent resource URL. Return HTTP error code 404 (Not Found)
* The server fails in processing a response for a valid resource URL. Return HTTP error code 500 (Internal Server Error)

Servers are optionally allowed to return content, even when throwning an error code. The following is the XML format for a tile map server error message. If the Content-type of the return on an error is set to text/xml, this format is the required form of the response.

<nowiki><?xml version="1.0" ?>
<TileMapServerError>
<Message>The requested tile is outside the bounding box of the tile map.</Message>
</TileMapServerError></nowiki>

==Implementation Advice==

===Spatial Referencing Systems===

Spatial referencing systems for the tile map service will be defined using the EPSG database as a reference for "well-known" projections, subject to interpretations, given below.

There are two substantial implementation issues with using the EPSG database as a source of truth for spatial reference systems:

* Firstly, the EPSG database has some specific definitions for commonly used geodetic coordinate systems, in particular EPSG:4326 -- geodetic coordinates relative to the WGS84 spheroid. The EPSG definition for 4326 says that the coordinate order is latitude, longitude and that the units are degrees, minutes, seconds. However, common usage of EPSG:4326 in web mapping says that the coordinate order is longitude, latitude and the units are decimal degrees.
* Secondly, the EPSG database does not include every commonly used spatial reference system. There are still many local systems which are not included in the database, though the EPSG does make an effort to include new systems as they are brought to their attention. However, the EPSG does not catalogue commonly used global and large area systems, presumably as a matter of policy. For example, no EPSG identifier is provided for a Mercator projection of the world, or an Albers projection of North America.

The issues will be dealt with by fiat in this specification, matching implementation practice rather than following the database definition:

* For all geodetic coordinate systems in the EPSG database, the tile map service specification will treat the coordinate order as longitude, latitude and the units as decimal degrees.
* Spatial reference systems not defined in the EPSG database may be defined in the tile map service specification itself, using an OSGEO authority string.
** '''OSGEO:41001''' <nowiki>PROJCS["WGS84 / Simple Mercator", GEOGCS["WGS 84", DATUM["WGS_1984", SPHEROID["WGS_1984",6378137,298.257223563]], PRIMEM["Greenwich",0], UNIT["Decimal_Degree", 0.0174532925199433]], PROJECTION["Mercator_1SP"], PARAMETER["central_meridian",0], PARAMETER["false_easting",0], PARAMETER["false_northing",0], UNIT["Meter",1]]</nowiki>
** '''OSGEO:42310''' <nowiki>PROJCS["WGS84+GRS80 / Mercator", GEOGCS["WGS 84", DATUM["WGS_1984", SPHEROID["GRS 1980",6378137,298.257222101], TOWGS84[0,0,0]], PRIMEM["Greenwich",0], UNIT["Decimal_Degree",0.0174532925199433]], PROJECTION["Mercator_1SP"], PARAMETER["central_meridian",0], PARAMETER["false_easting",0], PARAMETER["false_northing",0], UNIT["Meter",1]]</nowiki>
** '''OSGEO:42101''' <nowiki>PROJCS["WGS 84 / LCC Canada", GEOGCS["WGS 84", DATUM["WGS_1984", SPHEROID["WGS_1984",6378137,298.257223563]], PRIMEM["Greenwich",0], UNIT["Decimal_Degree",0.0174532925199433]], PROJECTION["Lambert_Conformal_Conic_2SP"], PARAMETER["central_meridian",-95.0], PARAMETER["latitude_of_origin",0], PARAMETER["standard_parallel_1",49.0], PARAMETER["standard_parallel_2",77.0], PARAMETER["false_easting",0.0], PARAMETER["false_northing",-8000000.0], UNIT["Meter",1]]</nowiki>
** '''OSGEO:42304''' <nowiki>PROJCS["NAD83 / NRCan LCC Canada", GEOGCS["NAD83", DATUM["North_American_Datum_1983", SPHEROID["GRS_1980",6378137,298.257222101], TOWGS84[0,0,0]], PRIMEM["Greenwich",0], UNIT["Decimal_Degree",0.0174532925199433]], PROJECTION["Lambert_Conformal_Conic_2SP"], PARAMETER["central_meridian",-95.0], PARAMETER["latitude_of_origin",49.0], PARAMETER["standard_parallel_1",49.0], PARAMETER["standard_parallel_2",77.0], PARAMETER["false_easting",0.0], PARAMETER["false_northing",0.0], UNIT["Meter",1]]</nowiki>

===Maximizing Cacheability===

Tile maps are usually base maps, and usually represent data that changes on a very slow cycle. They are also usually large in volume, comprising potentially millions of different tiles. Given these basic facts, the aggressive use of caching strategies can optimize performance of tile map services.

Caching can happen at multiple layers between the server and the client:

* At the client itself, as the user-agent caches results on the local disk.
* In a shared cache at an intermediate ISP, allowing multiple users of the ISP to pull data from the cache.
* In a cache on the server itself, to move load from the tile generator to a simpler caching process.

In order for caching to occur at any of these layers, the caching mechanisms need to know when a resource is cachable.

If your tile server is written using a scripting or programming language, you will probably be constructing your HTTP headers yourself, and it is important to include cache control headers when doing so to allow caching to occur.

There are different cache headers for HTTP 1.0 and HTTP 1.1, and because both protocols are in active use, it is important to include both.

For HTTP 1.0, use the "Expires" header. If you expect your data to change no more than once per week, set your Expires header to one week in the future. For example, if it is January 1, 2007, and you wanted your tiles to expire no more than one week after they are retreived, you would set your header using this PHP invocation:

header('Expires: Mon, 8 Jan 2007 14:57:12 GMT');

Or, to always set the Expires header to one week in the future:

header('Expires: ' . gmdate('D, j M Y H:i:s T', time() + 7 * 24 * 60 * 60)); // time + 7 days worth of seconds

For HTTP 1.1, use the "Cache-control" header. Unlike the older "Expires" header, "Cache-control" does not have a clock reference, just a time period to reatain the data, thereby avoiding the clock sychronization issues of "Expires".

header('Cache-Control: max-age=86400, must-revalidate');
header('Cache-Control: ' . 7 * 24 * 60 * 60 );

Read about HTTP 1.1 cache control headers in the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9 W3.org specification].

===Implementing Cacheability===

You can trust that the somewhere on the internet, someone will respect your cache control headers and your content will be cached, ''or'' you can set up your own cache. If you are running Apache 2.0 adding [http://httpd.apache.org/docs/2.0/mod/mod_cache.html mod_cache caching] to your tms is laughably easy.

Just add a mod_cache directive inside your <VirtualHost> definition:

<IfModule mod_disk_cache.c>
CacheRoot /tmp/apache-cache
CacheSize 1024000
CacheEnable disk /cgi-bin/tms
CacheDirLevels 5
CacheDirLength 3
</IfModule>

This example is for a disk cache, probably what you will use for your TMS, since the data volumes tend to be high. Note how the CacheEnable directive allows you to very precisely control which content you are going to cache. In my case, I am only caching the output from my TMS server, nothing else. If I wanted, I could be even narrower and restrict caching to just one tile map inside my service, or just one tile set.

===URLs That are Actually Scripts===

For large implementations of the tile map server specification, the data will not be statically pre-built, but will be demand-generated by some kind of backend service. That means that URLs that appear to be static may actually be dynamic.

The [http://hoohoo.ncsa.uiuc.edu/cgi/env.html CGI specification] allows this trivially, by passing any path information after the CGI executable in the URL back to the executable in the PATH_INFO environment variable:

<nowiki>http://tms.osgeo.org/cgi-bin/tms/1.0.0/vmap0</nowiki>

PATH_INFO = 1.0.0/vmap0

If "tms" is the CGI executable, it can easily extract the remaining path information and use that for processing purposes.

Note that by default some versions of Microsoft IIS do not conform to the CGI specification for this behavior (Apache does). See the note at http://support.microsoft.com/kb/q184320/ for information on how to enable this bahavior in IIS.

Note that it is allowable for URLs to include "."s in the middle of paths, so that executable scripts (like PHP files) can be legally used as TMS servers.

Here is a root resource:
<nowiki>http://tms.osgeo.org/tms.php</nowiki>

Here is the a tile request on that server:
<nowiki>http://tms.osgeo.org/tms.php/1.0.0/thetilemap/firstlevel/2/1.jpg</nowiki>

In general, the simplest way to extract information from the incoming script invocation is to take the incoming PATH_INFO environment variable, strip the "/" character from the start and end of the string, and then split the string into an array using the "/" character. In this manner, the first element of the array will be the version, the second element will be the tile map, the third will be the level, the fourth will be the tile "x" and the fifth will be the tile "y" (with a .extension).

===Using Faces===

The "face-id" attribute of the <TileMap> referenced in the <TileMapService> is used for some specialized clients. How that attribute is used by each client is described here.

''To be filled in by implementation knowledge...''

===Reference Implementations===

====Servers====

* TileCache
** http://www.tilecache.org/

====Clients====

* Worldkit: http://worldkit.org/tilemap/
* Openlayers: http://openlayers.org/
* Cadcorp SIS: [http://wiki.osgeo.org/images/a/a5/CadcorpTmsClient.png Screenshot]
* [http://www.merkaartor.org/ Merkaartor], an [http://www.osm.org OpenStreetMap] editor, can use a TMS server as source for background layers: ''Note that like Google's map tiles OpenStreetMap counts tile 0,0 from the top-left not the bottom-left.''

===Returning Error Codes===

If your tile map server is a static set of files, you will find that your web server sets the appropriate error codes automatically when people ask for resources that do not exist, or the server suffers a failure.

However, if your tile map server is dynamic, you will have to set the HTTP status codes yourself, otherwise the HTTP server will assign a code of 200 (OK) for your error message XML document, which would be wrong. In PHP, an error return function might look like this:

header("HTTP/1.0 404 Not Found");
header("Content-type: text/xml");
print "<?xml version='1.0' ?>";
print "<TileMapServerErrror>";
print "<Message>You requested a map tile [ $path_info ] that does not exist.</Message>";
print "</TileMapServerError>";

Note that in addition to setting the error code the Content-type was also correctly set. Also note that cache headers were ''not'' set, since errors are not a good thing to cache.

==See Also==

* [http://www.peej.co.uk/articles/rest.html What is REST]
* [http://www.shindiristudio.com/SEO-optimizacija-sajta/ SEO]
* [http://wiki.openstreetmap.org/wiki/Slippy_map_tilenames OpenStreetMap's "Slippy tiles"]. ''Note that like Google map tiles, their grid counting starts from the top-left not the bottom-left.''

[[Category:Standards]]
[[Category:Tiling]]

Live GIS Disc

2011-06-22T07:58:22Z

Wiki-WikiAdmin:

= About =

[http://live.osgeo.org OSGeo Live] provides [http://en.wikipedia.org/wiki/Live_CD bootable ISO-Images] and [http://en.wikipedia.org/wiki/Virtual_machine Virtual Machines] which allow users to try out fully-operational versions of popular Free Geospatial Software without the need to install a thing. Everything is set up for you ready to go: just reboot into it, glance at the help pages on the desktop, and go. The existing hard drive and operating system will not be modified in any way, everything happens in temporary system memory. As such it will run a bit slower than the "real thing" and you may want to grab a USB flash drive to save or transfer files with. You can load and boot a live-image completely from a USB stick too if you prefer.

We do this in large part by maintaining automated build scripts which collect many [[OSGeo]] programs and sample data-sets together, and then combine them to form the Live disc or VM itself. By tweaking these scripts users are free to make their own custom distributions, for example localized in their own language and with local map data.

* For the [http://2009.foss4g.org/ 2009 FOSS4G conference] a snapshot of Free Geospatial software has been collected onto the [http://arramagong.com Arramagong Live DVD and VM].
: ''The Arramagong Live DVD & VM contains a collection of the best Geospatial Open Source software, pre-configured with sample data. The DVD and Virtual Machine are available for download at http://live.osgeo.org/en/download.html . Refer to [[Live GIS Disc Quick Start]] to get started.''

= Key Links =
== Quick Start ==
* [[Live GIS Disc Quick Start]]

== How to add a project to OSGeoLive ==
* [[Live GIS Add Project]]
* [[Live_GIS_Disc_Apply|Questions to answer when requesting to add an application to OSGeo-Live]]

== Build Process ==
* [[Live GIS Build]] instructions

== Package List ==
* [http://spreadsheets.google.com/ccc?key=0Al9zh8DjmU_RdGIzd0VLLTBpQVJuNVlHMlBWSDhKLXc&hl=en_GB#gid=5 Package List and status spreadsheet]

* [[Live_GIS_Disc_Packages#Package_wishlist|Future/wishlist]]

== Documentation ==
[[Live_GIS_Add_Project#Documentation]]

Stable release: http://live.osgeo.org

Nightly build: http://adhoc.osgeo.osuosl.org/livedvd/docs/en/index.html

== Translate ==

[[Live GIS Translate]]

== Artwork ==
You can find the artwork sleeves, background images, booklet at:
* http://trac.osgeo.org/osgeo/browser/livedvd/artwork/

;Version 4.5:
* http://trac.osgeo.org/osgeo/browser/livedvd/artwork/backgrounds/4.5
* http://trac.osgeo.org/osgeo/browser/livedvd/artwork/sleeve/4.5

== Review ==

[[Live GIS Review]]

== Presentation ==

[[ Live GIS Presentation ]]

== Schedule ==
* [http://spreadsheets.google.com/ccc?key=tMRaCwabv7SiIG3moHEfMrQ&hl=en_GB Live GIS Disc Schedule]

== Contact Us ==
* Mailing List: http://lists.osgeo.org/mailman/listinfo/live-demo
: The mailing list is [http://news.gmane.org/gmane.comp.gis.osgeo.livedemo archived at Gmane] and [http://n2.nabble.com/OSGeo-FOSS4G-LiveDVD-f3623430.html Nabble]
* IRC: irc://irc.freenode.net#osgeolive
** You can log into IRC from: http://webchat.freenode.net/ Enter a nickname, and set channel=osgeolive
* [[Live_GIS_Disc_Meeting_Minutes|Meeting Minutes]]

== Downloads ==

Latest Stable Release: http://live.osgeo.org/en/download.html

Latest Development Release: http://live.osgeo.org/dev/build

Older Releases: http://download.osgeo.org/livedvd

== Issue Tracker==
Our bug and wish tracker is [http://trac.osgeo.org/osgeo/query?group=status&component=LiveDVD&order=priority hosted at OSGeo's Trac system]. To distinguish the LiveDVD project from other OSGeo projects, use the following conventions:
; Component field
: Set to `<tt>LiveDVD</tt>`
; Keywords:
: Version: Set to base release version: eg: 4.0, 4.5, 5.0 (not 4.5alpha1)
: Application: Set to application with issue (use lower case): eg: "geoserver"

; [https://trac.osgeo.org/osgeo/report/10 List of open tickets]

* [https://trac.osgeo.org/osgeo/query?status=new&status=assigned&status=reopened&component=LiveDVD&keywords=%7E4.0&order=priority Just those concerning the 4.0 release]
* [https://trac.osgeo.org/osgeo/query?status=new&status=assigned&status=reopened&component=LiveDVD&keywords=%7E4.5&order=priority Just those concerning the 4.5 release]
* [https://trac.osgeo.org/osgeo/query?status=closed&group=type&order=priority&component=LiveDVD List of tickets already fixed]

== OSGeo User Id ==
* Create an OSGeo id: http://www.osgeo.org/osgeo_userid , which is required to edit the wiki, commit to svn and create an issue in the issue tracker.

== Subversion ==
* Subversion: For config files and build scripts. You should always update from the server before editing a file, and always check the diff is as you intended before committing.
** Repository: https://svn.osgeo.org/osgeo/livedvd/gisvm/trunk and [http://trac.osgeo.org/osgeo/browser/livedvd/gisvm/trunk web view]
** On Linux systems: access Subversion using:
svn checkout https://svn.osgeo.org/osgeo/livedvd/gisvm/trunk

** On windows systems, install [http://tortoisesvn.tigris.org/ Tortoise Subversion], which extends Windows Explorer to include subversion commands.

To get commit access, you need to create yourself a user id, as per http://www.osgeo.org/osgeo_userid, then ask cameronDOTshorter.AT.lisasoftDOTcom to add you to the [https://www.osgeo.org/cgi-bin/auth/ldap_group.py?group=osgeo osgeo] user group.

The first thing you should do to test your svn install is to add your name the contributors list:
cd trunk/doc

# to edit a file
svn update contributors.csv
# edit contributors.csv

# optionally check to see what has changed.
svn diff contributors.csv

# check the file back into subversion
svn commit contributors.csv

# to add a file
cd <dir>
# create a file
svn add <file>
svn propset svn:mime-type <mime.type> <file>
svn commit <file>

# to move or rename a file
svn move <file>
svn commit <file>

On windows, it is even easier, using [http://tortoisesvn.tigris.org/ Tortoise SVN] which plugs directly into Windows Explorer.

== FAQ ==
* [[Live GIS Disc FAQ]]

== Press Releases ==
* [[FOSS4G 2009 Press Releases]]
** 27 August 2009, [[FOSS4G 2009 Press Release 28]] - Simple steps to get your project on the FOSS4G Live DVD
** 6 September 2009, [[FOSS4G 2009 Press Release 29]] - What Windows installers should be on the FOSS4G Live DVD + Live DVD Status.
** 3 October 2009, [http://cameronshorter.blogspot.com/2009/10/arramgong-gis-live-dvd-off-to-printers.html] '''Arramgong GIS Live DVD - off to printers'''
** 16 October 2009, [[FOSS4G 2009 Press Release 35]] - LiveDVD/VM on click2try [[FOSS4G 2009 Press Release 35 Cover|Cover Email]]
* 16 December 2009, [[Live GIS Disc Press Release 1]] - Defining the next LiveDVD/VM
* 14 January 2009, [[Live GIS Disc Press Release 2]] - 3 weeks to Live DVD 3.0 feature freeze
* 24 March 2010, [[Live GIS Disc Press Release 4]] - LiveDVD project joins Google Summer of Code
* 31 March 2010, [[Live GIS Disc Press Release 3]] - '''Arramagong Live DVD 3.0 released'''
* 10 June 2010, [[Live GIS Disc Press Release 5]] - Building OSGeo Live DVD for FOSS4G 2010
* 27 June 2010, [[Live GIS Disc Press Release 6]] - 1 week till OSGeoLive Feature Freeze
* 21 July 2010, [[Live GIS Disc Press Release 7]] - OGC and OSGeo collaborate on documentation
* 3 August 2010, [[Live GIS Disc Press Release 8]] - 1 week to test the OSGeo-Live DVD
* 13 August 2010, [[Live GIS Disc Press Release 9]] - Testing OSGeo-Live on the USB
* 3 September 2010, [[Live GIS Disc Press Release 10]] - '''Video & DVD for OSGeoLive 4.0, the best GeoSpatial''' OpenSource
* 23 November 2010, [[Live GIS Disc Press Release 11]] - Goals and schedule for OSGeo-Live 4.5
* 11 December 2010, [[Live GIS Disc Press Release 12]] - Contact application contacts
* 14 January 2011, [[Live GIS Disc Press Release 13]] - Last call for projects to be included on OSGeo-Live 4.5
* 13 February 2011, [[Live GIS Disc Press Release 14]] - Two weeks to translate Project Overviews
* 13 February 2011, [[Live GIS Disc Press Release 15]] - Two weeks to write Quick Starts
* 25 February 2011, [[Live GIS Disc Press Release 16]] - OSGeo-Live 4.5 ready for testing
* 28 March 2011, [[Live GIS Disc Press Release 17]] - '''OSGeo-Live 4.5 released'''
* 8 May 2011, [[Live GIS Disc Press Release 18]] - Call for interest in OSGeo-Live 5.0
* 4 June 2011, [[Live GIS Disc Press Release 19]] - Last call for new projects wishing to be included on OSGeo-Live
* 17 June 2011, [http://cameronshorter.blogspot.com/2011/06/memoirs-of-cat-herder-coordinating.html Memoirs of a Cat Herder - Coordinating OSGeo-Live volunteers]

== History ==
[[Live_GIS_History]]

= Use Cases =

There are multiple use cases for this product:

* '''Demo DVD''' that can be handed out at conferences.<br />This will contain a wide variety of applications, preconfigured with some sample data and containing introductory tutorials. It should be able to function completely offline, at least within the scope of the tutorials, and should provide an introduction to many products. This is very much a Live DVD, and as such should be conservative with regards to size (it will be run from RAM).
* '''Education DVD'''<br />This seems to be a more involved version than the Demo DVD, including more involved material, including train-the-trainer style material. This is targeted at those who will be teaching others, be it in workshops or university classes/labs. My expectation (mleslie: feel free to correct me) is that this is more likely to be installed on machines and used as a teaching resource, as opposed to a toy to play with, as with the Demo DVD. This will require material developed through the [[Category:Education|Education initiative]].
* '''Workstation Install DVD'''<br /> This need was seen in Cape Town, where the bandwidth seems to be a very limiting factor. Using the DVD to install either a complete OS, a set of packages to an existing Linux, or Windows installers completely offline is of great value in the developing world. Would it be of greater value to lose the Edu or demo material and put in complete application documentation?

= Links to related projects =
* [http://wiki.debian.org/DebianGis DebianGIS]. We encourage projects to package applications into Debian, which in turn is incorporated into Ubuntu.
* [https://wiki.ubuntu.com/UbuntuGIS UbuntuGIS]
* [http://wiki.osgeo.org/wiki/Enterprise_Linux_GIS Enterprise Linux GIS] packages as RPMs for redhat based systems.
* [http://www.gisvm.com/ GISVM home page] (GIS Virtual Machine by [[Ricardo Pinho]])
* [http://wiki.debian.org/DebianGis/LiveImages DebianGIS Live Image]
: [http://svn.debian.org/viewsvn/pkg-grass/packages/debian-gis/ Build scripts in DebianGIS's SVN]
* [http://livecd.ominiverdi.org/index.php?page=LiveCD&toc=livecd Omniverdi LiveCD project]
* [http://grass.osgeo.org/download/cdrom.php List of live CDs from the GRASS download site]
* [http://wiki.gfoss.it/index.php/LiveDVD-GFOSS.it Gfoss.it live DVD ]
* [http://www.archaeogeek.com/blog/portable-gis/ Portable GIS] - Zero-install GIS for MS Windows on a USB stick
* [http://www.poseidonlinux.org/ Poseidon Linux]
* [http://www.fossgis.de/projekte_gislive.html GISLive] - LiveDVD project from [http://www.fossgis.de FOSSGIS e.V.] (German language)
* [http://www.shindiristudio.com/SEO-optimizacija-sajta/ SEO]

= Links to Build tool options =
* The [http://packages.debian.org/sid/live-helper live-helper] package - [http://wiki.debian.org/DebianLive DebianLive home page]
** [http://clemensfam.org/john/?p=39 How-to for Ubuntu/Hardy]

* [http://www.gnewsense.org/Builder/HowToCreateYourOwnGNULinuxDistribution Gnewsense method], [http://www.diamondlinks.net/ Link Building]
* [http://www.howtoforge.com/ubuntu-linux-mint-livecd-with-remastersys Remastersys], [http://www.discount-lenses.com Cheap Halloween Contacts ]
* [http://www.debuntu.org/how-to-customize-your-ubuntu-live-cd Debian\Ubuntu Tricks]
* [https://help.ubuntu.com/community/LiveCDCustomization Ubuntu Help Way]

[[Category: Software Stack]]
[[Category: Live-demo]]