Using GeoWebCache with OpenLayers?

Note: We hope to provide a layer class in OpenLayers? for that will make the following unnecessary.

OpenLayers? is a popular WMS client that is bundled with GeoServer. In order to provide cached results, GeoWebCache must introduce additional constraints on requests from clients, as described by the WMS Tiling Client Recommendations, with the additional restriction that the grid is always defined based on world bounds, not the bounds of the layers. The latter restriction ensures that the same tiles can be used by clients other than OpenLayers?, such as Virtual Earth and Google Earth.

So quick summary, what do we have to ensure? 1) Tiles must match in size, both in terms of pixels and the area of the map that they cover. 2) Tiles must be aligned to the same grid.

The following are the default values. You could theoretically deviate from them, but your configuration must match your client.

  • Tile width (256px)
  • Tile height (256px)
  • Tile origin (EPSG:4326: -180.0,-90.0 , EPSG:900913: -20037508.34,-20037508.34)
  • Resolution (EPSG:4326: 180.0 / (2k) , EPSG:900913: (2*20037508.34)/(2k) , where k is the zoomlevel)

So how do we ensure that OpenLayers? respects these? A very simple client will actually do it, the key thing here is that maxExtent is set to world bounds and the layer does not specify any parameters that change the grid. All of OpenLayers?' default values (such as tile width) match up. 

var map, layer;
function init(){
  var mapOptions = { maxExtent: new OpenLayers.Bounds(-180, -90, 90, 180) };
  map = new OpenLayers.Map('map', mapOptions );
  var layerstates = new OpenLayers.Layer.WMS( 
                "States EPSG:4326 JPEG",
                "http://yourserver:8080/geowebcache/service/wms",
                {layers: 'topp:states', format: 'image/jpeg'} );
  map.addLayer(layerstates);
  map.setCenter(new OpenLayers.LonLat(-100,34), 4);
}

Troubleshooting

If GeoWebCache returns pink tiles you should right click on the tile and choose "View Image" (or whatever your webbrowser calls it). It's usually not an image at all, but a text that states the problem to you.

Unknown layer X. Check the logfiles, it may not have loaded properly.

Unknown layer top:states. Check the logfiles, it may not  have loaded properly.

The value of the layers= parameter is not a recognized layer. If you double check this value you should

  • Check the log file. You may have an error in your configuration
  • If running embedded in GeoServer, make sure you restart GeoServer after adding or modifying layers
  • Note that GeoWebCache will treat "layer1,layer2" as one layer. It will not synthesize several layers. (However, there is nothing preventing you from defining a layer with the name "layer1,layer2", and have it request "layer1,layer2" from the backend)

The bounds result in a zoom level of X

The bounds result in a zoom level of 2.502311446540723, expected something within 0.05 of an integer, check -127.619,23.735-64.081,50.592

This means your resolution is off. So either the height / width of the tile is not 256 pixels, or the bounds of the request cover the wrong area. Both can be inspected by looking at the URL. If it's not the height or width, check any resolution settings in your OpenLayers? client. Note that OpenLayers? may also use bounds to calculate what resolutions are needed, in which case we can override it:

For EPSG:4326, setting maxResolution: 0.703125 may help, provided minResolution or resolutions have not been set. Note that 0.703125 = 180.0 / 256 = (width of tile in degrees) / (width of tile in pixels)

The equivalent for EPSG:900913 is maxResolution: 156543.03390625

Your bounds in the W direction are offset by more than 5% compared to the underlying grid.

Your bounds in the y direction are offset by more than 5% compared to the underlying grid.

This means tile size is correct (within 5%), but your request if not aligned to the grid that GeoWebCache uses. OpenLayers? can use the extent of the map, layer or some other parameters to automatically calculate this. The key thing is to provide maxExtent: new OpenLayers.Bounds(minx,miny,maxx,maxy) such that the values align to the grid of GWC. Basically this consists of taking the map zoomed all the way out (1 tile in EPSG:900913, 2 tiles in EPSG:4326) and then continuously dividing each tile into 4 equally sized tiles. The edges of these tiles represent the grid at each zoomlevel.