Pattern plugin for GeoJson (#966)

This adds a plugin to add fill patterns to a GeoJson object.

* Create pattern.py plugin with StripePattern and CirclePattern classes.
* Change GeoJson template to accommodate patterns.
* Further refactor the GeoJson template a bit.
* Add example notebook.
* Add utilities function to get an object in the object tree.
* Add tests for plugin and utilities function.

Author: ColinTalbert

CHANGES.txt

@@ -6,6 +6,9 @@
 - Automatically detect VegaLite version from specs (JarnoRFB #959)
 - Validate style and highlight functions in GeoJson (jtbaker #1024)
 - AntPath plugin (ocefpaf #1016)
+- Update Leaflet version to 1.4.0 (conengmo #1047)
+- DualMap plugin (conengmo #933)
+- CirclePattern and StripePattern plugins (talbertc-usgs #966)
 
 API changes
 

examples/plugin-patterns.ipynb

@@ -23,6 +23,7 @@
     image_to_url,
     none_max,
     none_min,
+    get_obj_in_upper_tree
 )
 from folium.vector_layers import PolyLine
 
@@ -392,35 +393,29 @@ class GeoJson(Layer):
     """
     _template = Template(u"""
         {% macro script(this, kwargs) %}
-        {% if this.highlight %}
+        {%- if this.highlight %}
             {{this.get_name()}}_onEachFeature = function onEachFeature(feature, layer) {
                 layer.on({
                     mouseout: function(e) {
                         e.target.setStyle(e.target.feature.properties.style);},
                     mouseover: function(e) {
                         e.target.setStyle(e.target.feature.properties.highlight);},
                     click: function(e) {
-                        {{this._parent.get_name()}}.fitBounds(e.target.getBounds());}
-                    });
+                        {{ this.parent_map.get_name() }}.fitBounds(e.target.getBounds());}
+                });
             };
-        {% endif %}
+        {%- endif %}
         var {{this.get_name()}} = L.geoJson(
-            {% if this.embed %}{{this.style_data()}}{% else %}"{{this.data}}"{% endif %}
-            {% if this.smooth_factor is not none or this.highlight %}
-                , {
-                {% if this.smooth_factor is not none  %}
-                    smoothFactor:{{this.smooth_factor}}
-                {% endif %}
-
-                {% if this.highlight %}
-                    {% if this.smooth_factor is not none  %}
-                    ,
-                    {% endif %}
-                    onEachFeature: {{this.get_name()}}_onEachFeature
-                {% endif %}
-                }
-            {% endif %}
-            ).addTo({{this._parent.get_name()}});
+            {{ this.json }},
+            {
+            {%- if this.smooth_factor is not none  %}
+                smoothFactor: {{ this.smooth_factor }},
+            {%- endif %}
+            {%- if this.highlight %}
+                onEachFeature: {{ this.get_name() }}_onEachFeature,
+            {%- endif %}
+            }
+        ).addTo({{ this._parent.get_name()}} );
         {{this.get_name()}}.setStyle(function(feature) {return feature.properties.style;});
         {% endmacro %}
         """)  # noqa
@@ -454,7 +449,6 @@ def __init__(self, data, style_function=None, name=None,
         self.style_function = style_function or (lambda x: {})
 
         self.highlight = highlight_function is not None
-
         self.highlight_function = highlight_function or (lambda x: {})
 
         self.smooth_factor = smooth_factor
@@ -467,12 +461,16 @@ def __init__(self, data, style_function=None, name=None,
         elif tooltip is not None:
             self.add_child(Tooltip(tooltip))
 
+        self.parent_map = None
+        self.json = None
+
     def _validate_function(self, func, name):
         """
         Tests `self.style_function` and `self.highlight_function` to ensure
         they are functions returning dictionaries.
         """
-        test_feature = self.data if self.data.get('features') is None else self.data['features'][0]  # noqa
+        test_feature = self.data if self.data.get('features') is None \
+            else self.data['features'][0]
         if not callable(func) or not isinstance(func(test_feature), dict):
             raise ValueError('{} should be a function that accepts items from '
                              'data[\'features\'] and returns a dictionary.'
@@ -492,10 +490,24 @@ def style_data(self):
             self.data = {'type': 'FeatureCollection', 'features': [self.data]}
 
         for feature in self.data['features']:
-            feature.setdefault('properties', {}).setdefault('style', {}).update(self.style_function(feature))  # noqa
-            feature.setdefault('properties', {}).setdefault('highlight', {}).update(
-                self.highlight_function(feature))  # noqa
-        return json.dumps(self.data, sort_keys=True)
+            feature_style = self.style_function(feature)
+            for key, value in feature_style.items():
+                if isinstance(value, MacroElement):
+                    # Make sure objects are rendered:
+                    if value._parent is None:
+                        value._parent = self
+                        value.render()
+                    # Replace objects with their Javascript var names:
+                    feature_style[key] = "{{'" + value.get_name() + "'}}"
+
+            feature.setdefault('properties', {}).setdefault('style', {}) \
+                .update(feature_style)
+            feature.setdefault('properties', {}).setdefault('highlight', {}) \
+                .update(self.highlight_function(feature))
+
+        data_json = json.dumps(self.data, sort_keys=True)
+        # Remove quotes around Jinja2 template expressions:
+        return data_json.replace('"{{', '{{').replace('}}"', '}}')
 
     def _get_self_bounds(self):
         """
@@ -505,6 +517,11 @@ def _get_self_bounds(self):
         """
         return get_bounds(self.data, lonlat=True)
 
+    def render(self, **kwargs):
+        self.parent_map = get_obj_in_upper_tree(self, Map)
+        self.json = self.style_data() if self.embed else json.dumps(self.data)
+        super(GeoJson, self).render()
+
 
 class TopoJson(Layer):
     """

folium/features.py

@@ -25,6 +25,7 @@
 from folium.plugins.measure_control import MeasureControl
 from folium.plugins.minimap import MiniMap
 from folium.plugins.mouse_position import MousePosition
+from folium.plugins.pattern import CirclePattern, StripePattern
 from folium.plugins.polyline_text_path import PolyLineTextPath
 from folium.plugins.scroll_zoom_toggler import ScrollZoomToggler
 from folium.plugins.search import Search
@@ -37,6 +38,7 @@
     'AntPath',
     'BeautifyIcon',
     'BoatMarker',
+    'CirclePattern',
     'Draw',
     'DualMap',
     'FastMarkerCluster',
@@ -52,6 +54,7 @@
     'PolyLineTextPath',
     'ScrollZoomToggler',
     'Search',
+    'StripePattern',
     'Terminator',
     'TimeSliderChoropleth',
     'TimestampedGeoJson',

folium/plugins/__init__.py

@@ -0,0 +1,151 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import (absolute_import, division, print_function)
+import json
+
+from branca.element import Figure, JavascriptLink, MacroElement
+
+from folium.folium import Map
+from folium.utilities import get_obj_in_upper_tree
+
+from jinja2 import Template
+
+
+class StripePattern(MacroElement):
+    """Fill Pattern for polygon composed of alternating lines.
+
+    Add these to the 'fillPattern' field in GeoJson style functions.
+
+    Parameters
+    ----------
+    angle: float, default 0.5
+        Angle of the line pattern (degrees). Should be between -360 and 360.
+    weight: float, default 4
+        Width of the main lines (pixels).
+    space_weight: float
+        Width of the alternate lines (pixels).
+    color: string with hexadecimal, RGB, or named color, default "#000000"
+        Color of the main lines.
+    space_color: string with hexadecimal, RGB, or named color, default "#ffffff"
+        Color of the alternate lines.
+    opacity: float, default 0.75
+        Opacity of the main lines. Should be between 0 and 1.
+    space_opacity: float, default 0.0
+        Opacity of the alternate lines. Should be between 0 and 1.
+
+    See https://github.com/teastman/Leaflet.pattern for more information.
+    """
+
+    _template = Template(u"""
+        {% macro script(this, kwargs) %}
+        var {{ this.get_name() }} = new L.StripePattern(
+            {{ this.options }}
+        );
+        {{ this.get_name() }}.addTo({{ this.parent_map.get_name() }});
+        {% endmacro %}
+    """)
+
+    def __init__(self, angle=.5, weight=4, space_weight=4,
+                 color="#000000", space_color="#ffffff",
+                 opacity=0.75, space_opacity=0.0):
+        super(StripePattern, self).__init__()
+        self._name = 'StripePattern'
+        self.options = json.dumps({
+            'angle': angle,
+            'weight': weight,
+            'spaceWeight': space_weight,
+            'color': color,
+            'spaceColor': space_color,
+            'opacity': opacity,
+            'spaceOpacity': space_opacity
+        })
+        self.parent_map = None
+
+    def render(self, **kwargs):
+        self.parent_map = get_obj_in_upper_tree(self, Map)
+        super(StripePattern, self).render(**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://teastman.github.io/Leaflet.pattern/leaflet.pattern.js'),  # noqa
+            name='pattern'
+        )
+
+
+class CirclePattern(MacroElement):
+    """Fill Pattern for polygon composed of repeating circles.
+
+    Add these to the 'fillPattern' field in GeoJson style functions.
+
+    Parameters
+    ----------
+    width: int, default 20
+        Horizontal distance between circles (pixels).
+    height: int, default 20
+        Vertical distance between circles (pixels).
+    radius: int, default 12
+        Radius of each circle (pixels).
+    weight: float, default 2.0
+        Width of outline around each circle (pixels).
+    color: string with hexadecimal, RGB, or named color, default "#3388ff"
+        Color of the circle outline.
+    fill_color: string with hexadecimal, RGB, or named color, default "#3388ff"
+        Color of the circle interior.
+    opacity: float, default 0.75
+        Opacity of the circle outline. Should be between 0 and 1.
+    fill_opacity: float, default 0.5
+        Opacity of the circle interior. Should be between 0 and 1.
+
+    See https://github.com/teastman/Leaflet.pattern for more information.
+    """
+
+    _template = Template(u"""
+        {% macro script(this, kwargs) %}
+        var shape = new L.PatternCircle(
+            {{ this.options_pattern_circle }}
+        );
+        var {{this.get_name()}} = new L.Pattern(
+            {{ this.options_pattern }}
+        );
+        {{ this.get_name() }}.addShape(shape);
+        {{ this.get_name() }}.addTo({{ this.parent_map }});
+        {% endmacro %}
+    """)
+
+    def __init__(self, width=20, height=20, radius=12, weight=2.0,
+                 color="#3388ff", fill_color="#3388ff",
+                 opacity=0.75, fill_opacity=0.5):
+        super(CirclePattern, self).__init__()
+        self._name = 'CirclePattern'
+        self.options_pattern_circle = json.dumps({
+            'x': radius + 2 * weight,
+            'y': radius + 2 * weight,
+            'weight': weight,
+            'radius': radius,
+            'color': color,
+            'fillColor': fill_color,
+            'opacity': opacity,
+            'fillOpacity': fill_opacity,
+            'fill': True,
+        })
+        self.options_pattern = json.dumps({
+            'width': width,
+            'height': height,
+        })
+        self.parent_map = None
+
+    def render(self, **kwargs):
+        self.parent_map = get_obj_in_upper_tree(self, Map).get_name()
+        super(CirclePattern, self).render(**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://teastman.github.io/Leaflet.pattern/leaflet.pattern.js'),  # noqa
+            name='pattern'
+        )

folium/plugins/pattern.py

@@ -432,3 +432,14 @@ def deep_copy(item_original):
             children_new[subitem.get_name()] = subitem
         item._children = children_new
     return item
+
+
+def get_obj_in_upper_tree(element, cls):
+    """Return the first object in the parent tree of class `cls`."""
+    if not hasattr(element, '_parent'):
+        raise ValueError('The top of the tree was reached without finding a {}'
+                         .format(cls))
+    parent = element._parent
+    if not isinstance(parent, cls):
+        return get_obj_in_upper_tree(parent, cls)
+    return parent

folium/utilities.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+
+"""
+Test pattern
+---------------
+
+"""
+
+from __future__ import (absolute_import, division, print_function)
+import os
+
+import folium
+
+from folium import plugins
+
+
+def test_pattern():
+    m = folium.Map([40., -105.], zoom_start=6)
+
+    stripes = plugins.pattern.StripePattern(angle=-45)
+    stripes.add_to(m)
+    circles = plugins.pattern.CirclePattern(width=20, height=20, radius=5,
+                                            fill_opacity=0.5, opacity=1)
+
+    def style_function(feature):
+        default_style = {
+            'opacity': 1.0,
+            'fillColor': '#ffff00',
+            'color': 'black',
+            'weight': 2
+        }
+
+        if feature['properties']['name'] == 'Colorado':
+            default_style['fillPattern'] = stripes
+            default_style['fillOpacity'] = 1.0
+
+        if feature['properties']['name'] == 'Utah':
+            default_style['fillPattern'] = circles
+            default_style['fillOpacity'] = 1.0
+
+        return default_style
+
+    data = os.path.join(os.path.dirname(__file__), os.pardir, 'us-states.json')
+    folium.GeoJson(data, style_function=style_function).add_to(m)
+
+    out = m._parent.render()
+
+    # We verify that the script import is present.
+    script = '<script src="https://teastman.github.io/Leaflet.pattern/leaflet.pattern.js"></script>'  # noqa
+    assert script in out