add(pydeck) support for deck.gl widgets (#9342)

* add(pydeck) support for deck.gl widgets

bindings/pydeck/README.md

@@ -10,7 +10,7 @@
 The pydeck library is a set of Python bindings for making spatial visualizations with [deck.gl](https://deck.gl),
 optimized for a Jupyter environment. To get started, __[see the documentation](https://pydeck.gl/)__.
 
-__[To install pydeck, see the instructions here](https://pydeck.gl/installation.html)__.
+__[To install pydeck, see the instructions here](https://pydeck.gl/en/latest/installation.html)__.
 
 For __interactive demos__, click the binder logo below:
 
@@ -68,4 +68,4 @@ If you encounter an issue, file it in the [deck.gl issues page](https://github.c
 and include your browser's console output, if any.
 
 If you'd like to contribute to pydeck, please follow the [deck.gl contribution guidelines](https://github.com/visgl/deck.gl/blob/master/CONTRIBUTING.md)
-and the [pydeck development installation instructions](https://pydeck.gl/installation.html#development-notes).
+and the [pydeck development installation instructions](https://pydeck.gl/en/latest/contributing.html).

bindings/pydeck/docs/widget.rst

@@ -0,0 +1,7 @@
+Widget
+======
+
+.. automodule:: pydeck.bindings.widget
+    :members:
+    :undoc-members:
+    :show-inheritance:

bindings/pydeck/examples/01 - Introduction.ipynb

@@ -59,7 +59,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## 2. Configure the visualization: Choose your layer(s) and viewport\n",
+    "## 2. Configure the visualization: Choose your layer(s), viewport, and widget(s)\n",
     "\n",
     "pydeck's **`Layer`** object takes two positional and many keyword arguments:\n",
     "\n",
@@ -80,15 +80,19 @@
     "    coverage=1)\n",
     "```\n",
     "\n",
-    "There is of course an entire catalog of layers which you're welcome to check out within the [deck.gl documentation](https://deck.gl/#/documentation/deckgl-api-reference/layers/overview).\n",
+    "There is of course an entire catalog of layers which you're welcome to check out within the [deck.gl documentation](https://deck.gl/docs/api-reference/layers).\n",
     "\n",
     "### Configure your viewport\n",
     "\n",
     "We also have to specifiy a **`ViewState`** object.\n",
     "\n",
     "The **`ViewState`** object specifies a camera angle relative to the map data. If you don't want to manually specify it, the function **`pydeck.data_utils.compute_view`** can take your data and automatically zoom to it.\n",
     "\n",
-    "pydeck also provides some controls, most of which should be familiar from map applications throughout the web. By default, you can hold out and drag to rotate the map."
+    "pydeck also provides some controls, most of which should be familiar from map applications throughout the web. By default, you can hold out and drag to rotate the map.\n",
+    "\n",
+    "### Configure your UI widgets\n",
+    "\n",
+    "You may also want to add **`Widget`** objects to offer controls and information around the pydeck visualization. Browse the catalog of widgets within the [deck.gl documentation](https://deck.gl/docs/api-reference/widgets/overview)."
    ]
   },
   {
@@ -120,8 +124,11 @@
     "    pitch=40.5,\n",
     "    bearing=-27.36)\n",
     "\n",
+    "# Add a zoom control\n",
+    "widget = pdk.Widget('ZoomWidget')\n",
+    "\n",
     "# Combined all of it and render a viewport\n",
-    "r = pdk.Deck(layers=[layer], initial_view_state=view_state)\n",
+    "r = pdk.Deck(layers=[layer], initial_view_state=view_state, widgets=[widget])\n",
     "r.show()"
    ]
   },
@@ -197,7 +204,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -211,7 +218,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.7"
+   "version": "3.9.13"
   }
  },
  "nbformat": 4,

bindings/pydeck/pydeck/__init__.py

@@ -1,4 +1,4 @@
-from .bindings import map_styles, Deck, Layer, LightSettings, View, ViewState  # noqa
+from .bindings import map_styles, Deck, Layer, LightSettings, View, ViewState, Widget  # noqa
 
 from .nbextension import _jupyter_nbextension_paths  # noqa
 

bindings/pydeck/pydeck/bindings/__init__.py

@@ -3,5 +3,6 @@
 from .light_settings import LightSettings  # noqa
 from .view import View  # noqa
 from .view_state import ViewState  # noqa
+from .widget import Widget  # noqa
 
 from . import map_styles  # noqa

bindings/pydeck/pydeck/bindings/deck.py

@@ -39,6 +39,7 @@ def __init__(
         effects=None,
         map_provider=BaseMapProvider.CARTO.value,
         parameters=None,
+        widgets=None
     ):
         """This is the renderer and configuration for a deck.gl visualization, similar to the
         `Deck <https://deck.gl/docs/api-reference/core/deck>`_ class from deck.gl.
@@ -87,6 +88,7 @@ def __init__(
         else:
             self.layers = layers or []
         self.views = views
+        self.widgets = widgets
         # Use passed view state
         self.initial_view_state = initial_view_state
 

bindings/pydeck/pydeck/bindings/widget.py

@@ -0,0 +1,40 @@
+from .json_tools import JSONMixin
+
+TYPE_IDENTIFIER = "@@type"
+
+
+class Widget(JSONMixin):
+    """
+    Represents a deck.gl widget, which are UI components around the WebGL2/WebGPU canvas
+    to offer controls and information for a better user experience.
+
+    Parameters
+    ---------
+    type : str, default None
+        deck.gl widget to display, e.g., 'CompassWidget'
+    id : str, default None
+        Unique name for widget
+    placement : string, default 'top-left'
+        Placement of the widget on the map. Options are 'top-left', 'top-right', 'bottom-left', 'bottom-right', and 'fill'.
+        Note that not all widgets support custom placement.
+    view_id : string, default None
+        ID of the view to which the widget should be added. The widget will be added to the default view if not specified.
+        Note that not all widgets support custom view_id.
+    **kwargs
+        Any of the parameters passable to a deck.gl Widget
+    """
+
+    def __init__(self, type, id=None, placement=None, view_id=None, **kwargs):
+        self.type = type
+        self.id = id
+        self.placement = placement
+        self.view_id = view_id
+        self.__dict__.update(kwargs)
+
+    @property
+    def type(self):
+        return getattr(self, TYPE_IDENTIFIER)
+
+    @type.setter
+    def type(self, type_name):
+        self.__setattr__(TYPE_IDENTIFIER, type_name)

bindings/pydeck/tests/bindings/test_widget.py

@@ -0,0 +1,8 @@
+import json
+
+from pydeck import Widget
+
+
+def test_widget_constructor():
+    EXPECTED = {"@@type": "ZoomWidget", "placement": "top-right"}
+    assert json.loads(Widget(type="ZoomWidget", placement="top-right", view_id=None).to_json()) == EXPECTED

modules/jupyter-widget/package.json

@@ -35,6 +35,7 @@
     "@deck.gl/json": "9.1.0-beta.1",
     "@deck.gl/layers": "9.1.0-beta.1",
     "@deck.gl/mesh-layers": "9.1.0-beta.1",
+    "@deck.gl/widgets": "9.1.0-beta.1",
     "@jupyter-widgets/base": "^1.1.10 || ^2 || ^3 || ^4",
     "@loaders.gl/3d-tiles": "^4.2.0",
     "@loaders.gl/core": "^4.2.0",

modules/jupyter-widget/src/deck-bundle.js

@@ -13,3 +13,4 @@ export * from '@deck.gl/geo-layers';
 export * from '@deck.gl/mesh-layers';
 export * from '@deck.gl/google-maps';
 export * from '@deck.gl/json';
+export * from '@deck.gl/widgets';