Extension Modules API¶

VoronoiMap ships with 16 extension modules beyond the core vormap module. Each adds specialized spatial analysis, visualization, or export capability.

Visualization — `vormap_viz`¶

The primary visualization module. Computes Voronoi regions and exports to SVG, HTML, GeoJSON, and statistics formats.

`compute_regions(data)`¶

Compute Voronoi region polygons for all seed points. Uses SciPy when available, otherwise falls back to a manual tracing algorithm.

from vormap import load_data
from vormap_viz import compute_regions

data = load_data("mypoints.txt")
regions = compute_regions(data)
# regions[i] = list of (x, y) vertices for the i-th seed

Returns: list[list[tuple]] — One polygon (vertex list) per seed.

`export_svg(regions, data, output_path, ...)`¶

Export Voronoi regions as an SVG file with customizable color schemes.

export_svg(regions, data, "output.svg", color_scheme="viridis", width=1000, height=800)

`export_html(regions, data, output_path, ...)`¶

Export an interactive HTML visualization with tooltips and region highlighting.

`export_geojson(regions, data, output_path, ...)`¶

Export Voronoi regions as a GeoJSON FeatureCollection — useful for integration with Leaflet, Mapbox, or QGIS.

`compute_region_stats(regions, data)`¶

Compute per-region statistics: area, perimeter, vertex count, isoperimetric quotient, centroid coordinates.

stats = compute_region_stats(regions, data)
for s in stats:
    print(f"Region {s['index']}: area={s['area']:.1f}, vertices={s['vertices']}")

`compute_summary_stats(region_stats)`¶

Aggregate summary (mean, median, std, min, max) over all region statistics.

`lloyd_relaxation(data, iterations=10, *, bounds=None, callback=None)`¶

Apply Lloyd relaxation to make Voronoi regions more uniform. Iteratively replaces each seed with its region's centroid.

relaxed = lloyd_relaxation(data, iterations=20)

Convenience Functions¶

Function	Description
`generate_diagram(datafile, output_path, ...)`	Load → compute → export SVG
`generate_geojson(datafile, output_path, ...)`	Load → compute → export GeoJSON
`generate_stats(datafile, output_path, ...)`	Load → compute → export stats
`generate_relaxed_diagram(datafile, output_path, iterations, ...)`	Load → relax → export
`export_relaxation_html(data, iterations, output_path, ...)`	Animated relaxation HTML
`format_stats_table(region_stats, ...)`	Human-readable stats table
`export_stats_csv(region_stats, output_path, ...)`	CSV export
`export_stats_json(region_stats, output_path, ...)`	JSON export
`list_color_schemes()`	List available color scheme names

Spatial Clustering — `vormap_cluster`¶

Cluster Voronoi cells by adjacency and spatial metrics.

`cluster_regions(region_stats, regions, data, *, method="threshold", metric="area", ...)`¶

Cluster Voronoi cells using spatial adjacency and cell metrics.

from vormap_cluster import cluster_regions

result = cluster_regions(stats, regions, data, method="dbscan", metric="area", eps=50.0)
print(f"{result.num_clusters} clusters found")

Parameters:

Parameter	Type	Default	Description
`method`	`str`	`"threshold"`	Clustering algorithm: `"threshold"`, `"dbscan"`, `"agglomerative"`
`metric`	`str`	`"area"`	Metric to cluster on: `"area"`, `"perimeter"`, `"iq"`, `"vertices"`
`eps`	`float`	—	DBSCAN epsilon / agglomerative distance threshold
`min_cluster_size`	`int`	`2`	Minimum regions per cluster

`generate_clusters(datafile, output_path=None, *, ...)`¶

One-call convenience: load data, cluster, optionally export.

Export Functions¶

Function	Description
`export_cluster_json(result, output_path)`	JSON export
`export_cluster_svg(result, regions, data, output_path, ...)`	SVG visualization
`format_cluster_table(result)`	Human-readable table

Spatial Queries — `vormap_query`¶

