# GasFlux - 气体通量处理系统

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
[![Version](https://img.shields.io/badge/version-0.2.1-blue.svg)](https://github.com/your-repo/gasflux)

GasFlux 是一个专门用于处理无人机或飞行器采集的气体浓度数据的专业工具，主要用于计算气体通量（如 CO₂、CH₄ 等）。该系统集成了完整的数据处理流程，包括数据预处理、背景校正、空间插值和报告生成。

## 🌟 主要特性

- **完整处理流程**: 从原始 Excel 数据到最终通量计算的完整解决方案
- **多种气体支持**: 支持 CO₂、CH₄ 等常见温室气体
- **高级算法**: 集成 FastChrom 背景校正和克里金插值算法
- **灵活配置**: 基于 YAML 的配置系统，支持自定义参数
- **可视化输出**: 自动生成数据分析图表和报告
- **命令行工具**: 提供直观的 CLI 接口
- **Web API 服务**: 提供完整的 RESTful API，支持异步处理、实时监控和详细统计
- **跨平台支持**: 支持 Windows、macOS 和 Linux

## 📋 系统要求

- **Python**: 3.8 或更高版本
- **内存**: 至少 4GB RAM（推荐 8GB+）
- **磁盘空间**: 至少 1GB 可用空间

## 🚀 快速开始

### 安装

#### 方式一：从源码安装（推荐）

```bash
# 克隆仓库
git clone https://github.com/your-repo/gasflux.git
cd gasflux

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

# 安装包（开发模式）
pip install -e .
```

#### 方式二：使用预编译可执行文件

```bash
# 下载最新的可执行文件（Windows）
# GasFlux_RunExample.exe

# Linux/macOS
# GasFlux_RunExample
```

### 基本使用

#### 1. 处理单个数据文件

```bash
# 使用命令行工具
gasflux process data.csv

# 或使用 Python API
python -c "
from gasflux.processing_pipelines import process_main
process_main('data.csv', 'gasflux_config.yaml')
"
```

#### 2. 处理目录中的所有文件

```bash
gasflux process /path/to/data/directory
```

#### 3. 使用完整处理流程（Excel 数据）

```bash
python src/gasflux/run_example.py your_data.xlsx
```

## 🌐 Web API 服务

GasFlux 提供完整的 Web API 服务，支持通过 HTTP 接口进行数据处理。详见以下文档：

- [API 文档](API_DOCUMENTATION.md) - 完整的 API 接口说明
- [环境变量配置](ENVIRONMENT_VARIABLES.md) - 环境变量配置指南
- [Waitress 部署](WAITRESS_DEPLOYMENT.md) - 生产环境部署指南

### 启动 Web 服务

```bash
# 启动 API 服务（使用默认配置）
python run_api.py

# 或使用自定义环境变量
export GASFLUX_PORT=8080
export GASFLUX_LOG_LEVEL=DEBUG
python run_api.py

# 服务将在配置的地址和端口启动
# 访问 http://localhost:5000 查看 Web 界面
```

### 环境变量配置

GasFlux 支持通过环境变量进行灵活配置。详见 [ENVIRONMENT_VARIABLES.md](ENVIRONMENT_VARIABLES.md) 获取完整配置指南。

**常用配置示例**：

```bash
# 端口配置
export GASFLUX_PORT=8080

# 日志配置
export GASFLUX_LOG_LEVEL=DEBUG
export GASFLUX_LOG_FILE=/var/log/gasflux/api.log

# 性能配置
export GASFLUX_THREADS=16
export GASFLUX_MAX_CONTENT_LENGTH=524288000  # 500MB

# 目录配置
export GASFLUX_UPLOAD_FOLDER=/data/uploads
export GASFLUX_OUTPUT_FOLDER=/data/outputs
```

### API 特性

- **异步处理**: 支持大文件处理，不阻塞客户端
- **实时监控**: 通过任务 ID 实时查询处理状态
- **文件管理**: 自动文件上传、处理和下载
- **健康检查**: 系统状态监控和诊断
- **详细日志**: 完整的请求日志和性能监控
- **统计监控**: 实时 API 统计、性能指标和系统资源监控
- **环境变量配置**: 通过环境变量灵活配置，无需修改代码

## 📖 使用指南

### 配置文件

GasFlux 使用 YAML 格式的配置文件，位于 `gasflux_config.yaml`。主要配置项包括：

```yaml
# 输出目录
output_dir: ./output

# 数据验证参数
required_cols:
  latitude: [-90, 90]        # 纬度范围
  longitude: [-180, 180]     # 经度范围
  height_ato: [0, 200]       # 相对起飞高度（米）
  windspeed: [0, 20]         # 风速（m/s）
  temperature: [-50, 60]    # 温度（°C）
  pressure: [900, 1100]     # 气压（hPa）

# 气体配置
gases:
  ch4: [1.5, 10.0]    # 甲烷
  co2: [300, 500]    # 二氧化碳

# 处理策略
strategies:
  background: "algorithm"    # 背景校正方法
  spatial: "curtain"        # 空间处理模式
  interpolation: "kriging"  # 插值方法
```

### 生成配置文件

```bash
# 在当前目录生成默认配置文件
gasflux generate-config .

# 在指定目录递归生成配置文件
gasflux generate-config /path/to/data --recursive
```

### 数据格式要求

输入数据应为 CSV 格式，包含以下必需列：

- `latitude`: 纬度（-90 到 90）
- `longitude`: 经度（-180 到 180）
- `height_ato`: 相对起飞高度（米）
- `windspeed`: 风速（m/s）
- `winddir`: 风向（度）
- `temperature`: 温度（°C）
- `pressure`: 气压（hPa）
- 气体浓度列（如 `co2`, `ch4`）

## 🛠️ 高级用法

### 自定义配置

```bash
# 使用自定义配置文件
gasflux process data.csv --config-path my_config.yaml

# 生成高级配置模板
gasflux generate-config . --template advanced_config.yaml
```

### 完整处理流程

```bash
# 处理 Excel 文件并进行完整分析
python src/gasflux/run_example.py input.xlsx --output processed_data.csv

# 仅预处理，跳过通量分析
python src/gasflux/run_example.py input.xlsx --no-gasflux
```

### API 使用

```python
from gasflux.processing_pipelines import process_main
from gasflux.data_processor import process_file

# 数据预处理
processed_data = process_file('input.xlsx', 'output.csv')

# 通量分析
process_main('output.csv', 'config.yaml')
```

## 📊 输出结果

处理完成后将在输出目录生成：

- **数据文件**: 处理后的 CSV 数据
- **图表**: 浓度分布、风场、插值结果等
- **报告**: HTML 格式的分析报告
- **统计结果**: 通量计算结果和不确定性分析

## 🧪 测试

运行测试套件：

```bash
# 运行所有测试
pytest tests/

# 运行特定测试
pytest tests/test_processing.py

# 使用测试数据快速验证
gasflux process --test
```

## 🏗️ 开发

### 项目结构

```
gasflux/
├── src/gasflux/          # 核心代码
│   ├── __init__.py
│   ├── cli.py           # 命令行接口
│   ├── processing_pipelines.py  # 主要处理流程
│   ├── data_processor.py       # 数据预处理器
│   ├── background.py           # 背景校正
│   ├── interpolation.py        # 插值算法
│   ├── plotting.py            # 可视化
│   ├── reporting.py           # 报告生成
│   └── gasflux_config.yaml    # 默认配置
├── examples/             # 示例和模板
├── tests/               # 测试代码
├── build/               # 构建产物
└── requirements.txt     # 依赖列表
```

### 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📈 算法说明

### 背景校正算法

- **FastChrom**: 快速色谱背景校正算法
- **自适应阈值**: 自动确定背景区域
- **多尺度处理**: 支持不同时间尺度的背景变化

### 空间插值

- **克里金插值**: 地质统计学方法
- **半变异函数**: 支持球形、指数等模型
- **普通克里金**: 考虑空间自相关性

### 通量计算

- **质量平衡法**: 基于浓度梯度和风场
- **积分计算**: 考虑垂直分布和湍流扩散
- **不确定性分析**: Monte Carlo 方法评估误差

## 🐛 故障排除

### 常见问题

1. **内存不足**: 处理大型数据集时增加虚拟内存
2. **配置错误**: 使用 `gasflux generate-config` 生成有效配置
3. **依赖问题**: 确保所有 Python 包正确安装

### 日志和调试

```bash
# 启用详细日志
export GASFLUX_LOG_LEVEL=DEBUG
gasflux process data.csv
```