Merge pull request #933 from Conengmo/sync

Dual map plugin

Author: ocefpaf

examples/Plugins.ipynb

@@ -14,6 +14,7 @@
 from folium.plugins.beautify_icon import BeautifyIcon
 from folium.plugins.boat_marker import BoatMarker
 from folium.plugins.draw import Draw
+from folium.plugins.dual_map import DualMap
 from folium.plugins.fast_marker_cluster import FastMarkerCluster
 from folium.plugins.feature_group_sub_group import FeatureGroupSubGroup
 from folium.plugins.float_image import FloatImage
@@ -37,6 +38,7 @@
     'BeautifyIcon',
     'BoatMarker',
     'Draw',
+    'DualMap',
     'FastMarkerCluster',
     'FeatureGroupSubGroup',
     'FloatImage',

examples/plugin-DualMap.ipynb

@@ -0,0 +1,114 @@
+from jinja2 import Template
+
+from branca.element import MacroElement, Figure, JavascriptLink
+
+from folium.folium import Map
+from folium.utilities import deep_copy
+
+
+class DualMap(MacroElement):
+    """Create two maps in the same window.
+
+    Adding children to this objects adds them to both maps. You can access
+    the individual maps with `DualMap.m1` and `DualMap.m2`.
+
+    Uses the Leaflet plugin Sync: https://github.com/jieter/Leaflet.Sync
+
+    Parameters
+    ----------
+    layout : {'horizontal', 'vertical'}
+        Select how the two maps should be positioned. Either horizontal (left
+        and right) or vertical (top and bottom).
+    **kwargs
+        Keyword arguments are passed to the two Map objects.
+
+    Examples
+    --------
+    >>> # DualMap accepts the same arguments as Map:
+    >>> m = DualMap(location=(0, 0), tiles='cartodbpositron', zoom_start=5)
+    >>> # Add the same marker to both maps:
+    >>> Marker((0, 0)).add_to(m)
+    >>> # The individual maps are attributes called `m1` and `m2`:
+    >>> Marker((0, 1)).add_to(m.m1)
+    >>> LayerControl().add_to(m)
+    >>> m.save('map.html')
+
+    """
+
+    _template = Template("""
+        {% macro script(this, kwargs) %}
+        {{ this.m1.get_name() }}.sync({{ this.m2.get_name() }});
+        {{ this.m2.get_name() }}.sync({{ this.m1.get_name() }});
+        {% endmacro %}
+    """)
+
+    def __init__(self, location=None, layout='horizontal', **kwargs):
+        super(DualMap, self).__init__()
+        for key in ('width', 'height', 'left', 'top', 'position'):
+            assert key not in kwargs, ('Argument {} cannot be used with '
+                                       'DualMap.'.format(key))
+        if layout not in ('horizontal', 'vertical'):
+            raise ValueError('Undefined option for argument `layout`: {}. '
+                             'Use either \'horizontal\' or \'vertical\'.'
+                             .format(layout))
+        width = '50%' if layout == 'horizontal' else '100%'
+        height = '100%' if layout == 'horizontal' else '50%'
+        self.m1 = Map(location=location, width=width, height=height,
+                      left='0%', top='0%',
+                      position='absolute', **kwargs)
+        self.m2 = Map(location=location, width=width, height=height,
+                      left='50%' if layout == 'horizontal' else '0%',
+                      top='0%' if layout == 'horizontal' else '50%',
+                      position='absolute', **kwargs)
+        figure = Figure()
+        figure.add_child(self.m1)
+        figure.add_child(self.m2)
+        # Important: add self to Figure last.
+        figure.add_child(self)
+        self.children_for_m2 = []
+        self.children_for_m2_copied = []  # list with ids
+
+    def _repr_html_(self, **kwargs):
+        """Displays the HTML Map in a Jupyter notebook."""
+        if self._parent is None:
+            self.add_to(Figure())
+            out = self._parent._repr_html_(**kwargs)
+            self._parent = None
+        else:
+            out = self._parent._repr_html_(**kwargs)
+        return out
+
+    def add_child(self, child, name=None, index=None):
+        """Add object `child` to the first map and store it for the second."""
+        self.m1.add_child(child, name, index)
+        if index is None:
+            index = len(self.m2._children)
+        self.children_for_m2.append((child, name, index))
+
+    def render(self, **kwargs):
+        figure = self.get_root()
+        assert isinstance(figure, Figure), ('You cannot render this Element '
+                                            'if it is not in a Figure.')
+
+        figure.header.add_child(JavascriptLink('https://rawcdn.githack.com/jieter/Leaflet.Sync/master/L.Map.Sync.js'),  # noqa
+                                name='Leaflet.Sync')
+
+        super(DualMap, self).render(**kwargs)
+
+        for child, name, index in self.children_for_m2:
+            if child._id in self.children_for_m2_copied:
+                # This map has been rendered before, child was copied already.
+                continue
+            child_copy = deep_copy(child)
+            self.m2.add_child(child_copy, name, index)
+            # m2 has already been rendered, so render the child here:
+            child_copy.render()
+            self.children_for_m2_copied.append(child._id)
+
+    def fit_bounds(self, *args, **kwargs):
+        for m in (self.m1, self.m2):
+            m.fit_bounds(*args, **kwargs)
+
+    def keep_in_front(self, *args):
+        for m in (self.m1, self.m2):
+            m.keep_in_front(*args)

