{"id":44608246,"url":"https://github.com/sauravbhattacharya001/voronoimap","last_synced_at":"2026-05-03T01:03:02.526Z","repository":{"id":76701997,"uuid":"68616804","full_name":"sauravbhattacharya001/VoronoiMap","owner":"sauravbhattacharya001","description":"Voronoi partitioning of a geometric 2 dimensional space.","archived":false,"fork":false,"pushed_at":"2026-04-10T06:04:42.000Z","size":3454,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-10T08:13:18.958Z","etag":null,"topics":["algorithm","computational-geometry","data-science","delaunay-triangulation","geojson","geospatial","gis","graph-theory","lloyd-relaxation","matplotlib","nearest-neighbor","python","scipy","spatial-analysis","tessellation","visualization","voronoi","voronoi-diagram"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sauravbhattacharya001.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2016-09-19T15:01:15.000Z","updated_at":"2026-04-10T05:32:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"1d500648-94d9-4b10-8c6d-004e46f2e5e3","html_url":"https://github.com/sauravbhattacharya001/VoronoiMap","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/sauravbhattacharya001/VoronoiMap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sauravbhattacharya001%2FVoronoiMap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sauravbhattacharya001%2FVoronoiMap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sauravbhattacharya001%2FVoronoiMap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sauravbhattacharya001%2FVoronoiMap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sauravbhattacharya001","download_url":"https://codeload.github.com/sauravbhattacharya001/VoronoiMap/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sauravbhattacharya001%2FVoronoiMap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31825515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"online","status_checked_at":"2026-04-15T02:00:06.175Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithm","computational-geometry","data-science","delaunay-triangulation","geojson","geospatial","gis","graph-theory","lloyd-relaxation","matplotlib","nearest-neighbor","python","scipy","spatial-analysis","tessellation","visualization","voronoi","voronoi-diagram"],"created_at":"2026-02-14T11:25:51.666Z","updated_at":"2026-05-03T01:03:02.500Z","avatar_url":"https://github.com/sauravbhattacharya001.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003e🗺️ VoronoiMap\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cstrong\u003eEstimate aggregate statistics of unknown point sets using Voronoi partitioning and nearest-neighbor oracles\u003c/strong\u003e\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://pypi.org/project/voronoimap/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/voronoimap?color=blue\u0026logo=pypi\u0026logoColor=white\" alt=\"PyPI\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://pepy.tech/project/voronoimap\"\u003e\u003cimg src=\"https://img.shields.io/pepy/dt/voronoimap?color=blue\u0026logo=pypi\u0026logoColor=white\" alt=\"PyPI Downloads\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sauravbhattacharya001/VoronoiMap/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/sauravbhattacharya001/VoronoiMap/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sauravbhattacharya001/VoronoiMap/actions/workflows/docker.yml\"\u003e\u003cimg src=\"https://github.com/sauravbhattacharya001/VoronoiMap/actions/workflows/docker.yml/badge.svg\" alt=\"Docker\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sauravbhattacharya001/VoronoiMap/actions/workflows/codeql.yml\"\u003e\u003cimg src=\"https://github.com/sauravbhattacharya001/VoronoiMap/actions/workflows/codeql.yml/badge.svg\" alt=\"CodeQL\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://codecov.io/gh/sauravbhattacharya001/VoronoiMap\"\u003e\u003cimg src=\"https://codecov.io/gh/sauravbhattacharya001/VoronoiMap/graph/badge.svg\" alt=\"codecov\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sauravbhattacharya001/VoronoiMap/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/sauravbhattacharya001/VoronoiMap?logo=github\u0026color=green\" alt=\"GitHub Release\"\u003e\u003c/a\u003e\n    \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/sauravbhattacharya001/VoronoiMap?color=blue\" alt=\"License\"\u003e\u003c/a\u003e\n    \u003cimg src=\"https://img.shields.io/badge/python-3.9%2B-3776ab?logo=python\u0026logoColor=white\" alt=\"Python 3.9+\"\u003e\n    \u003ca href=\"https://sauravbhattacharya001.github.io/VoronoiMap/\"\u003e\u003cimg src=\"https://img.shields.io/badge/demo-live-brightgreen?logo=github-pages\u0026logoColor=white\" alt=\"Live Demo\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sauravbhattacharya001/VoronoiMap/pkgs/container/voronoimap\"\u003e\u003cimg src=\"https://img.shields.io/badge/ghcr.io-container-blue?logo=docker\u0026logoColor=white\" alt=\"GHCR\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sauravbhattacharya001/VoronoiMap/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/sauravbhattacharya001/VoronoiMap?style=flat\u0026logo=github\" alt=\"Stars\"\u003e\u003c/a\u003e\n    \u003cimg src=\"https://img.shields.io/github/repo-size/sauravbhattacharya001/VoronoiMap\" alt=\"Repo size\"\u003e\n    \u003ca href=\"https://github.com/sauravbhattacharya001/VoronoiMap/commits/main\"\u003e\u003cimg src=\"https://img.shields.io/github/last-commit/sauravbhattacharya001/VoronoiMap\" alt=\"Last commit\"\u003e\u003c/a\u003e\n    \u003cimg src=\"https://img.shields.io/badge/maintained-yes-brightgreen\" alt=\"Maintained\"\u003e\n    \u003ca href=\"https://github.com/sauravbhattacharya001/VoronoiMap/network/dependents\"\u003e\u003cimg src=\"https://img.shields.io/librariesio/dependents/pypi/voronoimap\" alt=\"Dependents\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n---\n\n## 📖 Overview\n\nVoronoiMap implements the **EstimateSUM** algorithm — a method where a partially informed attacker estimates aggregate statistics of an unknown set of objects embedded in the Euclidean plane, using only a nearest-neighbor oracle and Voronoi partitioning.\n\nThe algorithm discovers data points by sampling random locations, queries a nearest-neighbor oracle, then constructs Voronoi regions around each discovered point. By computing the ratio of the total search area to individual cell areas, it produces a statistical estimate of the total object count.\n\n📄 **Research Paper:** *Estimating Aggregate Statistics of Unknown Point Sets Using Voronoi Partitioning and Nearest-Neighbor Oracles* (PDF originally hosted on Docdro — link no longer available)\n\n🌐 **Live Demo:** [Interactive Voronoi Visualization](https://sauravbhattacharya001.github.io/VoronoiMap/)\n\n## ✨ Features\n\n- **Voronoi Region Estimation** — Approximate Voronoi cells via binary search along perpendicular bisectors\n- **Adaptive Boundary Detection** — Auto-detect search space boundaries from data with configurable padding\n- **KDTree Acceleration** — O(log n) nearest-neighbor lookups when SciPy is installed (falls back to O(n) brute-force)\n- **Data Caching** — Files loaded once from disk and cached in memory for subsequent queries\n- **Robust Geometry** — Cross-product collinearity tests, relative tolerance parallel-line detection, convergence-bounded loops\n- **Security Hardened** — Path traversal protection, NaN/Inf rejection, malformed input handling\n- **SVG Export** — Static SVG visualization with 6 color schemes\n- **Interactive HTML Export** — Pan/zoom, hover tooltips, live color switching, dark/light theme toggle\n- **GeoJSON Export** — Standard FeatureCollection for GIS tools (QGIS, Mapbox, Leaflet, Google Earth, ArcGIS)\n- **CLI \u0026 API** — Full-featured command-line interface and importable Python API\n- **Region Statistics** — Per-region metrics (area, perimeter, centroid, compactness), aggregate summary, CSV/JSON export\n- **Density Heatmap** — Color Voronoi cells by density, area, compactness, or vertex count with 3 color ramps (hot/cold, viridis, plasma); SVG and interactive HTML export\n- **Lloyd Relaxation** — Iterative centroid smoothing for uniform tessellations with animated HTML visualization\n- **Neighbourhood Graph** — Delaunay dual adjacency extraction with 14 graph metrics, degree distribution, clustering coefficient\n\n\n## Module Catalog (133 Modules)\n\nVoronoiMap has grown into a comprehensive spatial analysis toolkit with **133 modules** spanning core algorithms, visualization, spatial statistics, simulation, planning, artistic rendering, and autonomous analysis. Every module is listed below by category.\n\n### Core\n\n| Module | Description |\n|--------|-------------|\n| `vormap` | Core algorithm: EstimateSUM, Voronoi construction, boundary detection, KDTree acceleration |\n| `vormap_viz` | SVG + interactive HTML visualization with color schemes and dark/light themes |\n| `vormap_geometry` | Computational geometry primitives: area, centroid, perimeter, intersection, clipping |\n| `vormap_seeds` | Seed point generators: grid, hexagonal, random, Poisson disk, clustered |\n| `vormap_generate` | Synthetic point pattern generator: 6 patterns, NNI stats, CLI |\n| `vormap_pipeline` | Pipeline runner: chain multiple analysis steps into automated workflows |\n| `vormap_utils` | Shared utility functions for VoronoiMap modules |\n| `vormap_benchmark` | Performance benchmark suite for VoronoiMap operations |\n| `vormap_profile` | Spatial data profiler: comprehensive dataset summary statistics |\n| `vormap_quality` | Spatial data quality assessment for Voronoi diagrams |\n\n### Visualization \u0026 Export\n\n| Module | Description |\n|--------|-------------|\n| `vormap_heatmap` | Density heatmap: color cells by density, area, compactness with 3 color ramps |\n| `vormap_color` | Map coloring: four-color theorem for conflict-free cell coloring |\n| `vormap_coloring` | Graph coloring algorithms for Voronoi diagrams |\n| `vormap_animate` | Animated HTML visualization of diagram evolution over time |\n| `vormap_mosaic` | Image mosaic filter: stained-glass and pixel-art effects |\n| `vormap_report` | Self-contained HTML analysis report with stats, histograms, region table |\n| `vormap_geojson` | GeoJSON export (RFC 7946) for GIS tools (QGIS, Mapbox, Leaflet, ArcGIS) |\n| `vormap_kml` | KML export for Google Earth visualization |\n| `vormap_gpx` | GPX import/export: load waypoints/tracks/routes, export points for GPS devices |\n| `vormap_ascii` | Terminal (ASCII/Unicode) rendering of Voronoi diagrams |\n| `vormap_label` | Automatic label placement for Voronoi diagrams |\n| `vormap_gallery` | Interactive HTML showcase of VoronoiMap art styles |\n| `vormap_playground` | Interactive HTML Voronoi playground generator |\n| `vormap_cvd` | Color-vision-deficiency (deuteranopia) simulation on SVG output |\n\n### Spatial Statistics\n\n| Module | Description |\n|--------|-------------|\n| `vormap_autocorr` | Spatial autocorrelation: Moran's I, Geary's C, local indicators (LISA) |\n| `vormap_hotspot` | Hotspot detection: Getis-Ord Gi* statistic, significance testing |\n| `vormap_pattern` | Point pattern analysis: Clark-Evans NNI, Ripley's K/L, quadrat analysis |\n| `vormap_nndist` | Nearest-neighbor distance analysis: distribution, expected vs observed |\n| `vormap_outlier` | Spatial outlier detection: z-score and IQR methods on cell metrics |\n| `vormap_trend` | Trend surface analysis: 1st/2nd/3rd order polynomial OLS fitting |\n| `vormap_variogram` | Semivariogram analysis: empirical variogram, model fitting, kriging support |\n| `vormap_kde` | Kernel density estimation: Gaussian KDE with Silverman/Scott bandwidth |\n| `vormap_regularity` | Voronoi entropy, Lewis's law, Aboav-Weaire law, regularity index |\n| `vormap_montecarlo` | Monte Carlo spatial simulation: CSR testing, confidence envelopes |\n| `vormap_crossval` | Leave-one-out cross-validation for spatial interpolation methods |\n| `vormap_regress` | Spatial regression analysis for Voronoi diagrams |\n| `vormap_fingerprint` | Spatial distribution fingerprinting: compact signatures for point patterns |\n| `vormap_centroid` | Spatial center analysis for Voronoi point datasets |\n| `vormap_zonal` | Zonal statistics for Voronoi tessellations |\n\n### Graph \u0026 Network\n\n| Module | Description |\n|--------|-------------|\n| `vormap_graph` | Neighbourhood graph: adjacency extraction, 14 structural metrics |\n| `vormap_network` | Delaunay network: MST, betweenness centrality, components, efficiency |\n| `vormap_edge` | Edge analysis: boundary lengths, shared edges, edge density |\n| `vormap_delaunay` | Delaunay triangulation quality analysis for Voronoi tessellations |\n\n### Shape \u0026 Geometry\n\n| Module | Description |\n|--------|-------------|\n| `vormap_shape` | Cell shape analysis: IPQ compactness, elongation, rectangularity, orientation |\n| `vormap_hull` | Convex hull and bounding geometry: area ratios, convexity metrics |\n| `vormap_clip` | Region clipping: clip Voronoi cells to arbitrary polygon boundaries |\n| `vormap_power` | Weighted (power) Voronoi diagrams: site weights affect cell sizes |\n| `vormap_relax` | Lloyd's relaxation: iterative centroid smoothing for uniform tessellations |\n| `vormap_stability` | Stability analysis: sensitivity to point perturbation |\n| `vormap_symmetry` | Voronoi symmetry analysis: detect rotational and reflective symmetry |\n| `vormap_buffer` | Buffer zone analysis for Voronoi point datasets |\n| `vormap_circlepack` | Voronoi circle packing: largest inscribed circles per cell |\n\n### Spatial Operations\n\n| Module | Description |\n|--------|-------------|\n| `vormap_interp` | Spatial interpolation: natural neighbor weights for smooth surfaces |\n| `vormap_mapalgebra` | Map algebra: spatial operations (add/multiply/reclassify) on cell layers |\n| `vormap_merge` | Region merger: merge adjacent cells by attribute similarity |\n| `vormap_contour` | Contour extraction: isolines, IDW interpolation, 4 colormaps |\n| `vormap_query` | Spatial queries: KD-tree nearest-neighbor, k-nearest, radius, point location |\n| `vormap_sample` | Spatial sampling: stratified, systematic, centroid, boundary, density-weighted |\n| `vormap_transect` | Transect profiler: cross-section analysis along lines through the diagram |\n| `vormap_compare` | Diagram comparison: seed displacement, area change, topology difference |\n| `vormap_smooth` | Spatial smoothing of attribute values across Voronoi cells |\n| `vormap_isochrone` | Isochrone (travel-time zone) generator for Voronoi networks |\n| `vormap_changedetect` | Spatial change detection for Voronoi point datasets |\n\n### Clustering \u0026 Classification\n\n| Module | Description |\n|--------|-------------|\n| `vormap_cluster` | Spatial clustering: threshold, DBSCAN, agglomerative methods |\n| `vormap_classify` | Data classification: equal interval, quantile, natural breaks (Jenks), std dev |\n\n### Simulation \u0026 Modeling\n\n| Module | Description |\n|--------|-------------|\n| `vormap_diffusion` | Spatial diffusion: heat equation, SIR epidemic, threshold cascade |\n| `vormap_automata` | Cellular automata: Game of Life, majority, forest fire, epidemic on irregular grids |\n| `vormap_gravity` | Gravity models: classic, Huff, Hansen, doubly-constrained spatial interaction |\n| `vormap_watershed` | Watershed \u0026 flow: flow direction, accumulation, basin delineation |\n| `vormap_erosion` | Terrain erosion simulation over Voronoi networks |\n| `vormap_crystal` | Voronoi crystal growth simulator: anisotropic nucleation \u0026 growth |\n| `vormap_ecosystem` | Autonomous spatial ecosystem simulator on Voronoi tessellations |\n| `vormap_contagion` | Contagion simulator: SIR epidemic spread with auto-quarantine |\n| `vormap_evolve` | Evolutionary point placement optimizer for Voronoi diagrams |\n| `vormap_swarm` | Autonomous particle swarm optimizer for Voronoi point layouts |\n| `vormap_morph` | Smooth animated interpolation between point configurations |\n| `vormap_noise` | Worley (cellular) noise generator |\n\n### Planning \u0026 Territory\n\n| Module | Description |\n|--------|-------------|\n| `vormap_territory` | Territorial analysis: dominance, border pressure, balance metrics |\n| `vormap_landscape` | Landscape ecology: FRAGSTATS-style patch/class/landscape metrics |\n| `vormap_access` | Spatial accessibility: travel time, service area coverage |\n| `vormap_coverage` | Coverage analysis: service gaps, overlap, optimal site placement |\n| `vormap_siting` | Facility siting: gap filling, demand-weighted, max-min distance placement |\n| `vormap_pathplan` | Path planning: obstacle-aware navigation using Voronoi edge roadmaps |\n| `vormap_fractal` | Fractal dimension analysis of boundary complexity |\n| `vormap_temporal` | Temporal dynamics: track diagram evolution over time series |\n| `vormap_compete` | Territorial competition: multi-agent strategy simulation |\n| `vormap_cartogram` | Voronoi cartogram: area-proportional region distortion |\n| `vormap_treemap` | Hierarchical data layout as Voronoi treemap |\n| `vormap_displacement` | Voronoi displacement \u0026 normal-map generator |\n| `vormap_privacy` | Spatial privacy engine: differential privacy \u0026 k-anonymity for point data |\n\n### Agentic \u0026 Autonomous\n\n| Module | Description |\n|--------|-------------|\n| `vormap_sentinel` | Distribution monitoring: drift detection, anomaly alerting, baseline comparison |\n| `vormap_forecast` | Point pattern forecasting: density trends, hotspot emergence, void prediction |\n| `vormap_strategist` | Autonomous strategy planner: coverage, balance, spread, frontier advisors |\n| `vormap_doctor` | Spatial diagnostician: 12 checks, health scoring, auto-fix prescriptions |\n| `vormap_narrative` | Prose narrative generator: automatic story about spatial structure |\n| `vormap_recommend` | Analysis recommender: inspect data and suggest best tools |\n| `vormap_patrol` | Patrol planner: threat-weighted routes, coverage analysis, shift scheduling |\n| `vormap_dispatch` | Dispatch optimizer: demand assignment, overload detection, auto-rebalancing |\n| `vormap_balance` | Load balancer: Gini/entropy equity metrics, iterative rebalancing |\n| `vormap_resilience` | Resilience analyzer: failure simulation, critical point detection, cascade analysis |\n| `vormap_radar` | Autonomous spatial radar system for Voronoi point datasets |\n| `vormap_referee` | Autonomous spatial fairness referee |\n| `vormap_dream` | Autonomous spatial dreamer: generate synthetic distributions from learned patterns |\n| `vormap_terraform` | Autonomous terrain sculptor |\n| `vormap_architect` | Autonomous spatial layout architect |\n| `vormap_causality` | Spatial causality engine: counterfactual analysis for Voronoi interventions |\n| `vormap_equilibrium` | Spatial equilibrium engine: force field analysis and stability classification |\n| `vormap_forensics` | Spatial forensics: distribution provenance analysis and anomaly attribution |\n| `vormap_guardian` | Autonomous spatial guardian: integrity monitoring and constraint enforcement |\n| `vormap_negotiator` | Autonomous spatial negotiator: multi-objective territory resolution |\n\n### Artistic Rendering\n\n| Module | Description |\n|--------|-------------|\n| `vormap_stainedglass` | Stained-glass renderer |\n| `vormap_watercolor` | Watercolour painter |\n| `vormap_stipple` | Voronoi stippling: image-to-dot-art using weighted tessellation |\n| `vormap_lowpoly` | Low-poly image renderer |\n| `vormap_pixelart` | Pixel-art generator |\n| `vormap_halftone` | Halftone renderer |\n| `vormap_hatch` | Hatch pattern generator: pen-plotter / engraving style output |\n| `vormap_crossstitch` | Cross-stitch pattern generator |\n| `vormap_stringart` | String art generator |\n| `vormap_emboss` | Emboss / relief renderer |\n| `vormap_gradient` | Gradient-fill renderer |\n| `vormap_photomosaic` | Photo-mosaic renderer |\n| `vormap_text` | Voronoi typography: render text as cell mosaics |\n| `vormap_texture` | Seamless tileable texture generator |\n| `vormap_tile` | Seamless tileable Voronoi pattern generator |\n| `vormap_spiral` | Spiral pattern generator |\n| `vormap_kaleidoscope` | Kaleidoscope generator |\n| `vormap_penrose` | Penrose tiling generator |\n| `vormap_fracture` | Fracture simulator: realistic material fracture patterns |\n| `vormap_jigsaw` | Jigsaw puzzle generator: split images into puzzle pieces |\n| `vormap_flowfield` | Flow-field visualiser: vector fields \u0026 streamlines over diagrams |\n| `vormap_maze` | Voronoi-based maze generator |\n| `vormap_mesh3d` | 3D mesh exporter: extrude Voronoi cells into 3D geometry |\n| `vormap_voronoi3d` | 3D Voronoi tessellation visualizer |\n\n\n## 🔧 Installation\n\n### From PyPI (Recommended)\n\n```bash\n# Install the base package\npip install voronoimap\n\n# Install with fast KDTree-accelerated nearest-neighbor lookups\npip install voronoimap[fast]\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/sauravbhattacharya001/VoronoiMap.git\ncd VoronoiMap\n\n# Install in editable mode with dev dependencies\npip install -e \".[dev]\"\n```\n\n**Dependencies:**\n\n| Package | Required | Purpose |\n|---------|----------|---------|\n| Python 3.9+ | ✅ | Runtime |\n| NumPy ≥ 1.20 | Optional | Array operations for KDTree |\n| SciPy ≥ 1.7 | Optional | KDTree for fast NN lookups |\n| pytest ≥ 7.0 | Dev only | Test runner |\n\n## 🚀 Quick Start\n\n### Data Format\n\nPlace data files in a `data/` directory. Each file contains one point per line with space-separated longitude and latitude:\n\n```\n100.5 200.3\n450.2 750.1\n800.0 500.0\n```\n\n### Command Line\n\n```bash\n# After pip install:\nvoronoimap datauni5.txt 5\n\n# Multiple independent runs for better accuracy\nvoronoimap datauni5.txt 5 --runs 3\n\n# Custom search space boundaries (south north west east)\nvoronoimap datauni5.txt 5 --bounds 0 500 0 1000\n\n# Or run directly from source:\npython vormap.py datauni5.txt 5\n\n# Generate static SVG visualization\nvoronoimap datauni5.txt 5 --visualize diagram.svg --color-scheme rainbow\n\n# Generate interactive HTML visualization (pan/zoom, tooltips, theme toggle)\nvoronoimap datauni5.txt 5 --interactive diagram.html\n\n# Export as GeoJSON for GIS tools (QGIS, Mapbox, Leaflet, etc.)\nvoronoimap datauni5.txt 5 --geojson voronoi.geojson\n\n# GeoJSON without seed points (polygons only)\nvoronoimap datauni5.txt 5 --geojson voronoi.geojson --no-seeds\n\n# GeoJSON with explicit CRS\nvoronoimap datauni5.txt 5 --geojson voronoi.geojson --crs \"urn:ogc:def:crs:EPSG::4326\"\n\n# Compute per-region statistics (area, perimeter, centroid, compactness)\nvoronoimap datauni5.txt 5 --stats\n\n# Export statistics as CSV or JSON\nvoronoimap datauni5.txt 5 --stats-csv stats.csv\nvoronoimap datauni5.txt 5 --stats-json stats.json\n\n# Lloyd relaxation — smooth Voronoi regions toward uniformity\nvoronoimap datauni5.txt 5 --relax 10\n\n# Animated relaxation visualization (play/pause, step slider, convergence graph)\nvoronoimap datauni5.txt 5 --relax-animate relaxation.html\n\n# Neighbourhood graph analysis\nvoronoimap datauni5.txt 5 --graph\n\n# Export graph as JSON, CSV, or SVG overlay\nvoronoimap datauni5.txt 5 --graph-json graph.json\nvoronoimap datauni5.txt 5 --graph-csv graph.csv\nvoronoimap datauni5.txt 5 --graph-svg graph.svg --graph-labels\n```\n\n### Python API\n\n```python\nfrom vormap import get_sum, find_area, get_NN, load_data, set_bounds\n\n# Estimate the number of objects in a dataset\nestimated_count, max_edges, avg_edges = get_sum(\"datauni5.txt\", 5)\nprint(f\"Estimated {estimated_count} objects\")\n\n# Load data for direct function calls\ndata = load_data(\"datauni5.txt\")\n\n# Find area of a single Voronoi region\narea, num_vertices = find_area(data, 100.5, 200.3)\nprint(f\"Region area: {area}, vertices: {num_vertices}\")\n\n# Query nearest neighbor\nnearest_lng, nearest_lat = get_NN(data, 500.0, 500.0)\n\n# Manually set search bounds\nset_bounds(south=0, north=500, west=0, east=1000)\n```\n\n### Visualization\n\n```python\nimport vormap\nimport vormap_viz\n\n# Load data and compute regions\ndata = vormap.load_data(\"datauni5.txt\")\nregions = vormap_viz.compute_regions(data)\n\n# Static SVG export\nvormap_viz.export_svg(regions, data, \"diagram.svg\", color_scheme=\"rainbow\")\n\n# Interactive HTML export (pan/zoom, hover tooltips, color switching, dark mode)\nvormap_viz.export_html(regions, data, \"diagram.html\", title=\"My Voronoi Diagram\")\n\n# GeoJSON export for GIS tools\nvormap_viz.export_geojson(regions, data, \"voronoi.geojson\")\n\n# GeoJSON without seed points, with custom CRS\nvormap_viz.export_geojson(regions, data, \"voronoi.geojson\",\n                          include_seeds=False,\n                          crs_name=\"urn:ogc:def:crs:EPSG::4326\")\n\n# One-call GeoJSON generation\nvormap_viz.generate_geojson(\"datauni5.txt\", \"quick.geojson\")\n\n# One-call SVG generation\nvormap_viz.generate_diagram(\"datauni5.txt\", \"quick.svg\")\n```\n\n### Region Statistics\n\n### Density Heatmap\n\nColor Voronoi cells by spatial metrics to visualize clustering and uniformity:\n\n```bash\n# SVG heatmap colored by point density (inverse area)\nvoronoimap datauni5.txt 5 --heatmap heatmap.svg\n\n# Interactive HTML with metric/ramp switching and hover tooltips\nvoronoimap datauni5.txt 5 --heatmap-html heatmap.html\n\n# Color by compactness instead of density\nvoronoimap datauni5.txt 5 --heatmap heatmap.svg --heatmap-metric compactness\n\n# Use viridis color ramp and show values in cells\nvoronoimap datauni5.txt 5 --heatmap heatmap.svg --heatmap-ramp viridis --heatmap-values\n```\n\n**Available metrics:** `density` (default — inverse area, hot = clustered), `area`, `compactness` (isoperimetric quotient), `vertices`\n\n**Available color ramps:** `hot_cold` (default — blue → white → red), `viridis`, `plasma`\n\n```python\n# Python API\nimport vormap, vormap_viz, vormap_heatmap\n\ndata = vormap.load_data(\"datauni5.txt\")\nregions = vormap_viz.compute_regions(data)\nvormap_heatmap.export_heatmap_svg(regions, data, \"heatmap.svg\", metric=\"density\")\nvormap_heatmap.export_heatmap_html(regions, data, \"heatmap.html\")\n```\n\n```python\nimport vormap\nimport vormap_viz\n\ndata = vormap.load_data(\"datauni5.txt\")\nregions = vormap_viz.compute_regions(data)\n\n# Per-region metrics: area, perimeter, centroid, compactness, vertex count\nregion_stats = vormap_viz.compute_region_stats(regions, data)\nfor stat in region_stats:\n    print(f\"Seed ({stat['seed_x']:.1f}, {stat['seed_y']:.1f}): \"\n          f\"area={stat['area']:.2f}, compactness={stat['compactness']:.3f}\")\n\n# Aggregate summary (mean/median/min/max/std area, coefficient of variation)\nsummary = vormap_viz.compute_summary_stats(region_stats)\nprint(f\"Mean area: {summary['mean_area']:.2f}, CV: {summary['cv']:.3f}\")\n\n# Export as CSV, JSON, or formatted table\nvormap_viz.export_stats_csv(region_stats, \"stats.csv\")\nvormap_viz.export_stats_json(region_stats, \"stats.json\")\nprint(vormap_viz.format_stats_table(region_stats))\n\n# One-call convenience\nvormap_viz.generate_stats(\"datauni5.txt\", \"stats.csv\", fmt=\"csv\")\n```\n\n### Lloyd Relaxation\n\n```python\nimport vormap\nimport vormap_viz\n\ndata = vormap.load_data(\"datauni5.txt\")\n\n# Iterative centroid-based smoothing (Lloyd's algorithm)\n# Moves seeds toward region centroids for more uniform tessellations\nresult = vormap_viz.lloyd_relaxation(data, iterations=10)\nprint(f\"Converged: {result['converged']}, final movement: {result['movements'][-1]:.6f}\")\n\n# Access full history of seed positions at each iteration\nfor i, step in enumerate(result['history']):\n    print(f\"Iteration {i}: max_movement={result['movements'][i]:.6f}\")\n\n# One-call: generate relaxed SVG diagram\nvormap_viz.generate_relaxed_diagram(\"datauni5.txt\", \"relaxed.svg\", iterations=15)\n\n# Animated HTML visualization with play/pause, speed control, step slider,\n# convergence graph, ghost dots, color schemes, keyboard shortcuts\nvormap_viz.export_relaxation_html(data, result, \"relaxation.html\")\n```\n\n### Neighbourhood Graph\n\n```python\nimport vormap\nimport vormap_viz\n\ndata = vormap.load_data(\"datauni5.txt\")\nregions = vormap_viz.compute_regions(data)\n\n# Extract adjacency graph (Delaunay dual via shared Voronoi edges)\ngraph = vormap_viz.extract_neighborhood_graph(regions, data)\n\n# 14 graph metrics: density, clustering coefficient, diameter, avg path length,\n# degree distribution, connected components, isolated/leaf nodes, etc.\nstats = vormap_viz.compute_graph_stats(graph)\nprint(f\"Density: {stats['density']:.3f}, Clustering: {stats['clustering_coefficient']:.3f}\")\nprint(f\"Components: {stats['num_components']}, Diameter: {stats['diameter']}\")\n\n# Export as JSON (nodes with degree/neighbors, edges with lengths, stats)\nvormap_viz.export_graph_json(graph, \"graph.json\")\n\n# Export as CSV edge list\nvormap_viz.export_graph_csv(graph, \"graph.csv\")\n\n# SVG overlay: Voronoi regions + red graph edges + node markers\nvormap_viz.export_graph_svg(regions, data, graph, \"graph.svg\", show_labels=True)\n\n# Formatted stats table with degree histogram\nprint(vormap_viz.format_graph_stats_table(graph))\n\n# One-call convenience\nvormap_viz.generate_graph(\"datauni5.txt\", \"graph.json\", fmt=\"json\")\n```\n\n## 📚 API Reference\n\n\u003e **Full API documentation:** See [docs/API.md](docs/API.md) for complete reference of all 133 modules and their functions.\n\n### Core Functions\n\n| Function | Signature | Description |\n|----------|-----------|-------------|\n| `get_sum` | `(filename, n) → (estimate, max_edges, avg_edges)` | Core estimation algorithm. Samples `n` random points, builds Voronoi cells, returns estimated total count. |\n| `load_data` | `(filename, auto_bounds=True) → [(lng, lat), ...]` | Load point data from `data/` directory. Caches results. Auto-detects search bounds. |\n| `find_area` | `(data, lng, lat) → (area, vertices)` | Compute the Voronoi region area around the nearest neighbor of the given coordinates. |\n| `get_NN` | `(data, lng, lat) → (lng, lat)` | Find nearest neighbor. Uses KDTree O(log n) if SciPy available, O(n) otherwise. |\n| `set_bounds` | `(south, north, west, east) → None` | Manually set the search space boundaries. |\n| `compute_bounds` | `(points, padding=0.1) → (s, n, w, e)` | Compute bounds from points with padding. |\n\n### Visualization Functions\n\n| Function | Signature | Description |\n|----------|-----------|-------------|\n| `compute_regions` | `(data) → {seed: [(x,y), ...]}` | Compute Voronoi region polygons for all seed points. Uses SciPy when available. |\n| `export_svg` | `(regions, data, path, **opts) → path` | Export static SVG with color schemes, labels, and custom dimensions. |\n| `export_html` | `(regions, data, path, **opts) → path` | Export interactive HTML with pan/zoom, hover tooltips, live color switching, and dark/light theme. |\n| `export_geojson` | `(regions, data, path, **opts) → path` | Export GeoJSON FeatureCollection for GIS tools (QGIS, Mapbox, Leaflet, Google Earth). |\n| `generate_diagram` | `(datafile, path, **opts) → path` | One-call convenience: load → compute → export SVG. |\n| `generate_geojson` | `(datafile, path, **opts) → path` | One-call convenience: load → compute → export GeoJSON. |\n| `list_color_schemes` | `() → [str, ...]` | List available color schemes (pastel, warm, cool, earth, mono, rainbow). |\n\n### Statistics Functions\n\n| Function | Signature | Description |\n|----------|-----------|-------------|\n| `compute_region_stats` | `(regions, data) → [dict, ...]` | Per-region metrics: area, perimeter, centroid, compactness (isoperimetric quotient), vertex count, avg edge length. |\n| `compute_summary_stats` | `(region_stats) → dict` | Aggregate summary: mean/median/min/max/std area, coefficient of variation, coverage ratio. |\n| `export_stats_csv` | `(region_stats, path, **opts) → None` | Export region statistics as CSV with optional summary section. |\n| `export_stats_json` | `(region_stats, path, **opts) → None` | Export region statistics as JSON with optional summary. |\n| `format_stats_table` | `(region_stats, **opts) → str` | Format statistics as a human-readable text table. |\n| `generate_stats` | `(datafile, path, **opts) → dict` | One-call convenience: load → compute → export stats (table/csv/json). |\n\n### Lloyd Relaxation Functions\n\n| Function | Signature | Description |\n|----------|-----------|-------------|\n| `lloyd_relaxation` | `(data, iterations, **opts) → dict` | Iterative centroid smoothing. Returns history, movements, convergence flag. Supports bounds clamping, early termination, callbacks. |\n| `generate_relaxed_diagram` | `(datafile, path, **opts) → path` | One-call: load → relax → export SVG of the relaxed diagram. |\n| `export_relaxation_html` | `(data, result, path, **opts) → path` | Animated HTML: play/pause, speed control, step slider, convergence graph, ghost dots, color schemes, dark/light theme, keyboard shortcuts. |\n\n### Neighbourhood Graph Functions\n\n| Function | Signature | Description |\n|----------|-----------|-------------|\n| `extract_neighborhood_graph` | `(regions, data, **opts) → dict` | Extract adjacency graph from Voronoi regions (Delaunay dual via shared edges). |\n| `compute_graph_stats` | `(graph) → dict` | 14 graph metrics: density, clustering coefficient, diameter, avg path length, degree distribution, connected components, isolated/leaf nodes. |\n| `export_graph_json` | `(graph, path, **opts) → None` | Export graph as JSON (nodes with degree/neighbors, edges with lengths, stats). |\n| `export_graph_csv` | `(graph, path) → None` | Export graph as CSV edge list with summary. |\n| `export_graph_svg` | `(regions, data, graph, path, **opts) → path` | SVG overlay: Voronoi regions + red graph edges + node markers + optional degree labels. |\n| `format_graph_stats_table` | `(graph) → str` | Formatted stats table with degree histogram. |\n| `generate_graph` | `(datafile, path, **opts) → dict` | One-call convenience: load → compute → export graph (table/json/csv). |\n\n### Geometry Helpers\n\n| Function | Description |\n|----------|-------------|\n| `mid_point(x1, y1, x2, y2)` | Midpoint of two points |\n| `perp_dir(x1, y1, x2, y2)` | Perpendicular slope to a line segment |\n| `collinear(x1, y1, x2, y2, x3, y3)` | Cross-product collinearity test |\n| `eudist(x1, y1, x2, y2)` | Euclidean distance |\n| `polygon_area(lngs, lats)` | Shoelace formula for polygon area |\n\n## ⚙️ Algorithm\n\n```\n┌─────────────────────────────────────────────────┐\n│  1. Sample random point (px, py) in bounds      │\n│  2. Query oracle: nearest neighbor → (nx, ny)   │\n│  3. Binary search along perpendicular bisectors  │\n│     to find Voronoi region boundary vertices     │\n│  4. Compute region area via Shoelace formula     │\n│  5. Estimate = total_area / cell_area            │\n│  6. Average over N samples                       │\n└─────────────────────────────────────────────────┘\n```\n\n**Key Parameters:**\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `IND_S / IND_N` | 0.0 / 1000.0 | South / North search bounds |\n| `IND_W / IND_E` | 0.0 / 2000.0 | West / East search bounds |\n| `BIN_PREC` | 1e-6 | Binary search convergence threshold |\n| `MAX_VERTICES` | 50 | Max vertices per Voronoi cell |\n| `MAX_RETRIES` | 50 | Max retry attempts for estimation |\n| `BIN_SEARCH_MAX_ITER` | 100 | Binary search iteration limit |\n\n## Project Structure\n\n```\nVoronoiMap/\n├── vormap.py                    # Core algorithm implementation\n├── vormap_viz.py                # SVG + interactive HTML visualization\n├── vormap_*.py (128 modules)    # Spatial analysis toolkit (see catalog above)\n├── tests/                       # Unit \u0026 integration tests\n├── requirements.txt             # Optional dependencies\n├── pyproject.toml               # Package configuration\n├── Dockerfile                   # Container build\n├── LICENSE                      # MIT License\n├── data/                        # Point data files\n├── docs/\n│   └── index.html               # Interactive demo (GitHub Pages)\n└── .github/\n    ├── copilot-instructions.md  # Copilot agent context\n    ├── copilot-setup-steps.yml  # Copilot agent setup\n    ├── dependabot.yml           # Dependency updates\n    └── workflows/\n        ├── ci.yml               # CI: lint + test + coverage\n        ├── codeql.yml           # Security analysis\n        ├── docker.yml           # Docker build \u0026 push\n        └── pages.yml            # GitHub Pages deployment\n```\n\n## 🧪 Testing\n\n```bash\n# Run all tests\npython -m pytest tests/ -v\n\n# Run with coverage\npython -m pytest tests/ -v --cov=vormap --cov-report=term-missing\n\n# Run only security tests\npython -m pytest tests/test_vormap.py -v -k \"PathTraversal or MalformedInput\"\n```\n\n## 🔒 Security\n\nVoronoiMap includes security hardening in its data loading pipeline:\n\n- **Path traversal protection** — Filenames are validated to prevent directory escape (`../`, absolute paths)\n- **Input sanitization** — NaN, Inf, and non-numeric coordinates are silently skipped\n- **Bounded iterations** — All loops have explicit iteration limits to prevent denial-of-service\n- **Convergence guards** — Binary search and vertex discovery have failsafes against infinite loops\n\n## ❓ Troubleshooting \u0026 FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eImportError: No module named 'vormap'\u003c/strong\u003e\u003c/summary\u003e\n\nMake sure you installed the package, not just cloned the repo:\n\n```bash\n# From PyPI\npip install voronoimap\n\n# From source (editable)\npip install -e .\n```\n\nIf using a virtual environment, ensure it's activated.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSlow performance on large datasets\u003c/strong\u003e\u003c/summary\u003e\n\nInstall SciPy for KDTree-accelerated nearest-neighbor lookups (O(log n) vs O(n)):\n\n```bash\npip install voronoimap[fast]\n```\n\nRun the built-in benchmark to verify the speedup:\n\n```bash\npython vormap_benchmark.py --sizes 100 500 1000\n```\n\nSee the [Benchmarking Guide](https://sauravbhattacharya001.github.io/VoronoiMap/guide/benchmarking/) for detailed performance tuning.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eget_sum() returns wildly inaccurate estimates\u003c/strong\u003e\u003c/summary\u003e\n\n- **Increase sample size `n`** — Small `n` values produce high-variance estimates\n- **Run multiple times** — Use `--runs 5` on the CLI to average results\n- **Check your data** — Ensure coordinates are reasonable (no NaN/Inf values, which are silently dropped)\n- **Check search bounds** — The auto-detected bounds might miss outlier points; see `vormap.py` padding parameter\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFileNotFoundError when loading data files\u003c/strong\u003e\u003c/summary\u003e\n\nVoronoiMap looks for data files inside a `data/` directory relative to the working directory. Either:\n\n1. Run from the project root where `data/` exists\n2. Use absolute paths\n3. Create a `data/` directory and place your files there\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow do I export results for use in GIS software?\u003c/strong\u003e\u003c/summary\u003e\n\n```python\nfrom vormap import load_data\nfrom vormap_viz import compute_regions\nfrom vormap_geojson import export_geojson\n\ndata = load_data(\"mydata.txt\")\nregions = compute_regions(data)\nexport_geojson(regions, data, \"output.geojson\")\n```\n\nThe GeoJSON output is compatible with QGIS, Mapbox, Leaflet, ArcGIS, and Google Earth.\n\nFor Google Earth specifically, use `vormap_kml`:\n\n```python\nfrom vormap_kml import export_kml\nexport_kml(regions, data, \"output.kml\")\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCan I use VoronoiMap with geographic (lat/lon) coordinates?\u003c/strong\u003e\u003c/summary\u003e\n\nVoronoiMap works in Euclidean 2D space. For small geographic areas (city-scale), lat/lon coordinates work reasonably well. For larger areas where Earth's curvature matters, project to a local coordinate system (e.g., UTM) first, then feed the projected coordinates to VoronoiMap.\n\u003c/details\u003e\n\n## 🤝 Contributing\n\nContributions are welcome! See the **[Contributing Guide](CONTRIBUTING.md)** for full details on setup, code style, testing, and submitting PRs.\n\n**Quick start:**\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/my-feature`)\n3. Make your changes with tests\n4. Run the test suite (`python -m pytest tests/ -v`)\n5. Commit and push (`git push origin feature/my-feature`)\n6. Open a Pull Request\n\n## 📝 Tech Stack\n\n- **Language:** Python 3.9+\n- **Algorithms:** Voronoi partitioning, binary search, nearest-neighbor oracle, Shoelace formula\n- **Performance:** SciPy KDTree for O(log n) lookups\n- **Testing:** pytest + pytest-cov + Codecov\n- **CI/CD:** GitHub Actions (lint, test, coverage, Pages deployment)\n\n## 🐳 Docker\n\nRun VoronoiMap without installing anything locally:\n\n```bash\n# Pull the latest image\ndocker pull ghcr.io/sauravbhattacharya001/voronoimap:latest\n\n# Run with a local data file mounted\ndocker run --rm -v \"$(pwd)/data:/app/data\" ghcr.io/sauravbhattacharya001/voronoimap datauni5.txt 5\n\n# Generate SVG output\ndocker run --rm -v \"$(pwd):/output\" ghcr.io/sauravbhattacharya001/voronoimap \\\n  datauni5.txt 5 --visualize /output/diagram.svg\n\n# Interactive HTML with all modules available\ndocker run --rm -v \"$(pwd):/output\" ghcr.io/sauravbhattacharya001/voronoimap \\\n  datauni5.txt 5 --interactive /output/diagram.html\n\n# Build locally\ndocker build -t voronoimap .\ndocker run --rm voronoimap --help\n```\n\n## 📄 License\n\nMIT — see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt with 🧮 by \u003ca href=\"https://github.com/sauravbhattacharya001\"\u003eSaurav Bhattacharya\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsauravbhattacharya001%2Fvoronoimap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsauravbhattacharya001%2Fvoronoimap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsauravbhattacharya001%2Fvoronoimap/lists"}