pi-asf-sentinel1-slc

v1.2.5

Published

19 days ago

Pi skill: automatically download Sentinel-1 SLC IW data from ASF for SBAS-InSAR experiments. Same-track, same-direction, per-date full-coverage guarantees.

0High
0Medium
0Low

jinhucoco

pi-package pi-skill sentinel-1 asf insar sbas remote-sensing sar

ASF Sentinel-1 Download Skill（ASF 哨兵一号数据下载技能）

从 ASF (Alaska Satellite Facility) 自动下载用于 SBAS-InSAR 实验的 Sentinel-1 数据 Automatically download Sentinel-1 data from ASF for SBAS-InSAR experiments

🌟 核心特性（Key Features）

功能总览：一套技能覆盖 SBAS-InSAR 完整数据链

| 功能 | 脚本 | 需要账号 | |------|------|---------| | 🛰️ Sentinel-1 SLC 主数据下载（轨道分组/覆盖校验/多线程） | download.py multi_download.py robust_download.py | ✅ Earthdata | | 📡 精密轨道文件 POEORB（与 SLC 时相对应） | poeorb_download.py | ❌ 免账号 | | 🌤️ GACOS 大气延迟 ztd（时相 + 范围 + UTC 时刻） | gacos_download.py gacos_fetch.py | ❌ 仅需邮箱收结果 | | ⛰️ DEM 30m（NASADEM 官方源(中国大陆需要走代理)，研究区自动分幅） | dem_download.py | ✅ Earthdata |

核心能力：

🎯 面向 SBAS-InSAR 设计：自动保证同一相对轨道 + 同一方向（升/降轨）+ 完全覆盖研究区，形成 12 天规则时序
🛡️ 三重一致性校验：轨道一致性（同 frame 可能被不同轨道复用，下载前验证 pathNumber 完全一致）、卫星一致性（S1A/S1B/S1C 混用提示）、逐时相覆盖检查（每个时相影像并集必须完全覆盖研究区，单帧部分覆盖的时相自动排除）
📐 跨帧自动处理：研究区压在上下两景边界时，自动识别并下载同一时相的全部帧（并集覆盖）
🛰️ 多极化支持：默认同时搜索 VV+VH 与 VV，合并清单
🔄 稳健下载：断点续传 + 超时保护 + 自动重试 + 桌面进度条，网络中断不丢进度
⚡ 多线程分片下载（multi_download.py）：8 线程 Range 分片并发（大文件约 8× 提速），分片级断点续传 + 重试 + 失败片补下，大小 + MD5 双校验（坏数据自动重下），网络极差时自动降级单文件模式（连续 2 文件作废自动切换，不中断任务）
✅ 数据完整性保障：所有下载路径均做大小 + ASF 官方 md5sum 双校验，校验不通过自动删除重下，杜绝坏数据进入实验
📄 多格式矢量：支持 .shp / .kml（含 SARscape 导出的命名空间与三维带海拔坐标）
🔒 凭证本地安全：Earthdata 账号密码存技能目录 config.json，交互式配置，不接触公开网络

遵循 Agent Skills 标准（https://agentskills.io/specification），可在 pi / Codex / Claude Code / Cursor 等支持该标准的工具中使用。

📦 安装（Installation）

前置条件（Prerequisites）

账号要求（按功能）：

| 功能 | 需要的账号 | 说明 | |------|-----------|------| | SLC 主数据下载 | NASA Earthdata（必需）| 免费注册：https://urs.earthdata.nasa.gov/ ；用于 ASF 搜索与下载认证 | | DEM 下载 | NASA Earthdata（必需）| 与 SLC 下载同一个账号 | | POEORB 精密轨道 | 无需账号 | ESA 公开服务器直接下载 | | GACOS 大气延迟 | 无需注册，需一个可收邮件的邮箱 | 结果通过邮件发送（需邮箱 IMAP 授权码用于自动收件，163/QQ 邮箱均可） |

环境要求：

| 项 | 要求 | |----|------| | 操作系统 | Windows / Linux / macOS | | Python | 3.10+ | | 网络 | 可访问 api.asf.alaska.edu（中国大陆用户建议代理）|

路径 A：Pi 用户（推荐）