folium/plugins/__init__.py

@@ -9,6 +9,9 @@
 import tempfile
 import zlib
 from contextlib import contextmanager
+import copy
+import uuid
+import collections
 
 import numpy as np
 
@@ -415,3 +418,17 @@ def _tmp_html(data):
     finally:
         if os.path.isfile(filepath):
             os.remove(filepath)
+
+
+def deep_copy(item_original):
+    """Return a recursive deep-copy of item where each copy has a new ID."""
+    item = copy.copy(item_original)
+    item._id = uuid.uuid4().hex
+    if hasattr(item, '_children') and len(item._children) > 0:
+        children_new = collections.OrderedDict()
+        for subitem_original in item._children.values():
+            subitem = deep_copy(subitem_original)
+            subitem._parent = item
+            children_new[subitem.get_name()] = subitem
+        item._children = children_new
+    return item

folium/plugins/dual_map.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+
+"""
+Test DualMap
+------------
+"""
+
+from __future__ import (absolute_import, division, print_function)
+
+from jinja2 import Template
+
+import folium
+import folium.plugins
+
+
+def test_dual_map():
+    m = folium.plugins.DualMap((0, 0))
+
+    folium.FeatureGroup(name='both').add_to(m)
+    folium.FeatureGroup(name='left').add_to(m.m1)
+    folium.FeatureGroup(name='right').add_to(m.m2)
+
+    figure = m.get_root()
+    assert isinstance(figure, folium.Figure)
+    out = figure.render()
+
+    script = '<script src="https://rawcdn.githack.com/jieter/Leaflet.Sync/master/L.Map.Sync.js"></script>'  # noqa
+    assert script in out
+
+    tmpl = Template("""
+        {{ this.m1.get_name() }}.sync({{ this.m2.get_name() }});
+        {{ this.m2.get_name() }}.sync({{ this.m1.get_name() }});
+    """)
+
+    assert tmpl.render(this=m) in out

folium/utilities.py

@@ -1,10 +1,32 @@
 from __future__ import (absolute_import, division, print_function)
 
-from folium.utilities import camelize
+from folium.utilities import camelize, deep_copy
+from folium import Map, FeatureGroup, Marker
 
 
 def test_camelize():
     assert camelize('variable_name') == 'variableName'
     assert camelize('variableName') == 'variableName'
     assert camelize('name') == 'name'
     assert camelize('very_long_variable_name') == 'veryLongVariableName'
+
+
+def test_deep_copy():
+    m = Map()
+    fg = FeatureGroup().add_to(m)
+    Marker(location=(0, 0)).add_to(fg)
+    m_copy = deep_copy(m)
+
+    def check(item, item_copy):
+        assert type(item) is type(item_copy)
+        assert item._name == item_copy._name
+        for attr in item.__dict__.keys():
+            if not attr.startswith('_'):
+                assert getattr(item, attr) == getattr(item_copy, attr)
+        assert item is not item_copy
+        assert item._id != item_copy._id
+        for child, child_copy in zip(item._children.values(),
+                                     item_copy._children.values()):
+            check(child, child_copy)
+
+    check(m, m_copy)