In GeoWebCache, a projection is also known as a gridset.
GeoWebCache only advertises support for EPSG:4326 (longitude/latitude) and EPSG:900913 (spherical web mercator) by default. Any other projections need to be manually defined and configured.
Adding a custom projection to GeoWebCache involves modifying (or creating, if it doesn’t yet exist) the geowebcache.xml configuration file to include a custom projection definition and then associating the layer with that projection. (Read more about this file in the section on How to configure layers.)
Defining a projection¶
GeoWebCache does not know anything about projections; it only knows about its own tile grid. This information is used when passing information to the originating WMS. It is assumed that the WMS can understand requests in the custom projection.
In order to add a custom projection to GeoWebCache, the following information is required:
|Name||<name>||A human readable name for the projection. Can typically be the name of the projection (e.g. EPSG:2263).|
|SRS number||<srs><number>||The numerical identifier for the SRS (e.g. 2263).|
|SRS extent||<extent><coords>||The full extent for the projection in its native units.|
|List of valid resolutions||<resolutions>||While a list of resolutions typically decrease by a factor of two with each entry, this is not required.|
|Meters per unit||<metersPerUnit>||A constant value of the amount of meters in the native units for the projection.|
|Tile height and width||<tileHeight>, <tileWidth>||Typically 256 pixels each, though other values are valid.|
For full information, please see the GeoWebCache schema. (Read more about the schema in the section on How to configure layers.)
When defining a new SRS/gridset, it is important to use the full extent of the projection, even if your data only covers a portion of that extent. The extent of the layer itself is defined in the <gridSubset> of the layer definition below.
Determining SRS extent¶
If unsure about the full extent of the SRS, you can use an online resource such as http://spatialreference.org and use the Projected Bounds. For example, on the reference page for EPSG:2263 the Projected Bounds is listed as:
909126.0155, 110626.2880, 1610215.3590, 424498.0529
Determining meters per unit¶
While many SRS definitions are in meters, there are many other units possible. Setting this will prevent grid shifts and unexpected output.
The following is a short list of correct values of <metersPerUnit> for different units:
|Unit||Meters per unit|
While it is not necessary to put a <metersPerUnit> value when the projection is defined in meters, it is still good practice (and will prevent warnings from being displayed in the logs).
The following is an example of a custom projection definition, in this case EPSG:2263, or New York Long Island (ft).
<gridSets> ... <gridSet> <name>EPSG:2263</name> <srs><number>2263</number></srs> <extent> <coords> <double>909126.0155</double> <double>110626.2880</double> <double>1610215.3590</double> <double>424498.0529</double> </coords> </extent> <resolutions> <double>466.2771277605631</double> <double>233.13856388028155</double> <double>116.569281940140775</double> <double>58.2846409700703875</double> <double>29.14232048503519375</double> <double>14.571160242517596875</double> <double>7.2855801212587984375</double> </resolutions> <metersPerUnit>0.3048</metersPerUnit> <tileHeight>256</tileHeight> <tileWidth>256</tileWidth> </gridSet> ... </gridSets>
Note that specific layers will need to be associated with this projection before they can be viewed as such.
Associate a layer with the projection¶
Once the projection is loaded in GeoWebCache, the next step is to associate a given layer with that projection. This is done in the same geowebcache.xml file.
The necessary information is:
|Layer name||<name>||The layer name as published by GeoWebCache. It can be the same name as known to the WMS (for example, in GeoServer, this would be namespace:layername) or not.|
|Name of projection||<gridSetName>||The projection name as referenced in the layer definition (in this example, EPSG:2236)|
|Layer extent||<extent><coords>||The extent of the layer. This is where the restricted extent is set.|
|WMS URL||<wmsUrl>||The path to the WMS endpoint.|
The following is an example of a single layer added using the previously-defined (EPSG:2263) projection.
<layers> ... <wmsLayer> <name>my:layer</name> <gridSubsets> <gridSubset> <gridSetName>EPSG:2263</gridSetName> <extent> <coords> <double>937558.37821372</double> <double>89539.946131199</double> <double>1090288.6738155</double> <double>327948.21243638</double> </coords> </extent> </gridSubset> </gridSubsets> <wmsUrl><string>http://myserver/geoserver/wms</string></wmsUrl> </wmsLayer> ... </layers>
Once any changes are made to geowebcache.xml, it is necessary to reload the configuration.