{
"cells": [
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"0.3.0.dev\n"
]
}
],
"source": [
"import os\n",
"import folium\n",
"\n",
"print(folium.__version__)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# How to use ImageOverlay"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"It may happen that you want to draw an image on you map. Here are example on how to do that."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## In importing a PNG\n",
"\n",
"If you have a static image file on your disk, you can simply draw it on the map in doing:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"Mercator_projection_SW = os.path.join('data', 'Mercator_projection_SW.png')"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from folium import plugins\n",
"\n",
"\n",
"m = folium.Map([37, 0], zoom_start=1, tiles='stamentoner')\n",
"\n",
"plugins.ImageOverlay(\n",
" image=open(Mercator_projection_SW, 'br'),\n",
" bounds=[[-82, -180], [82, 180]],\n",
" opacity=0.8,\n",
").add_to(m)\n",
"\n",
"folium.LayerControl().add_to(m)\n",
"\n",
"m.save(os.path.join('results', 'ImageOverlay_0.html'))\n",
"\n",
"m"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"A few remarks:\n",
"\n",
"* Note that your image has to be in Mercator projection format.\n",
"\n",
" The image we've used is based on https://en.wikipedia.org/wiki/File:Mercator_projection_SW.jpg ; that you can find in wikipedia's article on Mercator Projection (https://en.wikipedia.org/wiki/Mercator_projection).\n",
"\n",
"\n",
"* In python 3, be careful to mention explictely the `read mode` of the file (`open(..., 'rb')`). You'll get an error otherwise. \n",
"\n",
"You can also provide simply a file name. In this case, the image will not be embedded in folium's output : you'll need to keep it on your server when your map will be deployed."
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/plain": [
"'data/Mercator_projection_SW.png'"
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"Mercator_projection_SW"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"import shutil\n",
"shutil.copyfile(Mercator_projection_SW, os.path.join('results', 'merc.png'))\n",
"\n",
"m = folium.Map([37, 0], zoom_start=1, tiles='stamentoner')\n",
"\n",
"plugins.ImageOverlay(\n",
" image='merc.png',\n",
" bounds=[[-82, -180], [82, 180]],\n",
" opacity=0.8,\n",
").add_to(m)\n",
"\n",
"folium.LayerControl().add_to(m)\n",
"\n",
"\n",
"m.save(os.path.join('results', 'ImageOverlay_1.html'))\n",
"\n",
"m"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## In importing a JPG"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This works exactly the same way if you want to put a JPG intead of a PNG."
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"Mercator_projection_SW = os.path.join('data', 'Mercator_projection_SW.jpg')\n",
"\n",
"m = folium.Map([37, 0], zoom_start=1, tiles='stamentoner')\n",
"\n",
"plugins.ImageOverlay(\n",
" image=open(Mercator_projection_SW, 'br'),\n",
" bounds=[[-82, -180], [82, 180]],\n",
" opacity=0.8,\n",
").add_to(m)\n",
"\n",
"folium.LayerControl().add_to(m)\n",
"\n",
"m.save(os.path.join('results', 'ImageOverlay_2.html'))\n",
"\n",
"m"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## In creating an image with numpy"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now you may wish to create your own image, based on another python computation.\n",
"For this, you'll need to have numpy installed on your machine."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Let's creater an image to draw a rectangle in the bounds [[0, -60], [60, 60]]"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"import numpy as np\n",
"\n",
"image = np.zeros((61, 61))\n",
"image[0, :] = 1.0\n",
"image[60, :] = 1.0\n",
"image[:, 0] = 1.0\n",
"image[:, 60] = 1.0"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can draw it on the map in using:"
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"/home/filipe/miniconda3/envs/FOLIUM/lib/python3.5/site-packages/branca/utilities.py:365: RuntimeWarning: invalid value encountered in true_divide\n",
" array = array * 255./array.max(axis=(0, 1)).reshape((1, 1, 4))\n"
]
},
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"m = folium.Map([37, 0], zoom_start=3)\n",
"\n",
"plugins.ImageOverlay(\n",
" image=image,\n",
" bounds=[[0, -60], [60, 60]],\n",
" colormap=lambda x: (1, 0, 0, x),\n",
").add_to(m)\n",
"\n",
"m"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Note that you need to provide a colormap of the form `lambda x: (R,G,B,A)` where `R,G,B,A` are floats between 0 and 1."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now, let's try to add a line at latitude 45°, and add a polyline to verify it's well rendered. We'll need to specify `origin='lower` to inform folium that the first lines of the array are to be plotted at the bottom of the image (see `numpy.imshow`, it's the same principle)."
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"/home/filipe/miniconda3/envs/FOLIUM/lib/python3.5/site-packages/branca/utilities.py:365: RuntimeWarning: invalid value encountered in true_divide\n",
" array = array * 255./array.max(axis=(0, 1)).reshape((1, 1, 4))\n"
]
},
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"image[45, :] = 1.0\n",
"\n",
"\n",
"m = folium.Map([37, 0], zoom_start=3)\n",
"\n",
"plugins.ImageOverlay(\n",
" image=image,\n",
" bounds=[[0, -60], [60, 60]],\n",
" colormap=lambda x: (1, 0, 0, x),\n",
" origin='lower',\n",
").add_to(m)\n",
"\n",
"folium.PolyLine([[45, -60], [45, 60]]).add_to(m)\n",
"\n",
"m.save(os.path.join('results', 'ImageOverlay_3.html'))\n",
"\n",
"m"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"But even with `origin='lower'`, the red line is not at the good latitude. This is due to Mercator projection used in Leaflet (and most other map systems).\n",
"\n",
"You can read wikipedia's article on Mercator Projection (https://en.wikipedia.org/wiki/Mercator_projection), or simply let folium do the job, in precising that you want the mercator stuff to be handled."
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"/home/filipe/miniconda3/envs/FOLIUM/lib/python3.5/site-packages/branca/utilities.py:365: RuntimeWarning: invalid value encountered in true_divide\n",
" array = array * 255./array.max(axis=(0, 1)).reshape((1, 1, 4))\n"
]
},
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 10,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"m = folium.Map([37, 0], zoom_start=3)\n",
"\n",
"folium.PolyLine([[45, -60], [45, 60]]).add_to(m)\n",
"\n",
"plugins.ImageOverlay(\n",
" image=image,\n",
" bounds=[[0, -60], [60, 60]],\n",
" origin='lower',\n",
" colormap=lambda x: (1, 0, 0, x),\n",
" mercator_project=True,\n",
").add_to(m)\n",
"\n",
"m.save(os.path.join('results', 'ImageOverlay_4.html'))\n",
"\n",
"m"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This time, the lines are properly positionned (at the precision of the array)."
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.5.2"
}
},
"nbformat": 4,
"nbformat_minor": 0
}