Merge pull request pbugnion#253 from razzius/master

Add tilt option to gmaps.figure

gmaps/figure.py

@@ -6,7 +6,7 @@
 from .maps import (
     Map, InitialViewport, GMapsWidgetMixin, map_params_doc_snippets
 )
-from .geotraitlets import MapType, MouseHandling
+from .geotraitlets import MapType, MouseHandling, Tilt
 from .toolbar import Toolbar
 from .errors_box import ErrorsBox
 from ._docutils import doc_subst
@@ -40,6 +40,7 @@ class Figure(GMapsWidgetMixin, widgets.DOMWidget):
         sync=True, **widgets.widget_serialization)
     _map = Instance(Map).tag(sync=True, **widgets.widget_serialization)
     map_type = MapType('ROADMAP')
+    tilt = Tilt()
     mouse_handling = MouseHandling('COOPERATIVE')
     layout = widgets.trait_types.InstanceDict(FigureLayout).tag(
         sync=True, **widgets.widget_serialization)
@@ -50,6 +51,10 @@ def __init__(self, *args, **kwargs):
         super(Figure, self).__init__(*args, **kwargs)
         self._map.map_type = self.map_type
         link((self._map, 'map_type'), (self, 'map_type'))
+
+        self._map.tilt = self.tilt
+        link((self._map, 'tilt'), (self, 'tilt'))
+
         self._map.mouse_handling = self.mouse_handling
         link((self._map, 'mouse_handling'), (self, 'mouse_handling'))
 
@@ -109,7 +114,7 @@ def add_layer(self, layer):
 
 @doc_subst(map_params_doc_snippets)
 def figure(
-        display_toolbar=True, display_errors=True, zoom_level=None,
+        display_toolbar=True, display_errors=True, zoom_level=None, tilt=45,
         center=None, layout=None, map_type='ROADMAP',
         mouse_handling='COOPERATIVE'):
     """
@@ -133,6 +138,15 @@ def figure(
         map. If specified, you must also specify the map center.
     :type zoom_level: int, optional
 
+    :param tilt:
+        Tilt can be either 0 or 45 indicating the tilt angle in
+        degrees.  45-degree imagery is only available for satellite
+        and hybrid map types, and is not available at every location
+        at every zoom level. For locations where 45-degree imagery is
+        not available, Google Maps will automatically fall back to 0
+        tilt.
+    :type tilt: int, optional
+
     :param center:
         Latitude-longitude pair determining the map center.
         By default, the map center is chosen to fit the data passed to the
@@ -179,6 +193,7 @@ def figure(
     To have a satellite map:
 
     >>> fig = gmaps.figure(map_type='HYBRID')
+
     """  # noqa: E501
     if zoom_level is not None or center is not None:
         if zoom_level is None or center is None:
@@ -202,6 +217,6 @@ def figure(
     _errors_box = ErrorsBox() if display_errors else None
     fig = Figure(
         _map=_map, _toolbar=_toolbar, _errors_box=_errors_box,
-        layout=layout, map_type=map_type,
+        layout=layout, map_type=map_type, tilt=tilt,
         mouse_handling=mouse_handling)
     return fig

gmaps/geotraitlets.py

@@ -185,6 +185,20 @@ def validate(self, obj, value):
             self.error(obj, value)
 
 
+class Tilt(traitlets.Integer):
+    """
+    Integer representing a tilt degree allowed by Google Maps
+    """
+    info_text = 'tilt angle in degrees (either 0 or 45)'
+    default_value = 45
+
+    def validate(self, obj, value):
+        if value in {0, 45}:
+            return value
+        else:
+            self.error(obj, value)
+
+
 class ColorAlpha(traitlets.Union):
     """
     Trait representing a color that can be passed to Google maps.

gmaps/maps.py

@@ -4,7 +4,7 @@
                        observe, Dict, HasTraits, Enum, Union)
 
 from .bounds import merge_longitude_bounds
-from .geotraitlets import Point, ZoomLevel, MapType, MouseHandling
+from .geotraitlets import Point, ZoomLevel, MapType, MouseHandling, Tilt
 from ._docutils import doc_subst
 from ._version import CLIENT_VERSION
 
@@ -194,6 +194,7 @@ class Map(ConfigurationMixin, GMapsWidgetMixin, widgets.DOMWidget):
     initial_viewport = InitialViewport(default_value='DATA_BOUNDS').tag(
             sync=True, to_json=_serialize_viewport)
     map_type = MapType('ROADMAP').tag(sync=True)
+    tilt = Tilt().tag(sync=True)
     mouse_handling = MouseHandling('COOPERATIVE').tag(sync=True)
 
     def add_layer(self, layer):

gmaps/tests/test_figure.py

@@ -100,6 +100,18 @@ def test_custom_map_type(self):
         fig = figure(map_type='SATELLITE')
         assert fig.map_type == 'SATELLITE'
 
+    def test_0_tilt(self):
+        fig = figure(tilt=0)
+        assert fig._map.tilt == 0
+
+    def test_45_tilt(self):
+        fig = figure(tilt=45)
+        assert fig._map.tilt == 45
+
+    def test_default_tilt(self):
+        fig = figure()
+        assert fig._map.tilt == 45
+
     def test_custom_mouse_handling(self):
         fig = figure(mouse_handling='NONE')
         assert fig.mouse_handling == 'NONE'

js/src/Map.js

@@ -112,7 +112,8 @@ export class PlainmapView extends ConfigurationMixin(widgets.DOMWidgetView) {
     readOptions(google) {
         const options = {
             mapTypeId: stringToMapType(google, this.model.get('map_type')),
-            gestureHandling: this.model.get('mouse_handling').toLowerCase()
+            gestureHandling: this.model.get('mouse_handling').toLowerCase(),
+            tilt: this.model.get('tilt')
         }
         return options
     }
@@ -127,6 +128,13 @@ export class PlainmapView extends ConfigurationMixin(widgets.DOMWidgetView) {
             }
         )
 
+        this.model.on(
+          'change:tilt',
+          () => {
+            this.setMapOptions({ tilt: this.model.get('tilt') })
+          }
+        )
+
         this.model.on(
             'change:mouse_handling',
             () => {