# 一键安装（自动注册为 pi 技能）
pi install npm:pi-asf-sentinel1-slc

# 安装 Python 依赖（asf_search / pyshp / shapely 等）
pip install asf_search pyshp shapely defusedxml matplotlib

路径 B：其他 AI 工具（Codex / Claude Code / Cursor）

方式 1（推荐）：宿主终端一键安装

curl -fsSL https://raw.githubusercontent.com/jinhucoco/asf-sentinel1-download/main/install.sh | bash

脚本自动完成：检测已安装的工具（Codex / Claude / pi）→ 安装到对应技能目录 → 安装 Python 依赖 → 生成凭证模板。未检测到任何工具时安装到通用位置 ~/.agents/skills/。

方式 2：手动安装（可选）

下载 asf-sentinel1-download-skill.zip，解压得到 asf-sentinel1-download/ 文件夹，放入对应技能目录：

~/.codex/skills/       # Codex
~/.claude/skills/      # Claude Code
~/.pi/agent/skills/    # pi
~/.agents/skills/      # 通用

然后安装依赖：pip install -r requirements.txt。

⚠️ 别忘了：安装完成后还需配置 Earthdata 账号密码（见下方「配置 Earthdata 凭证」），否则 ASF 认证会失败、无法下载数据。

💡 Codex 沙箱用户必读：Codex 沙箱默认关闭网络、HOME 目录只读，curl | bash 一键安装会失败。请在宿主终端（非沙箱）执行方式 1，或浏览器下载 zip 手动解压（方式 2，零命令行）。也可在对话中让 Codex 安装（需 network_access=true 且 ~/.codex 可写）。安装脚本支持 bash install.sh --dry-run 预览操作，并在检测到沙箱时输出降级指引。
🔑 装好后记得配置账号密码：在 Codex 对话中说 "配置 ASF 账号密码"（或手动编辑 ~/.codex/skills/asf-sentinel1-download/config.json，见下方「配置 Earthdata 凭证」）。未配置凭证时下载会认证失败。

配置 Earthdata 凭证（所有路径都需要）

方式 A（推荐，交互式）： 在 AI 对话中直接说 "配置 ASF 账号密码"，AI 引导输入并自动保存到 config.json，无需手动编辑文件。

方式 B（手动）： 编辑技能目录 config.json：

{
  "username": "your_earthdata_username",
  "password": "your_earthdata_password"
}

⚠️ 安全提示：config.json 含明文密码，仅本机使用，请确保文件权限仅本人可读写，切勿提交到公开仓库。

⚡ 快速开始（Quick Start）

3 分钟上手： ① 安装（见上）→ ② 配置凭证（对话中说"配置 ASF 账号密码"）→ ③ 直接使用：

在任意 AI 工具（pi / Codex / Claude Code）对话中说：

"从 ASF 下载哨兵数据，区域研究区.shp，时间 20200101 至 20251231，VV+VH"

AI 会自动完成全部流程，并交互式询问关键决策：

[OK] 认证成功
[OK] 极化 VV+VH: 搜索到 945 个结果
[OK] 共 5 个 (方向,轨道) 组

=== 可选轨道组（按景数排序） ===
  [1] DESCENDING / 轨道 135: 322 景
  [2] ASCENDING / 轨道 128: 248 景
  [3] DESCENDING / 轨道 33: 176 景
  ...
请选择要使用的轨道组编号（回车选默认第 1 个）: 1   ← 交互式选择

[OK] 轨道一致性校验通过: 全部 322 景均为轨道 135
[OK] 逐时相覆盖检查: 169 个有效时相 / 0 个无效
  frame 468: 154景 覆盖100% ✅完全覆盖
  frame 467: 15景  覆盖100% ✅完全覆盖

请选择取景频率:            ← 交互式选择
  [1] 全部（不采样）
  [2] 每月
  [3] 每季度
  [4] 每半年
  [5] 每年
输入编号（回车默认每月）: 2

每个区间取哪个时相？      ← 交互式选择
  [1] 最早时相
  [2] 中间时相
  [3] 最晚时相
输入编号（回车默认最早）: 1