Build a spatial index over Voronoi seeds for efficient nearest-neighbor and point-in-region queries.

`VoronoiIndex` class¶

from vormap_query import VoronoiIndex

# VoronoiIndex is created via run_query_cli or by constructing with seeds/regions

Method	Description
`nearest(point)`	Return the nearest seed to point
`nearest_k(point, k)`	Return the k nearest seeds
`locate(point)`	Return the index of the Voronoi region containing point
`within_radius(point, radius)`	All seeds within radius of point
`distance_to_boundary(point)`	Minimum distance to nearest region boundary
`batch_query(points)`	Nearest-seed query for each point
`batch_locate(points)`	Locate each point's containing region

`query_stats(results)`¶

Compute statistics over a batch of query results (distances, region distribution).

`coverage_analysis(points, index)`¶

Analyse how many query points fall in each Voronoi region — useful for understanding spatial coverage and identifying underserved areas.

Export Functions¶

Function	Description
`export_query_json(results, path)`	JSON export
`export_query_svg(seeds, queries, results, path, ...)`	SVG visualization

Heatmaps — `vormap_heatmap`¶

Density heatmap generation for Voronoi diagrams.

`export_heatmap_svg(regions, data, output_path, ...)`¶

Export a density heatmap SVG colored by a region metric (area, vertex count, isoperimetric quotient, or perimeter).

from vormap_heatmap import export_heatmap_svg

export_heatmap_svg(regions, data, "heatmap.svg", metric="area", ramp="viridis")

`export_heatmap_html(regions, data, output_path, ...)`¶

Export an interactive HTML heatmap with tooltips and color-ramp switching.

Outlier Detection — `vormap_outlier`¶

Detect spatial outliers in Voronoi region statistics using Z-score or IQR methods.

`detect_outliers(stats, metrics=None, method="zscore", threshold=None)`¶

from vormap_outlier import detect_outliers

result = detect_outliers(stats, metrics=["area", "iq"], method="iqr")
print(f"{result.outlier_count} outliers ({result.outlier_rate:.1%})")
print(result.format_report())

Parameters:

Parameter	Type	Default	Description
`metrics`	`list[str]`	all	Metrics to check: `"area"`, `"perimeter"`, `"iq"`, `"vertices"`
`method`	`str`	`"zscore"`	Detection method: `"zscore"` or `"iqr"`
`threshold`	`float`	varies	Z-score threshold (default 2.0) or IQR multiplier (default 1.5)

Export Functions¶

Function	Description
`export_outlier_json(result, path)`	JSON export
`export_outlier_svg(result, regions, data, path, ...)`	SVG with outliers highlighted
`export_outlier_csv(result, path)`	CSV export

Spatial Interpolation — `vormap_interp`¶

Interpolate scalar values associated with Voronoi seed points.

`nearest_interp(points, values, query)`¶

Return the value of the nearest seed point (piecewise constant).

`idw_interp(points, values, query, power=2.0, epsilon=1e-12)`¶

Inverse distance weighted interpolation.

from vormap_interp import idw_interp

result = idw_interp(
    points=[(0, 0), (10, 0), (5, 8)],
    values=[100, 200, 150],
    query=(5, 3),
    power=2.0
)

`natural_neighbor_interp(points, values, query, fallback_idw=True)`¶

Sibson natural neighbor interpolation using stolen area weights. Falls back to IDW if SciPy is unavailable.

`grid_interpolate(points, values, nx=50, ny=50, bounds=None, method="idw", power=2.0)`¶

Interpolate values over a regular grid. Supports "nearest", "idw", and "natural" methods.

Export Functions¶

Function	Description
`export_surface_svg(grid_result, output_path, ...)`	SVG surface heatmap
`export_surface_csv(grid_result, output_path)`	CSV grid export

Spatial Pattern Analysis — `vormap_pattern`¶

Statistical tests for spatial randomness, clustering, and dispersion.

`clark_evans_nni(points, bounds=None)`¶

