初次提交

2026-03-04 17:07:07 +08:00
commit af988ea7b9
37 changed files with 3674 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,128 @@
+# geo_tools
+
+> 专业地理信息数据处理工具库 —— 基于 geopandas / shapely / fiona
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+---
+
+## 功能特性
+
+- **统一 IO 接口**：一行代码读写 Shapefile、GeoJSON、GeoPackage、**File Geodatabase (GDB)**、KML、CSV 等格式
+- **核心几何运算**：基于 Shapely 2.x 的缓冲区、集合运算、有效性检查与自动修复
+- **坐标系处理**：重投影、CRS 信息查询、批量坐标转换，内置中国常用 CRS 常量
+- **空间分析**：叠置分析、最近邻、按位置选择、面积加权均值、属性统计汇总
+- **配置驱动**：通过 `.env` 或环境变量控制输出路径、日志级别、默认 CRS 等
+- **栅格预留接口**：为 rasterio 集成预留扩展点
+
+## 项目结构
+
+```
+geo_tools/
+├── geo_tools/           # 主包
+│   ├── config/          # Pydantic BaseSettings 全局配置
+│   ├── core/            # 核心处理（vector / geometry / projection / raster）
+│   ├── io/              # 数据读写（readers / writers，含 GDB）
+│   ├── analysis/        # 空间分析（spatial_ops / stats）
+│   └── utils/           # 通用工具（logger / validators / config）
+├── scripts/             # 独立处理脚本
+├── tests/               # pytest 测试套件
+├── data/sample/         # 示例数据（GeoJSON）
+├── output/              # 处理结果输出目录
+├── logs/                # 日志文件目录
+├── docs/                # 文档
+└── pyproject.toml       # 项目配置与依赖
+```
+
+## 快速开始
+
+### 安装依赖
+
+```bash
+# 推荐使用 conda 安装地理库（避免 GDAL 编译问题）
+conda install -c conda-forge geopandas shapely fiona pyproj
+
+# 然后安装本项目（开发模式）
+pip install -e ".[dev]"
+```
+
+### 基本使用
+
+```python
+import geo_tools
+
+# 读取矢量数据（自动识别格式）
+gdf = geo_tools.read_vector("data/sample/sample_points.geojson")
+
+# 读写 File Geodatabase
+layers = geo_tools.list_gdb_layers("path/to/data.gdb")
+gdf = geo_tools.read_gdb("path/to/data.gdb", layer="my_layer")
+geo_tools.write_gdb(gdf, "output/result.gdb", layer="result")
+
+# 坐标系转换
+gdf_proj = geo_tools.reproject(gdf, "EPSG:3857")
+
+# 缓冲区分析
+from geo_tools.core.geometry import buffer_geometry
+buffered_geom = buffer_geometry(gdf.geometry[0], distance=1000)
+
+# 空间叠置
+from geo_tools.analysis.spatial_ops import overlay
+result = geo_tools.overlay(layer_a, layer_b, how="intersection")
+
+# 面积加权均值
+from geo_tools.analysis.stats import area_weighted_mean
+result = area_weighted_mean(polygon_gdf, value_col="soil_ph", group_col="region")
+```
+
+### 配置
+
+复制 `.env.example` 为 `.env` 并按需修改：
+
+```bash
+GEO_TOOLS_OUTPUT_DIR=D:/output
+GEO_TOOLS_DEFAULT_CRS=EPSG:4490
+GEO_TOOLS_LOG_LEVEL=DEBUG
+```
+
+## 运行测试
+
+```bash
+# 运行全部测试
+pytest tests/ -v
+
+# 运行带覆盖率报告
+pytest tests/ -v --cov=geo_tools --cov-report=html
+```
+
+## 运行示例脚本
+
+```bash
+python scripts/example_workflow.py
+```
+
+## GDB 支持说明
+
+本项目通过 `fiona>=1.9` 的 `OpenFileGDB` 驱动读写 Esri File Geodatabase（`.gdb`）。
+
+| 操作 | 驱动 | 要求 |
+|------|------|------|
+| 读取 GDB | `OpenFileGDB` | fiona >= 1.9（内置） |
+| 写出 GDB | `OpenFileGDB` | fiona >= 1.9（内置） |
+| 编辑 GDB（高级） | `FileGDB` | 需要 ESRI FileGDB API |
+
+```python
+# 列出所有图层
+layers = geo_tools.list_gdb_layers("data.gdb")
+
+# 读取指定图层
+gdf = geo_tools.read_gdb("data.gdb", layer="土地利用", crs="EPSG:4490")
+
+# 写出到 GDB（新建或追加图层）
+geo_tools.write_gdb(result_gdf, "output.gdb", layer="分析结果", mode="w")
+```
+
+## 许可证
+
+MIT License