PyGMTSAR API参考手册:Stack、PRM、S1、ASF核心类方法与参数速查
PyGMTSAR API参考手册:Stack、PRM、S1、ASF核心类方法与参数速查
PyGMTSAR(Python InSAR)是一个面向 Sentinel-1 卫星干涉测量(InSAR)的 Python 开源库,支持 SBAS、PSI 等时序形变分析。本文是 PyGMTSAR 的 API 参考手册,对四大核心类 Stack、PRM、S1、ASF 的常用方法、参数与返回值进行速查整理,帮助新手和普通用户快速搭建完整的 InSAR 处理流程。
📌 当前版本:
2025.4.8.post1(见 pygmtsar/pygmtsar/init.py),可通过pip install pygmtsar安装,Docker 部署方式见 docker/README.md。
一、核心类一览:谁负责什么?
| 类 | 职责 | 源码位置 |
|---|---|---|
Stack |
InSAR 时序处理主入口,聚合了干涉、解缠、SBAS、PSI、地理编码、导出等全部处理方法 | pygmtsar/pygmtsar/Stack.py |
PRM |
封装单景 Sentinel-1 的 PRM 元数据(参数读写、基线计算、SLC 读取) | pygmtsar/pygmtsar/PRM.py |
S1 |
Sentinel-1 场景扫描、burst 几何提取、轨道文件下载 | pygmtsar/pygmtsar/S1.py |
ASF |
从 Alaska Satellite Facility(ASF)数据池下载 SLC 场景与 burst 数据 | pygmtsar/pygmtsar/ASF.py |
Stack 类通过 20 多个 Mixin 类继承链获得全部能力(Stack → Stack_export → Stack_ps → … → Stack_prm → Stack_base → IO → datagrid),因此你只需要一个 Stack 对象就能调用所有功能。下图就是使用这些类完成的 SBAS 时序分析结果(土耳其地震形变场):
典型流程代码速览
下面是一个最小可用的 PyGMTSAR 工作流(完整注释版见 tests/imperial_valley_2015.py):
from pygmtsar import S1, Stack, ASF, Tiles
# 1. 下载场景、轨道与 DEM
asf = ASF(username, password)
asf.download(DATADIR, SCENES, SUBSWATH)
scenes = S1.scan_slc(DATADIR)
S1.download_orbits(DATADIR, scenes)
Tiles().download_dem(scenes, filename='dem.nc')
# 2. 初始化 Stack 并配置
stack = Stack('raw', drop_if_exists=True)
stack.set_scenes(scenes).set_reference('2015-04-03')
stack.load_dem('dem.nc', scenes)
stack.compute_align() # 配准(计算子带偏移)
pairs = stack.sbas_pairs(days=100, meters=150) # SBAS 对
stack.compute_geocode() # 构建地理编码网格
# 3. 干涉与解缠
data = stack.open_data()
phase = stack.multilooking(stack.phasediff(pairs), wavelength=400, coarsen=(1, 4))
corr = stack.correlation(phase, stack.multilooking(np.square(np.abs(data)), wavelength=400, coarsen=(1, 4)))
intf = stack.interferogram(stack.goldstein(phase, corr, 32))
unwrap = stack.unwrap_snaphu(intf, corr)
# 4. 时序分析与导出
disp = stack.los_displacement_mm(
stack.lstsq(unwrap - stack.gaussian(unwrap, wavelength=60000), corr))
stack.export_geotiff(disp, 'disp')
二、PRM 类:元数据与方法速查表
PRM 对象本质是一张"参数名 = 参数值"的键值表(内部为 pandas DataFrame),常用 PRM 参数包括 near_range、num_rng_bins、num_valid_az、PRF、rng_samp_rate、SC_clock_start、SC_height、SLC_file、led_file、rshift/ashift 等。示例 PRM 文件可在 todo/baseline/S1_20201222_ALL_F2.PRM 查看。
创建与读写
| 方法 | 签名 | 说明 |
|---|---|---|
| 从文件创建 | PRM.from_file(prm_filename) |
读取 PRM 文件为对象,自动记录 filename |
| 从字符串创建 | PRM.from_str(prm_string) |
支持 str/bytes |
| 从列表创建 | PRM.from_list(prm_list) |
参数行列表 |
| 取值 | prm.get(*args) |
单参数返回标量,多参数返回列表,整型参数自动转 int |
| 赋值 | prm.set(prm=None, **kwargs) |
批量或逐项设置,如 prm.set(near_range=800000) |
| 选取 | prm.sel('near_range', 'PRF') |
只保留指定参数,生成新 PRM |
| 比较 | prm.diff(other) |
返回两个 PRM 的差异 DataFrame |
| 写回 | prm.to_file(path) / prm.update() |
保存为 PRM 文件 |
以上方法定义见 pygmtsar/pygmtsar/PRM.py。
核心计算方法
| 方法 | 签名 | 说明 |
|---|---|---|
| 读取 SLC | prm.read_SLC_int(scale=2.5e-07, shape=None) |
用 Dask 分块读取二进制 SLC,返回 re/im 的 xarray 数据集 |
| 基线计算 | prm1.SAT_baseline(prm2, tail=None) |
计算 B_parallel/B_perpendicular,SBAS 选对的核心依据 |
| 多普勒/轨道修正 | prm.calc_dop_orb(earth_radius=0, doppler_centroid=0, inplace=False) |
更新轨道参数 |
| 坐标转换 | prm.SAT_llt2rat(coords=None, fromfile=None, tofile=None, precise=1, binary=False) |
经纬高 ↔ 雷达坐标 |
| 视线参数 | prm.SAT_look(coords=None, ...) |
计算入射角、视线方向 |
| 偏移拟合 | PRM.fitoffset(rank_rng, rank_azi, matrix=None, matrix_fromfile=None, SNR=20) |
基于互相关矩阵稳健拟合配准偏移 |
| 稳健回归 | PRM.robust_trend2d(data, rank) |
GMT trend2d 的 Python 替代,rank 取 1/2/3 |
| 像元间距 | prm.get_spacing(grid=1) |
返回方位/距离向像元尺寸(米) |
| 读取 LED 轨道 | prm.read_LED() |
解析 LED 文件为 DataFrame(含 clock 列) |
| 基线投影 | prm.get_baseline_projections(other, baseline, alpha) |
返回平行/垂直基线分量 |
SAT_baseline 等 GMTSAR 移植方法位于 pygmtsar/pygmtsar/PRM_gmtsar.py,read_SLC_int 位于 pygmtsar/pygmtsar/PRM.py。
⚠️ 小提示:2.5e-07 是 Sentinel-1 的缩放因子,open_data()/read_SLC_int() 默认乘上该值还原复数幅度,一般无需改动。
三、S1 类:场景扫描与轨道下载参数速查
S1 是静态方法类,不需要实例化。
S1.scan_slc() — 扫描本地 SLC 场景
签名:S1.scan_slc(datadir, orbit=None, mission=None, subswath=None, polarization=None, calibration=False),定义见 pygmtsar/pygmtsar/S1.py。
| 参数 | 取值 | 说明 |
|---|---|---|
datadir |
目录路径 | 递归搜索 .tiff/.xml/.EOF 文件 |
orbit |
'A' / 'D' / None |
升/降轨过滤 |
mission |
'S1A' / 'S1B' / None |
卫星过滤 |
subswath |
1 2 3 12 23 123 / None |
子带过滤 |
polarization |
'VV' 'VH' 'HH' 'HV' / None |
极化过滤 |
calibration |
bool |
是否同时定位 noise/calibration 文件 |
返回以日期为索引的 GeoDataFrame,列含 datetime、orbit、mission、polarization、subswath、datapath、metapath、orbitpath、geometry(burst 多边形),可直接交给 Stack.set_scenes()。
S1.download_orbits() — 下载精确轨道文件
签名:S1.download_orbits(basedir, scenes, n_jobs=8, joblib_backend='loky', skip_exist=True, retries=30, timeout_second=3),定义见 pygmtsar/pygmtsar/S1.py。scenes 可传场景名列表或 scan_slc() 的返回值;优先下载 RESORB,失败时回退 POEORB;下载带 30 次重试,断网续传友好。
辅助方法:S1.read_annotation(filename)(解析场景 XML)、S1.get_geoloc(annotation)(GCP 网格)、S1.geoloc2bursts(metapath)(burst 边界多边形),分别位于 S1.py。
四、ASF 类:Sentinel-1 数据下载参数速查
ASF 需要 Earthdata 账号(免费申请)。
| 方法 | 签名要点 | 说明 |
|---|---|---|
| 初始化 | ASF(username=None, password=None) |
缺省时交互式输入账号密码 |
| 搜索 | ASF.search(geometry, startTime, stopTime, flightDirection=None, platform='SENTINEL-1', processingLevel='auto', polarization='VV', beamMode='IW') |
返回 burst 级 GeoDataFrame |
| 统一入口 | asf.download(basedir, scenes_or_bursts, subswaths=None, polarization='VV', **kwargs) |
自动区分整景(-SLC)与 burst(-BURST) |
| 下载整景 | asf.download_scenes(basedir, scenes, subswaths, polarization='VV', session=None, n_jobs=4, skip_exist=True, retries=30, timeout_second=3, debug=False) |
只下载所需子带与极化,省磁盘 |
| 下载 burst | asf.download_bursts(basedir, bursts, session=None, n_jobs=8, skip_exist=True, retries=30, ...) |
自动重构 burst 级 .tiff/.xml/noise/calibration 文件 |
| 可视化 | ASF.plot(bursts) |
绘制 burst 足迹图 |
定义分别位于 ASF.py、ASF.py、ASF.py。下载均支持断点续传(skip_exist=True 时自动跳过完整文件),失败自动重试 30 次。
五、Stack 类:时序处理流水线方法速查
初始化与配置
stack = Stack('raw', drop_if_exists=True) # 已存在时报错,除非 drop_if_exists=True
stack.set_scenes(scenes) # 传入 S1.scan_slc() 的 GeoDataFrame
stack.set_reference('2015-04-03') # 指定参考景(日期字符串)
stack.to_dataframe() # 查看内部场景表
stack.plot_scenes() # 可视化场景覆盖范围
__init__(basedir, drop_if_exists=False) 与 set_scenes(scenes) 定义见 pygmtsar/pygmtsar/Stack.py;set_reference、get_pairs、get_pairs_matrix 见 Stack_base.py。
处理流水线:按顺序速查
| 阶段 | 方法 | 关键参数 | 源码 |
|---|---|---|---|
| PRM 访问 | stack.PRM(date=None, subswath=None)、stack.PRM_merged() |
打开单景/合并后 PRM | Stack_prm.py |
| 数据读取 | stack.open_data(dates=None, subswath=None, scale=2.5e-07) |
返回复数 SLC 堆栈(date 维) |
IO.py |
| 配准 | stack.compute_align(geometry='auto', dates=None, n_jobs=-1, degrees=12/3600) |
计算并应用子带间偏移 | Stack_align.py |
| SBAS 选对 | stack.sbas_pairs(days=None, meters=None, invert=False, dates=None) |
时基线(天)/空基线(米)约束 | Stack_sbas.py |
| SBAS 绘图 | stack.plot_baseline(pairs, caption='Baseline') |
基线图 | Stack_sbas.py |
| 地理编码 | stack.compute_geocode(coarsen=60.) |
默认 60 m 输出网格 | Stack_geocode.py |
| 相干干涉 | stack.phasediff(pairs, data='auto', topo='auto', ...) |
计算干涉图与 topo 相位 | Stack_phasediff.py |
| 多视 | stack.multilooking(data, weight=None, wavelength=None, coarsen=None) |
高斯滤波 + 多视降采样 | Stack_multilooking.py |
| 滤波/相干 | stack.goldstein(phase, corr, psize=32)、stack.correlation(phase, intensity)、stack.interferogram(phase) |
Goldstein 自适应滤波与相干系数 | Stack_phasediff.py |
| 解缠 | stack.unwrap_snaphu(phase, weight=None, conf=None, conncomp=False);一维解缠 stack.unwrap1d(data, weight=None, tolerance=π/2) |
基于 SNAPHU/一维动态规划 | Stack_unwrap.py |
| 去趋势 | stack.gaussian(data, wavelength, truncate=3.0, resolution=60) |
高斯平滑去大气/潮汐趋势 | Stack_detrend.py |
| 最小二乘 | stack.lstsq(data, weight=None, matrix='auto', cumsum=True) |
相干加权 SBAS 解算 | Stack_lstsq.py |
| 速度 | stack.velocity(data) |
由累积位移求速率 | Stack_detrend.py |
| 单位换算 | stack.los_displacement_mm(data) |
弧度 → 视线向毫米 | Stack_incidence.py |
| PSI | stack.compute_ps(geometry=None, dates=None, data='auto', name='ps') |
永久散射体提取 | Stack_ps.py |
| 地理坐标 | stack.ra2ll(data, autoscale=True) |
雷达坐标 → 经纬度 | Stack_geocode.py |
| DEM | stack.load_dem(dem, geometry='auto')、stack.download_dem(geometry='auto', product='1s')、stack.get_dem()、stack.set_dem(filename) |
加载/下载/管理 DEM | Stack_dem.py |
| 导出 | stack.export_geotiff(data, name, compress='LZW')、stack.export_vtk(data, name, topo='auto', mask=None)、export_csv / export_geojson / export_netcdf |
GeoTIFF、3D VTK、CSV 等 | Stack_export.py |
| 状态管理 | stack.dump(to_path=None)、Stack.restore(from_path)、stack.open_stack(name)、stack.save_stack(data, name) |
保存/恢复对象状态与 2D 堆栈 | IO.py |
💡 长流程建议随时 stack.dump() 把进度存成 stack.pickle,中断后用 Stack.restore() 秒级续算,不必重跑下载与配准。
下图是用 velocity() + export_vtk() 输出的 Golden Valley 沉降速度场(>5 cm/年):
六、辅助类速查:DEM、地图瓦片与工具函数
| 类 | 常用方法 | 说明 |
|---|---|---|
Tiles |
Tiles().download_dem(geometry, filename=None, product='1s', provider='GLO', skip_exist=True, n_jobs=8);download_landmask(...) |
从开放存储下载 Copernicus GLO/SRTM/ALOS DEM 与陆地掩膜 |
AWS |
AWS().download_dem(...) |
⚠️ 已废弃,内部会提示改用 Tiles().download_dem(),见 AWS.py |
GMT |
GMT.download_dem(...) / download_landmask(...) |
基于 GMT 服务器的传统下载方式 |
XYZTiles |
download_googlemaps / download_openstreetmap / download_openrailwaymap 等 |
下载地图瓦片做底图 |
utils |
nanconvolve2d_gaussian、interp2d_like、binary_erosion 等 |
高斯滤波、插值、形态学工具 |
MultiInstanceManager |
MultiInstanceManager(*instances) |
对多个 Stack 实例批量调用同一方法 |
Tiles.download_dem 定义见 pygmtsar/pygmtsar/Tiles.py。相干系数(correlation)也是重要产品——例如澳大利亚 Kalkarindji 洪水事件中,相干损失直接勾勒出淹没范围:
七、官方示例脚本与配套资料
仓库 tests/ 目录提供 9 个可运行的完整案例脚本,建议对照 API 逐个阅读:
- 地震形变:tests/türkiye_earthquakes_2023.py、tests/iran–iraq_earthquake_2017.py
- 沉降监测:tests/imperial_valley_2015.py、tests/goldenvalley.py
- 火山喷发:tests/pico_do_fogo_volcano_eruption_2014.py、tests/la_cumbre_volcano_eruption_2020.py
- 其他:tests/kalkarindji_flooding_2024.py(洪水)、tests/lakesarez_landslides_2017.py(滑坡)、tests/türkiye_elevation_2019.py(DEM 反演)
配套资料:
- 📖 官方预览电子书:book/PyGMTSAR_preview.pdf
- 🐳 一键安装脚本(Colab):pygmtsar/pygmtsar/data/google_colab.sh
- 🐳 Docker 镜像说明:docker/README.md
- 📜 已发表项目与论文清单:pubs/README.md
八、新手常见疑问 FAQ
Q1:Stack('raw') 报 "The base directory already exists"?
这是保护机制。确认目录可删除后加 drop_if_exists=True 重建,或换一个 basedir 名称。
Q2:同一日期出现多景时 scan_slc() 提示要用 Stack.reframe()?
表示当天有多景拼接(stitched)场景,需调用 reframe 类方法拼合成单景后再处理。
Q3:sbas_pairs(days, meters) 与 baseline_pairs() 什么关系?
baseline_pairs(days=100, meters=None) 已更名,内部直接转发到 sbas_pairs(),新代码请使用 sbas_pairs。
Q4:解缠太吃内存怎么办?
降低干涉图分辨率(decimator 多视)、用 corr.where(corr>=阈值) 屏蔽低相干区,并通过 conf= 传入 SNAPHU 分块配置。
掌握以上四个类的核心方法,你已可覆盖 PyGMTSAR 从数据获取到成果发布的完整 InSAR 分析链路。祝分析顺利!


