DBSCAN Animator

Interactive DBSCAN visualization and animation in Jupyter Notebook.

English | 中文

This repository provides a Jupyter Notebook for interactive visualization and animation of the DBSCAN (Density-Based Spatial Clustering of Applications with Noise) algorithm. The notebook illustrates the algorithm step by step, including:

• Core point detection
• Connecting core points
• Formation of clusters

With ipywidgets interactive controls, users can adjust algorithm parameters in real time—such as the number of sample points, neighborhood radius, and minimum points—and immediately see how these changes affect the clustering results through dynamic animations.

Click the button below to view the animation:

---

Run Online (No Local Installation Required)

This project can be run entirely in your browser — no local installation required — and offers two options for online execution: Binder for interactive, code-free visualization, and Google Colab for full notebook editing and experimentation.

Binder - Voila Rendered

For viewers who just want to see and interact with the animations without seeing code or Markdown:

Binder - Original Notebook

Beyond the Voila-rendered version,there is a fully interactive notebook environment available.

Click here to view, run, and edit all code and Markdown cells within a temporary, interactive environment:

Google Colab

The Google Colab version provides a full-featured online Notebook environment.

You can run and modify code directly in your browser, and save any changes to your Google Drive:

---

Local Run

Environment & Dependencies

To run this project locally, make sure your environment has the following Python packages installed (see requirements.txt for specific versions):

• numpy
• matplotlib
• networkx
• shapely
• ipywidgets

Installation Guide

Click to view installation steps

1. Create a virtual environment (optional but recommended):

   python -m venv .venv
   source .venv/bin/activate   # Windows: .venv\Scripts\activate

2. Install dependencies:

   pip install -r requirements.txt

Run the Notebook

1. Edit the notebook: Open dbscan_animator.ipynb in the src directory and run the cells in order. Adjust parameters via the control panel, then click Run Interact to start the animation.

2. Display with Voila locally: The source notebook contains Markdown cells and outputs that may affect its appearance when served with Voila. It is recommended to create a cleaned copy with Markdown cells removed and outputs cleared beforing serving it with Voila:

jq '(.cells |= map(select(.cell_type != "markdown") | .outputs = [] | .execution_count = null))' \
  src/dbscan_animator.ipynb > build/dbscan_animator_for_display.ipynb

Then run:

voila build/dbscan_animator_for_display.ipynb

Open http://localhost:8866 to view the demo.

---

Implementation

• Core DBSCAN Functions: Implements main DBSCAN logic with find_core_points, build_core_graph, and find_reachable_and_noise.
• Visualization Tools: Functions for plotting points, core circles, connections, and cluster polygons.
• Animations: radar_animation for neighborhood scanning and core_connection_animation to visualize cluster connections.
• Workflow: dbscan_workflow handles the UI and coordinates the step-by-step animation.

---

Contributing

Feel free to open Issues or Pull Requests! Please follow the repository's license and contribution guidelines.

License

MIT License — see the LICENSE file for details.