floschl/pysamosa

# PySAMOSA    [](https://zenodo.org/badge/latestdoi/646028227) [](https://www.gnu.org/licenses/lgpl-3.0) ![]() PySAMOSA 是一个基于 Python 的软件，用于处理来自 SAR 卫星测高的开洋和沿海波形，以测量海洋和内陆水域的海面高度、波浪高度和风速。 卫星测高是一种用于对地观测的星载遥感技术。关于卫星测高法的更多细节，请参见[此处](https://www.altimetry.info/file/Radar_Altimetry_Tutorial.pdf)。 从反射回波/波形中提取三个地球物理参数的过程称为重跟踪。测量的（含噪）波形将与开洋功率回波波形模型 SAMOSA2 [1, 2] 进行拟合。 在沿海区域，回波会受到来自强反射目标（如沙洲和泥滩、潮滩、船舶平台、隐蔽的海湾或靠近海岸线的平静水域）的虚假信号的影响。 支持以下欧洲航天局（ESA）卫星测高任务： - Sentinel-3 (S3) - Sentinel-6 Michael Freilich (S6-MF) 该软件对波形（即 1 级 (L1b) 数据）进行重跟踪，以提取重跟踪变量 SWH、range 和 Pu。 使用了来自官方 EUMETSAT 基线的开洋重跟踪器实现规范文档（S3 [1]，S6-MF [2]）。 为了对沿海波形进行重跟踪，实现了以下重跟踪器： - SAMOSA+ [3] - CORAL [4, 5] 此外，可以使用 SAMOSA2 模型的零多普勒波束和由 ESA L2 GPP 项目 [7] 创建的专门调整的 $\alpha_p$ LUT 表，对 FF-SAR 处理的 S6-MF 数据进行重跟踪。FF-SAR 处理数据的应用已在 [5] 中得到验证。 未验证（实验性）功能： ## 入门指南 ### 使用方法 将 pysamosa 安装到你的环境中 ``` $ pip install pysamosa ``` 这是一个用于重跟踪来自 S6-MF 任务的单个 L1b 文件的示例 ``` from pathlib import Path import numpy as np from pysamosa.common_types import L1bSourceType from pysamosa.data_access import data_vars_s3, data_vars_s6 from pysamosa.retracker_processor import RetrackerProcessor from pysamosa.settings_manager import get_default_base_settings, SettingsPreset l1b_files = [] # l1b_files.append(Path('S6A_P4_1B_HR______20211120T051224_20211120T060836_20220430T212619_3372_038_018_009_EUM__REP_NT_F06.nc')) l1b_files.append(Path.cwd().parent / '.data' / 's6' / 'l1b' / 'S6A_P4_1B_HR______20211120T051224_20211120T060836_20220430T212619_3372_038_018_009_EUM__REP_NT_F06.nc') l1b_src_type = L1bSourceType.EUM_S6_F06 data_vars = data_vars_s6 # 配置 coastal CORAL retracker pres = SettingsPreset.CORALv2 rp_sets, retrack_sets, fitting_sets, wf_sets, sensor_sets = get_default_base_settings(settings_preset=pres, l1b_src_type=l1b_src_type) rp_sets.nc_dest_dir = l1b_files[0].parent / 'processed' rp_sets.n_offset = 0 rp_sets.n_inds = 0 #0 means all rp_sets.n_procs = 6 #use 6 cores in parallel rp_sets.skip_if_exists = False additional_nc_attrs = { 'L1B source type': l1b_src_type.value.upper(), 'Retracker preset': pres.value.upper(), } rp = RetrackerProcessor(l1b_source=l1b_files, l1b_data_vars=data_vars['l1b'], rp_sets=rp_sets, retrack_sets=retrack_sets, fitting_sets=fitting_sets, wf_sets=wf_sets, sensor_sets=sensor_sets, nc_attrs_kw=additional_nc_attrs, bbox=[np.array([-29.05, -29.00, 0, 360])], ) rp.process() #start processing print(rp.output_l2) #retracked L2 output can be found in here ``` 一个运行的重跟踪最小工作示例在 `notebooks/retracking_example.ipynb` 中展示。 ### 开发 强烈建议使用合适的 Python IDE，例如 [PyCharm Community](https://www.jetbrainscom/pycharm/download/) 或 Visual Studio Code。 使用 IDE 将使你能够更好地熟悉代码、调试和扩展它。 克隆仓库 ``` $ git clone {repo_url} ``` 进入克隆的目录 ``` $ cd pysamosa ``` 将依赖项安装到你的 conda 环境/虚拟环境中 ``` $ pip install -r requirements.txt ``` 通过运行 cython 编译 .pyx 文件（例如 model_helpers.pyx）来构建扩展 对于 Windows 用户：安装时可能需要已安装的 C/C++ 编译器，例如 MSCV，它随免费的 [Visual Studio Community](https://visualstudio.microsoft.com/vs/community/) 提供 ``` $ python setup.py build_ext --inplace ``` 可选：在 HPC 集群上编译（通常不需要） ``` $ LDSHARED="icc -shared" CC=icc python setup.py build_ext --inplace ``` ## 技巧 以下列表提供了软件推荐用法的简要说明。 1. **使用 Jupyter Notebook 入门** `notebooks/retracking_example.ipynb` 包含一个示例脚本，展示如何重跟踪一个 EUMETSAT 基线 L1b 样本文件。 重跟踪得到的 SWH 和 SWH 数据与 EUMETSAT 基线 L2 数据进行了比较。`notebooks/demo_script.py` 提供了上面的代码示例，以便快速启动一个小型重跟踪示例。 2. **更多入口点** 文件 `main_s3.py`、`main_s6.py`、`main_cs.py`、（`main_*.py`）等是批量处理多个 nc 文件的入口点。 读取一个 L1b 文件列表（或单个文件）进行重跟踪，这些文件可以是完全重跟踪，也可以基于给定的边界框（bbox）参数。每个处理过的 L1b 文件会输出一个重跟踪后的 L2 文件。 3. **设置** `RetrackerProcessor` 的输入要求在初始化期间插入 `RetrackerProcessorSettings`、`RetrackerSettings`、`FittingSettings`、`WaveformSettings` 和 `SensorSettings` 对象。这些设置对象的默认值可以通过 `get_default_base_settings` 函数，基于 `L1bSourceType` 和 `SettingsPreset` 这两个设置来获取。 例如，以下代码片段取自 `main_s3.py` 文件，它使用默认的基于 SAMOSA 的开洋重跟踪器（无 SettingsPreset）重跟踪 Sentinel-3 数据（从测量索引 25800 开始的 100 个波形，使用 6 个核心）。 ``` l1b_src_type = L1bSourceType.EUM_S3 pres = SettingsPreset.NONE #use this for the standard SAMOSA-based retracker [2] # pres = SettingsPreset.CORALv2 #use this for CORALv2 [5] # pres = SettingsPreset.NONE #use this for SAMOSA+ [3] rp_sets, retrack_sets, fitting_sets, wf_sets, sensor_sets = get_default_base_settings(settings_preset=pres, l1b_src_type=l1b_src_type) rp_sets.nc_dest_dir = nc_dest_path / run_name rp_sets.n_offset = 25800 rp_sets.n_inds = 100 rp_sets.n_procs = 6 rp_sets.skip_if_exists = False ``` 4. **评估环境** `./pysamosa/tests/` 目录下有多个单元测试，旨在更详细地分析重跟踪输出。 最重要的测试脚本是 `test_retrack_multi.py`，它包括对 S3A、S6、CS2 任务的短沿轨段进行重跟踪（以及一个通用的输入 nc 文件）。 `test_retrack_single` 允许你检查单个波形的重跟踪结果，并将其与参考重跟踪结果进行比较。 请取消文件 `conftest.py` 中 `mpl.use('TkAgg')` 这行的注释，以绘制测试输出，这对于文件 `tests/test_retrack_multi.py` 和 `tests/test_retrack_multi.py` 中的重跟踪测试特别有用。 5. **CORALv1 和 CORALv2 的区别** - v2 有两个额外的扩展，这是 S6-MF 所需要的。 - `retrack_sets.interference_masking_mask_before_le = True` 前缘之前的干扰信号也会被自适应干扰抑制方案（AIM，CORAL 特性）屏蔽掉。 - `fitting_sets.Fit_Var_2_MinMax_Hs = (0.0, 20)` 拟合过程的 SWH 下界设置为 0.0，如 [2] 中所定义。 6. **质量标志** 在重跟踪过程中，质量标志变量 `swh_qual` 和 `range_qual`（后者只是前者的副本）是重跟踪输出的一部分，表示每个单独波形的重跟踪质量（0=好，1=差）。 这在沿海场景中尤其重要，因为那里的波形会受到虚假信号的影响，这些信号往往导致波形重跟踪错误。CORAL 沿海重跟踪器最大化了沿海区域的有效记录数。 因此，我们强调在重跟踪产品中考虑 `swh_qual`/`range_qual` 质量标志的重要性。 ## 验证 ### 运行测试 要运行所有单元测试（使用 pytest 框架），请执行 ``` $ pytest ``` ### 与 EUMETSAT L2 基线数据比较 将 S3 和 S6-MF 任务的一个开洋段的重跟踪结果与 EUMETSAT L2 基线（S3: 004, S6-MF: F06）进行比较 （由 `notebooks/retracking_example.ipynb` Jupyter notebook 生成） S3 | S6-MF :-:|:-:  |  ## 贡献 - 复刻此仓库 - 提交拉取请求以合并回此仓库。 在提交更改之前，请确保你的更改能通过 flake8、black、isort 以及测试，包括使用 tox 测试其他 Python 版本： ``` $ flake8 pysamosa tests scripts $ black . --check --diff $ isort . --check-only --diff $ pytest $ tox ``` 如果你的拉取请求被接受，你将被包含在下一个正式发布版本中，并将被列为 Zenodo 创建的 DOI 链接的共同作者。 ## 未来工作 本项目可能的发展方向： 与重跟踪相关 - 使 CS-2 重跟踪与 CS-2 基线处理链对齐，并根据 [ESA Cryo-TEMPO 项目](https://earth.esa.int/eogateway/documents/20142/37627/Cryo-TEMPO-ATBD-Coastal-Oceans.pdf) 开发的 [SAMpy](https://github.com/cls-obsnadir-dev/SAMPy) 进行验证 - 实现 EUMETSAT 基线处理链的演进版本 [6]，例如计划于 2023 年第三季度进行的数值重跟踪 与软件相关 - 创建用于沿海重跟踪演示的 notebook - 创建更丰富的文档（readthedocs） ## 引用 如果你使用此软件或代码，请引用此 DOI： Florian Schlembach; Marcello Passaro. PySAMOSA: An Open-source Software Framework for Retracking SAMOSA-based, Open Ocean and Coastal Waveforms of SAR Satellite Altimetry. Zenodo. https://zenodo.org/badge/latestdoi/646028227. ## 致谢 作者感谢 此软件包使用 [Cookiecutter](https://github.com/audreyr/cookiecutter) 和 [audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage) 项目模板创建。 ## 参考文献 [1] SAMOSA Detailed Processing Model: Christine Gommenginger, Cristina Martin-Puig, Meric Srokosz, Marco Caparrini, Salvatore Dinardo, Bruno Lucas, Marco Restano, Américo, Ambrózio and Jérôme Benveniste, Detailed Processing Model of the Sentinel-3 SRAL SAR altimeter ocean waveform retracker, Version 2.5.2, 31 October 2017, Under ESA-ESRIN Contract No. 20698/07/I-LG (SAMOSA), Restricted access as defined in the Contract, Jérôme Benveniste (Jerome.Benvensite@esa.int) pers. comm. [2] EUMETSAT. Sentinel-6/Jason-CS ALT Level 2 Product Generation Specification (L2 ALT PGS), Version V4D; 2022. https://www.eumetsat.int/media/48266. [3] Dinardo, Salvatore. ‘Techniques and Applications for Satellite SAR Altimetry over Water, Land and Ice’. Dissertation, Technische Universität, 2020. https://tuprints.ulb.tu-darmstadt.de/11343/. [4] Schlembach, F.; Passaro, M.; Dettmering, D.; Bidlot, J.; Seitz, F. Interference-Sensitive Coastal SAR Altimetry Retracking Strategy for Measuring Significant Wave Height. Remote Sensing of Environment 2022, 274, 112968. https://doi.org/10.1016/j.rse.2022.112968. [5] Schlembach, F.; Ehlers, F.; Kleinherenbrink, M.; Passaro, M.; Dettmering, D.; Seitz, F.; Slobbe, C. Benefits of Fully Focused SAR Altimetry to Coastal Wave Height Estimates: A Case Study in the North Sea. Remote Sensing of Environment 2023, 289, 113517. https://doi.org/10.1016/j.rse.2023.113517. [6] Scharroo, R.; Martin-Puig, C.; Meloni, M.; Nogueira Loddo, C.; Grant, M.; Lucas, B. Sentinel-6 Products Status. Ocean Surface Topography Science Team (OSTST) meeting in Venice 2022. https://doi.org/10.24400/527896/a03-2022.3671. [7] ESA L2 GPP Project: FF-SAR SAMOSA LUT generation was funded under ESA contract 4000118128/16/NL/AI.

标签：CORAL算法, ESA任务, Python软件, SAMOSA模型, SAR卫星, Sentinel-3, Sentinel-6, 内陆水体, 卫星数据, 卫星测高, 参数估计, 地球科学, 地球观测, 地理信息, 气候研究, 水文学, 沿海监测, 波形处理, 波高测量, 海洋学, 海洋遥感, 海面高度测量, 环境监测, 空间遥感, 软件框架, 逆向工具, 遥感技术, 重跟踪算法, 风速反演