first commit

.venv/Lib/site-packages/pydeck/bindings/__init__.py

@@ -0,0 +1,7 @@
+from .deck import Deck  # noqa
+from .layer import Layer  # noqa
+from .light_settings import LightSettings  # noqa
+from .view import View  # noqa
+from .view_state import ViewState  # noqa
+
+from . import map_styles  # noqa

.venv/Lib/site-packages/pydeck/bindings/base_map_provider.py

@@ -0,0 +1,9 @@
+from enum import Enum
+
+
+class BaseMapProvider(Enum):
+    """Basemap provider available in pydeck"""
+
+    MAPBOX = "mapbox"
+    GOOGLE_MAPS = "google_maps"
+    CARTO = "carto"

.venv/Lib/site-packages/pydeck/bindings/deck.py

@@ -0,0 +1,201 @@
+import os
+
+from .json_tools import JSONMixin
+from .layer import Layer
+from ..io.html import deck_to_html
+from ..settings import settings as pydeck_settings
+from ..widget import DeckGLWidget
+from .view import View
+from .view_state import ViewState
+from .base_map_provider import BaseMapProvider
+from .map_styles import DARK, get_from_map_identifier
+
+
+class Deck(JSONMixin):
+    def __init__(
+        self,
+        layers=None,
+        views=[View(type="MapView", controller=True)],
+        map_style=DARK,
+        api_keys=None,
+        initial_view_state=ViewState(latitude=0, longitude=0, zoom=1),
+        width="100%",
+        height=500,
+        tooltip=True,
+        description=None,
+        effects=None,
+        map_provider=BaseMapProvider.CARTO.value,
+        parameters=None,
+    ):
+        """This is the renderer and configuration for a deck.gl visualization, similar to the
+        `Deck <https://deck.gl/#/documentation/deckgl-api-reference/deck>`_ class from deck.gl.
+        Pass `Deck` a Mapbox API token to display a basemap; see the notes below.
+
+        Parameters
+        ----------
+
+        layers : pydeck.Layer or list of pydeck.Layer, default None
+            List of :class:`pydeck.bindings.layer.Layer` layers to render.
+        views : list of pydeck.View, default ``[pydeck.View(type="MapView", controller=True)]``
+            List of :class:`pydeck.bindings.view.View` objects to render.
+        api_keys : dict, default None
+            Dictionary of geospatial API service providers, where the keys are ``mapbox``, ``google_maps``, or ``carto``
+            and the values are the API key. Defaults to None if not set. Any of the environment variables
+            ``MAPBOX_API_KEY``, ``GOOGLE_MAPS_API_KEY``, and ``CARTO_API_KEY`` can be set instead of hardcoding the key here.
+        map_provider : str, default 'carto'
+            If multiple API keys are set (e.g., both Mapbox and Google Maps), inform pydeck which basemap provider to prefer.
+            Values can be ``carto``, ``mapbox`` or ``google_maps``
+        map_style : str or dict, default 'dark'
+            One of 'light', 'dark', 'road', 'satellite', 'dark_no_labels', and 'light_no_labels', a URI for a basemap
+            style, which varies by provider, or a dict that follows the Mapbox style `specification <https://docs.mapbox.com/mapbox-gl-js/style-spec/>`.
+            The default is Carto's Dark Matter map. For Mapbox examples, see  Mapbox's `gallery <https://www.mapbox.com/gallery/>`.
+            If not using a basemap, set ``map_provider=None``.
+        initial_view_state : pydeck.ViewState, default ``pydeck.ViewState(latitude=0, longitude=0, zoom=1)``
+            Initial camera angle relative to the map, defaults to a fully zoomed out 0, 0-centered map
+            To compute a viewport from data, see :func:`pydeck.data_utils.viewport_helpers.compute_view`
+        height : int, default 500
+            Height of Jupyter notebook cell, in pixels.
+        width : int` or string, default '100%'
+            Width of visualization, in pixels (if a number) or as a CSS value string.
+        tooltip : bool or dict of {str: str}, default True
+            If ``True``/``False``, toggles a default tooltip on visualization hover.
+            Layers must have ``pickable=True`` set in order to display a tooltip.
+            For more advanced usage, the user can pass a dict to configure more custom tooltip features.
+            Further documentation is `here <tooltip.html>`_.
+
+        .. _Deck:
+            https://deck.gl/#/documentation/deckgl-api-reference/deck
+        .. _gallery:
+            https://www.mapbox.com/gallery/
+        """
+        self.layers = []
+        if isinstance(layers, Layer):
+            self.layers.append(layers)
+        else:
+            self.layers = layers or []
+        self.views = views
+        # Use passed view state
+        self.initial_view_state = initial_view_state
+        self.deck_widget = DeckGLWidget()
+        self.deck_widget.custom_libraries = pydeck_settings.custom_libraries
+        api_keys = api_keys or {}
+        self._set_api_keys(api_keys)
+
+        self.deck_widget.height = height
+        self.deck_widget.width = width
+        self.deck_widget.tooltip = tooltip
+
+        self.description = description
+        self.effects = effects
+
+        self.map_provider = str(map_provider).lower() if map_provider else None
+        self.deck_widget.map_provider = map_provider
+
+        custom_map_style_error = "The map_provider parameter must be 'mapbox' when map_style is provided as a dict."
+
+        if isinstance(map_style, dict):
+            assert map_provider == BaseMapProvider.MAPBOX.value, custom_map_style_error
+            self.map_style = map_style
+        else:
+            self.map_style = get_from_map_identifier(map_style, map_provider)
+
+        self.parameters = parameters
+
+    @property
+    def selected_data(self):
+        if not self.deck_widget.selected_data:
+            return None
+        return self.deck_widget.selected_data
+
+    def _set_api_keys(self, api_keys: dict = None):
+        """Sets API key for base map provider for both HTML embedding and the Jupyter widget"""
+        for k in api_keys:
+            k and BaseMapProvider(k)
+        for provider in BaseMapProvider:
+            attr_name = f"{provider.value}_key"
+            provider_env_var = f"{provider.name}_API_KEY"
+            attr_value = api_keys.get(provider.value) or os.getenv(provider_env_var)
+            setattr(self, attr_name, attr_value)
+            setattr(self.deck_widget, attr_name, attr_value)
+
+    def show(self):
+        """Display current Deck object for a Jupyter notebook"""
+        self.update()
+        return self.deck_widget
+
+    def update(self):
+        """Update a deck.gl map to reflect the current configuration
+
+        For example, if you've modified data passed to Layer and rendered the map using `.show()`,
+        you can call `update` to change the data on the map.
+
+        Intended for use in a Jupyter environment.
+        """
+        self.deck_widget.json_input = self.to_json()
+        has_binary = False
+        binary_data_sets = []
+        for layer in self.layers:
+            if layer.use_binary_transport:
+                binary_data_sets.extend(layer.get_binary_data())
+                has_binary = True
+        if has_binary:
+            self.deck_widget.data_buffer = binary_data_sets
+
+    def to_html(
+        self,
+        filename=None,
+        open_browser=False,
+        notebook_display=None,
+        iframe_width="100%",
+        iframe_height=500,
+        as_string=False,
+        offline=False,
+        **kwargs,
+    ):
+        """Write a file and loads it to an iframe, if in a Jupyter environment;
+        otherwise, write a file and optionally open it in a web browser
+
+        Parameters
+        ----------
+        filename : str, default None
+            Name of the file.
+        open_browser : bool, default False
+            Whether a browser window will open or not after write.
+        notebook_display : bool, default None
+            Display the HTML output in an iframe if True. Set to True automatically if rendering in Jupyter.
+        iframe_width : str or int, default '100%'
+            Width of Jupyter notebook iframe in pixels, if rendered in a Jupyter environment.
+        iframe_height : int, default 500
+            Height of Jupyter notebook iframe in pixels, if rendered in Jupyter or Colab.
+        as_string : bool, default False
+            Returns HTML as a string, if True and ``filename`` is None.
+        css_background_color : str, default None
+            Background color for visualization, specified as a string in any format accepted for CSS colors.
+
+        Returns
+        -------
+        str
+            Returns absolute path of the file
+        """
+        deck_json = self.to_json()
+        f = deck_to_html(
+            deck_json,
+            mapbox_key=self.mapbox_key,
+            google_maps_key=self.google_maps_key,
+            filename=filename,
+            open_browser=open_browser,
+            notebook_display=notebook_display,
+            iframe_height=iframe_height,
+            iframe_width=iframe_width,
+            tooltip=self.deck_widget.tooltip,
+            custom_libraries=pydeck_settings.custom_libraries,
+            as_string=as_string,
+            offline=offline,
+            **kwargs,
+        )
+        return f
+
+    def _repr_html_(self):
+        # doesn't actually need the HTML packaging in iframe_with_srcdoc,
+        # so we just take the HTML.data part
+        return self.to_html(notebook_display=True).data

