====== Orbit Tile Map Service file ======

An Orbit Tile Map Service resource connection file (*.otm) is a file reference to a Tile Map Service. \\
It is strongly advised to read first the documentation about [[dev:technology:core:web_resources|]].

==== Structure ====

The Orbit Tile Map Service driver relies on a tile engine, a computer graphics technique which generates a larger graphic from re-using a number of smaller graphics to minimize data traffic and increase real-time rendering performance.

Tiled maps are composed of a set of scale-appropriate cartographic renderings, each divided up into regularly spaced image tiles, called Tile Sets.

The tiling engine support different formats that can each drive the tiling engine, and may have specific configurations.

==== Formats ====

**Generic** 

The following fields can be used in ''MapURL'' :
  * <TileX> : The tile column index.
  * <TileY> : The tile row index.
  * <Level> : The zoom level (0 means top-level).
  * <TileXi> : The tile column index inversed.
  * <TileYi> : The tile row index inversed.

<code bash>
Format=Generic
MapUrl=http://tile.openstreetmap.org/<Level>/<TileX>/<TileY>.png
Levels=19
</code>

** OpenStreetMap**

<code bash>
Format=OpenStreetMap
MapUrl=http://tile.openstreetmap.org
Levels=19
</code>

** BingMaps **

Required extra configuration settings :
  * apiKey : Your Bing API key.
  * imagerySet : The imagery set name to use.\\ Available values can be found here: [[https://learn.microsoft.com/en-us/bingmaps/rest-services/imagery/get-imagery-metadata]]

<code bash>
Format=BingMaps
ApiKey=<api-key>
ImagerySet=<imagerySet>
</code>

**WMTS**

<code bash>
Format=WMTS
MapUrl=https://geodata.nationaalgeoregister.nl/tiles/service/wmts
Layer=omtrekgerichtevisualisatie
PreferredCRS=28992
</code>

**WMS**

<code bash>
Format=WMS
MapUrl=https://service.pdok.nl/kadaster/au/wms/v2_0
Layer=AU.AdministrativeUnit
CRS=28992
</code>

==== Transparency ====

When an alpha channel is available (for example PNG images), it can be used on rendering.

<code bash>
UseAlphaChannel=true
</code>

When no alpha channel is available, a color and margin can be configured that defines a color that will then be made transparent.

<code bash>
UseTransparentColor=true
TransparentColor=255.255.255
TransparentColorMargin=10
</code>

==== Authentication ====

You can add username and password to OTM configurations when needed.\\ 
Username and password will be sent on every tile request using the HTTP Basic Authentication scheme (using the Authorization header).

<code bash>
Username=xxx
Password=yyy
</code>

==== Reasons to use ====

A Web Service reference file simplifies use of Web resources and enables additional configurations :
  * Manage and share web resource in the same way as regular, file based resources.
  * Associate an [[dev:technology:supported_formats:other:olg|Orbit Legend file]]. 
  * Set additional service configurations, see Structure. 

==== Create ====

Create and edit the .otm file using a simple text editor (e.g. Notepad).  Take care of spelling and file syntax.

==== Legend and Georeference ====

The resource can be accompanied by an [[dev:technology:supported_formats:other:olg|]] and [[dev:technology:supported_formats:other:ord|]].

A Tile Map Service is most likely georeferenced. The resource coordinate system must be defined via the associated .ord file, just like other regular file based resources.

The CRS for OpenStreetMap is "WGS 84 / World Mercator" EPSG 3857. \\
If the tile service is using another coordinate system, you can define custom georeference transformation for the top tile, using a .geo file.  

==== Examples ====

** Esri World Imagery ** \\
https://services.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer \\
{{:dev:technology:supported_formats:image:esri_world_imagery.zip|}}

<code bash>
Format=Generic
MapUrl=https://services.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer/tile/<Level>/<TileY>/<TileX>.jpg
Levels=23
DiskCacheName=services.arcgisonline.com.World_Imagery
</code>

**PDOK BRT Achtergrondkaart** \\
https://www.pdok.nl \\
.otm creation.

<code bash>
Format=WMTS
MapUrl=https://geodata.nationaalgeoregister.nl/tiles/service/wmts
Layer=brtachtergrondkaart
PreferredCRS=28992
TransparentColor=255.255.255
UserName=
Password=
</code>

** OpenStreetmap ** \\
http://www.openstreetmap.org \\
{{:dev:technology:supported_formats:image:openstreetmap.zip|}} 

<code bash>
Format=OpenStreetMap
MapUrl=http://a.tile.openstreetmap.org http://b.tile.openstreetmap.org http://c.tile.openstreetmap.org
Levels=19
DiskCacheName=openstreetmap
</code>