Repository files navigation

Dash Deck is a proof of concept library for building 3D interactive maps and graphical visualizations directly in Dash. Built on top ofdeck.gl, it supports maps built usingpydeck and deck.gl’sJSON API.

• Try it in theDash Deck Explorer
• Readthe announcement
• Get it onPyPi, which has the latest version published by Plotly.
• Get it onconda-forge, a community maintained package index. To ensure that this version is up to date, please verify on the PyPi page.

First install this library:

pip install dash-deck

then, define your map using the deck.gl JSON API:

data= {"description":"A minimal deck.gl example rendering a circle with text","initialViewState": {"longitude":-122.45,"latitude":37.8,"zoom":12},"layers": [        {"@@type":"TextLayer","data": [{"position": [-122.45,37.8],"text":"Hello World"}],        },    ],}

finally, create your component and add it to your layout:

importdashimportdash_deckimportdash_html_componentsashtmldeck_component=dash_deck.DeckGL(data=data,id="deck-gl")app=dash.Dash(__name__)app.layout=html.Div(deck_component)

For a full example, seeusage.py. To find examples of the JSON API, seethe deck.gl playground.

First, install the package from GitHub (the package is not yet available via CRAN):

remotes::install_github("plotly/dash-deck")

then, define your map using the deck.gl JSON API:

deck_data<-list("description"="A minimal deck.gl example rendering a circle with text","initialViewState"=list("longitude"=-122.45,"latitude"=37.8,"zoom"=12),"layers"=list(list("@@type"="TextLayer","data"=list(list("position"=list(-122.45,37.8),"text"="Hello World"))        )    ))

finally, create your component and add it to your layout:

library(dash)library(dashDeck)library(dashHtmlComponents)deck_component<- deckGL(data=deck_data,id="deck-gl")app<-Dash$new()app$layout(htmlDiv(deck_component))

Make sure you havepydeck installed:

pip install pydeck

then, define a layer usingpdk and run it:

importpydeckaspdklayer=pdk.Layer("TextLayer",    [{"position": [-122.45,37.8],"text":"Hello World"}])# Renderr=pdk.Deck(layers=[layer])

then, convert it to JSON and add it to your layout:

importdashimportdash_deckimportdash_html_componentsashtmldeck_component=dash_deck.DeckGL(r.to_json(),id="deck-gl")app=dash.Dash(__name__)app.layout=html.Div(deck_component)

To learn how to usepydeck, read more inthe official documentations. You can find a complete example inusage-pdk.py.

Make sure that you have created aMapbox access token, and export it as an environment variable. For example, you can add the following line to your.bashrc:

export MAPBOX_ACCESS_TOKEN="pk.ey..."

Then, inside your app, define retrieve and define it asmapbox_api_token:

importosmapbox_api_token=os.getenv("MAPBOX_ACCESS_TOKEN")

When you define your component, simply pass it toDeckGL as an argument:

...r=pdk.Deck(...)deck_component=dash_deck.DeckGL(r.to_json(),id="deck-gl",mapboxKey=mapbox_api_token)...

The Pydeck team has already created many amazing demos, which are shown intheir doc gallery. We ported them for Dash Deck with minor modifications. You can read the docstring of eachusage-<name>.py file, you will be able to find the source code of the original demo. You can also try them directly in theDash Deck Explorer.

First, make sure you clone the project:

git clone https://github.com/plotly/dash-deck.gitcd dash-deck/

Create and activate a conda env:

conda create -n deck-demos python=3.7conda activate deck-demos

Or a venv (make sure yourpython3 is 3.6+):

python3 -m venv venvsource venv/bin/activate  # for Windows, use venv\Scripts\activate.bat

Install all the dev and demo requirements:

pip install -r requirements.txtpip install -r demos/requirements.txt

You can now run the demo you want to try (replace<name> with the layer type you want to try):

python demos/usage-<name>.py

If you want to show multiple maps side-by-side, you need to specify a"view" dict (when constructing your map dictionary) orpdk.View (which is given topdk.Deck). For example, you would add the following parameter to yourpdk.Deck:

map_view=pdk.View("MapView",width="75%",height="600px",controller=True)r=pdk.Deck(...,views=[map_view])

or add the following dictionary to yourdata dictionary:

data= {"layer": ...,    ...,"views": [{"@@type":"MapView","width":"75%","height":"600px"}],}deck_component=dash_deck.DeckGL(data,id="deck-gl")

Seedemos/usage-views.py for manually creating aview dictionary, anddemos/usage-pdk-views.py for manually creating apdk.View.

You can also directly modifydash_deck.DeckGL's style:

deck_component=dash_deck.DeckGL(...,style={"width":"50vw","height":"50vh"})

Thestyle prop is useful for directly changing the CSS of Dash Deck. For example, you can also change thebackground-color. Seedemos/usage-style-prop.py for an example.

Various events are exposed as read-only props, and you can use them asInput orState to your callbacks. They are disabled by default in order to maximize performance for cases where a lot of data are passed throughsetProps.

To use them, either setenableEvents toTrue, or give a list with the gestures that you want to enable. For example, the two following lines are equivalent:

dash_deck.DeckGL(r.to_json(),enableEvents=True)dash_deck.DeckGL(r.to_json(),enableEvents=['click','hover','dragStart','dragEnd'])

Two types of events are available.Info is the picking info describing the object being clicked andEvent is the original gesture event (in JSON). You can read more aboutInfo in the deck.gl developer guide.

The following props are available:

• clickEvent, clickInfo
• dragStartEvent, dragStartInfo
• dragEndEvent, dragEndInfo
• hoverEvent, hoverInfo

