Custom projections

Note

In GeoWebCache, a projection is also known as a gridset.

By default, GeoWebCache only advertises support for EPSG:4326 (longitude/latitude) and EPSG:900913 (spherical web mercator). Any other projection needs to be defined and configured manually.

Adding a custom projection to GeoWebCache requires modifying (or creating, if it doesn’t already 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 How to configure layers.)

Defining a projection

Note

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:

Field

Tag

Description

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, although other values are valid.

Note

For full information, please see the GeoWebCache schema. (Read more about the schema in the section on How to configure layers.)

Warning

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 you are unsure of 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.

A short list of correct values of <metersPerUnit> for different units is as follows:

Unit

Meters per unit

Degrees

111319.49079327358

Feet

0.3048

Inches

0.0254

Meters

1

While it is not required 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).

Example

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

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 the projection to a given layer. This is done in the same geowebcache.xml file.

The necessary information is:

Field

Tag

Description

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.

Example

Below 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>

Any change made to geowebcache.xml, it is required to reload the configuration.

Previous: How to configure layers
Next: Palettes