using DeckGL
# Sample data - any Tables.jl-compatible source works
data = (
lng = [-122.4, -122.5, -122.3, -122.45, -122.35],
lat = [37.8, 37.7, 37.9, 37.75, 37.85],
size = [100, 200, 150, 180, 120]
)
# Create a layer
layer = ScatterplotLayer(
data = data,
get_position = [:lng, :lat], # Reference columns by symbol
get_radius = :size, # Data-driven radius
get_fill_color = [255, 140, 0, 200], # RGBA color
radius_min_pixels = 4
)
# Create the deck
deck = Deck(
layer,
initial_view_state = ViewState(
longitude = -122.4,
latitude = 37.8,
zoom = 11
),
map_style = "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json"
)Getting Started
This guide will help you get up and running with DeckGL.jl.
Installation
DeckGL.jl can be installed from GitHub:
using Pkg
Pkg.add(url="https://github.com/RallypointOne/DeckGL.jl")Basic Concepts
DeckGL.jl has three main components:
- Layers - Define what data to visualize and how
- ViewState - Configure the camera (position, zoom, angle)
- Deck - Container that combines layers, view state, and the basemap
Your First Visualization
Let’s create a simple scatterplot over a basemap:
In a notebook or on this page a Deck displays itself. Elsewhere, open_html(deck) opens it in a browser and save_html(deck, "map.html") writes it to a file.
Basemaps
map_style is the URL of a MapLibre style, drawn underneath the layers. Carto publishes several that are free and need no API key:
| Style | URL |
|---|---|
| Positron (light) | https://basemaps.cartocdn.com/gl/positron-gl-style/style.json |
| Dark Matter | https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json |
| Voyager | https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json |
Appending -nolabels to the style name (positron-nolabels) drops the place labels, which is often what you want when the layer carries its own text.
Deck(
layer,
initial_view_state = ViewState(longitude = -122.4, latitude = 37.8, zoom = 11),
map_style = "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json"
)Leaving map_style out draws the layers on a blank background, which is what you want for non-geographic data — see OrthographicView on the Layers page.
Two things follow from a basemap being a separate map library underneath deck.gl:
- It always needs network access, for MapLibre itself and for the map tiles. This is true even with
bundle=:local, which only inlines deck.gl. - deck.gl owns the camera. The basemap follows it, so
initial_view_stateand the controller settings apply to both.
Data Input
DeckGL.jl works with any Tables.jl-compatible data source:
# NamedTuple of vectors
data = (x = [1, 2, 3], y = [4, 5, 6])
# DataFrame
using DataFrames
df = DataFrame(x = [1, 2, 3], y = [4, 5, 6])
# Vector of NamedTuples
rows = [(x=1, y=4), (x=2, y=5), (x=3, y=6)]Column References
Use Symbol to reference columns for data-driven properties:
layer = ScatterplotLayer(
data = data,
get_position = [:lng, :lat], # Two columns for position
get_radius = :size, # Column for radius
get_fill_color = [255, 0, 0, 200] # Static color
)How Data Reaches the Browser
You do not have to think about this, but it explains why some layers behave differently.
Most layers upload their accessors straight to the GPU, so a table is packed column-by-column into typed arrays and sent as deck.gl’s binary form. Nothing is allocated per row on either side, and for a million points the page is several times smaller and builds an order of magnitude faster than one row of JSON per record.
Two things follow from that:
Columns that cannot be packed — strings, or variable-length paths — are sent as a plain array and read by index instead.
get_text = :nameworks exactly as you would expect; it just takes a different route.Picking reports an index, not a row object, because there are no row objects. The
tooltipprop handles this for you by shipping the columns it needs separately:ScatterplotLayer(data = df, get_position = [:lng, :lat], tooltip = [:name, :magnitude])Setting
tooltipturns onpickableunless you say otherwise. Passtruefor every column.
Aggregation layers (HexagonLayer, GridLayer, HeatmapLayer, ContourLayer, ScreenGridLayer) bin their records before drawing and read each one through its accessor, so they cannot take binary attributes at all — deck.gl silently produces a single bin if you give them any. They are sent an index array instead, over the same packed columns. Picking one selects a bin, so tooltip = true shows the bin’s own aggregated values rather than a source row.
Color Specification
Colors are specified as RGB or RGBA arrays with values 0-255, a hex string, or any Colors.jl colorant once that package is loaded:
# RGB (alpha defaults to 255)
color = [255, 0, 0] # Red
# RGBA (with transparency)
color = [255, 0, 0, 128] # Semi-transparent red
# Hex string
color = "#ff0000"
color = "#ff000080" # with alpha
# Colors.jl, via a package extension
using Colors
color = colorant"tomato"For data-driven colors, reference a column:
get_fill_color = :color_columnViewState
The ViewState controls the camera:
ViewState(
longitude = -122.4, # Center longitude
latitude = 37.8, # Center latitude
zoom = 11, # Zoom level (0-20+)
pitch = 45, # Tilt angle (0-60 degrees)
bearing = 0 # Rotation (0-360 degrees)
)Display Options
Open in Browser
open_html(deck)Save as HTML File
save_html(deck, "visualization.html")Get HTML String
html_string = to_html(deck)Jupyter/VS Code
In notebook environments, Deck objects display automatically:
deck # Displays inline in notebookConvenience Functions
For quick visualizations, use the convenience functions. These are not exported — names like scatter, lines, text, hexbin and heatmap would collide with Plots.jl and Makie.jl — so call them qualified:
# Scatterplot
DeckGL.scatter(data, :lng, :lat, radius=:size, color=[255, 140, 0])
# Arcs
DeckGL.arcs(data, [:src_lng, :src_lat], [:dst_lng, :dst_lat])
# Hexagonal binning
DeckGL.hexbin(data, :lng, :lat, radius=1000)
# Heatmap
DeckGL.heatmap(data, :lng, :lat, weight=:value)The full set is scatter, arcs, lines, paths, polygons, text, hexbin, heatmap and geojson. Each returns a Deck you can display:
DeckGL.scatter(data, :lng, :lat) |> open_htmlIf you would rather use them unqualified, import them explicitly:
using DeckGL
using DeckGL: scatter, heatmapMultiple Layers
Combine multiple layers in a single visualization:
layers = [
ScatterplotLayer(data=points, get_position=[:lng, :lat]),
TextLayer(data=labels, get_position=[:lng, :lat], get_text=:name),
PathLayer(data=routes, get_path=:path)
]
deck = Deck(layers, initial_view_state=ViewState(zoom=10))Next Steps
- Layers - Explore all available layer types
- API Reference - Complete function and type documentation
- Examples - More visualization examples