Merge pull request #180 from andrewgiessel/image_overlay_tweaks

Image overlay tweaks

Author: ocefpaf

folium/folium.py

@@ -952,16 +952,23 @@ def json_style(style_cnt, line_color, line_weight, line_opacity,
 
     @iter_obj('image_overlay')
     def image_overlay(self, data, opacity=0.25, min_lat=-90.0, max_lat=90.0,
-                      min_lon=-180.0, max_lon=180.0, image_name=None, filename=None):
-        """Simple image overlay of raster data from a numpy array.  This is a lightweight
-        way to overlay geospatial data on top of a map.  If your data is high res, consider
-        implementing a WMS server and adding a WMS layer.
-
-        This function works by generating a PNG file from a numpy array.  If you do not
-        specifiy a filename, it will embed the image inline.  Otherwise, it saves the file in the
-        current directory, and then adds it as an image overlay layer in leaflet.js.
-        By default, the image is placed and stretched using bounds that cover the 
-        entire globe.
+                      min_lon=-180.0, max_lon=180.0, image_name=None, filename=None,
+                      data_projection='mercator'):
+        """Simple image overlay of raster data from a numpy array.  This is a
+        lightweight way to overlay geospatial data on top of a map.
+        If your data is high res, consider implementing a WMS server
+        and adding a WMS layer.
+
+        This function works by generating a PNG file from a numpy
+        array.  If you do not specifiy a filename, it will embed the
+        image inline.  Otherwise, it saves the file in the current
+        directory, and then adds it as an image overlay layer in
+        leaflet.js.  By default, the image is placed and stretched
+        using bounds that cover the entire globe.  By default, we
+        assume that your data is in geodetic projection and thus
+        project it to web mercator for display purposes.  If you are
+        overlaying a non-georeferenced image, set data_projection to
+        None.
 
         Parameters
         ----------
@@ -976,10 +983,12 @@ def image_overlay(self, data, opacity=0.25, min_lat=-90.0, max_lat=90.0,
         max_lon: float, default  180.0
         image_name: string, default None
             The name of the layer object in leaflet.js
-        filename: string, default None
+        filename: string or None, default None
             Optional file name of output.png for image overlay.  If None, we use a 
             inline PNG.
-
+        data_projection: string or None, default 'mercator'
+            Used to specify projection of image.  If None, do no projection
+            
         Output
         ------
         Image overlay data layer in obj.template_vars
@@ -988,7 +997,7 @@ def image_overlay(self, data, opacity=0.25, min_lat=-90.0, max_lat=90.0,
         -------
         # assumes a map object `m` has been created
         >>> import numpy as np
-        >>> data = np.random.random((100,100))
+        >>> data = np.random.random((180,360))
         
         # to make a rgba from a specific matplotlib colormap:
         >>> import matplotlib.cm as cm
@@ -1000,12 +1009,16 @@ def image_overlay(self, data, opacity=0.25, min_lat=-90.0, max_lat=90.0,
 
         # put it only over a single city (Paris)
         >>> m.image_overlay(data, min_lat=48.80418, max_lat=48.90970, min_lon=2.25214, max_lon=2.44731)
-        
-        """
 
+        """
         if isinstance(data, str):
             filename = data
         else:
+            assert data_projection in [None, 'mercator']
+            # this assumes a lat x long array
+            # with 2x as many points in long as lat dims.
+            if data_projection is 'mercator':
+                data = utilities.geodetic_to_mercator(data)
             try:
                 png_str = utilities.write_png(data)
             except Exception as e:

folium/utilities.py

@@ -344,4 +344,50 @@ def png_pack(png_tag, data):
         png_pack(b'IHDR', struct.pack("!2I5B", width, height, 8, 6, 0, 0, 0)),
         png_pack(b'IDAT', zlib.compress(raw_data, 9)),
         png_pack(b'IEND', b'')])
+
+def _row2lat(row):
+    return 180.0/np.pi*(2.0*np.arctan(np.exp(row*np.pi/180.0))-np.pi/2.0)
+    
+def geodetic_to_mercator(geodetic):
+    """This function takes an 2D array in geodetic coordinates (ie: lat x
+    lon unprojected) and converts it to web mercator.  This is needed
+    to correctly overlay an image on a leaflet map, which uses web
+    mercator by default.
+
+    This code works with arrays that match the relative proportions of
+    latitude and longitude of the earth, meaning that they have twice
+    as many points in longitude as latitude (i.e.: (180, 360) for 1
+    degree resolution).
+
+    The code for this is from:
+    http://stackoverflow.com/questions/25058880/convert-to-web-mercator-with-numpy
+
+    Parameters
+    ----------
+    geodetic: numpy image array
+        Latitude x Longitude array, in mono (NxM), rgb (NxMx3) or RGBA (NxMx4)
+
+    Returns
+    -------
+    meractor: projected numpy image array
+
+    """
+    
+    geo = np.repeat(np.atleast_3d(geodetic), 2, axis=0)
+    merc = np.zeros_like(geo)
+    side = geo.shape[0]
+
+    for row in range(side):
+        lat = _row2lat(180 - ((row * 1.0)/side) * 360)
+        g_row = (abs(90 - lat)/180)*side
+        fraction = g_row-np.floor(g_row)
+
+        # Here I optimized the code by using the numpy vector operations 
+        # instead of the for loop:
+
+        high_row = geo[np.floor(g_row), :, :] * (fraction)
+        low_row = geo[np.ceil(g_row), :, :] * (1-fraction)
+        merc[row, :, :] = high_row + low_row
+
+    return np.squeeze(merc)
 

tests/folium_tests.py

@@ -484,21 +484,26 @@ def test_fit_bounds(self):
     def test_image_overlay(self):
         """Test image overlay"""
         from numpy.random import random
-        from folium.utilities import write_png
+        from folium.utilities import write_png, geodetic_to_mercator
         import base64
 
         data = random((100,100))
         png_str = write_png(data)
         with open('data.png', 'wb') as f:
             f.write(png_str)
-        inline_image_url = "data:image/png;base64,"+base64.b64encode(png_str).decode('utf-8')
+
+        image_url = 'data.png'
+        inline_image_url = ("data:image/png;base64," +
+                            base64.b64encode(write_png(geodetic_to_mercator(data))).decode('utf-8'))
 
         image_tpl = self.env.get_template('image_layer.js')
         image_name = 'Image_Overlay'
         image_opacity = 0.25
-        image_url = 'data.png'
+
         min_lon, max_lon, min_lat, max_lat = -90.0, 90.0, -180.0, 180.0
         image_bounds = [[min_lon, min_lat], [max_lon, max_lat]]  
+
+        # Test the external png.
 
         image_rendered = image_tpl.render({'image_name': image_name,
                                            'image_url': image_url,
@@ -509,6 +514,7 @@ def test_image_overlay(self):
         self.map.image_overlay(data, filename=image_url)
         assert image_rendered in self.map.template_vars['image_layers']
 
+        # Test the inline png.
 
         image_rendered = image_tpl.render({'image_name': image_name,
                                            'image_url': inline_image_url,