{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"contentcontainer med left\" style=\"margin-left: -50px;\">\n",
    "<dl class=\"dl-horizontal\">\n",
    "  <dt>Title</dt> <dd> Tiles Element</dd>\n",
    "  <dt>Dependencies</dt> <dd>Bokeh</dd>\n",
    "  <dt>Backends</dt>\n",
    "      <dd><a href='./Tiles.ipynb'>Bokeh</a></dd>\n",
    "      <dd><a href='../plotly/Tiles.ipynb'>Plotly</a></dd>\n",
    "</dl>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import holoviews as hv\n",
    "from holoviews import opts\n",
    "hv.extension('bokeh')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``Tiles`` element represents a so called web mapping tile source usually used for geographic plots, which fetches tiles appropriate to the current zoom level. To declare a ``Tiles`` element simply provide a URL to the tile server, a standard tile server URL has a number of templated variables which describe the location and zoom level. In the most common case that is a Web Map Tile Service (WMTS) source which looks like this:\n",
    "    \n",
    "    'https://tile.openstreetmap.org/{Z}/{X}/{Y}.png'\n",
    "    \n",
    "Here ``{X}``, ``{Y}`` and ``{Z}`` describe the location and zoom level of each tile. Alternative formats include bbox tile sources with ``{XMIN}``, ``{XMAX}``, ``{YMIN}``, ``{YMAX}`` variables, and quad-key tile sources with a single ``{Q}`` variable.\n",
    "\n",
    "A simple example of a WMTS source is OpenStreetMap:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hv.Tiles('https://tile.openstreetmap.org/{Z}/{X}/{Y}.png', name=\"OSM\").opts(width=600, height=550)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One thing to note about tile sources is that they are always defined in the [pseudo-Mercator projection](https://epsg.io/3857), which means that if you want to overlay any data on top of a tile source the values have to be expressed as eastings and northings. If you have data in another projection, e.g. latitudes and longitudes, it may make sense to use [GeoViews](https://geoviews.org/) for it to handle the projections for you.\n",
    "\n",
    ">\n",
    "> **Note**: \n",
    "> \n",
    ">   Holoviews provides functions to project longitude, latitude into Web Mercator coordinates. \n",
    ">   See [`hv.util.transform.lon_lat_to_easting_northing(longitude, latitude)`](https://holoviews.org/reference_manual/holoviews.element.html?highlight=lon_lat_to_easting_northing#holoviews.element.Tiles.lon_lat_to_easting_northing)\n",
    ">\n",
    "\n",
    "Both HoloViews and GeoViews provides a number of tile sources by default, provided by CartoDB, OpenStreetMap, and Esri. Stamen tile sources are also available but require a Stadia account when not running locally; see [stadiamaps.com](https://stadiamaps.com/).\n",
    "\n",
    "Tile sources can be imported from the ``holoviews.element.tiles`` module and are provided as callable functions which return a ``Tiles`` element:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hv.element.tiles.EsriImagery().opts(width=600, height=550)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The full set of predefined tile sources can be accessed on the ``holoviews.element.tiles.tile_sources`` and ``holoviews.element.tiles.stamen_sources`` dictionaries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hv.Layout([ts().relabel(name) for name, ts in hv.element.tiles.tile_sources.items()]).opts(\n",
    "    opts.Tiles(xaxis=None, yaxis=None, width=225, height=225)).cols(4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For full documentation and the available style and plot options, use ``hv.help(hv.Tiles).``"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}