129 lines
3.8 KiB
Markdown
129 lines
3.8 KiB
Markdown
# geo_tools
|
||
|
||
> 专业地理信息数据处理工具库 —— 基于 geopandas / shapely / fiona
|
||
|
||
[](https://www.python.org)
|
||
[](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
|