Compute the Clark-Evans Nearest Neighbor Index. Values < 1 indicate clustering, > 1 indicate dispersion, ≈ 1 indicate spatial randomness.

`ripleys_k(points, radii=None, n_radii=20, bounds=None)`¶

Compute Ripley's K function and Besag's L function at multiple radii. L(r) − r > 0 indicates clustering at scale r.

`quadrat_analysis(points, rows=None, cols=None, bounds=None)`¶

Perform quadrat (grid cell) analysis using a chi-squared test for complete spatial randomness.

`mean_center(points)`¶

Compute the mean center (geographic centroid) of a point pattern.

`standard_distance(points)`¶

Compute the standard distance (spatial spread) of a point set.

`convex_hull_ratio(points, bounds=None)`¶

Ratio of convex hull area to bounding box area — measures point distribution compactness.

`analyze_pattern(points, bounds=None, ...)`¶

Run all pattern analyses and return a combined PatternSummary.

from vormap_pattern import analyze_pattern, format_pattern_report

summary = analyze_pattern(points)
print(format_pattern_report(summary))

Region Clipping — `vormap_clip`¶

Clip Voronoi regions to arbitrary convex boundary polygons.

Boundary Constructors¶

from vormap_clip import make_rectangle, make_circle, make_ellipse, make_regular_polygon

rect = make_rectangle(0, 0, 100, 100)
circle = make_circle(center=(50, 50), radius=40)
ellipse = make_ellipse(center=(50, 50), rx=40, ry=25)
hexagon = make_regular_polygon(center=(50, 50), radius=40, sides=6)

`clip_all_regions(regions, data, boundary, ...)`¶

Clip all Voronoi regions to a boundary polygon. Returns a ClipResult with clipped regions, area statistics, and boundary info.

`point_in_polygon(point, polygon)`¶

Ray-casting point-in-polygon test.

`load_boundary(filepath)`¶

Load boundary polygon from a text file (one x y per line).

Graph Coloring — `vormap_color`¶

Four-color map coloring using graph coloring algorithms.

`color_voronoi(data_or_file, algorithm="dsatur", num_colors=4, palette=None)`¶

One-call convenience: compute regions, extract adjacency graph, color it.

from vormap_color import color_voronoi

result = color_voronoi("mypoints.txt", num_colors=4, palette="pastel")

`greedy_color(graph, num_colors=4)`¶

Greedy graph coloring with random vertex ordering.

`dsatur_color(graph, num_colors=4)`¶

DSATUR algorithm — assigns colors based on saturation degree (number of distinct colors used by neighbors). Produces better results than greedy.

`validate_coloring(graph, coloring)`¶

Verify that no adjacent nodes share a color.

Diagram Comparison — `vormap_compare`¶

Compare two Voronoi diagrams for structural and geometric similarity.

`DiagramSnapshot`¶

from vormap_compare import DiagramSnapshot

snap_a = DiagramSnapshot.from_datafile("data1.txt")
snap_b = DiagramSnapshot.from_datafile("data2.txt")

`compare_diagrams(snap_a, snap_b, max_match_distance=None)`¶

Full comparison: seed matching, area deltas, topology differences, similarity score, and human-readable verdict.

result = compare_diagrams(snap_a, snap_b)
print(result.summary())

`match_seeds(seeds_a, seeds_b, max_distance=None)`¶

Greedy nearest-neighbor seed matching between two diagrams.

`compare_areas(stats_a, stats_b, mapping)`¶

Compare region areas between matched seeds — returns per-region deltas and aggregate statistics.

`compare_topology(regions_a, data_a, regions_b, data_b, mapping)`¶

Compare neighbourhood topology (adjacency graph) between two diagrams.

Edge Network — `vormap_edge`¶

Extract and analyze the primal edge network from Voronoi region boundaries.

`extract_edge_network(regions, *, tol=0.5)`¶

Extract unique edges (shared boundaries between adjacent regions).

`compute_edge_stats(network)`¶

