# FlexBRDF 教程

本教程介绍如何使用 FlexBRDF [[1](#参考文献)] 将高光谱图像（如 AVIRIS-NG）中的双向反射分布函数（BRDF）归一化到标准光照条件。特别地，本教程主要介绍如何使用终端命令行脚本来校正图像。

## 1. 准备工作

为了生成 BRDF 校正后的反射率图像，需要反射率图像及其辅助数据集。辅助数据集包括太阳天顶角和方位角、传感器观测天顶角和方位角。对于可选的地形校正，还需要地形的坡度和坡向信息。

对于 AVIRIS 类数据集，辅助数据集存储在 L1B 包中的 *\*_obs_ort / \*_obs* 文件中，而反射率数据集在 L2 包中（[AVIRIS-Classic](https://aviris.jpl.nasa.gov/dataportal/20170911_AV_Download.readme)/[AVIRIS-NG](https://avirisng.jpl.nasa.gov/dataportal/ANG_L1B_L2_Data_Product_Readme_v02.txt)）。对于 NEON AOP 数据集，辅助数据集与反射率数据集一起存储在 [HDF5 文件](https://www.neonscience.org/resources/learning-hub/tutorials/neon-refl-h5-py)中。NASA 的一些新数据集以 NetCDF 格式提供，[已添加初步支持](./netcdf_glt.md)。

HyTools 及其依赖项已正确[安装](https://github.com/EnSpec/hytools/tree/master#installation)。可以通过此[章节](https://github.com/EnSpec/hytools/blob/master/README.md#basic-usage)中的测试代码进行验证。

## 2. 配置

所有设置和文件路径都在一个 JSON 文件中指定，这是执行完整过程的首要步骤。这些设置应在实际执行前完成。一些配置模板可以在[这里](https://github.com/EnSpec/hytools/tree/master/examples/configs)找到。

要更改特定用途的设置，用户可以直接编辑示例配置 JSON 文件，或运行以下脚本来生成具有修改设置的新配置 JSON 文件。

```bash
python ./scripts/configs/image_correct_json_generate.py
```
将根据设置生成一个新的 JSON 文件。

默认和推荐的设置在[此示例配置文件](https://github.com/EnSpec/hytools/blob/master/examples/configs/topo_brdf_glint_correct_config.json)中描述。关键设置将在接下来的部分介绍。

#### 选择校正输出中要导出的内容
配置中的 *export* 部分决定了是否执行 BRDF 模型估计部分或 BRDF 模型应用部分。这两个部分可以分开按顺序执行，也可以同时执行。
```json
"export": {
      "coeffs": false,
      "image": true,
      "masks": true,
      "subset_waves": [],
      "output_dir": "/data2/avng/l2/hytools_avng_example/",
      "suffix": "topo_brdf_glint"
},
```
  * 整个校正过程的主要结果是图像和校正系数。至少应启用其中一个的导出（设置为 *true*）。*coeffs* 可以设置为 *true*，以便保存供将来使用，称为"预计算"系数。
  * 如果在过程中生成的掩码层也可以在 *image* 和 *masks* 都设置为 *true* 时保存。
  * *subset_waves* 是指定要导出哪些波段的列表。它们通过最接近的波长（纳米）指定，例如 ```[440,550,660]``` 表示在可见光范围内导出 3 个波段。空列表 ```[]``` 表示导出完整的图像立方体。
  * *output_dir* 和 *suffix* 是关于输出的最终位置和后缀。

#### 选择如何校正图像
目前，在 HyTools 中用户可以选择三种校正方法（[TOPO](#TOPO), [BRDF](#BRDF), [Glint](#glint)）。它们都可以启用。
```json
"corrections": [
      "topo",
      "brdf",
      "glint"
],
```
校正的顺序很重要。一些常见设置如下所示。
|校正设置|含义|
|---|---|
|[ ]|空，无校正|
|['topo']|仅地形校正|
|['brdf']|仅 BRDF 校正，适用于平坦区域|
|['topo','brdf']|先地形校正，然后 BRDF 校正|
|['brdf','glint']|先 BRDF 校正，然后耀斑校正|
|['topo','brdf','glint']|按顺序进行三种校正|

#### TOPO
地形校正方法的选项包括 ['scs','scs+c','c','cosine','mod_minneart']，分别对应太阳-冠层-传感器方法[[2](#参考文献)]、太阳-冠层-传感器+C 方法[[2](#参考文献)]、C 方法[[3](#参考文献)]、余弦方法 [[3](#参考文献)] 和修改的 Minnaert 方法 [[3](#参考文献)]。推荐的地形校正方法是 "scs+c"。
```json
"topo": {
      "type": "scs+c",
      ... ...
      ... ...
},
```


#### BRDF

BRDF 校正方法的选项包括 ['flex','universal']，分别对应 FlexBRDF 方法 [[1](#参考文献)] 和通用方法。

几何核可以从 ['li_sparse','li_dense','li_dense_r','li_dense_r','roujean'] 中选择。
体积核可以从 ['ross_thin','ross_thick','hotspot','roujean'] 中选择。

```json
"brdf": {
    "type": "flex",
    "grouped": true,
    "geometric": "li_dense_r",
    "volume": "ross_thick",
      ... ....
      ... ....      
    "bin_type": "dynamic",
    "num_bins": 18,
    "ndvi_bin_min": 0.05,
    "ndvi_bin_max": 1.0,
    "ndvi_perc_min": 10,
    "ndvi_perc_max": 95,
    "solar_zn_type": "scene"
},   
```
虽然每条飞行线可以独立进行 BRDF 校正，但 FlexBRDF 建议将同一天且地理位置相近的所有线路放在同一组中，并估计共享的 BRDF 校正系数。

FlexBRDF 使用 NDVI 来区分不同的土地覆盖类型。它在 NDVI 范围内动态使用 N 个分箱。默认情况下，飞行组中的像素将根据 NDVI 百分位数分为 18 个子组。在每个子组内估计 BRDF 系数。不在 [*ndvi_bin_min*, *ndvi_bin_max*] 范围内的像素不包含在统计中。

在 BRDF 校正设置下，同一 BRDF 飞行线组中的所有像素最终将归一化到整个"场景"平均太阳天顶角的光照条件。


```json
"num_cpus":2,
```
如果 BRDF 校正组中有多条飞行线，反射率图像应与配置 JSON 文件中的辅助文件配对。这也意味着配置中文件列表（"*input_files*" 和 "*anc_files*"）的顺序应相互匹配。基本上，分配给 RAY 的 CPU 数量也应与飞行线的总数匹配。在示例中，有两条飞行线。


#### Glint

耀斑校正的选项包括 ['hochberg','gao','hedley']，分别对应 Hochberg 等人 2003 年的方法[[4](#参考文献)]、Gao 等人 2021 年的方法[[5](#参考文献)] 和 Hedley 等人 2005 年的方法[[6](#参考文献)]。

#### 用于生成配置文件的简化 GUI
这个[基于 Python 的 GUI](https://github.com/EnSpec/hytools/blob/master/scripts/configs/image_correct_json_generate_gui.py) 仅提供最少的选项来生成图像校正配置文件。它具有 [image_correct_json_generate.py](https://github.com/EnSpec/hytools/blob/master/scripts/configs/image_correct_json_generate.py) 的大部分功能，但它假设同一组的文件专门位于同一目录中。它不提供所有选项，更像是配置生成方式的一个示例。

![配置文件的 GUI](./img/config_json_gen_gui.jpg "GUI")


## 3. 执行

实际的图像校正脚本是 [image_correct.py](https://github.com/EnSpec/hytools/blob/master/scripts/image_correct.py)。它可以估计 BRDF 系数，也可以使用预计算的系数或实时生成结果图像来进行图像校正。

```bash
python ./scripts/image_correct.py 配置/JSON/文件的路径
```

根据配置设置，在此步骤中获得各种输出。

如果启用了图像导出，将生成完整的图像立方体（```"subset_waves": []```）或波段子集的图像立方体（```subset_waves": [波长1,波长2,波长3,...] ```）。

如果在配置的 *export* 部分中 *image* 和 *mask* 都设置为 *true*，将生成一个单独的掩码文件。

所有结果图像均为 ENVI 格式。

如果启用了 TOPO/BRDF 模型系数导出，它们将以 JSON 格式存储，并可以在其他 hytools 脚本（[image_correct_json_generate.py](https://github.com/EnSpec/hytools/blob/master/scripts/configs/image_correct_json_generate.py) 或 [trait_estimate_json_generate.py](https://github.com/EnSpec/hytools/blob/master/scripts/configs/trait_estimate_json_generate.py)）或[程序](https://github.com/EnSpec/hytools/blob/master/examples/hytools_basics_notebook.ipynb)中用作预计算系数，以更定制化的方式。每个图像应有自己的 TOPO/BRDF 系数 JSON 文件，尽管同一 FlexBRDF 组中的 BRDF JSON 共享相同的系数集。


## 4. （可选）性状预测

使用线性高光谱模型估计的性状可以在 HyTools 中实现。与 BRDF 校正类似，可以通过组合映射脚本（[trait_estimate.py](https://github.com/EnSpec/hytools/blob/master/scripts/trait_estimate.py)）、模型系数 JSON 文件（[示例](https://github.com/EnSpec/hytools/blob/master/scripts/configs/plsr_model_format_v0_1.py)）和配置 JSON 文件（[trait_estimate_json_generate.py](https://github.com/EnSpec/hytools/blob/master/scripts/configs/trait_estimate_json_generate.py)）来生成图像网格格式的性状图。

可以同时执行多个预测，并且可以在不预先计算存储消耗大的校正图像立方体的情况下，实时对图像反射率进行 TOPO/BRDF/耀斑校正。因此，前一节中的预计算 TOPO/BRDF 系数起着关键作用。

## 5. （实验性）地形校正中的子组

在某些特殊情况下，数据以瓦片形式提供，而不是以线形式提供。这意味着需要在整组 BRDF 校正之前，将同一线路中的一些瓦片分组进行地形校正。

配置文件中添加了一些新项目（[topogroup_brdf_correct_config.json](../examples/configs/topogroup_brdf_correct_config.json)）来完成此任务。还为此调整了一个新脚本（[image_correct_topogroup.py](../scripts/image_correct_topogroup.py)）。

所有新项目都添加在 *'topo'* 部分。必须启用 ```subgrouped```。```sample_perc``` 是用于提取随机样本以估计地形校正系数的采样百分比。在 ```subgroup``` 中，配置 JSON 中附加到每个的组标签可以是任何字符串，只要同一子组中的线路共享相同的组标签。

```json
"topo": {
      ... ...
      "subgrouped":true,
      "sample_perc": 0.01,
      "subgroup": {
          "/data/line1_path_name":"group00",
          "/data/line2_path_name":"group00",
          "/data/line3_path_name":"group01"
      }
},    
```



## 参考文献
[1] Queally, N., Ye, Z., Zheng, T., Chlus, A., Schneider, F., Pavlick, R. P., & Townsend, P. A. (2022). 
FlexBRDF: A flexible BRDF correction for grouped processing of airborne imaging spectroscopy flightlines. *Journal of Geophysical Research: Biogeosciences*, *127*(1), e2021JG006622. 
https://doi.org/10.1029/2021JG006622

[2] Scott A. Soenen, Derek R. Peddle,  & Craig A. Coburn (2005).
SCS+C: A Modified Sun-Canopy-Sensor Topographic Correction in Forested Terrain. *IEEE Transactions on Geoscience and Remote Sensing*, *43*(9), 2148-2159.
https://doi.org/10.1109/TGRS.2005.852480


[3] Richter, R., Kellenberger, T., & Kaufmann, H. (2009).
Comparison of topographic correction methods. *Remote Sensing*, *1*(3), 184-196.
https://doi.org/10.3390/rs1030184


[4] Hochberg, E. J., Andréfouët, S., & Tyler, M. R. (2003). Sea surface correction of high spatial resolution Ikonos images to improve bottom mapping in near-shore environments. *IEEE transactions on geoscience and remote sensing*, *41*(7), 1724-1729. 
https://doi.org/10.1109/TGRS.2003.815408

[5] Gao, B. C., & Li, R. R. (2021). Correction of sunglint effects in high spatial resolution hyperspectral imagery using SWIR or NIR bands and taking account of spectral variation of refractive index of water. *Advances in Environmental and Engineering Research*, *2*(3), 1-15. https://doi.org/10.21926/aeer.2103017


[6] Hedley, J. D., Harborne, A. R., & Mumby, P. J. (2005). Simple and robust removal of sun glint for mapping shallow‐water benthos. *International Journal of Remote Sensing*, *26*(10), 2107-2112. https://doi.org/10.1080/01431160500034086