.venv/Lib/site-packages/pydeck/bindings/json_tools.py

@@ -0,0 +1,100 @@
+"""
+Support serializing objects into JSON
+"""
+import json
+
+from pydeck.types.base import PydeckType
+
+# Attributes to ignore during JSON serialization
+IGNORE_KEYS = [
+    "mapbox_key",
+    "google_maps_key",
+    "deck_widget",
+    "binary_data_sets",
+    "_binary_data",
+    "_kwargs",
+]
+
+
+def to_camel_case(snake_case):
+    """Makes a snake case string into a camel case one
+
+    Parameters
+    -----------
+    snake_case : str
+        Snake-cased string (e.g., "snake_cased") to be converted to camel-case (e.g., "camelCase")
+
+    Returns
+    -------
+    str
+        Camel-cased (e.g., "camelCased") version of input string
+    """
+    output_str = ""
+    should_upper_case = False
+    for i, c in enumerate(snake_case):
+        if c == "_" and i != 0:
+            should_upper_case = True
+            continue
+        output_str = output_str + c.upper() if should_upper_case else output_str + c
+        should_upper_case = False
+    return output_str
+
+
+def lower_first_letter(s):
+    return s[:1].lower() + s[1:] if s else ""
+
+
+def camel_and_lower(w):
+    return lower_first_letter(to_camel_case(w))
+
+
+def lower_camel_case_keys(attrs):
+    """Makes all the keys in a dictionary camel-cased and lower-case
+
+    Parameters
+    ----------
+    attrs : dict
+        Dictionary for which all the keys should be converted to camel-case
+    """
+    for snake_key in list(attrs.keys()):
+        if "_" not in snake_key:
+            continue
+        if snake_key == "_data":
+            camel_key = "data"
+        else:
+            camel_key = camel_and_lower(snake_key)
+        attrs[camel_key] = attrs.pop(snake_key)
+
+
+def default_serialize(o, remap_function=lower_camel_case_keys):
+    """Default method for rendering JSON from a dictionary"""
+    if issubclass(type(o), PydeckType):
+        return repr(o)
+    attrs = vars(o)
+    attrs = {k: v for k, v in attrs.items() if v is not None}
+    for ignore_attr in IGNORE_KEYS:
+        if attrs.get(ignore_attr):
+            del attrs[ignore_attr]
+    if remap_function:
+        remap_function(attrs)
+    return attrs
+
+
+def serialize(serializable):
+    """Takes a serializable object and JSONifies it"""
+    return json.dumps(serializable, sort_keys=True, default=default_serialize)
+
+
+class JSONMixin(object):
+    def __repr__(self):
+        """
+        Override of string representation method to return a JSON-ified version of the
+        Deck object.
+        """
+        return serialize(self)
+
+    def to_json(self):
+        """
+        Return a JSON-ified version of the Deck object.
+        """
+        return serialize(self)

