dash-sylvereye 0.4.1

Dash Sylvereye is a Plotly Dash component library for producing interactive web-based visualizations of large primal road networks in Python.

WebGL-accelerated visualization of large primal road networks for Plotly Dash dashboards.

Tens of thousands of interactive nodes, edges, and markers, smoothly, in the browser. Tied into Dash callbacks: every visual property is reactive, every element is clickable. Loads networks straight from OpenStreetMap through OSMnx.

---

Dash Sylvereye is a Plotly Dash component library, developed at the Observatorio Metropolitano CentroGeo at CentroGeo, that renders interactive web-based visualizations of large primal road networks in Python. The geometry is drawn with WebGL on top of a tiled Leaflet map; every node, edge, and marker is independently styleable and clickable, and every visual property is wired through Dash's callback architecture so the visualization reacts to anything else in the dashboard at runtime.

It's aimed at:

• Mobility, transportation, and urban-data researchers who need to display real-world street networks (tens of thousands of segments) and overlay analytics on top.
• Dashboard developers who already build Plotly Dash apps and want a first-class road-network component, not a generic Plotly trace.
• Anyone working with OSMnx output who wants to render the resulting MultiDiGraph directly, without falling back to Matplotlib or a generic map widget.

Status

Current release: 0.4.1. Runs on Python 3.11+ and Dash 4.x. Distributed under the MIT license.

Surface	State
Source layout	dash_sylvereye/ (PEP 621, hatchling, uv.lock committed)
JS source	src/lib/ (React 18 + react-leaflet 4 + PIXI.js 7 + leaflet-pixi-overlay)
Tests	Selenium integration suite under tests/ (drives headless Chrome)
Docs	Live at dashsylvereye.observatoriogeo.mx (Docusaurus 3.10, source under website/)
Examples	5 runnable end-to-end scripts under examples/
Distribution	PyPI (also publishes R and Julia wrappers via dash-generate-components)

Release history: GitHub Releases.

What it does

A SylvereyeRoadNetwork component takes three flat lists, nodes_data, edges_data, markers_data, and renders them on top of a Leaflet tile layer through a WebGL overlay. Each element is independently controlled:

Element	Customizable visual properties	Click event
Node	color, size, alpha, visibility	clicked_node
Edge	color, width, alpha, visibility	clicked_edge
Marker	color, size, alpha, visibility, icon, tooltip	clicked_marker
Direction arrows	follow edge geometry, can be toggled globally	(not interactive)
Tile layer	URL, opacity, attribution, subdomains	(n/a)

Three methods per visual property:

• DEFAULT: one value applies to every element.
• SCALE: interpolate from a numeric data field on each element (color scales are computed client-side with chroma.js).
• CUSTOM: read the rendered value from each element's own dict.

Networks load from a NetworkX graph or a GraphML file produced by OSMnx in one line, or you can build the data lists by hand. SUMO .net.xml traffic-simulation networks are supported as an optional extra.

See the Overview page for the full feature tour.

Quickstart

A minimal Dash app rendering the road network of Kamppi (Helsinki) from OpenStreetMap:

import osmnx as ox
from dash import Dash, html
from dash_sylvereye import SylvereyeRoadNetwork
from dash_sylvereye.utils import load_from_osmnx_graph

road_network = ox.graph_from_place('Kamppi, Helsinki, Finland', network_type='drive')
nodes_data, edges_data = load_from_osmnx_graph(road_network)

app = Dash()
app.layout = html.Div([
    SylvereyeRoadNetwork(
        id='sylvereye-roadnet',
        nodes_data=nodes_data,
        edges_data=edges_data,
        tile_layer_url='https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png',
        tile_layer_subdomains='abcde',
        tile_layer_opacity=0.9,
        map_center=[60.1663, 24.9313],
        map_zoom=15,
        map_style={'width': '100%', 'height': '98vh'},
    ),
])

if __name__ == '__main__':
    app.run()

Walk-throughs of the click callbacks, scaled visuals, markers, and per-element customization live under Examples.

Install

pip install dash-sylvereye

If you use uv: uv add dash-sylvereye.

Optional extras:

