geo-visualizer

Geo Visualizer

使用 Folium 根据地理数据创建交互式 HTML 地图。

功能

• 标记：使用自定义图标、弹出窗口和工具提示绘制点
• 热力图：可视化密度／强度数据
• 分级统计图：根据数据值为区域着色
• 路线／线条：绘制点与点之间的路径
• 圆形／区域：显示基于半径的覆盖范围
• 图层控制：切换多个图层
• 聚类：自动聚合密集的标记

快速开始

from geo_visualizer import GeoVisualizer

# Simple marker map
viz = GeoVisualizer()
viz.add_markers([
    {"lat": 40.7128, "lon": -74.0060, "name": "New York"},
    {"lat": 34.0522, "lon": -118.2437, "name": "Los Angeles"}
])
viz.save("cities.html")

# From CSV
viz = GeoVisualizer()
viz.from_csv("locations.csv", lat_col="latitude", lon_col="longitude")
viz.save("map.html")

CLI 用法

# Plot markers from CSV
python geo_visualizer.py --input locations.csv --lat latitude --lon longitude --output map.html

# Add heatmap
python geo_visualizer.py --input data.csv --lat lat --lon lng --heatmap --output heat.html

# With clustering
python geo_visualizer.py --input stores.csv --lat lat --lon lon --cluster --output stores.html

# Choropleth map
python geo_visualizer.py --geojson states.geojson --data stats.csv --key state --value population --output choropleth.html

API 参考

GeoVisualizer 类

class GeoVisualizer:
    def __init__(self, center=None, zoom=10, tiles="OpenStreetMap")

    # Data loading
    def from_csv(self, filepath, lat_col, lon_col, **kwargs) -> 'GeoVisualizer'
    def from_dataframe(self, df, lat_col, lon_col, **kwargs) -> 'GeoVisualizer'
    def from_geojson(self, filepath) -> 'GeoVisualizer'

    # Markers
    def add_marker(self, lat, lon, popup=None, tooltip=None, icon=None, color="blue")
    def add_markers(self, locations: list, name_col=None, popup_cols=None)
    def cluster_markers(self, enabled=True) -> 'GeoVisualizer'

    # Layers
    def add_heatmap(self, points=None, weight_col=None, radius=15) -> 'GeoVisualizer'
    def add_choropleth(self, geojson, data, key_on, value_col, **kwargs) -> 'GeoVisualizer'
    def add_route(self, points, color="blue", weight=3) -> 'GeoVisualizer'
    def add_circle(self, lat, lon, radius_m, color="blue", fill=True)

    # Output
    def save(self, filepath) -> str
    def get_html(self) -> str
    def fit_bounds(self) -> 'GeoVisualizer'

标记选项

# Custom icons
viz.add_marker(lat, lon, icon="fa-coffee", color="red")

# With popup content
viz.add_marker(lat, lon, popup="<b>Store #123</b><br>Open 9-5")

# From CSV with popup columns
viz.from_csv("stores.csv", lat_col="lat", lon_col="lon")
viz.add_markers(viz.data, popup_cols=["name", "address", "phone"])

热力图选项

# Basic heatmap
viz.add_heatmap()

# Weighted heatmap (e.g., by sales volume)
viz.add_heatmap(weight_col="sales", radius=20, blur=15, max_zoom=12)

分级统计地图

# Color regions by data
viz.add_choropleth(
    geojson="us-states.geojson",
    data=state_data,
    key_on="feature.properties.name",  # GeoJSON property
    value_col="population",
    fill_color="YlOrRd",  # Color scale
    legend_name="Population"
)

瓦片图层

可用的底图：

• OpenStreetMap（默认）
• CartoDB positron（浅色、简约）
• CartoDB dark_matter（深色主题）
• Stamen Terrain（地形要素）
• Stamen Toner（高对比度黑白）

viz = GeoVisualizer(tiles="CartoDB positron")

工作流示例

门店定位地图

viz = GeoVisualizer()
viz.from_csv("stores.csv", lat_col="lat", lon_col="lon")
viz.add_markers(viz.data, popup_cols=["name", "address", "hours"])
viz.cluster_markers(True)
viz.fit_bounds()
viz.save("store_locator.html")

销售热力图

viz = GeoVisualizer(tiles="CartoDB dark_matter")
viz.from_csv("sales.csv", lat_col="lat", lon_col="lon")
viz.add_heatmap(weight_col="revenue", radius=25)
viz.save("sales_heat.html")

配送路线

viz = GeoVisualizer()
stops = [(40.7, -74.0), (40.8, -73.9), (40.75, -73.95)]
viz.add_route(stops, color="blue", weight=4)
for i, (lat, lon) in enumerate(stops):
    viz.add_marker(lat, lon, popup=f"Stop {i+1}")
viz.save("route.html")

输出

• HTML：可在任何浏览器中查看的交互式地图
• 自动适配：自动缩放以显示所有数据
• 响应式：适用于移动设备

依赖项

• folium>=0.14.0
• pandas>=2.0.0
• branca>=0.6.0