Aggregate statistics: total edges, mean/median/std length, length distribution, degree statistics.

Export Functions¶

Function	Description
`export_edge_csv(network, output_path, ...)`	CSV edge list
`export_edge_json(network, output_path)`	JSON export
`export_edge_svg(network, output_path, ...)`	SVG visualization
`format_edge_stats(stats)`	Human-readable table

Neighborhood Graph — `vormap_graph`¶

Extract and analyze the dual (adjacency) graph from Voronoi regions.

`extract_neighborhood_graph(regions, data=None, *, tol=0.5)`¶

Build the adjacency graph — nodes are seed points, edges connect seeds whose Voronoi regions share a boundary.

`compute_graph_stats(graph)`¶

Compute degree distribution, clustering coefficient, diameter, and connected component statistics.

`generate_graph(datafile, output_path=None, *, fmt="table")`¶

One-call convenience: load → compute → export.

KML Export — `vormap_kml`¶

Export Voronoi regions as KML for Google Earth / Google Maps.

`export_kml(regions, data, output_path, ...)`¶

Export Voronoi regions as a KML file with region styling and metadata.

`generate_kml(datafile, output_path, ...)`¶

One-call convenience: load → compute → export KML.

Power Diagrams — `vormap_power`¶

Weighted Voronoi diagrams (also called power diagrams or Laguerre diagrams).

`assign_weights(seeds, method='uniform', *, value=1.0, ...)`¶

Generate a weight vector. Methods: "uniform", "random", "distance_based", "density_based", "custom".

`compute_power_diagram(seeds, weights, mode='power', bounds=None, resolution=200)`¶

Compute a weighted Voronoi diagram. Returns a PowerDiagramResult with per-cell areas, centroids, and statistics.

from vormap_power import assign_weights, compute_power_diagram

seeds = [(100, 200), (300, 400), (500, 100)]
weights = assign_weights(seeds, method='random')
result = compute_power_diagram(seeds, weights)
print(result.summary())

`weight_effect_analysis(seeds, weights, mode='power', ...)`¶

Compare weighted diagram against a uniform-weight baseline to quantify the effect of weights on region sizes.

Distance Modes¶

Mode	Formula	Description
`"power"`	d² − w	Standard power distance
`"multiplicative"`	d / w	Weight scales distance
`"additive"`	d − w	Weight offsets distance

Seed Generation — `vormap_seeds`¶

Generate seed point distributions for testing and experimentation.

Generators¶

Function	Description
`random_uniform(n, ...)`	Uniformly distributed random points
`grid(...)`	Regular rectangular grid
`hexagonal(...)`	Hexagonal (honeycomb) grid
`jittered_grid(...)`	Regular grid with random perturbation
`poisson_disk(...)`	Well-spaced points via Bridson's algorithm
`halton(n, ...)`	Low-discrepancy Halton sequence

All generators accept x_min, x_max, y_min, y_max bounds and an optional seed parameter for reproducibility.

from vormap_seeds import poisson_disk, save_seeds

points = poisson_disk(min_distance=20.0, seed=42)
save_seeds(points, "my_seeds.txt")

`save_seeds(points, filename, header=True)`¶

Save seed points to a text file compatible with vormap.py.

`load_seeds(filename)`¶

Load seed points from a text file.

Territory Analysis — `vormap_territory`¶

Analyze territorial properties of Voronoi diagrams: border regions, interior regions, size inequality, compactness metrics.

`analyze_territories(regions, data, bounds=None, boundary_tolerance=0.05)`¶

Run full territorial analysis.

from vormap_territory import analyze_territories, format_territory_report

analysis = analyze_territories(regions, data)
print(format_territory_report(analysis))

Returns a dict with:

Per-region metrics: area, perimeter, compactness, border/interior classification, shared border lengths
Aggregate metrics: Gini coefficient, mean compactness, border-to-interior ratio
Territory classification (fragmented, balanced, dominated)

Export Functions¶

