# BRDF校正工具 - 使用说明文档

## 一、软件概述

BRDF校正工具是一款用于高光谱图像双向反射分布函数（BRDF）校正的统一GUI应用程序，支持两种场景：

1. **陆地植被BRDF校正**（FlexBRDF算法）
   - 适用于陆地植被和地表的BRDF、地形和镜面反射校正
   - 支持AVIRIS、AVIRIS-NG等机载高光谱数据

2. **水体BRDF校正**（Ocean BRDF Correction）
   - 专用于水体和海洋的BRDF校正
   - 支持多种BRDF模型和不确定性估算

---

## 二、快速开始

### 2.1 启动软件

```bash
python brdf_gui.py
```

启动后将显示主界面，选择需要使用的模块：
- 点击"进入陆地模块"打开陆地植被BRDF校正
- 点击"进入水体模块"打开水体BRDF校正

---

## 三、陆地植被BRDF校正模块（FlexBRDF）

### 3.1 界面布局

模块界面分为左右两部分：
- **左侧**：配置选项卡（文件与波段映射、校正参数、输出设置）
- **右侧**：执行日志和进度显示

### 3.2 文件与波段映射页

#### 3.2.1 文件夹设置

| 参数 | 说明 | 默认值 |
|------|------|--------|
| 输入文件夹 | 反射率文件所在目录（ENVI格式） | 空 |
| 辅助文件夹 | 观测几何数据目录 | 空 |
| CPU核心数 | 并行处理使用的CPU核心数 | 1 |

**操作步骤**：
1. 点击"浏览..."按钮选择输入文件夹和辅助文件夹
2. 点击"自动匹配文件"按钮，软件会自动匹配反射率文件（`_rfl`后缀）和观测几何文件（`_obs`后缀）
3. 匹配成功的文件对将显示在列表中

#### 3.2.2 文件匹配规则

- 反射率文件命名格式：`{prefix}_rfl{ext}`
- 观测几何文件命名格式：`{prefix}_obs{ext}`
- 软件根据`{prefix}`部分自动匹配对应文件对

#### 3.2.3 手动添加文件对

如需手动指定文件对：
1. 在"手动添加文件对"区域，分别选择反射率文件和观测几何文件
2. 点击"添加文件对"按钮

#### 3.2.4 波段映射设置

每个输入文件需要映射以下观测几何参数到辅助文件的波段：

| 参数名称 | 说明 | 默认波段 |
|----------|------|----------|
| path_length | 路径长度 | 0 |
| sensor_zn | 传感器天顶角 | 1 |
| sensor_az | 传感器方位角 | 2 |
| solar_zn | 太阳天顶角 | 3 |
| solar_az | 太阳方位角 | 4 |
| phase | 相位角 | 5 |
| slope | 坡度 | 6 |
| aspect | 坡向 | 7 |
| cosine_i | 入射角余弦 | 8 |

**设置方法**：
1. 在文件列表中选择一个文件
2. 在右侧波段映射表格中设置各参数对应的波段索引（从0开始）
3. 点击"应用当前映射"保存设置

### 3.3 校正参数页

#### 3.3.1 选择校正类型

勾选需要执行的校正类型（可单选或多选）：

| 校正类型 | 说明 |
|----------|------|
| Topo (地形校正) | 消除地形起伏对反射率的影响 |
| BRDF (双向反射分布函数) | 校正各向异性反射效应 |
| Glint (耀斑校正) | 消除水体或湿润表面的镜面反射 |

#### 3.3.2 地形校正参数（Topo Correction）

| 参数 | 选项 | 默认值 | 说明 |
|------|------|--------|------|
| 类型 (type) | mod_minneart, scs+c, cosine, c, scs | mod_minneart | 地形校正算法类型 |
| 拟合类型 (c_fit_type) | nnls, ols, wls | nnls | 系数拟合方法 |

**掩膜条件设置**：
- **计算掩膜 (calc_mask)**：定义参与计算校正因子的像素条件
- **应用掩膜 (apply_mask)**：定义应用校正的像素条件

