svg-water-quality-generator 1.0.0

专用于从水质监测数据生成SVG热力图的独立Python库

SVG Water Quality Generator

🌊 专用于从OSS数据生成水质SVG热力图的精简Python工具

🚀 项目简介

SVG Water Quality Generator 是一个专门用于处理OSS水质监测数据并生成高质量SVG热力图的工具。支持从OSS ZIP文件下载、解析INDEXS.CSV+POS.TXT格式数据、使用增强插值算法生成平滑热力图，并输出精确的地理边界信息用于地图叠加。

✨ 核心特性

• 🔗 OSS直连下载：直接从阿里云OSS下载ZIP数据包
• 📋 标准格式解析：支持INDEXS.CSV + POS.TXT格式数据
• 🧮 增强插值算法：Alpha Shape边界检测 + 高分辨率插值
• 🎨 SVG矢量输出：透明背景，适合地图叠加
• 📍 地理边界信息：输出精确的经纬度坐标用于地图定位
• 🔄 批量处理：自动识别并处理所有可用指标

📦 安装方法

使用uv安装（推荐）

# 克隆项目
git clone <repository-url>
cd svg-water-quality-generator

# 初始化uv项目
uv init

# 安装依赖
uv add numpy pandas matplotlib scipy requests pillow chardet python-dotenv

传统pip安装

# 安装依赖
pip install -r requirements.txt

# 安装项目
pip install -e .

🎯 快速开始

基本使用

from water_quality_processor import WaterQualityProcessor

# OSS ZIP文件URL
oss_zip_url = "https://your-oss-bucket.oss-cn-shanghai.aliyuncs.com/data.zip"

# 使用处理器
with WaterQualityProcessor(
    output_dir="./outputs",
    grid_resolution=400
) as processor:
    
    # 处理数据并生成SVG
    results = processor.process_from_oss_zip(
        zip_url=oss_zip_url,
        colormap="jet",
        boundary_method="alpha_shape",
        interpolation_method="linear",
        transparent_bg=True
    )
    
    # 查看结果
    for indicator, result in results.items():
        if result:
            print(f"指标: {result['indicator_name']}")
            print(f"SVG文件: {result['svg_path']}")
            print(f"边界文件: {result['bounds_path']}")

运行示例

# 直接运行主脚本
uv run python water_quality_processor.py

# 运行使用示例
uv run python example_usage.py

📊 支持的水质指标

自动识别并处理以下指标：

指标代码	中文名称	英文名称	单位
cod	化学需氧量	Chemical Oxygen Demand	mg/L
nh3n	氨氮	Ammonia Nitrogen	mg/L
tp	总磷	Total Phosphorus	mg/L
tn	总氮	Total Nitrogen	mg/L
chla	叶绿素a	Chlorophyll-a	μg/L
cod_mn	高锰酸盐指数	COD Permanganate	mg/L
ss	总悬浮物	Total Suspended Solids	mg/L
bga	蓝绿藻	Blue-Green Algae	细胞/mL

🗂️ 数据格式要求

输入数据结构

ZIP文件必须包含：

• INDEXS.csv - 水质指标数据
• POS.txt - GPS坐标数据

INDEXS.csv 格式示例

number,CHLa,Turbidity,SS,COD,TP,NH3-N,Bga,CODMn,TN
1,6.646,10.689,10.635,9.053,0.066,0.127,6.034,3.174,0.471
2,6.427,11.098,11.172,9.030,0.063,0.123,2.686,3.121,0.463

POS.txt 格式示例

/path/file_1.csv latitude: 31.516106 longitude: 120.267944 height: 110.27
/path/file_2.csv latitude: 31.516125 longitude: 120.267938 height: 110.26

📂 输出文件

每个水质指标生成两个文件：

1. SVG热力图文件

• 文件名：{指标}_heatmap.svg
• 格式：矢量SVG，透明背景
• 用途：直接叠加到地图上

2. 地理边界JSON文件

• 文件名：{指标}_bounds.json
• 内容：精确的经纬度边界信息
• 用途：地图定位和叠加

边界文件示例

{
  "geographic_bounds": {
    "min_longitude": 120.264922,
    "max_longitude": 120.267936,
    "min_latitude": 31.515932,
    "max_latitude": 31.520750,
    "center_longitude": 120.266429,
    "center_latitude": 31.518341
  },
  "grid_info": {
    "grid_resolution": 400,
    "valid_pixels": 83583
  },
  "projection_info": {
    "coordinate_system": "WGS84",
    "units": "degrees"
  }
}

🎨 配置选项

颜色映射

• jet - 彩虹色映射（默认）
• water_quality - 专业水质色彩
• viridis - 感知均匀色彩
• RdYlBu_r - 红-黄-蓝反向

边界检测方法

• alpha_shape - Alpha Shape算法（默认，高精度）
• convex_hull - 凸包算法（快速）
• density_based - 密度边界检测

插值方法

• linear - 线性插值（默认）
• cubic - 三次插值（更平滑）
• nearest - 最近邻插值

🏗️ 项目结构

svg-water-quality-generator/
├── water_quality_processor.py    # 主处理脚本
├── example_usage.py             # 使用示例
├── src/                         # 核心模块
│   ├── core/                    # 核心功能
│   │   ├── downloader.py        # OSS下载器
│   │   └── extractor.py         # ZIP解压器
│   ├── data/                    # 数据处理
│   │   ├── parser.py            # 数据解析器
│   │   ├── standardizer.py      # 数据标准化
│   │   └── validator.py         # 数据验证
│   ├── interpolation/           # 插值算法
│   │   ├── alpha_shape.py       # Alpha Shape
│   │   ├── convex_hull.py       # 凸包算法
│   │   ├── density_boundary.py  # 密度边界
│   │   └── enhanced_interpolation.py # 增强插值
│   ├── visualization/           # 可视化
│   │   ├── svg_generator.py     # SVG生成器
│   │   ├── color_mapper.py      # 颜色映射
│   │   └── layout_calculator.py # 布局计算
│   ├── config/                  # 配置
│   │   └── indicators.py        # 指标配置
│   └── utils/                   # 工具
│       └── logger.py            # 日志工具
└── tests/                       # 测试
    └── test_basic_functionality.py

🚀 地图叠加示例

生成的SVG和边界信息可以直接用于Web地图：

Leaflet.js 示例

// 读取边界信息
const bounds = L.latLngBounds(
  [31.515932, 120.264922],  // 西南角
  [31.520750, 120.267936]   // 东北角
);

// 叠加SVG图像
const overlay = L.imageOverlay('cod_heatmap.svg', bounds, {
  opacity: 0.7,
  interactive: false
});

overlay.addTo(map);

🛠️ 开发环境

运行测试

uv run python tests/test_basic_functionality.py

代码格式化

black src/ tests/ *.py
flake8 src/ tests/ *.py

📝 版本信息

• 当前版本: 1.0.0
• Python要求: >= 3.8
• 主要依赖: numpy, pandas, matplotlib, scipy

🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目。

📄 许可证

MIT License - 查看 LICENSE 文件了解详情。