# BRDF_GUI 项目交接文档

---

## 1. 项目概述

### 1.1 项目基本信息
| 项目 | 内容 |
|------|------|
| **项目名称** | BRDF_GUI |
| **项目类型** | 高光谱图像处理软件 |
| **主要功能** | BRDF（双向反射分布函数）校正 |
| **开发语言** | Python 3.9+ |
| **GUI框架** | PyQt5 |
| **许可证** | GNU GPL v3.0 |

### 1.2 项目背景
本项目是一个用于遥感数据BRDF校正的综合性工具集，主要处理高光谱图像中的观测和光照几何效应，支持从机载（AVIRIS、AVIRIS-NG）和星载传感器获取的数据。

### 1.3 核心功能模块
1. **ocbrdf** - 水体/海洋BRDF校正模块（基于EUMETSAT/OLCI算法）
2. **Flexbrdf (HyTools)** - 陆地BRDF校正和通用高光谱图像处理库
3. **GUI** - 基于PyQt5的图形用户界面

---

## 2. 项目结构

```
BRDF_GUI/
├── .idea/                          # PyCharm配置目录
├── GUI/                            # GUI应用程序
│   ├── brdf_gui.py                 # 主GUI程序 (1303行)
│   └── DESIGN.md                   # UI设计规范文档
├── ocbrdf/                         # 海洋BRDF校正模块
│   ├── ocbrdf_main3.py            # 主BRDF校正模块 (908行)
│   ├── brdf_model_O25.py           # O25 BRDF模型
│   ├── brdf_model_M02.py           # Morel et al. (2002)模型
│   ├── brdf_model_M02SeaDAS.py     # SeaDAS变体
│   ├── brdf_model_L11.py           # Lee et al. (2011)模型
│   ├── brdf_utils.py               # 工具函数
│   ├── Raman.py                    # 拉曼散射校正
│   ├── aviris.py                   # AVIRIS数据处理
│   └── src/                        # 其他源文件
├── Flexbrdf/                       # HyTools库（陆地BRDF）
│   ├── setup.py                    # 包安装配置
│   ├── README.md                   # 英文文档
│   ├── hytools/                    # 核心库包
│   │   ├── base.py                 # 主类
│   │   ├── brdf/                   # BRDF校正模块
│   │   ├── io/                     # 输入输出模块
│   │   ├── topo/                   # 地形校正
│   │   ├── glint/                  # 镜面反射校正
│   │   ├── masks/                  # 掩膜工具
│   │   └── transform/              # 光谱变换
│   ├── scripts/                    # 命令行脚本
│   └── examples/                   # 示例和教程
└── requirements.txt                # 项目依赖
```

---

## 3. 技术栈与依赖

### 3.1 核心技术
| 技术 | 版本 | 用途 |
|------|------|------|
| Python | 3.9+ | 主要开发语言 |
| PyQt5 | - | GUI框架 |
| NumPy | >=1.21.0 | 数值计算 |
| xarray | >=0.20.0 | 多维数据数组处理 |
| rasterio | >=1.2.0 | 地理空间栅格IO |
| spectral | >=0.22.0 | ENVI文件处理 |
| Ray | >=2.0.0 | 分布式并行处理 |
| scikit-learn | >=1.0.0 | 机器学习工具 |
| SciPy | >=1.7.0 | 科学计算 |
| pandas | >=1.3.0 | 数据处理 |
| matplotlib | >=3.5.0 | 可视化 |
| h5py/h5netcdf | >=3.0.0 | HDF5和NetCDF支持 |

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

---

## 4. 模块详细说明

### 4.1 ocbrdf模块（水体BRDF校正）

#### 功能描述
专门用于水体/海洋高光谱数据的BRDF校正，支持多种BRDF模型。

