### NeXtMidas support for WMS and GeoWebCache

NeXtMidas has support for downloading maps from a Web Map Service. A GeoWebCache acts as a proxy between a GeoServer and a map client.

In order to get cached results from a GeoWebCache, extra guildlines must be followed.

##### Full GeoWebCache guidelines

1. TILED=true is included in the request
2. Only one layer can be referenced in the getMap request
3. Image requested same height/width saved in layer configuration
4. The requested CRS matches one of the available tile layer gridsets
5. The image requested lines up with the existing grid bounds
6. Only supported Parameter filters are included in the request

##### Guidelines for NeXtMidas interaction with a standard GeoWebCache

1. Include GWC=TRUE as one of the WMS Keyword Parameters

- This will force TILED=true to be included in the requests
- NeXtMidas will prefer the CRS EPSG:4326, which is one of the two standard CRSs supported by GeoWebCache
- The tile requests will be 256x256 matching the EPSG:4326 height/width requirements
- The tile image bounds will align with the EPSG:4326 grid bounds
- BGCOLOR will NOT be included in the getMap request, as it is a parameter filter and not supported by default

2. LAYERS= should reference only one layer or TRANSITIONS= should be set, so only one layer is requested at a time

##### Sample Standard Configuration GeoWebCache compliant WMS

- A NeXtMidas command such as:
  nM> plot {LT=WMS,URL=mapURL,Layers="shapePolitical,Relief,cadrg,imint",&
  TRANSITIONS="500,1.5e3,1e8",GWC=true,NumRetriesIfBGColor=4}
- This results in tiled requests similiar to this:
  url/maps/geoserver/MapData/wms?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&CRS=EPSG:4326&BBOX=42.69287109375,-71.47705078125,42.71484375,-71.455078125&WIDTH=256&HEIGHT=256&LAYERS=imint&STYLES=&FORMAT=image/png&EXCEPTIONS=INIMAGE&TRANSPARENT=FALSE&TILED=true

##### WMS Keyword Parameters

- LT=WMS
  - Specifies layer type as LayerWMS
- URL=
  - Specifies the URL of the WMS server
- LAYERS=
  - List the layer(s)
- TRANSITIONS=
  - A pixel-to-degrees ratio at which NeXtMidas should switch to the next layer
  - Note: enabling the onAxis readout of WMS_level can assist in choosing these transition values. READOUTEXT=+Show|+WMS_level
- GWC=true
  - GeoWebCache friendly behavior enabled, including TILED=true
- NumRetriesIfBGColor=
  - Retries for a good tile if an errorless background only color tile is received.
- IGNOREHREF=true
  - Avoids having to wait for a timeout if a WMS server is improperly configured and returning an internal HREF in GetCapabilities
- ByNameCRSs=
  - Allows the preferred CRS(s) to be directly specified by comma separated name(s).
  - CRSs are arbitrated based on the standard GetCapabilities request.
  - If the map server is erroneously returning more CRSs than it actually supports, this can cause an unsupported CRS to be chosen.
  - The default CRS in NeXtMidas 4.1.0+ is EPSG:4326, but earlier versions of NeXtMidas have CRS:84 as the default.
- RequestedVersion=
  - WMS 1.3.0 will be preferred by default. Specifying "1.1.1" will change the preference to 1.1.1.
  - RequestedVersion must come BEFORE the URL specification.
  - This is useful if the WMS server has lat/lon ordering incorrect for WMS 1.3.0.
- ConnectTimeout=
  - To override the default network connection open timeout
  - ConnectTimeout must come BEFORE the URL specification.
- ReadTimeout=
  - To override the default network connection read timeout
  - ReadTimeout must come BEFORE the URL specification.
- AutoConnect=false
  - Disable the automatic connection to the Map Server while setting the URL
  - AutoConnect=false must come BEFORE the URL specification.
- BRIGHTNESS=
  - Sets brightness
- CONTRAST=
  - Sets contrast
- DOWNLOADTHREADS=
  - Set the number of download threads.
  - NeXtMidas 4.0.0+ has the default being 32.
  - Older versions of NeXtMidas had the default as 4.
- CACHESIZE=
  - Set the number of map images cached.
  - NeXtMidas 4.0.0+ the default tiled cache was updated be intelligent and based on available JVM memory, with a maximum of 1024.
  - Older versions of NeXtMidas had the default tiled cache size as 16.
  - The default cache size when not doing tiled requests remains 4.

##### Custom GeoWebCache configurations are not currently supported

- Custom GeoWebCache configurations with different height/width or grid bounds are not currently supported
- In order to support this, NeXtMidas would need to make a separate WMS 1.1.1 GetCapabilities request and act on that information
  `url/maps/geoserver/gwc/service/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetCapabilities&TILED=true`
- The VendorSpecificCapabilities TileSet section of the response contains
  - SRS specific specifications
  - BoundingBox
  - Resolutions
  - Width
  - Height
  - Format
  - Layers
  - Styles
  - Layer specific specifications
  - Name
  - Title
  - Abstract
  - SRS
  - LatLonBoundingBox minx= miny= maxx= maxy=
  - BoundingBox SRS= minx= miny= maxx= maxy=