For an example of using events, please seedemos/usage-events.py.

Thepydeck tooltip can be used in Dash Deck. Moreover, rather than passing it topdk.Deck, you will need to pass it todash_deck.DeckGL:

deck_component=dash_deck.DeckGL(r.to_json(),id="deck-gl",tooltip=True)

You can also customize your tooltip:

deck_component=dash_deck.DeckGL(r.to_json(),id="deck-gl",tooltip={"html": ...,"style": ...    })

To learn more about tooltips, please check out thesection in the Pydeck docs. You will also be able to find somedemos with custom tooltips.

To build custom layers, you will need to create a custom version of Dash Deck. To do this you will need:

1. Clone this project, create a venv,npminstall andbuild (see CONTRIBUTING.md).
2. Add necessary packages to yourpackage.json. E.g.npm install turf, if you need a library called turn.
3. Create a Javascript file insidedash-deck/src/lib/ that will contain your layer. Seethis as an example.
4. Import the Javascript file indash-deck/src/lib/components/DeckGL.react.js, e.g.:

...importLabeledGeoJsonLayerfrom"../labeled-geojson-layer.js";...

5. Add it to theJSONConfiguration in the same file:

constconfiguration={classes:Object.assign({},    ...,LabeledGeoJsonLayer),enumerations: ...}

6. npm build
7. Start creating an app that usespydeck or JSON. Seedash-deck/demos/other/usage-custom-layer.py.
8. Run the tests (see contributing.md).
9. When you are ready, create the installable distribution files by runningpython setup.py sdist insidedash-deck/.

SeeCONTRIBUTING.md

Dash and Dash Deck are licensed under MIT. Please viewLICENSE for more details.

If you are interested in supporting the development of this library, check out ourconsulting & training page. For enterprise support and deployment,contact us.

This component lets you visualizes PyDeck and deck/json filesdirectly in Dash. It also exposes various events (such as click,hover and drag) inside callbacks.

Keyword arguments:

• data (dict | string; optional): Your map using the Deck.gl JSON format. This can be generated by callingpdk.Deck(...).to_json(). Both a Python dictionary and a JSON-string your map is accepted.
• id (string; optional): The ID used to identify this component in Dash callbacks.
• style (dict; optional): Custom CSS for your map. This is useful for changing the height, width, and sometimes the background color.
• enableEvents (list of strings | boolean; default False): Either a boolean indicating if all event callbacks should be enabled, or a list of stringsindicating which ones should be used. If it's a list, you will need to specify one of thefollowing gestures:click,dragStart,dragEnd,hover.
• tooltip (dict | boolean; default False): This can be a boolean value (e.g.True,False) to display the default tooltip.You can also give a dictionary specifying anhtml template and custom style usingcss. For moreinformation about templating, see:https://pydeck.gl/tooltip.html
• mapboxKey (string; optional): You will need a mapbox token to use deck.gl. Please create a mapboxand follow the instructions here:https://docs.mapbox.com/help/how-mapbox-works/access-tokens/
• disableContext (boolean; default False): This is a boolean value (e.g.True,False) indicating whether or not to disable the default context menuthat shows up when right clicking on the map. If set toTrue, right clicking to rotatea map or adjust its pitch will not trigger the default context menu.
• clickEvent (dict; optional): Read-only prop. To use this, make sure thatenableEvents is set toTrue, or thatenableEvents is a list that contains this event type.This prop is updated when an element in the map is clicked. This containsthe original gesture event (in JSON).
• clickInfo (dict; optional): Read-only prop. To use this, make sure thatenableEvents is set toTrue, or thatenableEvents is a list that contains this event type.This prop is updated when an element in the map is clicked. This containsthe picking info describing the object being clicked.Complete description here:https://deck.gl/docs/developer-guide/interactivity#the-picking-info-object
• hoverEvent (dict; optional): Read-only prop. To use this, make sure thatenableEvents is set toTrue, or thatenableEvents is a list that contains this event type.This prop is updated when an element in the map is hovered. This containsthe original gesture event (in JSON).
• hoverInfo (dict; optional): Read-only prop. To use this, make sure thatenableEvents is set toTrue, or thatenableEvents is a list that contains this event type.This prop is updated when an element in the map is hovered. This containsthe picking info describing the object being hovered.Complete description here:https://deck.gl/docs/developer-guide/interactivity#the-picking-info-object
• dragStartEvent (dict; optional): Read-only prop. To use this, make sure thatenableEvents is set toTrue, or thatenableEvents is a list that contains this event type.To use this, make sure thatenableEvents is set toTrue, or thatenableEvents is a list that contains this event type.This prop is updated when the user starts dragging on the canvas. This containsthe original gesture event (in JSON).
• dragStartInfo (dict; optional): Read-only prop. To use this, make sure thatenableEvents is set toTrue, or thatenableEvents is a list that contains this event type.This prop is updated when the user starts dragging on the canvas. This containsthe picking info describing the object being dragged.Complete description here:https://deck.gl/docs/developer-guide/interactivity#the-picking-info-object
• dragEndEvent (dict; optional): Read-only prop. To use this, make sure thatenableEvents is set toTrue, or thatenableEvents is a list that contains this event type.This prop is updated when the user releases from dragging the canvas. This containsthe original gesture event (in JSON).
• dragEndInfo (dict; optional): Read-only prop. To use this, make sure thatenableEvents is set toTrue, or thatenableEvents is a list that contains this event type.This prop is updated when the user releases from dragging the canvas. This containsthe picking info describing the object being dragged.Complete description here:https://deck.gl/docs/developer-guide/interactivity#the-picking-info-object