[OK] 每月采样(first时相): 135 景
[OK] 清单已导出: sampled_DESCENDING_135_monthly.csv
输入 y 全部下载，n 取消: y      ← 交互式确认
[下载] ...（断点续传 + 桌面进度条）

🚀 使用（Usage）

对话式（推荐）

当技能被 AI 代理加载时，直接说：

"从 ASF 下载哨兵数据，区域 研究区.shp，时间 20240101 至 20240630，VV+VH 和 VV"

AI 自动执行：认证 → 搜索 → 轨道分组 → 展示选择 → 覆盖校验 → 采样 → 确认 → 下载。

命令行（手动，不用 AI 对话时）

# 先分析数据质量（轨道/卫星/frame 覆盖/逐时相/覆盖图/清单）
python analyze.py --aoi 研究区.kml --start 20200101 --end 20251231 \
  --pol VV+VH --out ./analysis --sample --plot

# 再下载（稳健版：断点续传 + 超时 + 重试 + 桌面进度条）
python robust_download.py --aoi 研究区.kml --start 20240101 --end 20240630 \
  --pol VV+VH --out ./sentinel1_data

# 大流量/慢网络首选（多线程分片，约 8× 提速，自动降级保底）
# 方式1：清单驱动（推荐——先用 analyze.py 生成清单再批量挂机下载）
python analyze.py --aoi 研究区.kml --start 20200101 --end 20251231 \
  --pol VV+VH --out ./analysis
python multi_download.py --list ./analysis/list_DESCENDING_135.csv \
  --out ./sentinel1_data [--threads 8]

# 方式2：搜索驱动（指定轨道直接下载，跳过交互选择）
python multi_download.py --aoi 研究区.kml --start 20200101 --end 20251231 \
  --pol VV+VH --track 135 --out ./sentinel1_data [--threads 8]

参数说明

| 参数 | 必填 | 说明 | |------|------|------| | --aoi | 是 | 矢量文件路径，.shp 或 .kml（WGS84 坐标） | | --start / --end | 是 | 起止日期，格式 YYYYMMDD | | --pol | 否 | 极化（逗号分隔可多个），默认 VV+VH,VV | | --out | 否 | 下载目录，默认 ./sentinel1_data | | --max | 否 | 每个极化的结果数量上限 | | --sample | 否 | （analyze.py）交互式采样：每月/每季/每半年/每年/全部 | | --plot | 否 | （analyze.py）生成研究区 vs 影像覆盖图 | | --no-gui | 否 | 关闭桌面进度条窗口 |

稳健下载特点：断点续传（.part 标记）、60s socket 超时、120s 读超时、最多 10 次自动重试、跳过已完成文件；搜索后生成 inventory.txt 数据清单。

多线程版（multi_download.py）特点：

| 能力 | 说明 | |------|------| | 分片并发 | 默认 8 线程 Range 分片（<300MB 自动 4 片），大文件提速明显 | | 断点续传 | 分片级续传（中断的片从断点继续，不重下） | | 失败自愈 | 每片重试 6 次 + 失败片循环补下 3 轮，网络断连不丢进度 | | 大小探测 | bytes=0-0 探测真实大小（ASF 的 HEAD/Content-Length 不可靠） | | 数据校验 | 大小 + MD5 双校验，不匹配自动删除重下 | | 自动降级 | 多线程连续 2 文件作废 → 自动切单文件模式（mode.flag），任务不中断 | | 完成标记 | 清单跑完写 complete.flag，配合守护脚本可自动停止 | | 挂机友好 | 日志写 --out/multi_download.log，可反复重启续跑（跳过已完成） |

💡 实战验证：154 景（695GB，轨道 135 古浪，VV+VH）在持续断网环境下 35 小时完成，全程零数据损坏。

🧠 工作原理（How It Works）

SBAS-InSAR 数据要求

SBAS（小基线集）干涉处理要求时间序列内所有影像：

同一相对轨道（pathNumber 一致）——保证几何关系一致
同一方向（升轨/降轨一致）——保证观测几何一致
完全覆盖研究区——保证研究区每个点都有完整时序
规则时间间隔——Sentinel-1 12 天重访周期

自动选择流程

