rookieplayerjr/pygmt-plotting-skill

PyGMT 绘图

PyGMT 封装了 Generic Mapping Tools。每个方法参数既接受 Python 全名（projection），也接受 GMT 单字母别名（J）——本技能使用全名。当 outgrid=None 时，栅格处理函数返回 xarray.DataArray，结果可直接链式传递给绘图函数。

必需的图形格式（期刊排版风格）

所有科学图形必须遵循以下格式规则：

• 框架：MAP_FRAME_TYPE='plain'，MAP_FRAME_PEN='1p,black'。切勿重复绘制框架（不要在同一个面板中同时使用 basemap 和 plot 设置框架）。
• 面板标签：大写字母（A, B, C...）位于框架内左上角，无括号，粗体 ≥10p，方形白底黑框（白色填充 + 0.8p 黑色笔触，clearance='1.5p/1.5p/1.5p/1.5p'）。与左边框和上边框距离相等。标题文本（例如“East”）分别居中于顶部。
• 刻度标签：仅出现在左（W）和下（S）边缘。
• 颜色条：水平置于底部，带单位标签，与轴标签有足够偏移（+o0c/0.8c）。
• 色标：发散型位移用 vik，顺序型用 inferno 或 roma。
• 深度轴正方向向下（断层/剖面/3D 图形硬性规则）：深度轴必须标记为 0, 20, 40 …（正公里数），绝不能是 0, -20, -40。将深度存储为正值（深度向下增加），设置区域深度范围为 [0, zmax]，并用负高度翻转轴：二维剖面使用 projection="X<w>c/-<h>c"（负高度 → y 向下增加）；三维透视图中使用 zsize="-<h>c"（负值 → 深处在底部，标签为正）。绝不要为了得到“向上为正”而输出负的 z 数据——那会在深度轴上添加负号。当以这种方式翻转三维 z 轴时，任何面内上倾矢量的垂直分量也会翻转符号（上倾现在意味着正深度减小）。
• 无双重框架：subplot 已处理框架 → 不要在面板内再次调用 basemap(frame=)。
• 自检：生成每张图形后，读取/检查。在展示给用户之前修复双重框架、内容被裁剪、标签不一致等问题。

快速起步

import pygmt

fig = pygmt.Figure()
with pygmt.config(MAP_FRAME_TYPE="plain", MAP_FRAME_PEN="1p,black"):
    fig.basemap(region=[-125, -114, 32, 42], projection="M12c", frame=["WSne", "xaf", "yaf"])
    fig.coast(land="gray90", water="white", shorelines="0.5p,black")
    pygmt.makecpt(cmap="vik", series=[-10, 10])         # 设置会话 CPT
    fig.plot(x=[-119.5], y=[35.3], style="c0.3c", fill=[5.0], cmap=True, pen="0.5p,black")
    fig.colorbar(frame="x+lVelocity (mm/yr)", position="JBC+w8c/0.4c+h+o0c/0.8c")
fig.savefig("map.png", dpi=300, crop=True)

fig.show() 预览；fig.savefig("f.pdf")（矢量）或 .png/.tif（栅格，需传 dpi=）。

三个通用参数

每个地图命令都接受这些参数；第一个命令设置它们，后续命令复用。

• region (R) — [W, E, S, N]（注意顺序：西、东、南、北）。"g"/"d" = 全球；"JP" = ISO 国家代码；追加 +r 表示角坐标。
• projection (J) — code[params/]width，宽度必须带单位（c/i/p）："M12c" 墨卡托，"X10c/6c" 线性，"L-100/35/33/45/12c" 兰伯特圆锥，"G-120/40/12c" 正射投影。
• frame (B) — ["WSne", "xaf", "yaf+lLabel", "+tTitle"]。大写字母边缘 = 轴 + 刻度 + 标注，小写 = 无标注。a=标注/主刻度，f=次刻度，g=网格。轴标签 +l 仅在笛卡尔（X）投影上生效，不适用于地理投影。

选择投影 / CPT（速查表）

需求	投影
区域地图（中低纬度，InSAR/群震）	M 墨卡托 "M12c"
大陆尺度，低畸变	L 兰伯特圆锥 "L lon0/lat0/lat1/lat2/w"
定位小图 / 半球	G 正射投影 "G lon0/lat0/w"
全球	W 摩尔威德 / N 罗宾逊 / H 汉默
深度/距离剖面	X 线性，负高度 → y 向下："X12c/-4c"

数据类型	CPT
发散型（位移、速度、异常；零居中）	vik, roma, broc, polar
顺序标量	inferno, roma, batlow, viridis, turbo
地形	geo（陆地）, oleron/relief（陆地+海洋）, gray（山体阴影）
循环型（包裹相位、方位角）	romaO, vikO

