# 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