From 443ec09c5c74bce0df48d58ac646e9787cc14f3f Mon Sep 17 00:00:00 2001 From: zhanghuilai Date: Mon, 5 Jan 2026 09:45:34 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=94=B9readme?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 287 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 237 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 80dc64b..3358bd8 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,262 @@ +# GasFlux - 气体通量处理系统 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) -[![Tests](https://github.com/gasflux/gasflux/workflows/CI/badge.svg)](https://github.com/gasflux/gasflux/actions?query=workflow%3A%22CI%22) -[![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v0.json)](https://github.com/charliermarsh/ruff) -[![format - Black](https://img.shields.io/badge/format-black-000000.svg)](https://github.com/psf/black) -[![types - mypy](https://img.shields.io/badge/types-mypy-blue.svg)](https://github.com/python/mypy) +[![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 +GasFlux 是一个专门用于处理无人机或飞行器采集的气体浓度数据的专业工具，主要用于计算气体通量（如 CO₂、CH₄ 等）。该系统集成了完整的数据处理流程，包括数据预处理、背景校正、空间插值和报告生成。 -`pip install gasflux` \ -`gasflux --help` +## 🌟 主要特性 -📖 **[详细用户指南](USER_GUIDE.md)** - 完整的功能说明和使用教程 +- **完整处理流程**: 从原始 Excel 数据到最终通量计算的完整解决方案 +- **多种气体支持**: 支持 CO₂、CH₄ 等常见温室气体 +- **高级算法**: 集成 FastChrom 背景校正和克里金插值算法 +- **灵活配置**: 基于 YAML 的配置系统，支持自定义参数 +- **可视化输出**: 自动生成数据分析图表和报告 +- **命令行工具**: 提供直观的 CLI 接口 +- **跨平台支持**: 支持 Windows、macOS 和 Linux -GasFlux is a tool for processing atmospheric gas concentration data and windspeeds into mass emissions fluxes, with principle applications to greenhouse gas measurement and vulcanology. Currently it works with in situ ("sniffing") data from UAVs and other aircraft, using mass balance as a paradigm and kriging as an interpolation strategy, but the intention is to expand this to other kinds of sampling and processing strategies, such as open-path and tracer methods. +## 📋 系统要求 -It is released under the AGPLv3 license as a free and open-source project - comments, pull requests, issues and co-development are warmly welcomed. Currently development is co-ordinated by Jamie McQuilkin ([@pipari](https://github.com/pipari)) at the UAV Greenhouse Gas group at the University of Manchester. +- **Python**: 3.8 或更高版本 +- **内存**: 至少 4GB RAM（推荐 8GB+） +- **磁盘空间**: 至少 1GB 可用空间 -## User Installation +## 🚀 快速开始 -The package is available on PyPi and can be installed using `pip install gasflux`. +### 安装 -## Usage +#### 方式一：从源码安装（推荐） -The package interface is in active development. Currently it ingests a data csv file (or folder containing only data csv files) and a config file that dictates the parameters of the analysis. +```bash +# 克隆仓库 +git clone https://github.com/your-repo/gasflux.git +cd gasflux -This is done through the syntax `gasflux process --config `. - -### The config file - -The default gasflux_config.yaml is located in the package source. It can be generated in a supplied directory using `gasflux generate-config `. If a directory is supplied to `gasflux process` and a config is not also explicitly supplied, the package will look for one config file in that directory or its subdirectories and attempt to process all csv files in that directory and subdirectories. If multiple or no config is found, it will raise an error. If supplying a single csv file for processing (rather than a directory), only the parent directory will be searched for config files (not its subdirectories). - -Through it, variables can be passed to the [scikit-gstat](https://scikit-gstat.readthedocs.io/en/latest/) package used for kriging and the [pybaselines](https://pybaselines.readthedocs.io/en/latest/) package used for background correction. - -### The data file - -Input data files must be csv-type (i.e. readable by `pandas`) and have the following columns (all lower case): - -- `timestamp` (datetime) -- `latitude` (float) -- `longitude` (float) -- `height_ato` (float) - height above takeoff -- `windspeed` (float) - in m/s, as measured or inferred at each measurement point -- `winddir` (float) - in standard 0-360 degree format, relative to the earth -- `temperature` (float) in degrees celsius -- `pressure` (float) - in hPa/mBar - -At least one gas concentration in ppm is also required. The column name should be the gas name, e.g. `co2`, `ch4`, `n2o`, etc. - -The gas should be entered in the gasflux_config.yaml file along with a range of concentrations in ppmv, e.g.: +# 安装依赖 +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 +``` + +## 📖 使用指南 + +### 配置文件 + +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, 500] - co2: [300, 5000] - c2h6: [-0.5, 10] + ch4: [1.5, 10.0] # 甲烷 + co2: [300, 500] # 二氧化碳 + +# 处理策略 +strategies: + background: "algorithm" # 背景校正方法 + spatial: "curtain" # 空间处理模式 + interpolation: "kriging" # 插值方法 ``` -Ensuring input data are sufficient and correctly formatted is non-trivial and important, but is left to the user. Data sources vary enormously so it is difficult to generalise this part of the analysis - in many cases these will be a mix of flight logs, GPS, one or more anemometers, one or more gas sensors, a thermometer, hygrometer, barometer. +### 生成配置文件 -Synchronisation and fusion of these data sources is important and should be given great attention - there are several ways to do this, including GPS logging on each sensor, recording everything on a single device, or NTP server synchronisation. Care should also be taken to avoid loss of data through resampling or interpolation. +```bash +# 在当前目录生成默认配置文件 +gasflux generate-config . -One way to convert encoded DJI logs is to use `djiparsetext`, a C++ library available on github [here](https://github.com/uav4geo/djiparsetxt) and documented [here](http://djilogs.live555.com/). +# 在指定目录递归生成配置文件 +gasflux generate-config /path/to/data --recursive +``` -## Development +### 数据格式要求 + +输入数据应为 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 +``` -### Installation -To install, clone the repository using e.g. `git clone` and use `pip install -e .` to install it as an editable python package. -It's highly recommended to use a virtual environment to manage dependencies. If you're not currently using one, [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/install.html) is a good option. -Then run `pip install -r requirements.txt` and `pip install -r dev-requirements.txt` to install the required dependencies. -User requirements.txt is generated using `pigar generate` rather than `pip freeze`.