① 矢量 → WKT（shp 用 pyshp，kml 用 ElementTree，兼容多种命名空间/三维坐标）
② Earthdata 认证（ASFSession.auth_with_creds → EDL token + asf-urs cookie）
③ 逐极化搜索（不限定方向）并合并结果
④ 按 (飞行方向, 相对轨道号) 分组
⑤ 覆盖判断：
   ├─ 单景完全覆盖（同轨道同帧 footprint 一致）→ 直接可用
   └─ 并集覆盖（研究区跨上下景边界时，同一时相多帧并集覆盖）→ 提示并保留
⑥ 展示各轨道组景数 → 用户选择
⑦ 严格校验：
   ├─ 轨道一致性（组内所有影像 pathNumber 必须完全一致）
   ├─ 卫星一致性（S1A/S1B/S1C 不混用提示）
   └─ 逐时相覆盖（每个时相并集必须完全覆盖研究区，无效时相自动排除）
⑧ 清单确认（可输入轨道号筛选）→ 批量下载
⑨ 下载校验（大小 > 0）

跨帧边界处理（Cross-Frame）

Sentinel-1 SLC 产品按 frame 切分（每帧约 250km）。当研究区恰好压在上下两帧边界时：

单帧都不完全覆盖研究区 ❌
同一时相的上下两帧并集完全覆盖 ✅

本技能用 shapely unary_union 计算组内所有影像 footprint 的并集判断覆盖，自动识别并下载同一时相的所有帧。

关键代码（核心覆盖判断）

def group_union_covers(wkt_aoi, products):
    """判断一组影像的 footprint 并集是否完全覆盖研究区"""
    from shapely.geometry import shape
    from shapely.wkt import loads
    from shapely.ops import unary_union
    aoi = loads(wkt_aoi)
    polys = [shape(r.geometry) for r in products if r.geometry]
    union = unary_union(polys)
    return union.covers(aoi)

🔬 真实实验示例（Real Example）

以安徽地区某研究区、2025-07-01 至 2025-10-01、轨道 142 升轨为例：

[OK] AOI → WKT: POLYGON((116.749206 32.830839, ...))
[OK] Earthdata 认证成功
[OK] 极化 VV+VH: 搜索到 8 个结果
[OK] 共 1 个 (方向,轨道) 组
[OK] 完全覆盖研究区的轨道组: ASCENDING/142

序号  日期        相对轨道  方向        极化    文件名
1   20250923  142       ASCENDING  VV+VH   S1A_IW_SLC__1SDV_..._061114.zip
2   20250911  142       ASCENDING  VV+VH   S1A_IW_SLC__1SDV_..._060939.zip
3   20250830  142       ASCENDING  VV+VH   S1A_IW_SLC__1SDV_..._060764.zip
4   20250818  142       ASCENDING  VV+VH   S1A_IW_SLC__1SDV_..._060589.zip
5   20250806  142       ASCENDING  VV+VH   S1A_IW_SLC__1SDV_..._060414.zip
6   20250725  142       ASCENDING  VV+VH   S1A_IW_SLC__1SDV_..._060239.zip
7   20250713  142       ASCENDING  VV+VH   S1A_IW_SLC__1SDV_..._060064.zip
8   20250701  142       ASCENDING  VV+VH   S1A_IW_SLC__1SDV_..._059889.zip

8 景、12 天均匀间隔（07-01 → 07-13 → 07-25 → 08-06 → 08-18 → 08-30 → 09-11 → 09-23）、同一轨道 142 升轨、全部 VV+VH 双极化——完美的 SBAS 时间序列。

📁 文件结构（File Structure）

asf-sentinel1-download/
├── SKILL.md              # 技能定义（frontmatter + 触发条件 + 工作流）
├── download.py           # 主脚本（搜索 + 轨道分组 + 覆盖判断 + 下载）
├── analyze.py            # 数据分析模式（轨道/卫星/frame/逐时相/每月采样/覆盖图）
├── analysis.py           # 分析核心函数库（可独立调用）
├── robust_download.py    # 稳健下载（断点续传 + 超时 + 重试 + 数据列表）
├── multi_download.py     # 多线程分片下载（8 线程并发 + MD5 双校验 + 自动降级，大流量首选）
├── progress_gui.py       # 桌面进度条（Tkinter）
├── requirements.txt      # 依赖清单
├── config.example.json   # 凭证模板（安装时复制为 config.json，本地填写真实账号）
├── install.sh            # 一键安装脚本（检测 Codex/Claude/pi）
└── tests/                # 42 个单元测试
    ├── test_download.py
    ├── test_analysis.py
    └── test_package_consistency.py   # 发布镜像与根目录一致性守护

