Merge pull request #151 from BibMartin/plugins

Plugins object and a few plugins

Author: ocefpaf

examples/plugins_examples.ipynb

@@ -661,7 +661,7 @@ def add_plugin(self, plugin):
                 A plugin to be added to the map. It has to implement the methods
                 `render_html`, `render_css` and `render_js`.
         """
-        self.plugins[plugin.name] = plugin
+        plugin.add_to_map(self)
 
     def _auto_bounds(self):
         if 'fit_bounds' in self.template_vars:

folium/folium.py

@@ -1,124 +1,13 @@
 # -*- coding: utf-8 -*-
-
-from uuid import uuid4
-import json
-
-class Plugin():
-    """Basic plugin object that does nothing.
-    Other plugins may inherit from this one."""
-    def __init__(self):
-        """Creates a plugin to append into a map with Map.add_plugin. """
-        self.name = "Plugin_"+uuid4().hex
-
-    def render_html(self):
-        """Generates the HTML part of the plugin."""
-        return ""
-
-    def render_css(self):
-        """Generates the CSS part of the plugin."""
-        return ""
-
-    def render_js(self):
-        """Generates the Javascript part of the plugin."""
-        return ""
-    def render_header(self):
-        """Generates the Header part of the plugin."""
-        return ""
-
-
-class ScrollZoomToggler(Plugin):
-    """Adds a button to enable/disable zoom scrolling."""
-    def __init__(self, zoom_enabled=False):
-        """Creates a ScrollZoomToggler plugin to append into a map with
-        Map.add_plugin.
-
-        Parameters
-        ----------
-            zoom_enabled: bool, default False
-                Whether the zoom scrolling shall be enabled at display.
-        """
-        self.zoom_enabled = zoom_enabled
-        self.name = "ScrollZoomToggler_"+uuid4().hex
-
-    def render_html(self):
-        """Generates the HTML part of the plugin."""
-        return """<img id="{}" alt="scroll"
-       src="https://cdnjs.cloudflare.com/ajax/libs/ionicons/1.5.2/png/512/arrow-move.png"
-       onclick="toggleScroll()"></img>""".format(self.name)
-
-    def render_css(self):
-        """Generates the CSS part of the plugin."""
-        return """
-        #"""+self.name+""" {
-            position:absolute;
-            width:35px;
-            bottom:10px;
-            height:35px;
-            left:10px;
-            background-color:#fff;
-            text-align:center;
-            line-height:35px;
-            vertical-align: middle;
-            }
-            """
-
-    def render_js(self):
-        """Generates the Javascript part of the plugin."""
-        out = """
-        map.scrollEnabled = true;
-
-        var toggleScroll = function() {
-            if (map.scrollEnabled) {
-                map.scrollEnabled = false;
-                map.scrollWheelZoom.disable();
-                }
-            else {
-                map.scrollEnabled = true;
-                map.scrollWheelZoom.enable();
-                }
-            };
-        """
-        if not self.zoom_enabled:
-            out += "\n        toggleScroll();"
-        return out
-
-class MarkerCluster(Plugin):
-    """Adds a MarkerCluster layer on the map."""
-    def __init__(self, data):
-        """Creates a MarkerCluster plugin to append into a map with
-        Map.add_plugin.
-
-        Parameters
-        ----------
-            data: list of list or array of shape (n,3).
-                Data points of the form [[lat, lng, popup]].
-        """
-        self.data = [tuple(x) for x in data]
-        self.name = "MarkerCluster_"+uuid4().hex
-
-    def render_header(self):
-        """Generates the HTML part of the plugin."""
-        return """
-        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet.markercluster/0.4.0/MarkerCluster.css" />
-	    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet.markercluster/0.4.0/MarkerCluster.Default.css" />
-	    <script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet.markercluster/0.4.0/leaflet.markercluster.js"></script>
-        """
-
-    def render_js(self):
-        """Generates the Javascript part of the plugin."""
-        out = """
-        var addressPoints = """+json.dumps(self.data)+""";
-
-        var markers = L.markerClusterGroup();
-
-		for (var i = 0; i < addressPoints.length; i++) {
-			var a = addressPoints[i];
-			var title = a[2];
-			var marker = L.marker(new L.LatLng(a[0], a[1]), { title: title });
-			marker.bindPopup(title);
-			markers.addLayer(marker);
-		}
-
-		map.addLayer(markers);
-		"""
-        return out
+"""
+Folium plugins
+--------------
+
+Add different objetcs/effects on a folium map.
+"""
+from .marker_cluster import MarkerCluster
+from .scroll_zoom_toggler import ScrollZoomToggler
+from .terminator import Terminator
+from .boat_marker import BoatMarker
+from .layer import Layer, LayerControl
+from .geo_json import GeoJson

folium/plugins/__init__.py

@@ -0,0 +1,61 @@
+# -*- coding: utf-8 -*-
+"""
+Boat marker
+-----------
+
+Creates a marker shaped like a boat. Optionally you can append a wind direction. 
+"""
+import json
+
+from .plugin import Plugin
+
+class BoatMarker(Plugin):
+    """Adds a BoatMarker layer on the map."""
+    def __init__(self, position=None, heading=0, wind_heading=None, wind_speed=0, **kwargs):
+        """Creates a BoatMarker plugin to append into a map with
+        Map.add_plugin.
+
+        Parameters
+        ----------
+            position: tuple of length 2, default None
+                The latitude and longitude of the marker.
+                If None, then the middle of the map is used.
+
+            heading: int, default 0
+                Heading of the boat to an angle value between 0 and 360 degrees
+
+            wind_heading: int, default None
+                Heading of the wind to an angle value between 0 and 360 degrees
+                If None, then no wind is represented.
+
+            wind_speed: int, default 0
+                Speed of the wind in knots.
+        """
+        super(BoatMarker, self).__init__()
+        self.plugin_name = 'BoatMarker'
+        self.position = None if position is None else tuple(position)
+        self.heading = heading
+        self.wind_heading = wind_heading
+        self.wind_speed = wind_speed
+        self.kwargs = kwargs.copy()
+        
+    def render_header(self, nb):
+        """Generates the HTML part of the plugin."""
+        return """
+            <script src="https://thomasbrueggemann.github.io/leaflet.boatmarker/js/leaflet.boatmarker.min.js"></script>
+            """  if nb==0 else ""
+
+    def render_js(self, nb):
+        """Generates the Javascript part of the plugin."""
+        kwargs_str =  "{%s}" % ",".join(["%s : %s" % (key,json.dumps(val)) for (key,val) in self.kwargs.items()])
+        position_str = "map.getCenter()" if self.position is None else "[%.12f,%.12f]"%self.position
+        out = 'var boatMarker_%s = L.boatMarker(%s, %s).addTo(map);' % (nb,position_str,kwargs_str)
+        
+        if self.wind_heading is None:
+            out += "boatMarker_%s.setHeading(%s);" % (nb,int(self.heading))
+        else:
+            out += "boatMarker_%s.setHeadingWind(%s, %s, %s);"%(nb,int(self.heading),
+                                                             int(self.wind_speed),
+                                                             int(self.wind_heading),
+                                                             )
+        return out

folium/plugins/boat_marker.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+"""
+GeoJson plugin
+--------------
+
+Add a geojson feature collection on a folium map.
+"""
+import json
+
+from .plugin import Plugin
+
+class GeoJson(Plugin):
+    """Adds a GeoJson layer on the map."""
+    def __init__(self, data):
+        """Creates a GeoJson plugin to append into a map with
+        Map.add_plugin.
+
+        Parameters
+        ----------
+            data: file, dict or str.
+                The geo-json data you want to plot.
+                If file, then data will be read in the file and fully embeded in Leaflet's javascript.
+                If dict, then data will be converted to json and embeded in the javascript.
+                If str, then data will be passed to the javascript as-is.
+
+                examples :
+                    # providing file
+                    GeoJson(open('foo.json'))
+
+                    # providing dict
+                    GeoJson(json.load(open('foo.json')))
+
+                    # providing string
+                    GeoJson(open('foo.json').read())
+        """
+        super(GeoJson, self).__init__()
+        self.plugin_name = 'GeoJson'
+        if 'read' in dir(data):
+            self.data = data.read()
+        elif type(data) is dict:
+            self.data = json.dumps(data)
+        else:
+            self.data = data
+
+    def render_js(self, nb):
+        """Generates the Javascript part of the plugin."""
+        out = """
+        var geojson_{nb} = L.geoJson({data}).addTo(map);
+        """.format(nb=nb, data = self.data)
+        return out

folium/plugins/geo_json.py

@@ -0,0 +1,77 @@
+# -*- coding: utf-8 -*-
+"""
+Layer plugin
+------------
+
+Add layers and layer control to the map.
+"""
+from .plugin import Plugin
+
+class Layer(Plugin):
+    """Adds a layer to the map."""
+    def __init__(self, url=None, layer_name = None, min_zoom=1, max_zoom=18, attribution=''):
+        """Crates a layer object to be added on a folium map.
+        
+        Parameters
+        ----------
+            url : str
+                The url of the layer service, in the classical leaflet form.
+                    example: url='//otile1.mqcdn.com/tiles/1.0.0/osm/{z}/{x}/{y}.png'
+            layer_name : str
+                Tha name of the layer that will be displayed in the layer control.
+                If None, a random hexadecimal string will be created.
+            min_zoom : int, default 1
+                The minimal zoom allowed for this layer
+            max_zoom : int, default 18
+                The maximal zoom allowed for this layer
+            attribution : str, default ''
+                Tha atribution string for the layer.
+        """
+        super(Layer, self).__init__()
+        self.plugin_name = 'Layer'
+        self.tile_url = url
+        self.attribution = attribution
+        self.min_zoom = min_zoom
+        self.max_zoom = max_zoom
+        self.object_id = self.object_name
+        if layer_name is not None:
+            self.object_name = layer_name
+
+    def render_js(self, nb):
+        """Generates the JS part of the plugin."""
+        return """
+        var layer_"""+self.object_id+""" = L.tileLayer('"""+self.tile_url+"""', {
+            maxZoom: """+str(self.max_zoom)+""",
+            minZoom: """+str(self.min_zoom)+""",
+            attribution: '"""+str(self.attribution)+"""'
+            });
+        layer_"""+self.object_id+""".addTo(map);
+        """
+
+class LayerControl(Plugin):
+    """Adds a layer control to the map."""
+    def __init__(self, base_layer_name="Base Layer"):
+        """Creates a LayerControl object to be added on a folium map.
+        
+        Parameters
+        ----------
+            base_layer_name : str, default "Base Layer"
+                The name of the base layer that you want to see on the control.
+        """
+        super(LayerControl, self).__init__()
+        self.plugin_name = 'LayerControl'
+        self.base_layer_name = base_layer_name
+
+    def render_js(self, nb):
+        """Generates the JS part of the plugin."""
+        return """
+        var baseLayer = {
+          "%s": base_tile,"""% self.base_layer_name+\
+        ",".join(['"%s" : layer_%s ' % (x.object_name,x.object_id) for x in self.map.plugins['Layer']])+\
+        """};
+
+        L.control.layers(baseLayer, layer_list).addTo(map);
+        """
+    
+    
+    

folium/plugins/layer.py

@@ -0,0 +1,52 @@
+# -*- coding: utf-8 -*-
+"""
+Marker Cluster plugin
+---------------------
+
+Creates a MarkerCluster plugin to add on a folium map.
+"""
+import json
+
+from .plugin import Plugin
+
+class MarkerCluster(Plugin):
+    """Adds a MarkerCluster layer on the map."""
+    def __init__(self, data):
+        """Creates a MarkerCluster plugin to append into a map with
+        Map.add_plugin.
+
+        Parameters
+        ----------
+            data: list of list or array of shape (n,3).
+                Data points of the form [[lat, lng, popup]].
+        """
+        super(MarkerCluster, self).__init__()
+        self.plugin_name = 'MarkerCluster'
+        self.data = [tuple(x) for x in data]
+
+    def render_header(self, nb):
+        """Generates the HTML part of the plugin."""
+        return """
+        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet.markercluster/0.4.0/MarkerCluster.css" />
+        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet.markercluster/0.4.0/MarkerCluster.Default.css" />
+        <script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet.markercluster/0.4.0/leaflet.markercluster.js"></script>
+        """ if nb==0 else ""
+
+    def render_js(self, nb):
+        """Generates the Javascript part of the plugin."""
+        out = """
+        var addressPoints = """+json.dumps(self.data)+""";
+
+        var markers = L.markerClusterGroup();
+
+        for (var i = 0; i < addressPoints.length; i++) {
+            var a = addressPoints[i];
+            var title = a[2];
+            var marker = L.marker(new L.LatLng(a[0], a[1]), { title: title });
+            marker.bindPopup(title);
+            markers.addLayer(marker);
+        }
+
+        map.addLayer(markers);
+        """
+        return out