#### 核心文件
| 文件 | 说明 |
|------|------|
| `ocbrdf_main3.py` | 主校正引擎，读取ENVI BSQ文件，处理xarray数据集 |
| `brdf_model_O25.py` | O25模型（EUMETSAT BRDF4OLCI 2024） |
| `brdf_model_M02.py` | Morel et al. (2002)模型，使用f/Q查找表 |
| `brdf_model_L11.py` | Lee et al. (2011)模型，使用QAA v6反演 |
| `brdf_utils.py` | 多项式求解器、坐标处理等工具函数 |
| `Raman.py` | 拉曼散射校正 |
| `aviris.py` | AVIRIS数据IO工具 |

#### 数据要求
- **输入格式**: ENVI BSQ, xarray Dataset
- **必需波段**: 442nm, 490nm, 560nm, 665nm（根据模型不同有所变化）
- **输出**: 标准化遥感反射率(nrrs)、BRDF校正因子、不确定性估计

#### 关键算法参数
- **角度约定**: OLCI约定，相对方位角(raa=0表示太阳和观测在同一侧)
- **LUT路径**: 期望在模块位置相对的`BRDF_LUTs/BRDF_{model}.nc`路径

### 4.2 Flexbrdf/HyTools模块（陆地BRDF校正）

#### 功能描述
通用高光谱图像处理库，支持BRDF、地形和镜面反射校正。

#### 核心算法
| 类型 | 算法 |
|------|------|
| BRDF校正 | FlexBRDF、Universal BRDF |
| 地形校正 | SCS、SCS+C、Cosine、C、Mod-Minnaert |
| 镜面反射校正 | Hochberg 2003、Hedley 2005、Gao 2021 |

#### 数据格式支持
- ENVI格式
- NEON AOP HDF5
- NetCDF（EMIT、AVIRIS-NG）

#### 核心文件
| 文件 | 说明 |
|------|------|
| `hytools/base.py` | HyTools主类，高光谱数据IO和处理 |
| `hytools/brdf/flex.py` | FlexBRDF算法实现 |
| `hytools/brdf/kernels.py` | Ross Thick、Li Dense、Roujean核函数 |
| `hytools/io/envi.py` | ENVI文件读写 |
| `hytools/io/neon.py` | NEON AOP HDF5支持 |
| `hytools/io/netcdf.py` | NetCDF格式支持 |

#### 并行处理
- 使用Ray进行分布式计算
- `no_ray/`目录包含单进程版本脚本

### 4.3 GUI模块

#### 功能描述
基于PyQt5的图形用户界面，提供BRDF校正工作流的可视化操作。

#### 主要功能
- 掩膜条件编辑器（7种掩膜类型）
  - ndi: 归一化差异指数掩膜
  - ancillary: 辅助数据掩膜
  - neon_edge: NEON边缘掩膜
  - kernel_finite: 核函数有限性掩膜
  - water: 水体掩膜
  - external: 外部掩膜
  - band: 波段掩膜
- BRDF配置界面
- JSON配置生成
- 文件选择对话框
- 暗色主题UI（NVIDIA设计风格）

