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 同時設定 frame）。
• 面板標籤：大寫字母（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]，並以負高度翻轉軸：2D 剖面使用 projection="X<w>c/-<h>c"（負高度 → y 軸向下增加）；3D 立體圖使用 zsize="-<h>c"（負值 → 深層在底部，標籤為正）。切勿為了讓「上方 = 正」而輸出負的 z 資料——那會使深度軸出現負號。當你以這種方式翻轉 3D 的 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])         # 設定 session 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，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/swarm）	M 麥卡托 "M12c"
大陸級，低變形	L 蘭伯特圓錐 "L lon0/lat0/lat1/lat2/w"
定位插圖 / 半球	G 正射 "G lon0/lat0/w"
全球	W Mollweide / N Robinson / H Hammer
深度/距離剖面	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= 時，它會成為session 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 文件未提及的陷阱：region/國際換日線/投影陷阱、session-CPT 覆寫與「無 z 切片」錯誤、xarray gtype/registration 在算術後重置、grdimage 全黑、earth_relief 快取、字型設定範圍、多面板色條、0.x 參數重新命名、Ghostscript/conda 安裝修正。§8 實戰陷阱： inset basemap 會刪除註記/標籤（手動繪製或使用 shift_origin）；inset 強制預設圖框，因此 box="+p" 會造成雙重圖框；meca +m 的 Mw 比例縮放不可見（需手動調整 beachball 大小）；meca(cmap=True) 對負深度會導致記憶體分割錯誤；手寫 rasterio tif → grdimage 會導致記憶體分割錯誤（改用 xarray）；shading 維度不符（先用 grdsample）；inset 色條標籤溢出（+mal）；fig.plot(fill="white") 會增加不必要的黑色邊框。§9 向量箭頭 (style="v")： +g/+h 並未損壞——箭頭僅在同時傳入 +e/+b 時才會出現；長度小於箭頭長度的向量會無聲地失去箭頭（以 +n<len> 修正）；+h 接近 1 時箭頭會退化，使填充消失。當 PyGMT 圖件行為異常或意外報錯時，請閱讀此文件。
• CRAFT.md — 社群出版工藝：畫家模型圖層順序、科學色圖（分歧色圖必須以零為中心且對稱）、山影方位角慣例、比例尺/指北針/經緯網、多面板對齊與共享色條、向量 vs 點陣匯出、地震構造圖層。請閱讀此文件以讓圖件看起來更美觀且達到投稿標準。
• GALLERY.md — 13 個可直接改編的場景範本（底圖、多面板、插圖、分類散點圖、速度場、直方圖、玫瑰圖、3D、等高線、剖面、雙軸）。
• scripts/ — 可執行、參數化的範本：displacement_map.py、seismicity_map.py、cross_section.py、multipanel_components.py。每個都可獨立執行並附帶示範資料；編輯頂部的 CONFIG 區塊。