📌 仓库 skills/asf-sentinel1-download/ 是发布镜像（npm 与 install.sh 整体复制此目录），与根目录由 tests/test_package_consistency.py 自动校验同步。

download.py 核心函数

| 函数 | 职责 | |------|------| | aoi_to_wkt / shp_to_wkt / kml_to_wkt | 矢量 → WKT 多边形 | | parse_polarization / parse_direction | 极化/方向参数归一化 | | footprint_contains | 单景覆盖判断 | | group_union_covers | 组内并集覆盖判断（跨帧） | | group_by_frame | 同帧识别（同一时相上下景） | | group_by_orbit | 按 (方向, 轨道) 分组 | | run_download | 主流程（含轨道/卫星/逐时相严格校验） | | _confirm | 用户确认（y/轨道号/取消） |

analysis.py 核心函数

| 函数 | 职责 | |------|------| | check_per_date_coverage | 逐时相覆盖检查（每时相并集必须完全覆盖） | | check_orbit_consistency | 轨道一致性（同 frame 跨轨道检出） | | check_satellite_consistency | 卫星一致性（S1A/S1B/S1C） | | analyze_frame_coverage | 每帧覆盖面积比/景数/时相范围 | | sample_by_frequency | 按频率采样（月/季/半年/年/全部 + 时相规则） | | ask_frequency / ask_rule | 交互式询问采样频率与时相规则 | | export_list | 清单导出（TXT + CSV） | | plot_coverage | 研究区 vs 影像覆盖图 |

配套数据下载器（SBAS 完整数据链）

| 脚本 | 用途 | 官方源 | |------|------|--------| | poeorb_download.py | 精密轨道（POEORB）| ESA step.esa.int（免认证）| | gacos_download.py / gacos_fetch.py | GACOS 大气延迟 ztd（提交/收件）| gacos.net 表单 + 邮箱结果 | | dem_download.py | NASADEM 30m DEM | USGS e4ftl01（Earthdata）|

三者均从研究区/下载清单自动推导所需数据（分幅/时相/时刻），详见 SKILL.md「配套数据下载」章节。

🧪 测试（Testing）

pip install pytest
cd asf-sentinel1-download
python -m pytest tests/ -v

42 个测试全部通过，覆盖：

日期/极化/方向参数解析
shp/kml → WKT 转换（含 SARscape 三维坐标）
单景覆盖 + 跨帧并集覆盖
逐时相覆盖检查（每时相并集必须完全覆盖）
轨道一致性（同 frame 跨轨道检出）
卫星一致性（S1A/S1C）
frame 覆盖面积比分析
按频率采样（月/季/半年/年）
发布镜像一致性（根目录 vs skills/ 副本，防漂移）
文件名消毒、URL 白名单（安全）
清单格式、确认流程

⚠️ 已知限制（Known Limitations）

仅限 Sentinel-1 SLC IW：当前硬编码 processingLevel=SLC、beamMode=IW（最常用组合）；如需 GRD 或 EW 模式需修改代码
WGS84 坐标：shp 必须为经纬度坐标系（UTM 等投影需先转换）
大文件：SLC 单景约 4.5GB，8 景约 36GB，请确保磁盘空间充足
网络：ASF 大文件下载建议稳定网络；robust_download.py 提供断点续传

🤝 贡献（Contributing）

欢迎提交 PR 或 issue：

支持更多产品类型（GRD/EW）
增加 ASF 其他卫星（ALOS-2 等）
自动化 SBAS 预处理流程

📄 License

MIT License

🙏 致谢（Acknowledgments）

ASF (Alaska Satellite Facility) — 数据源与官方 Python 库
asf_search — 官方搜索库
shapely — 几何覆盖计算
本技能由 SAR 科研工作流驱动设计，用于 SBAS-InSAR 时序形变监测