#### 设计规范
- 主色调: 深灰色背景 + 绿色(#76b900)强调色
- 工业风格字体
- 参见 `GUI/DESIGN.md`

---

## 5. 配置说明

### 5.1 JSON配置系统
项目使用基于JSON的配置系统进行批处理。

#### 配置文件示例位置
```
Flexbrdf/examples/configs/
├── aviris.json
├── brdf_glint_correct_config.json
├── glint_correct_config.json
├── topo_brdf_glint_correct_config.json
└── ...
```

#### 配置生成脚本
```
Flexbrdf/scripts/configs/
├── image_correct_json_generate.py
├── image_correct_json_generate_gui.py
├── trait_estimate_json_generate.py
└── plsr_model_format_v0_1.py
```

### 5.2 环境要求
- **输入数据**: 高光谱图像（ENVI、HDF5或NetCDF格式）
- **辅助数据**: 太阳/传感器几何角度（SZA、SAA、VZA、VAA、RAA）
- **可选数据**: 地形数据（坡度、坡向）用于地形校正
- **查找表**: BRDF LUT以NetCDF格式存储（需单独获取）

---

## 6. 使用说明

### 6.1 安装步骤

1. **克隆/解压项目**
```bash
cd BRDF_GUI
```

2. **安装依赖**
```bash
pip install -r requirements.txt
```

3. **安装HyTools包（可选）**
```bash
cd Flexbrdf
pip install -e .
```

### 6.2 运行方式

#### GUI模式
```bash
python GUI/brdf_gui.py
```

#### 命令行模式（ocbrdf）
```bash
python ocbrdf/ocbrdf_main3.py --config config.json
```

#### 命令行模式（FlexBRDF）
```bash
cd Flexbrdf
python scripts/flex_main.py --config config.json
```

### 6.3 常用脚本

| 脚本 | 功能 |
|------|------|
| `image_correct.py` | 图像校正 |
| `brdf_correct_bip.py` | BRDF校正（BIP格式） |
| `rad2reflectance.py` | 辐射度转反射率 |
| `neon2envi.py` | NEON格式转ENVI |
| `transform.py` | 光谱变换 |
| `trait_estimate.py` | 性状估计 |

---

## 7. 开发团队与版权

### 7.1 核心开发者
- **HyTools**: Adam Chlus (JPL), Zhiwei Ye, Ting Zheng, Natalie Queally, Evan Greenberg, Philip Townsend (威斯康星大学麦迪逊分校)
- **ocbrdf**: 基于EUMETSAT BRDF4OLCI研究（合同号 RB_EUM-CO-21-4600002626-JIG）

### 7.2 许可证
GNU General Public License v3.0

### 7.3 引用信息
参见 `Flexbrdf/CITATION.cff`

---

## 8. 文档资源

### 8.1 中文文档
- `Flexbrdf/examples/FlexBRDF_tutorial.md` - FlexBRDF中文教程

### 8.2 英文文档
- `Flexbrdf/README.md` - 库文档和基本使用
- `Flexbrdf/docs/` - Sphinx API文档

### 8.3 设计文档
- `GUI/DESIGN.md` - UI设计规范

---

## 9. 重要注意事项

### 9.1 BRDF LUT路径
ocbrdf模块期望在以下位置找到BRDF查找表：
```
BRDF_LUTs/BRDF_{model}.nc
```
（相对于模块位置）

### 9.2 角度约定
- 使用OLCI约定
- 相对方位角(raa)=0表示太阳和观测在同一侧

### 9.3 并行处理
- FlexBRDF使用Ray进行分布式计算
- 如不需要并行，可使用`no_ray/`目录下的单进程脚本

### 9.4 数据格式兼容性
- 确保输入数据格式正确（ENVI BSQ、HDF5或NetCDF）
- 几何角度数据必须正确配准

### 9.5 内存要求
- 高光谱数据体积大，确保有足够的系统内存
- 建议使用分块处理大文件

---

## 10. 常见问题与解决方案

### Q1: 找不到BRDF查找表
**解决方案**: 确保`BRDF_LUTs/`目录存在，并包含对应的`.nc`文件

### Q2: GUI启动失败
**解决方案**: 检查PyQt5是否正确安装：`pip install PyQt5`

### Q3: 内存不足错误
**解决方案**: 使用分块处理脚本或增加系统内存

### Q4: 角度数据格式错误
**解决方案**: 检查输入的角度数据是否符合OLCI约定

---

## 11. 后续开发建议

### 11.1 可能的改进方向
1. 添加更多BRDF模型支持
2. 优化大文件处理性能
3. 增强GUI的批量处理能力
4. 添加更多可视化功能
5. 支持更多传感器类型

### 11.2 维护建议
1. 定期更新依赖包版本
2. 保持与最新Python版本兼容
3. 持续完善文档
4. 添加更多单元测试

---

## 12. 联系方式

如有问题，请参考：
- 项目文档：`Flexbrdf/README.md`
- 中文教程：`Flexbrdf/examples/FlexBRDF_tutorial.md`
- API文档：`Flexbrdf/docs/`

---

**文档生成日期**: 2026年4月10日  
**文档版本**: v1.0  
**项目状态**: 交接完成