Extra	What it pulls	When to use it
examples	osmnx>=2.0, numpy	To run the scripts under examples/.
sumolib	sumolib>=1.0	To use load_from_sumo_network for SUMO .net.xml networks.
dev	dash[dev]>=4.0.0	To regenerate the Python/R/Julia wrappers (dash-generate-components).
test	pytest, selenium, pillow, plus examples	To run the integration suite.

Install one with pip install dash-sylvereye[examples] or several with pip install dash-sylvereye[examples,sumolib].

Architecture

   Python (Dash callback graph)
              │
              ▼
   SylvereyeRoadNetwork component  (Dash → React → react-leaflet)
              │
              ▼
   Leaflet map (tile layer + zoom/pan)
              │
              ▼
   leaflet-pixi-overlay
              │
              ▼
   PIXI.js WebGL scene  (nodes, edges, markers, arrows)

A SylvereyeRoadNetwork JSX component wraps a <MapContainer> from react-leaflet with a leaflet-pixi-overlay instance underneath; nodes, edges, markers, and arrows are drawn into a PIXI.js container by hand-written sprite code. Spatial hit-testing for edge clicks uses RBush + JSTS; color scales use chroma.js. The whole React surface is transpiled by dash-generate-components into a Dash component, so the Python side ships only PropTypes and defaultProps definitions, no live React.

Full walk-through at Software stack.

Documentation

All documentation lives at dashsylvereye.observatoriogeo.mx. Highlights:

Section	Pointer
What is Dash Sylvereye?	/docs/overview
Installation	/docs/installation
Examples (5 walk-throughs)	/docs/example1
Component keyword arguments	/docs/component_parameters
Click events (clicked_* payloads)	/docs/click_events
Data format (nodes, edges, markers)	/docs/data_format
Loading networks (OSMnx / GraphML / SUMO)	/docs/data_loading
Per-element customization	/docs/nodes_customization · /docs/edges_customization · /docs/markers_customization
Citation	/docs/citation

Running the examples

git clone https://github.com/observatoriogeo/dash-sylvereye.git
cd dash-sylvereye
uv sync --extra examples
uv run python examples/01_BasicVisualization.py

Then open http://127.0.0.1:8050/ in your browser. The first run downloads the Kamppi road network from OpenStreetMap and caches it to examples/cache/kamppi.graphml; subsequent runs are offline.

The other scripts demonstrate further features:

• 02_BasicInteractivity.py: clicked_node and clicked_edge callbacks.
• 03_BasicCustomization.py: SCALE methods (color, size, width interpolated by a data field).
• 04_AddingMarkers.py: zoom-aware markers + clicked_marker.
• 05_CustomColors.py: CUSTOM methods (per-element colors and diameters from categorical attributes).

Development

uv is the project's package and environment manager. The full build needs both Node (≥18.18) and the dev Python extras (which provide dash-generate-components):

git clone https://github.com/observatoriogeo/dash-sylvereye.git
cd dash-sylvereye
uv sync --all-extras
npm install
uv run -- npm run build      # webpack bundle + Python/R/Julia wrapper regen

Run the integration tests (headless Chrome must be installed and on PATH; Selenium Manager auto-fetches a matching ChromeDriver):

uv run pytest tests/

Full development workflow, including the JS → Python regeneration loop and the validation gate, lives in CLAUDE.md.

Citation

If you use Dash Sylvereye in your research, please cite:

A. Garcia-Robledo and M. Zangiabady, "Dash Sylvereye: A Python Library for Dashboard-Driven Visualization of Large Street Networks," in IEEE Access, vol. 11, pp. 121142–121161, 2023. https://doi.org/10.1109/ACCESS.2023.3327008

BibTeX:

@article{garciarobledo2023sylvereye,
  author  = {Garcia-Robledo, Alberto and Zangiabady, Mahsa},
  title   = {Dash {S}ylvereye: A {P}ython Library for Dashboard-Driven Visualization of Large Street Networks},
  journal = {IEEE Access},
  volume  = {11},
  pages   = {121142--121161},
  year    = {2023},
  doi     = {10.1109/ACCESS.2023.3327008},
}

License

Dash Sylvereye is distributed under the MIT License. See LICENSE for the full text. Copyright © Centro de Investigación en Ciencias de Información Geoespacial, A.C.

Contact

• Bug reports and feature requests: GitHub Issues.
• Academic and collaboration enquiries: [e-mail].