掩膜条件类型详见[第5章 掩膜条件说明](#五掩膜条件说明)。

#### 3.3.3 BRDF校正参数（BRDF Correction）

| 参数 | 选项/范围 | 默认值 | 说明 |
|------|-----------|--------|------|
| 算法类型 (type) | flex, universal | flex | BRDF算法类型 |
| 启用分组 (grouped) | 勾选/取消 | 勾选 | 是否按NDVI分组计算 |
| 几何核 (geometric) | li_sparse, li_dense, li_sparse_r, li_dense_r, roujean | li_sparse | 几何光学核函数 |
| 体积核 (volume) | ross_thin, ross_thick, hotspot, roujean | ross_thick | 体积散射核函数 |
| b/r 比率 | 0.1 - 10.0 | 2.5 | 树冠宽度/高度比 |
| h/b 比率 | 0.1 - 5.0 | 2.0 | 树高/树冠宽度比 |
| 采样比例 (sample_perc) | 0.01 - 1.0 | 0.1 | 用于拟合的采样比例 |
| 插值方法 (interp_kind) | linear, nearest, cubic | linear | 插值方法 |
| 分箱类型 (bin_type) | dynamic, fixed | dynamic | NDVI分箱类型 |
| 分箱数量 (num_bins) | 1 - 100 | 18 | NDVI分箱数量 |
| NDVI最小值 (ndvi_bin_min) | 0.0 - 1.0 | 0.05 | 分箱NDVI下限 |
| NDVI最大值 (ndvi_bin_max) | 0.0 - 1.0 | 1.0 | 分箱NDVI上限 |
| NDVI百分比最小值 (ndvi_perc_min) | 0 - 100 | 10 | 有效样本百分比下限 |
| NDVI百分比最大值 (ndvi_perc_max) | 0 - 100 | 95 | 有效样本百分比上限 |
| 太阳天顶角类型 (solar_zn_type) | scene, fixed, mean, custom | scene | 太阳天顶角计算方法 |

**核函数组合推荐**：
- 植被覆盖区：`li_sparse` + `ross_thick`
- 稀疏植被区：`roujean` + `roujean`
- 浓密植被区：`li_dense` + `ross_thick`

#### 3.3.4 耀斑校正参数（Glint Correction）

| 参数 | 选项 | 默认值 | 说明 |
|------|------|--------|------|
| 类型 (type) | mod_minneart, scs+c, cosine, c, scs, nir, mask | nir | 耀斑校正方法 |
| 拟合类型 (c_fit_type) | nnls, ols, wls | nnls | 系数拟合方法 |

**掩膜条件设置**：
- **计算掩膜 (calc_mask)**：定义参与计算耀斑因子的像素
- **应用掩膜 (apply_mask)**：定义应用耀斑校正的像素

### 3.4 输出设置页

| 参数 | 说明 | 默认值 |
|------|------|--------|
| 输出目录 | 校正结果保存路径 | 空 |
| 后缀 (Suffix) | 输出文件名后缀 | topo_brdf_glint |
| 输出系数 (coeffs) | 输出校正系数文件 | 不勾选 |
| 输出图像 (image) | 输出校正后图像 | 勾选 |
| 输出掩膜 (masks) | 输出使用的掩膜 | 不勾选 |

**输出文件名格式**：
```
{原文件名}_{后缀}.dat
```

### 3.5 操作按钮

| 按钮 | 功能 |
|------|------|
| 加载 JSON 配置 | 从JSON文件加载之前保存的配置 |
| 保存 JSON 配置 | 将当前配置保存为JSON文件 |
| 生成配置并运行 | 生成配置并启动BRDF校正处理 |

---

## 四、水体BRDF校正模块（Ocean BRDF）

### 4.1 输入文件设置

| 参数 | 文件格式 | 说明 |
|------|----------|------|
| 高光谱文件 | ENVI (.dat, .bsq, .bip, .bil, .hdr) | 高光谱遥感影像 |
| 角度文件 | ENVI (.dat, .bsq, .bip, .bil, .hdr) | 观测几何角度数据 |
| 水体掩膜 | GeoTIFF (.tif, .tiff) | 水体区域掩膜 |

### 4.2 BRDF模型参数

| 参数 | 选项 | 默认值 | 说明 |
|------|------|--------|------|
| BRDF模型 | L11, M02, M02SeaDAS, O25 | L11 | BRDF校正模型 |
| 处理块大小 | 1024 - 16384 | 4096 | 光谱维分块大小 |
| 空间块大小 | 256 - 2048 | 512 | 空间维分块大小 |
| 计算不确定性 | 勾选/取消 | 取消 | 是否计算BRDF不确定度 |

**BRDF模型说明**：
- **L11**：Lee et al. (2011) 模型，适用于开阔大洋
- **M02**：Morel et al. (2002) 模型，经典水体BRDF模型
- **M02SeaDAS**：SeaDAS实现的M02模型
- **O25**：最新优化模型

### 4.3 输出变量选择

支持多选（按住Ctrl键选择多个）：

| 变量 | 说明 |
|------|------|
| Rw_brdf | BRDF校正后的水体反射率 |
| rho_ex_w | 水体反射率 (nrrs * π) |
| nrrs | 归一化遥感反射率 |
| C_brdf | BRDF校正因子 |
| brdf_unc | BRDF不确定度（需勾选计算不确定性） |
| nrrs_unc | nrrs不确定度（需勾选计算不确定性） |

**默认选中**：Rw_brdf, nrrs, C_brdf

### 4.4 输出设置

| 参数 | 选项 | 默认值 |
|------|------|--------|
| 输出路径 | 文件前缀路径 | 空 |
| 输出格式 | ENVI | ENVI |

### 4.5 运行

点击"运行水体BRDF校正"按钮开始处理。

---

## 五、掩膜条件说明

掩膜用于定义参与计算或应用校正的像素范围。所有掩膜条件取交集（同时满足）。

### 5.1 支持的掩膜类型

| 类型 | 说明 | 参数 |
|------|------|------|
| **ndi** | 归一化差值指数 | band_1, band_2, min, max |
| **ancillary** | 辅助数据掩膜 | name, min, max |
| **neon_edge** | NEON数据边缘掩膜 | radius |
| **kernel_finite** | 核函数有限性掩膜 | 无参数 |
| **water** | 水体掩膜 | band_1, band_2, threshold |
| **external** | 外部掩膜文件 | file_path, class |
| **band** | 单波段阈值 | band, min, max |

### 5.2 各类型详细参数

#### ndi（归一化差值指数）

```
ndi = (band_1 - band_2) / (band_1 + band_2)
保留范围: [min, max] 内的像素
```

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| band_1 | 整数 | 550 | 第一个波段波长(nm) |
| band_2 | 整数 | 2150 | 第二个波段波长(nm) |
| min | 浮点数 | -1.0 | NDI最小值 |
| max | 浮点数 | 0.0 | NDI最大值 |

**典型应用**：
- NDVI植被掩膜：band_1=850, band_2=680, min=0.2, max=1.0
- NDWI水体掩膜：band_1=860, band_2=1240, min=-1.0, max=0.0

#### ancillary（辅助数据掩膜）

基于观测几何参数创建掩膜。

| 参数 | 类型 | 默认值 | 可选值 |
|------|------|--------|--------|
| name | 字符串 | slope | slope, aspect, cosine_i, sensor_zn, sensor_az, solar_zn, solar_az, phase, path_length, utc_time |
| min | 浮点数 | 0.0 | - |
| max | 浮点数 | 1.0 | - |

**典型应用**：
- 坡度掩膜：只处理坡度小于30度的区域
  - name=slope, min=0, max=30
- 太阳天顶角掩膜：排除大太阳天顶角
  - name=solar_zn, min=0, max=60

#### neon_edge（NEON边缘掩膜）

用于消除NEON高光谱数据图像边缘的噪声区域。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| radius | 整数 | 1 | 边缘裁剪像素数 |

#### kernel_finite（核函数有限性掩膜）

自动排除会导致核函数计算溢出或不稳定的像素。无需参数。

#### water（水体掩膜）

使用特定波段组合识别水体。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| band_1 | 整数 | 550 | 第一个波段波长(nm) |
| band_2 | 整数 | 850 | 第二个波段波长(nm) |
| threshold | 浮点数 | 0.0 | 水体识别阈值 |

#### external（外部掩膜文件）

使用外部分类或掩膜文件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| file_path | 字符串 | 空 | 外部掩膜文件路径 |
| class | 整数 | 1 | 要保留的类别值 |

#### band（单波段阈值）

基于单个波段的值创建掩膜。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| band | 整数 | 650 | 波段波长(nm) |
| min | 浮点数 | 0.0 | 最小值 |
| max | 浮点数 | 1.0 | 最大值 |

### 5.3 掩膜条件设置步骤

1. 在校正参数页找到掩膜设置区域
2. 点击"+ 添加条件"按钮
3. 选择掩膜类型
4. 设置对应参数值
5. 可添加多个条件（取交集）
6. 点击"删除"按钮移除不需要的条件

---

## 六、配置文件的保存与加载

### 6.1 保存配置

1. 完成所有参数设置
2. 点击"保存 JSON 配置"按钮
3. 选择保存路径和文件名
4. 配置将以JSON格式保存，包含：
   - 输入文件列表
   - 波段映射关系
   - 校正参数设置
   - 掩膜条件
   - 输出设置

### 6.2 加载配置

1. 点击"加载 JSON 配置"按钮
2. 选择之前保存的JSON配置文件
3. 软件将自动恢复所有设置

**注意**：
- 加载配置后会自动匹配文件对，请确保输入文件和辅助文件路径仍然有效
- 如果文件路径已改变，需要重新手动设置文件夹路径

---

## 七、典型工作流程

### 7.1 陆地植被BRDF校正流程

1. **启动软件** → 选择"陆地植被BRDF校正"
2. **设置文件夹** → 选择输入文件夹和辅助文件夹
3. **匹配文件** → 点击"自动匹配文件"
4. **检查映射** → 确认波段映射设置正确
5. **选择校正** → 勾选需要的校正类型（Topo/BRDF/Glint）
6. **设置参数** → 根据数据特点调整校正参数
7. **设置掩膜** → 添加合适的掩膜条件（如NDVI>0.2）
8. **设置输出** → 指定输出目录和后缀
9. **保存配置** → （可选）保存当前配置
10. **运行** → 点击"生成配置并运行"

### 7.2 水体BRDF校正流程

1. **启动软件** → 选择"水体BRDF校正"
2. **选择文件** → 依次选择高光谱文件、角度文件、水体掩膜
3. **选择模型** → 选择适合的BRDF模型（通常用L11）
4. **选择变量** → 勾选需要的输出变量
5. **调整参数** → （可选）调整块大小以优化性能
6. **设置输出** → 指定输出文件前缀路径
7. **运行** → 点击"运行水体BRDF校正"

---

## 八、常见问题与解决方案

### 8.1 文件匹配问题

**问题**：自动匹配找不到文件对

**解决**：
- 检查文件命名是否符合 `{prefix}_rfl` 和 `{prefix}_obs` 格式
- 确保输入文件夹和辅助文件夹路径正确
- 使用手动添加功能指定文件对

### 8.2 波段映射问题

**问题**：提示波段索引超出范围

**解决**：
- 检查辅助文件的实际波段数
- 确认波段索引从0开始计数
- 验证辅助文件格式正确

### 8.3 内存不足问题

**问题**：处理大文件时内存溢出

**解决**：
- 减少CPU核心数设置
- 对于水体模块，减小处理块大小（chunk_size）
- 分块处理（FlexBRDF会自动分块）

### 8.4 掩膜问题

**问题**：校正后结果为空或过少

**解决**：
- 检查掩膜条件是否过于严格
- 验证NDVI或波段阈值设置是否合理
- 查看掩膜类型是否与数据匹配

---

## 九、技术参数参考

### 9.1 支持的文件格式

| 类型 | 格式 |
|------|------|
| 输入反射率 | ENVI标准格式 (.dat + .hdr) |
| 观测几何 | ENVI标准格式 (.dat + .hdr) |
| 水体掩膜 | GeoTIFF (.tif) |
| 输出结果 | ENVI标准格式 |
| 配置文件 | JSON (.json) |

### 9.2 系统要求

- **操作系统**：Windows 10/11, Linux, macOS
- **Python版本**：3.8+
- **内存**：建议8GB以上（处理大图像需要更多）
- **依赖库**：PyQt5, numpy, scipy等（详见requirements.txt）

---

## 十、联系与支持

如有问题或建议，请查看项目文档或联系开发团队。

---

*文档版本：v1.0*
*最后更新：2026年4月*