Function	Description
`export_territory_json(analysis, output_path)`	JSON export
`export_territory_csv(analysis, output_path)`	CSV per-region metrics
`format_territory_report(analysis)`	Human-readable report

Extension Modules API¶

Visualization — vormap_viz¶

compute_regions(data)¶

export_svg(regions, data, output_path, ...)¶

export_html(regions, data, output_path, ...)¶

export_geojson(regions, data, output_path, ...)¶

compute_region_stats(regions, data)¶

compute_summary_stats(region_stats)¶

lloyd_relaxation(data, iterations=10, *, bounds=None, callback=None)¶

Convenience Functions¶

Spatial Clustering — vormap_cluster¶

cluster_regions(region_stats, regions, data, *, method="threshold", metric="area", ...)¶

generate_clusters(datafile, output_path=None, *, ...)¶

Export Functions¶

Spatial Queries — vormap_query¶

VoronoiIndex class¶

query_stats(results)¶

coverage_analysis(points, index)¶

Export Functions¶

Heatmaps — vormap_heatmap¶

export_heatmap_svg(regions, data, output_path, ...)¶

export_heatmap_html(regions, data, output_path, ...)¶

Outlier Detection — vormap_outlier¶

detect_outliers(stats, metrics=None, method="zscore", threshold=None)¶

Export Functions¶

Spatial Interpolation — vormap_interp¶

nearest_interp(points, values, query)¶

idw_interp(points, values, query, power=2.0, epsilon=1e-12)¶

natural_neighbor_interp(points, values, query, fallback_idw=True)¶

grid_interpolate(points, values, nx=50, ny=50, bounds=None, method="idw", power=2.0)¶

Export Functions¶

Spatial Pattern Analysis — vormap_pattern¶

clark_evans_nni(points, bounds=None)¶

ripleys_k(points, radii=None, n_radii=20, bounds=None)¶

quadrat_analysis(points, rows=None, cols=None, bounds=None)¶

mean_center(points)¶

standard_distance(points)¶

convex_hull_ratio(points, bounds=None)¶

analyze_pattern(points, bounds=None, ...)¶

Region Clipping — vormap_clip¶

Boundary Constructors¶

clip_all_regions(regions, data, boundary, ...)¶

point_in_polygon(point, polygon)¶

load_boundary(filepath)¶

Graph Coloring — vormap_color¶

color_voronoi(data_or_file, algorithm="dsatur", num_colors=4, palette=None)¶

greedy_color(graph, num_colors=4)¶

dsatur_color(graph, num_colors=4)¶

validate_coloring(graph, coloring)¶

Diagram Comparison — vormap_compare¶

DiagramSnapshot¶

compare_diagrams(snap_a, snap_b, max_match_distance=None)¶

match_seeds(seeds_a, seeds_b, max_distance=None)¶

compare_areas(stats_a, stats_b, mapping)¶

compare_topology(regions_a, data_a, regions_b, data_b, mapping)¶

Edge Network — vormap_edge¶

extract_edge_network(regions, *, tol=0.5)¶

compute_edge_stats(network)¶

Export Functions¶

Neighborhood Graph — vormap_graph¶

extract_neighborhood_graph(regions, data=None, *, tol=0.5)¶

compute_graph_stats(graph)¶

generate_graph(datafile, output_path=None, *, fmt="table")¶

KML Export — vormap_kml¶

export_kml(regions, data, output_path, ...)¶

generate_kml(datafile, output_path, ...)¶

Power Diagrams — vormap_power¶

assign_weights(seeds, method='uniform', *, value=1.0, ...)¶

compute_power_diagram(seeds, weights, mode='power', bounds=None, resolution=200)¶

weight_effect_analysis(seeds, weights, mode='power', ...)¶

Distance Modes¶

Seed Generation — vormap_seeds¶

Generators¶

save_seeds(points, filename, header=True)¶

load_seeds(filename)¶

Territory Analysis — vormap_territory¶

analyze_territories(regions, data, bounds=None, boundary_tolerance=0.05)¶