.venv/Lib/site-packages/pydeck/bindings/layer.py

@@ -0,0 +1,172 @@
+import uuid
+
+import numpy as np
+
+from ..data_utils import is_pandas_df, has_geo_interface, records_from_geo_interface
+from .json_tools import JSONMixin, camel_and_lower
+
+from pydeck.types import Image
+from pydeck.exceptions import BinaryTransportException
+
+
+TYPE_IDENTIFIER = "@@type"
+FUNCTION_IDENTIFIER = "@@="
+QUOTE_CHARS = {"'", '"', "`"}
+
+
+class Layer(JSONMixin):
+    def __init__(self, type, data=None, id=None, use_binary_transport=None, **kwargs):
+        """Configures a deck.gl layer for rendering on a map. Parameters passed
+        here will be specific to the particular deck.gl layer that you are choosing to use.
+
+        Please see the deck.gl
+        `Layer catalog <https://deck.gl/docs/api-reference/layers>`_
+        to determine the particular parameters of your layer. You are highly encouraged to look
+        at the examples in the pydeck documentation.
+
+        Parameters
+        ==========
+
+        type : str
+            Type of layer to render, e.g., `HexagonLayer`
+        id : str, default None
+            Unique name for layer
+        data : str or list of dict of {str: Any} or pandas.DataFrame, default None
+            Either a URL of data to load in or an array of data
+        use_binary_transport : bool, default None
+            Boolean indicating binary data
+        **kwargs
+            Any of the parameters passable to a deck.gl layer.
+
+        Examples
+        ========
+
+        For example, here is a HexagonLayer which reads data from a URL.
+
+          >>> import pydeck
+          >>> # 2014 location of car accidents in the UK
+          >>> UK_ACCIDENTS_DATA = ('https://raw.githubusercontent.com/uber-common/'
+          >>>                     'deck.gl-data/master/examples/3d-heatmap/heatmap-data.csv')
+          >>> # Define a layer to display on a map
+          >>> layer = pydeck.Layer(
+          >>>     'HexagonLayer',
+          >>>     UK_ACCIDENTS_DATA,
+          >>>     get_position=['lng', 'lat'],
+          >>>     auto_highlight=True,
+          >>>     elevation_scale=50,
+          >>>     pickable=True,
+          >>>     elevation_range=[0, 3000],
+          >>>     extruded=True,
+          >>>     coverage=1)
+
+        Alternately, input can be a pandas.DataFrame:
+
+          >>> import pydeck
+          >>> df = pd.read_csv(UK_ACCIDENTS_DATA)
+          >>> layer = pydeck.Layer(
+          >>>     'HexagonLayer',
+          >>>     df,
+          >>>     get_position=['lng', 'lat'],
+          >>>     auto_highlight=True,
+          >>>     elevation_scale=50,
+          >>>     pickable=True,
+          >>>     elevation_range=[0, 3000],
+          >>>     extruded=True,
+          >>>     coverage=1)
+        """
+        self.type = type
+        self.id = id or str(uuid.uuid4())
+
+        # Add any other kwargs to the JSON output
+        self._kwargs = kwargs.copy()
+        if kwargs:
+            for k, v in kwargs.items():
+                # We assume strings and arrays of strings are identifiers
+                # ["lng", "lat"] would be converted to '[lng, lat]'
+                # TODO given that data here is usually a list of records,
+                # we could probably check that the identifier is in the row
+                # Errors on case like get_position='-', however
+
+                if isinstance(v, str) and v[0] in QUOTE_CHARS and v[0] == v[-1]:
+                    # Skip quoted strings
+                    kwargs[k] = v.replace(v[0], "")
+                elif isinstance(v, str) and Image.validate(v):
+                    # Have pydeck convert local images to strings and/or apply extra quotes
+                    kwargs[k] = Image(v)
+                elif isinstance(v, str):
+                    # Have @deck.gl/json treat strings values as functions
+                    kwargs[k] = FUNCTION_IDENTIFIER + v
+                elif isinstance(v, list) and v != [] and isinstance(v[0], str):
+                    # Allows the user to pass lists e.g. to specify coordinates
+                    array_as_str = ""
+                    for i, identifier in enumerate(v):
+                        if i == len(v) - 1:
+                            array_as_str += "{}".format(identifier)
+                        else:
+                            array_as_str += "{}, ".format(identifier)
+                    kwargs[k] = "{}[{}]".format(FUNCTION_IDENTIFIER, array_as_str)
+
+            self.__dict__.update(kwargs)
+
+        self._data = None
+        self.use_binary_transport = use_binary_transport
+        self._binary_data = None
+        self.data = data
+
+    @property
+    def data(self):
+        return self._data
+
+    @data.setter
+    def data(self, data_set):
+        """Make the data attribute a list no matter the input type, unless
+        use_binary_transport is specified, which case we circumvent
+        serializing the data to JSON
+        """
+        if self.use_binary_transport:
+            self._binary_data = self._prepare_binary_data(data_set)
+        elif is_pandas_df(data_set):
+            self._data = data_set.to_dict(orient="records")
+        elif has_geo_interface(data_set):
+            self._data = records_from_geo_interface(data_set)
+        else:
+            self._data = data_set
+
+    def get_binary_data(self):
+        if not self.use_binary_transport:
+            raise BinaryTransportException("Layer must be flagged with `use_binary_transport=True`")
+        return self._binary_data
+
+    def _prepare_binary_data(self, data_set):
+        # Binary format conversion gives a sizable speedup but requires
+        # slightly stricter standards for data input
+        if not is_pandas_df(data_set):
+            raise BinaryTransportException("Layer data must be a `pandas.DataFrame` type")
+
+        layer_accessors = self._kwargs
+        inverted_accessor_map = {v: k for k, v in layer_accessors.items() if type(v) not in [list, dict, set]}
+
+        binary_transmission = []
+        # Loop through data columns and convert them to numpy arrays
+        for column in data_set.columns:
+            # np.stack will take data arrays and conveniently extract the shape
+            np_data = np.stack(data_set[column].to_numpy())
+            # Get rid of the accessor so it doesn't appear in the JSON output
+            del self.__dict__[inverted_accessor_map[column]]
+            binary_transmission.append(
+                {
+                    "layer_id": self.id,
+                    "column_name": column,
+                    "accessor": camel_and_lower(inverted_accessor_map[column]),
+                    "np_data": np_data,
+                }
+            )
+        return binary_transmission
+
+    @property
+    def type(self):
+        return getattr(self, TYPE_IDENTIFIER)
+
+    @type.setter
+    def type(self, type_name):
+        self.__setattr__(TYPE_IDENTIFIER, type_name)