用 pygmt.makecpt(cmap="vik", series=[-50, 50, 5]) 创建一个 CPT —— 不带 output= 时会成为会话 CPT，之后的 grdimage/plot(cmap=True)/colorbar 会自动使用它。用 pygmt.grd2cpt(grid=g, cmap="geo") 对栅格颜色进行直方图均衡。

期刊排版风格（每张图形强制执行）

以下是本技能定制的默认风格——当目标期刊另有规定时覆盖它们：

1. 将绘图内容包裹在 with pygmt.config(MAP_FRAME_TYPE="plain", MAP_FRAME_PEN="1p,black"): 中。切勿重复绘制框架（subplot/basemap 已处理——不要在面板内部再次传递 frame=）。
2. 刻度标签仅出现在 **W（左）**和 **S（下）**边缘 → frame=["WSne", ...]。
3. 面板标签：大写字母（A, B, C…），无括号，粗体 ≥10p，放在方形白底黑框（白色填充 + 0.8p 黑色笔触）中，与左边框和上边框等距：

   fig.text(position="TL", text="A", font="12p,Helvetica-Bold,black",
            justify="TL", offset="j0.2c", fill="white", pen="0.8p,black", clearance="1.5p/1.5p")
   

4. 颜色条：水平置于底部，带单位标签，与轴标签有足够偏移：position="JBC+w8c/0.4c+h+o0c/0.8c"，frame="x+lQuantity (unit)"。
5. 发散型位移 → vik；顺序型 → inferno/roma。
6. 栅格分辨率——无莫尔条纹（硬性规则）：对条纹/散斑栅格（包裹干涉图、相干性）成像时，渲染面板的像素数必须 ≥ 栅格的原生列数：panel_cm × dpi / 2.54 >= n_columns。默认：单面板 ≥16 cm, dpi=400（GMT 现代模式：gmt begin fig png E400）。如果多面板布局会导致欠采样，应拆分为单面板图形而不是缩小尺寸。欠采样的密集条纹会产生莫尔波纹——这是 ScanSAR 包裹相位面板中反复出现的失败模式。
7. 自检：保存后，读取输出图像并修复双重框架、内容被裁剪、标签不一致或密集条纹区域的莫尔/类网格虚假纹理，然后再展示给用户。

新图形的绘制工作流

1. 根据上方速查表确定区域、投影和 CPT。
2. 在 GALLERY.md 或 scripts/ 中选择最接近的模板并加以改编。
3. 在排版风格 config 块内绘图；从底层到顶层构建（地形→海岸线→数据→标注→颜色条）。
4. fig.savefig(..., dpi=300)（对于条纹/散斑栅格使用 dpi=400+ 并检查像素数规则），然后读取图像并自检（上述第 7 步）。

参考资料

• REFERENCE.md — 完整 API：图形生命周期、coast/plot/text、grdimage/grdcontour/grdview、makecpt/colorbar、数据集、栅格处理（grdcut/grdgradient/grdtrack/surface…）、xarray、meca、velo、project、subplot/inset/shift_origin/legend。
• GOTCHAS.md — 社区收集的 API 文档未提及的陷阱：区域/日期线/投影陷阱、会话 CPT 覆盖与“无 z 切片”错误、xarray gtype/registration 在算术运算后重置、grdimage 全黑、earth_relief 缓存、字体配置作用域、多面板颜色条、0.x 参数重命名、Ghostscript/conda 安装修复。§8 经过实地验证的陷阱： 小图 basemap 丢失标注/标签（手动绘制或使用 shift_origin）；小图强制默认框架导致 box="+p" 产生双重框架；meca +m 的 Mw 缩放不可见（需手动缩放海滩球大小）；meca(cmap=True) 在负深度上段错误；手写 rasterio tif → grdimage 段错误（改用 xarray）；shading 维度不匹配（先 grdsample）；小图颜色条标签溢出（+mal）；fig.plot(fill="white") 添加多余的黑色边框。§9 矢量箭头（style="v"）： +g/+h 并非损坏——只有同时传递 +e/+b 时箭头头才会出现；矢量长度小于箭头头长度会静默丢失箭头（用 +n<len> 修复）；+h 接近 1 时箭头头退化，填充消失。当 PyGMT 图形行为异常或意外报错时，请阅读此文件。
• CRAFT.md — 社区出版工艺：画家模型图层顺序、科学色图（发散型必须零居中且对称）、山体阴影方位角约定、比例尺/指北针/经纬网、多面板对齐与共享颜色条、矢量 vs 栅格导出、地震构造分层。阅读此文件以使图形美观并达到投稿标准。
• GALLERY.md — 13 个可直接改编的场景模板（底图、多面板、小图、分类散点图、速度场、直方图、玫瑰图、三维、等高线、剖面、双轴）。
• scripts/ — 可运行、参数化的模板：displacement_map.py、seismicity_map.py、cross_section.py、multipanel_components.py。每个脚本都附带示例数据可独立运行；编辑顶部的 CONFIG 块即可。