====
WMTS
====
The ``gt-wmts`` module constitutes functionality to work with a OGC Web Map Tile server. It contains the class WebMapTileServer that extends the AbstractOpenWebService, for making direct calls to the server.
It has also the class WMTSTileService that extends the functionality within :doc:`gt-tile-client <../tile-client/index>` module to offer functionality for a specific tile matrix structure.
At last it has two classes that is useful for accessing a WMTS layer within your application: WMTSCoverageReader and WMTSMapLayer.
**Maven**::
org.geotools
gt-wmts
${geotools.version}
WebMapTileServer
----------------
The client code takes care of version negotiation, and even a few server specific wrinkles for you. It is based on the functionality of AbstractOpenWebService, and handles the requests: GetCapabilities and GetTile.
This page contains examples how how to connect and use the GeoTools WebMapTileServer class. WebMapTileServer acts as a proxy
for a remote "Web Map Tile Server" and can be used to examine and retrieve published information in the forms of descriptive Java beans, and raw images.
* To begin communicating with a server, pass in a URL pointing to a WMTS.
Constructing a WebMapTileServer object:
.. code-block:: java
URL url = null;
try {
url = new URL("https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi");
} catch (MalformedURLException e) {
// will not happen
}
WebMapTileServer wmts = null;
try {
wmts = new WebMapTileServer(url);
} catch (IOException e) {
// There was an error communicating with the server
// For example, the server is down
} catch (ServiceException e) {
// The server returned a ServiceException (unusual in this case)
} catch (SAXException e) {
// Unable to parse the response from the server
// For example, the capabilities it returned was not valid
}
Assuming nothing went wrong, we now have a WebMapTileServer object ``wmts``
that contains the Capabilities document returned from the server. It
can also provide further communication with the server.
WMTSCapabilities
^^^^^^^^^^^^^^^^
WMTSCapabilities is used to describe the abilities and published information available via a Web Map Tile Service.
You can retrieve a WMTSCapabilities directly from your WebMapTileService:
.. code-block:: java
WMTSCapabilities capabilities = wmts.getCapabilities();
From the capabilities you can retrieve info about the Service, the available Requests, the available Layers and the
configured MatrixSets.
Service
^^^^^^^
Service contains metadata information about the server:
.. code-block:: java
WMTSCapabilities capabilities = wmts.getCapabilities();
String serverName = capabilities.getService().getName();
String serverTitle = capabilities.getService().getTitle();
System.out.println("Capabilities retrieved from server: " + serverName + " (" + serverTitle + ")");
Request
^^^^^^^
The WMTS Operations describe the requests entry points:
.. code-block:: java
URL requestUrl = wmts.getCapabilities().getRequest().getGetTile().getGet();
Layer
^^^^^
The Layer section contains detailed information about the layers on the server:
.. code-block:: java
WMTSCapabilities capabilities = wmts.getCapabilities();
// gets all the layers in a list, in the order they appear in
// the capabilities document
List layers = capabilities.getLayerList();
Every layer has a list of related Formats::
String layerName = ...
// Get formats for a given layer
List formats = wmts.getCapabilities().getLayer(layerName).getFormats()
Styles
^^^^^^
For each layer you can get its available styles:
.. code-block:: java
for (WMTSLayer layer : wmts.getCapabilities().getLayerList()) {
System.out.println("Layer: " + layer.getName());
System.out.println(" " + layer.getTitle());
for (StyleImpl style : layer.getStyles()) {
// Print style info
System.out.println("Style:");
System.out.println(" Name: " + style.getName());
System.out.println(" Title: " + style.getTitle());
}
}
MatrixSet
^^^^^^^^^
Each Layer could use one or more matrix set's, and for each matrix it can restrict which tiles that are available.
This depends on the extent of the layer compared to the global extent of the matrix set.
Here's an example on how to loop in the matrices of the published layers:
.. code-block:: java
for (WMTSLayer layer : wmts.getCapabilities().getLayerList()) {
for (String tileMatrixId : layer.getTileMatrixLinks().keySet()) {
List limits = layer.getTileMatrixLinks().get(tileMatrixId).getLimits();
TileMatrixSet matrixSet = wmts.getCapabilities().getMatrixSet(tileMatrixId);
List matrices = matrixSet.getMatrices();
for (TileMatrix matrix : matrices) {
System.out.println("LAYER " + layer.getName()
+ ", matrixSet id : " + tileMatrixId
+ ", matrix " + matrix.getIdentifier()
+ ", matrixGrid" + matrix.getMatrixWidth() + "x" + matrix.getMatrixHeight()
+ ", tileSize" + matrix.getTileWidth() + "x" + matrix.getTileHeight());
}
}
}
GetTileRequest
^^^^^^^^^^^^^^
Making a GetTile request is more interesting than looking at WMTS capabilities.
1. We need to ask the client to create us a GetTileRequest object:
.. code-block:: java
GetTileRequest req = wmts.createGetTileRequest();
2. Using data from the capabilities document (or our own personal choices) we can configure the request object:
.. code-block:: java
req.setLayer(layer);
req.setStyle(...);
req.setFormat("image/png");
req.setTileMatrixSet(...);
req.setTileMatrix(...);
req.setTileRow(9);
req.setTileCol(12);
3. The GetTile supports headers for the http calls.
.. code-block:: java
req.getHeaders().add("Authentication", "Bearer uyhhkhasghbasgy9ji62gddkjady3y");
4. Then we would issue the request, and get the image.
.. code-block:: java
GetTileResponse response = server.issueRequest(req);
BufferedImage image = response.getTileImage();
WMTSTileService
---------------
This class builds on the functionality of TileService. The main difference between a WMTS and a TileService is that a given WMTS layer might not cover all of the matrix set.
This is handled through matrix set links given by the configuration of each layer.
.. literalinclude:: /../src/main/java/org/geotools/wmts/WMTSDownloader.java
:language: java
:start-after: // start wmtsTileService example
:end-before: // end wmtsTileService example
WMTSCoverageReader
------------------
These classes is based on a WebMapTileServer and is useful for exporting or displaying maps from a WMTS server.
For export we treat the tiles as a coverage with the WMTSCoverageReader, and use ImageIO to write the rendered image.
.. literalinclude:: /../src/main/java/org/geotools/wmts/WMTSCoverage.java
:language: java
:start-after: // start wmtsCoverage example
:end-before: // end wmtsCoverage example
WMTSMapLayer
------------
To display the WMTS within a map we would use WMTSMapLayer in a similar way.
.. literalinclude:: /../src/main/java/org/geotools/wmts/WMTSMapViewer.java
:language: java
:start-after: // start wmtsMapViewer example
:end-before: // end wmtsMapViewer example
In addition it's possible to use the TileLayer class of gt-tile-client with a WMTSTileService as input.
Be aware that TileLayer is a subclass of DirectLayer which uses the Viewport to specify dimensions.
References:
^^^^^^^^^^^
* http://www.opengeospatial.org/standards/wmts (OGC standard)
* http://www.geowebcache.org/ (WMTS server)
* :doc:`gt-tile-client <../tile-client/index>`