Add PolyLineOffset Plugin (#1091)

Add PolyLineOffset Plugin

See https://github.com/bbecquet/Leaflet.PolylineOffset

Author: FabeG

examples/plugin-PolyLineOffset.ipynb

@@ -9,6 +9,7 @@
 """
 
 from folium.plugins.antpath import AntPath
+from folium.plugins.polyline_offset import PolyLineOffset
 from folium.plugins.beautify_icon import BeautifyIcon
 from folium.plugins.boat_marker import BoatMarker
 from folium.plugins.draw import Draw
@@ -50,6 +51,7 @@
     'MiniMap',
     'MousePosition',
     'PolyLineTextPath',
+    'PolyLineOffset',
     'ScrollZoomToggler',
     'Search',
     'StripePattern',

folium/plugins/__init__.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import absolute_import, division, print_function
+
+from branca.element import JavascriptLink
+
+from folium.vector_layers import PolyLine
+
+
+class PolyLineOffset(PolyLine):
+    """
+    Add offset capabilities to the PolyLine class.
+
+    This plugin adds to folium Polylines the ability to be drawn with a
+    relative pixel offset, without modifying their actual coordinates. The offset
+    value can be either negative or positive, for left- or right-side offset,
+    and remains constant across zoom levels.
+
+    See :func:`folium.vector_layers.path_options` for the `Path` options.
+
+    Parameters
+    ----------
+    locations: list of points (latitude, longitude)
+        Latitude and Longitude of line (Northing, Easting)
+    popup: str or folium.Popup, default None
+        Input text or visualization for object displayed when clicking.
+    tooltip: str or folium.Tooltip, optional
+        Display a text when hovering over the object.
+    offset: int, default 0
+        Relative pixel offset to draw a line parallel to an existant one,
+        at a fixed distance.
+    **kwargs:
+        Polyline options. See their Github page for the
+        available parameters.
+
+    See https://github.com/bbecquet/Leaflet.PolylineOffset
+
+    Examples
+    --------
+    >>> plugins.PolyLineOffset([[58, -28], [53, -23]], color="#f00", opacity=1, offset=-5).add_to(m)
+    >>> plugins.PolyLineOffset([[58, -28], [53, -23]], color="#080", opacity=1, offset=10).add_to(m)
+
+    """
+
+    def __init__(self, locations, popup=None, tooltip=None, offset=0, **kwargs):
+        super(PolyLineOffset, self).__init__(
+            locations=locations, popup=popup, tooltip=tooltip, **kwargs
+        )
+        self._name = "PolyLineOffset"
+        # Add PolyLineOffset offset.
+        self.options.update({"offset": offset})
+
+    def render(self, **kwargs):
+        super(PolyLineOffset, self).render()
+        figure = self.get_root()
+        figure.header.add_child(
+            JavascriptLink("https://cdn.jsdelivr.net/npm/[email protected]/leaflet.polylineoffset.min.js"),  # noqa
+            name="polylineoffset",
+        )

folium/plugins/polyline_offset.py

@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+
+"""
+Test PolyLineOffset
+-------------------
+"""
+
+from __future__ import absolute_import, division, print_function
+
+import folium
+from folium import plugins
+from folium.utilities import normalize
+
+import pytest
+
+
+@pytest.mark.parametrize("offset", [0, 10, -10])
+def test_polylineoffset(offset):
+    m = folium.Map([20.0, 0.0], zoom_start=3)
+
+    locations = [
+        [59.355600, -31.99219],
+        [55.178870, -42.89062],
+        [47.754100, -43.94531],
+        [38.272690, -37.96875],
+        [27.059130, -41.13281],
+        [16.299050, -36.56250],
+        [8.4071700, -30.23437],
+        [1.0546300, -22.50000],
+        [-8.754790, -18.28125],
+        [-21.61658, -20.03906],
+        [-31.35364, -24.25781],
+        [-39.90974, -30.93750],
+        [-43.83453, -41.13281],
+        [-47.75410, -49.92187],
+        [-50.95843, -54.14062],
+        [-55.97380, -56.60156],
+    ]
+
+    polylineoffset = plugins.PolyLineOffset(locations=locations, offset=offset)
+    polylineoffset.add_to(m)
+
+    m._repr_html_()
+    out = m._parent.render()
+
+    # We verify that the script import is present.
+    script = '<script src="https://cdn.jsdelivr.net/npm/[email protected]/leaflet.polylineoffset.min.js"></script>'  # noqa
+    assert script in out
+
+    # We verify that the script part is correct.
+    expected_rendered = """
+    var {name} = L.polyline(
+    {locations},
+    {{
+    "bubblingMouseEvents": true,
+    "color": "#3388ff",
+    "dashArray": null,
+    "dashOffset": null,
+    "fill": false,
+    "fillColor": "#3388ff",
+    "fillOpacity": 0.2,
+    "fillRule": "evenodd",
+    "lineCap": "round",
+    "lineJoin": "round",
+    "noClip": false,
+    "offset": {offset},
+    "opacity": 1.0,
+    "smoothFactor": 1.0,
+    "stroke": true,
+    "weight": 3
+    }}
+    )
+    .addTo({map});
+    """.format(
+        locations=locations,
+        name=polylineoffset.get_name(),
+        offset=offset,
+        map=m.get_name(),
+    )
+
+    rendered = polylineoffset._template.module.script(polylineoffset)
+    assert normalize(expected_rendered) == normalize(rendered)
+
+
+def test_polylineoffset_without_offset():
+    m = folium.Map([20.0, 0.0], zoom_start=3)
+
+    locations = [[59.355600, -31.99219], [55.178870, -42.89062]]
+
+    polylineoffset = plugins.PolyLineOffset(locations=locations)
+    polylineoffset.add_to(m)
+
+    m._repr_html_()
+    out = m._parent.render()
+
+    # We verify that the script import is present.
+    script = '<script src="https://cdn.jsdelivr.net/npm/[email protected]/leaflet.polylineoffset.min.js"></script>'  # noqa
+    assert script in out
+
+    # We verify that the script part is correct.
+    expected_rendered = """
+    var {name} = L.polyline(
+    {locations},
+    {{
+    "bubblingMouseEvents": true,
+    "color": "#3388ff",
+    "dashArray": null,
+    "dashOffset": null,
+    "fill": false,
+    "fillColor": "#3388ff",
+    "fillOpacity": 0.2,
+    "fillRule": "evenodd",
+    "lineCap": "round",
+    "lineJoin": "round",
+    "noClip": false,
+    "offset": 0,
+    "opacity": 1.0,
+    "smoothFactor": 1.0,
+    "stroke": true,
+    "weight": 3
+    }}
+    )
+    .addTo({map});
+    """.format(
+        locations=locations, name=polylineoffset.get_name(), map=m.get_name()
+    )
+
+    rendered = polylineoffset._template.module.script(polylineoffset)
+    assert normalize(expected_rendered) == normalize(rendered)