.venv/Lib/site-packages/pydeck/bindings/light_settings.py

@@ -0,0 +1,36 @@
+from .json_tools import JSONMixin
+
+
+class LightSettings(JSONMixin):
+    """
+    Configuration of lights on the plane
+
+    Parameters
+    ---------
+        lights_position : array, default None
+            Location of lights in an array of X/Y/Z coordinates
+        diffuse_ratio : float, default None
+            Proportion of light at many angles
+        specular_ratio : float, default None
+            Proportion of light reflected in a mirror-like manner
+        lights_strength : array, default None
+            Brightness of lights
+        number_of_lights : int, default None
+            Number of lights in visualization
+    """
+
+    def __init__(
+        self,
+        number_of_lights=2,
+        lights_position=None,
+        diffuse_ratio=None,
+        specular_ratio=None,
+        lights_strength=None,
+        ambient_ratio=None,
+    ):
+        self.ambient_ratio = ambient_ratio
+        self.diffuse_ratio = diffuse_ratio
+        self.lights_position = lights_position
+        self.lights_strength = lights_strength
+        self.number_of_lights = number_of_lights
+        self.specular_ratio = specular_ratio

.venv/Lib/site-packages/pydeck/bindings/map_styles.py

@@ -0,0 +1,59 @@
+import warnings
+
+
+DARK = "dark"
+LIGHT = "light"
+SATELLITE = "satellite"
+ROAD = "road"
+DARK_NO_LABELS = "dark_no_labels"
+LIGHT_NO_LABELS = "light_no_labels"
+
+MAPBOX_LIGHT = "mapbox://styles/mapbox/light-v9"
+MAPBOX_DARK = "mapbox://styles/mapbox/dark-v9"
+MAPBOX_ROAD = "mapbox://styles/mapbox/streets-v9"
+MAPBOX_SATELLITE = "mapbox://styles/mapbox/satellite-v9"
+
+CARTO_DARK = "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json"
+CARTO_DARK_NO_LABELS = "https://basemaps.cartocdn.com/gl/dark-matter-nolabels-gl-style/style.json"
+CARTO_LIGHT = "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json"
+CARTO_LIGHT_NO_LABELS = "https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json"
+CARTO_ROAD = "https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json"
+
+GOOGLE_SATELLITE = "satellite"
+GOOGLE_ROAD = "roadmap"
+
+styles = {
+    DARK: {"mapbox": MAPBOX_DARK, "carto": CARTO_DARK},
+    DARK_NO_LABELS: {"carto": CARTO_DARK_NO_LABELS},
+    LIGHT: {"mapbox": MAPBOX_LIGHT, "carto": CARTO_LIGHT},
+    LIGHT_NO_LABELS: {"carto": CARTO_LIGHT_NO_LABELS},
+    ROAD: {"carto": CARTO_ROAD, "google_maps": GOOGLE_ROAD, "mapbox": MAPBOX_ROAD},
+    SATELLITE: {"mapbox": MAPBOX_SATELLITE, "google_maps": GOOGLE_SATELLITE},
+}
+
+
+def get_from_map_identifier(map_identifier: str, provider: str) -> str:
+    """Attempt to get a style URI by map provider, otherwise pass the map identifier
+    to the API service
+
+    Provide reasonable cross-provider default map styles
+
+    Parameters
+    ----------
+    map_identifier : str
+        Either a specific map provider style or a token indicating a map style. Currently
+        tokens are "dark", "light", "satellite", "road", "dark_no_labels", or "light_no_labels".
+        Not all map styles are available for all providers.
+    provider : str
+        One of "carto", "mapbox", or "google_maps", indicating the associated base map tile provider.
+
+    Returns
+    -------
+    str
+        Base map URI
+
+    """
+    try:
+        return styles[map_identifier][provider]
+    except KeyError:
+        return map_identifier