Export Functions¶

Visualization — `vormap_viz`¶

`compute_regions(data)`¶

`export_svg(regions, data, output_path, ...)`¶

`export_html(regions, data, output_path, ...)`¶

`export_geojson(regions, data, output_path, ...)`¶

`compute_region_stats(regions, data)`¶

`compute_summary_stats(region_stats)`¶

`lloyd_relaxation(data, iterations=10, *, bounds=None, callback=None)`¶

Spatial Clustering — `vormap_cluster`¶

`cluster_regions(region_stats, regions, data, *, method="threshold", metric="area", ...)`¶

`generate_clusters(datafile, output_path=None, *, ...)`¶

Spatial Queries — `vormap_query`¶

`VoronoiIndex` class¶

`query_stats(results)`¶

`coverage_analysis(points, index)`¶

Heatmaps — `vormap_heatmap`¶

`export_heatmap_svg(regions, data, output_path, ...)`¶

`export_heatmap_html(regions, data, output_path, ...)`¶

Outlier Detection — `vormap_outlier`¶

`detect_outliers(stats, metrics=None, method="zscore", threshold=None)`¶

Spatial Interpolation — `vormap_interp`¶

`nearest_interp(points, values, query)`¶

`idw_interp(points, values, query, power=2.0, epsilon=1e-12)`¶

`natural_neighbor_interp(points, values, query, fallback_idw=True)`¶

`grid_interpolate(points, values, nx=50, ny=50, bounds=None, method="idw", power=2.0)`¶

Spatial Pattern Analysis — `vormap_pattern`¶

`clark_evans_nni(points, bounds=None)`¶

`ripleys_k(points, radii=None, n_radii=20, bounds=None)`¶

`quadrat_analysis(points, rows=None, cols=None, bounds=None)`¶

`mean_center(points)`¶

`standard_distance(points)`¶

`convex_hull_ratio(points, bounds=None)`¶

`analyze_pattern(points, bounds=None, ...)`¶

Region Clipping — `vormap_clip`¶

`clip_all_regions(regions, data, boundary, ...)`¶

`point_in_polygon(point, polygon)`¶

`load_boundary(filepath)`¶

Graph Coloring — `vormap_color`¶

`color_voronoi(data_or_file, algorithm="dsatur", num_colors=4, palette=None)`¶

`greedy_color(graph, num_colors=4)`¶

`dsatur_color(graph, num_colors=4)`¶

`validate_coloring(graph, coloring)`¶

Diagram Comparison — `vormap_compare`¶

`DiagramSnapshot`¶

`compare_diagrams(snap_a, snap_b, max_match_distance=None)`¶

`match_seeds(seeds_a, seeds_b, max_distance=None)`¶

`compare_areas(stats_a, stats_b, mapping)`¶

`compare_topology(regions_a, data_a, regions_b, data_b, mapping)`¶

Edge Network — `vormap_edge`¶

`extract_edge_network(regions, *, tol=0.5)`¶

`compute_edge_stats(network)`¶

Neighborhood Graph — `vormap_graph`¶

`extract_neighborhood_graph(regions, data=None, *, tol=0.5)`¶

`compute_graph_stats(graph)`¶

`generate_graph(datafile, output_path=None, *, fmt="table")`¶

KML Export — `vormap_kml`¶

`export_kml(regions, data, output_path, ...)`¶

`generate_kml(datafile, output_path, ...)`¶

Power Diagrams — `vormap_power`¶

`assign_weights(seeds, method='uniform', *, value=1.0, ...)`¶

`compute_power_diagram(seeds, weights, mode='power', bounds=None, resolution=200)`¶

`weight_effect_analysis(seeds, weights, mode='power', ...)`¶

Seed Generation — `vormap_seeds`¶

`save_seeds(points, filename, header=True)`¶

`load_seeds(filename)`¶

Territory Analysis — `vormap_territory`¶

`analyze_territories(regions, data, bounds=None, boundary_tolerance=0.05)`¶