PyGMTSAR API参考手册:Stack、PRM、S1、ASF核心类方法与参数速查

原创2026-11-16 19:40:42453 阅读

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 Stack 类 SBAS 时序 InSAR 形变分析结果示例

典型流程代码速览

下面是一个最小可用的 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/年):

PyGMTSAR SBAS 时序分析 InSAR 沉降速度图结果

六、辅助类速查: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 洪水事件中,相干损失直接勾勒出淹没范围:

PyGMTSAR InSAR 相干系数与淹没区识别结果

七、官方示例脚本与配套资料

仓库 tests/ 目录提供 9 个可运行的完整案例脚本,建议对照 API 逐个阅读:

配套资料:

八、新手常见疑问 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 分析链路。祝分析顺利!

登录后查看全文
pygmtsar