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]로 설정한 다음 음수 높이로 축을 뒤집습니다: 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])         # 세션 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` 몰바이데 / `N` 로빈슨 / `H` 해머
깊이/거리 단면	`X` 선형, 음수 높이 → y가 아래를 가리킴: `"X12c/-4c"`

데이터 종류	CPT
발산형 (변위, 속도, 이상치; 0-중심)	`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")를 사용합니다.

하우스 스타일 (모든 그림에 적용)

이것은 스킬의 주관적인 기본값입니다. 대상 저널이 달리 명시하면 재정의하십시오.

with pygmt.config(MAP_FRAME_TYPE="plain", MAP_FRAME_PEN="1p,black"): 안에서 그림을 그립니다. 프레임을 두 번 그리지 마십시오 (subplot/basemap이 처리하므로 패널 내부에서 frame=을 다시 전달하지 마십시오).
눈금 레이블은 W(왼쪽) 및 S(아래쪽) 가장자리에만 → frame=["WSne", ...].
패널 레이블: 대문자(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")
```
컬러바: 하단에 수평, 단위 레이블 포함, 축 레이블로부터 충분한 오프셋: position="JBC+w8c/0.4c+h+o0c/0.8c", frame="x+lQuantity (unit)".
발산형 변위 → vik; 순차형 → inferno/roma.
래스터 해상도 — 모아레 패턴 금지 (엄격 규칙): 간섭무늬/스펙클 그리드(래핑된 간섭도, 일관성)를 이미징할 때 렌더링된 패널 픽셀 수는 그리드의 기본 열 수보다 크거나 같아야 합니다: panel_cm × dpi / 2.54 >= n_columns. 기본값: 단일 패널 16cm 이상, dpi=400 (GMT 현대 모드: gmt begin fig png E400). 다중 패널 레이아웃에서 언더샘플링이 발생하면 축소하는 대신 단일 패널 그림으로 분할하십시오. 언더샘플링된 조밀한 간섭무늬는 모아레 리플로 에일리어싱됩니다. ScanSAR 래핑 위상 패널에서 반복적으로 발생하는 오류 모드입니다.
자가 점검: 저장 후 출력 이미지를 읽고 이중 프레임, 잘린 콘텐츠, 일관성 없는 레이블, 또는 조밀한 간섭무늬 영역의 모아레/그리드 같은 잘못된 질감을 수정한 후 사용자에게 보여주십시오.

새 그림 작업 흐름

위 치트 시트에서 영역, 투영법, CPT를 결정합니다.
GALLERY.md 또는 scripts/에서 가장 가까운 템플릿을 선택하여 적용합니다.
하우스 스타일 config 블록 안에서 그림을 그립니다. 아래쪽 레이어 → 위쪽 레이어(음영기복 → 해안선 → 데이터 → 주석 → 컬러바) 순서로 구축합니다.
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 — 커뮤니티 발행 기술: 페인터 모델 레이어 순서, 과학적 컬러맵(발산형은 0-중심 및 대칭이어야 함), 음영기복 방위각 규칙, 축척 막대/나침반/경위선망, 다중 패널 정렬 및 공유 컬러바, 벡터 대 래스터 내보내기, 지진지구조론적 레이어링. 그림을 보기 좋고 제출 준비가 되도록 만들려면 이 문서를 읽으십시오.
GALLERY.md — 13개의 즉시 적용 가능한 시나리오 템플릿(기본 지도, 다중 패널, 삽입도, 분류된 산점도, 속도장, 히스토그램, 장미도, 3D, 등고선, 단면, 이중 축).
scripts/ — 실행 가능한 파라미터화된 템플릿: displacement_map.py, seismicity_map.py, cross_section.py, multipanel_components.py. 각각 데모 데이터로 독립 실행 가능하며, 상단의 CONFIG 블록을 편집하십시오.

pygmt-plotting-skill