.venv/Lib/site-packages/pydeck/bindings/view.py

@@ -0,0 +1,33 @@
+from .json_tools import JSONMixin
+
+TYPE_IDENTIFIER = "@@type"
+
+
+class View(JSONMixin):
+    """
+    Represents a "hard configuration" of a camera location
+
+    Parameters
+    ---------
+    type : str, default None
+        deck.gl view to display, e.g., MapView
+    controller : bool, default None
+        If enabled, camera becomes interactive.
+    **kwargs
+        Any of the parameters passable to a deck.gl View
+    """
+
+    def __init__(self, type=None, controller=None, width=None, height=None, **kwargs):
+        self.type = type
+        self.controller = controller
+        self.width = width
+        self.height = height
+        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)

.venv/Lib/site-packages/pydeck/bindings/view_state.py

@@ -0,0 +1,42 @@
+from .json_tools import JSONMixin
+
+
+class ViewState(JSONMixin):
+    """An object that represents where the state of a viewport, essentially where the screen is focused.
+
+    If you have two dimensional data and you don't want to set this manually,
+    see :func:`pydeck.data_utils.viewport_helpers.compute_view`.
+
+
+    Parameters
+    ---------
+    longitude : float, default None
+        x-coordinate of focus
+    latitude : float, default None
+        y-coordinate of focus
+    zoom : float, default None
+        Magnification level of the map, usually between 0 (representing the whole world)
+        and 24 (close to individual buildings)
+    min_zoom : float, default None
+        Least mangified zoom level the user can navigate to
+    max_zoom : float, default None
+        Most magnified zoom level the user can navigate to
+    pitch : float, default None
+        Up/down angle relative to the map's plane, with 0 being looking directly at the map
+    bearing : float, default None
+        Left/right angle relative to the map's true north, with 0 being aligned to true north
+    """
+
+    def __init__(
+        self, longitude=None, latitude=None, zoom=None, min_zoom=None, max_zoom=None, pitch=None, bearing=None, **kwargs
+    ):
+        self.longitude = longitude
+        self.latitude = latitude
+        self.zoom = zoom
+        self.min_zoom = min_zoom
+        self.max_zoom = max_zoom
+        self.pitch = pitch
+        self.bearing = bearing
+
+        if kwargs:
+            self.__dict__.update(kwargs)