Metadata-Version: 2.4
Name: dash_sylvereye
Version: 0.4.0
Summary: Dash Sylvereye is a Plotly Dash component library for producing interactive web-based visualizations of large primal road networks in Python.
Author-email: Alberto Garcia-Robledo <alberto.garob@gmail.com>
License: MIT License
        
        Copyright (c) 2021 Centro de Investigación en Ciencias de Información Geoespacial, A.C.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://dashsylvereye.observatoriogeo.mx
Project-URL: Documentation, https://dashsylvereye.observatoriogeo.mx
Project-URL: Source, https://github.com/observatoriogeo/dash-sylvereye
Project-URL: Issues, https://github.com/observatoriogeo/dash-sylvereye/issues
Project-URL: Changelog, https://github.com/observatoriogeo/dash-sylvereye/releases
Keywords: dash,plotly,visualization,road network,street network,graph,osmnx,openstreetmap,leaflet,pixi,webgl,geospatial,gis
Classifier: Framework :: Dash
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dash>=4.0.0
Requires-Dist: memoization>=0.4.0
Provides-Extra: dev
Requires-Dist: dash[dev]>=4.0.0; extra == "dev"
Provides-Extra: examples
Requires-Dist: osmnx>=2.0; extra == "examples"
Requires-Dist: numpy; extra == "examples"
Provides-Extra: sumolib
Requires-Dist: sumolib>=1.0; extra == "sumolib"
Provides-Extra: test
Requires-Dist: osmnx>=2.0; extra == "test"
Requires-Dist: numpy; extra == "test"
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: selenium>=4.20; extra == "test"
Requires-Dist: pillow; extra == "test"
Dynamic: license-file

<p align="center">
  <img src="https://cdn.jsdelivr.net/gh/observatoriogeo/dash-sylvereye@main/website_logo_solid_background.png" width="375" height="275" title="Logo">
</p>

**Dash Sylvereye** is a [Plotly Dash](https://plotly.com/dash) component library for producing interactive web-based visualizations of large primal road networks in Python.

The main elements of a Dash Sylvereye visualization are nodes, edges, and markers. Edges can have direction arrows, too. All of these elements are drawn through WebGL on top of tiled web maps.

The goal of Dash Sylvereye is to allow users to smoothly render interactive road networks with dozens of thousands of nodes and edges, as well as dozens of thousands of interactive markers, in commodity systems such as mid-range laptops and workstations.

Thanks to its integration with Dash, the various elements of a Dash Sylvereye visualization can be updated at runtime by other Dash components in a Dash dashboard.

Dash Sylvereye visualizations are customizable, allowing for the programmatic manipulation of colors, sizes, alpha, and visibility of individual nodes, edges, and markers.

Markers can show custom popup messages when hovered over and the default marker icon can be replaced by custom SVG images on a marker-by-marker basis.

Nodes, edges, and markers are interactive. Dash Sylvereye supports for various callback properties allowing the programmer to define the behavior when the individual elements of a visualization are clicked.

## Features

* WebGL-accelerated drawing of nodes and edges allowing for a smooth navigation on road networks with dozens of thousands of nodes and edges on budget systems.
* WebGL-accelerated drawing of markers allowing for a smooth navigation on visualizations with dozens of thousands of markers on budget systems.
* Full integration with Plotly Dash: road network data and visual properties can be dinamically updated by reacting to other Dash components.
* Dash click events for individual nodes, edges, and markers.
* Support for any map tiles supported by Leaflet.js.
* Loading of road networks from NetworkX graphs produced by OSMnx.
* Loading of road networks from GraphML files produced by OSMnx.
* Simple list-of-dictionaries road network data format for easy loading of networks from any source.
* Customization of visibility, transparency, color, and size of individual nodes, edges, and markers.
* Automatic color scaling of nodes, edges, and markers via Chroma.js.
* Support for customizable markers via custom SVG files.
* Support for marker tooltips.

## Documentation

Dash Sylvereye's homepage and full documentation are at [dashsylvereye.observatoriogeo.mx](https://dashsylvereye.observatoriogeo.mx).

## Running the examples

The Python environment is managed with [uv](https://docs.astral.sh/uv/). Install uv first if you don't have it:

````
curl -LsSf https://astral.sh/uv/install.sh | sh
````

Then clone, sync the `examples` extras, and run an example:

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

Visit http://127.0.0.1:8050/ in your browser to see the visualization. The first example run downloads the road network for Kamppi (Helsinki) from OpenStreetMap and caches it to `examples/cache/kamppi.graphml`; subsequent runs are offline.

The other scripts under `examples/` demonstrate further features: `02_BasicInteractivity.py` (node and edge click callbacks), `03_BasicCustomization.py` (SCALE-mode color and width gradients), `04_AddingMarkers.py` (zoom-aware markers + click callbacks), and `05_CustomColors.py` (per-element CUSTOM colors and diameters).

## Build instructions

Building the JS bundle and regenerating the Python/R/Julia wrappers requires both Node and the `dev` Python extras:

````
git clone https://github.com/observatoriogeo/dash-sylvereye.git
cd dash-sylvereye
uv sync --extra dev          # provides dash-generate-components
npm install
uv run -- npm run build      # webpack bundle + dash-generate-components
````

## Running the integration tests

````
uv sync --extra test
uv run pytest tests/test_examples.py
````

The suite drives headless Chrome via Selenium (Selenium Manager auto-fetches a matching ChromeDriver), so Chrome must be installed.

## Citation

If you use Dash Sylvereye in your work, please cite the following article:

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, doi: [10.1109/ACCESS.2023.3327008](https://doi.org/10.1109/ACCESS.2023.3327008).
