PyGMT Plotting Skill

PyGMT-Plotting

PyGMT kapselt die Generic Mapping Tools. Jeder Methodenparameter akzeptiert sowohl den Python- vollständigen Namen (projection) als auch das GMT-Einbuchstaben-Alias (J) – dieser Skill verwendet die vollständigen Namen. Gitterverarbeitungsfunktionen geben xarray.DataArray zurück, wenn outgrid=None ist, sodass Ergebnisse direkt in Plotting-Funktionen verkettet werden können.

Erforderliches Abbildungsformat (Hausstil)

Alle wissenschaftlichen Abbildungen MÜSSEN diesen Formatregeln folgen:

• Rahmen: MAP_FRAME_TYPE='plain', MAP_FRAME_PEN='1p,black'. Niemals den Rahmen zweimal zeichnen (kein Basemap + Plot, die beide den Rahmen setzen).
• Panelbeschriftungen: GROSSBUCHSTABE (A, B, C...) in der oberen linken Ecke innerhalb des Rahmens, keine Klammern, fett ≥10p, quadratische Box (weiße Füllung + 0,8p schwarzer Stift, clearance='1.5p/1.5p/1.5p/1.5p'). Gleicher Abstand zu linkem und oberem Rand. Titeltext (z. B. „Osten“) separat oben zentriert.
• Achsenbeschriftungen: Nur am linken (W) und unteren (S) Rand.
• Farbskala: Horizontal unten, mit Einheitenbeschriftung, ausreichender Abstand zu Achsenbeschriftungen (+o0c/0.8c).
• Farbskala: vik für divergierende Verschiebung, sequenziell: inferno oder roma.
• Tiefenachsen lesen POSITIV, nach unten (zwingende Regel für Verwerfungs-/Querschnitts-/3D-Abbildungen): Die Tiefenachse muss mit 0, 20, 40 … (positive Kilometer) beschriftet sein, niemals 0, -20, -40. Speichern Sie die Tiefe als positiven Wert (Tiefe nimmt nach unten zu), setzen Sie den Regions-Tiefenbereich auf [0, zmax] und kippen Sie die Achse mit einer negativen Höhe: 2D-Querschnitte verwenden projection="X<w>c/-<h>c" (negative Höhe → y nimmt nach unten zu); 3D-Perspektivplots verwenden zsize="-<h>c" (negativ → tief unten, Beschriftungen positiv). Geben Sie niemals negative z-Daten aus, nur um „oben = positiv“ zu erreichen – das würde Minuszeichen auf der Tiefenachse platzieren. Wenn Sie eine 3D-z-Achse auf diese Weise kippen, kehrt sich auch die vertikale Komponente eines im Panel liegenden Aufwärtsvektors um (Aufwärts bedeutet nun abnehmende positive Tiefe).
• Keine Doppelrahmen: Subplot kümmert sich um den Rahmen → rufen Sie NICHT basemap(frame=) innerhalb von Panels auf.
• Selbstprüfung: Überprüfen/Inspizieren Sie das generierte Bild nach der Erstellung. Beheben Sie doppelte Rahmen, abgeschnittene Inhalte, inkonsistente Beschriftungen, bevor Sie es dem Benutzer zeigen.

Kurzstart

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])         # setzt die 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() zeigt eine Vorschau; fig.savefig("f.pdf") (Vektor) oder .png/.tif (Raster, dpi= übergeben).

Die drei universellen Parameter

Jeder Kartenbefehl akzeptiert diese; der erste Befehl setzt sie und spätere Befehle verwenden sie wieder.

• region (R) — [W, E, S, N] (Reihenfolge beachten: West, Ost, Süd, Nord). "g"/"d" = global; "JP" = ISO-Ländercode; +r für Eckkoordinaten anhängen.
• projection (J) — code[params/]width, Breite muss eine Einheit haben (c/i/p): "M12c" Mercator, "X10c/6c" linear, "L-100/35/33/45/12c" Lambert konisch, "G-120/40/12c" orthografisch.
• frame (B) — ["WSne", "xaf", "yaf+lLabel", "+tTitle"]. Großbuchstabe = Achse+Striche+Beschriftungen, Kleinbuchstabe = keine Beschriftungen. a=Annotation/Hauptstrich, f=Nebenstrich, g=Gitter. Achsenbeschriftungen +l funktionieren nur auf kartesischen (X) Projektionen, nicht auf geografischen.

Projektion / CPT auswählen (Spickzettel)

Bedarf	Projektion
Regionskarte (niedrig–mittlere Breite, InSAR/Swarm)	M Mercator "M12c"
Kontinental, geringe Verzerrung	L Lambert konisch "L lon0/lat0/lat1/lat2/w"
Übersichtskarte / Hemisphäre	G orthografisch "G lon0/lat0/w"
Global	W Mollweide / N Robinson / H Hammer
Tiefen-/Distanzschnitt	X linear, negative Höhe → y zeigt nach unten: "X12c/-4c"

Datenart	CPT
Divergierend (Verschiebung, Geschwindigkeit, Anomalie; null-zentriert)	vik, roma, broc, polar
Sequenziell skalar	inferno, roma, batlow, viridis, turbo
Topografie	geo (Land), oleron/relief (Land+Ozean), gray (Schummerung)
Zyklisch (phasengewickelt, Azimut)	romaO, vikO

Erstellen Sie eine CPT mit pygmt.makecpt(cmap="vik", series=[-50, 50, 5]) – ohne output= wird sie zur Session-CPT, sodass nachfolgende grdimage/plot(cmap=True)/colorbar sie automatisch verwenden. Histogramm-Äqualisierung der Farben eines Gitters mit pygmt.grd2cpt(grid=g, cmap="geo").

Hausstil (bei jeder Abbildung durchsetzen)

Dies sind die meinungsstarken Standardeinstellungen des Skills – überschreiben Sie sie, wenn das Zieljournal etwas anderes vorgibt:

1. Zeichnen in with pygmt.config(MAP_FRAME_TYPE="plain", MAP_FRAME_PEN="1p,black"): einwickeln. Niemals den Rahmen zweimal zeichnen (Subplot/Basemap kümmert sich darum – frame= nicht innerhalb von Panels erneut übergeben).
2. Achsenbeschriftungen nur am W (linken) und S (unteren) Rand → frame=["WSne", ...].
3. Panelbeschriftungen: GROSSBUCHSTABE (A, B, C…), keine Klammern, fett ≥10p, in einer quadratischen weißen Box (weiße Füllung + 0,8p schwarzer Stift), gleicher Abstand von links und oben:

   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. Farbskala: horizontal unten, mit Einheitenbeschriftung, großzügiger Abstand zu Achsenbeschriftungen: position="JBC+w8c/0.4c+h+o0c/0.8c", frame="x+lQuantity (unit)".
5. Divergierende Verschiebung → vik; sequenziell → inferno/roma.
6. Rasterauflösung – kein Moiré (harte Regel): Bei der Darstellung von Interferenz-/Speckle-Gittern (phasengewickelte Interferogramme, Kohärenz) MUSS die Pixelanzahl des gerenderten Panels ≥ der nativen Spalten des Gitters sein: panel_cm × dpi / 2,54 >= n_columns. Standard: Einzelpanel ≥16 cm bei dpi=400 (GMT modern mode: gmt begin fig png E400). Wenn ein Mehrpanel-Layout unterabtasten würde, teilen Sie es in Einzelpanel-Abbildungen auf, anstatt zu verkleinern. Unterabgetastete dichte Interferenzstreifen erzeugen Moiré-Wellen – ein wiederkehrendes Fehlermuster bei ScanSAR-phasengewickelten Panels.
7. Selbstprüfung: Lesen Sie das Ausgabebild nach dem Speichern und beheben Sie doppelte Rahmen, abgeschnittene Inhalte, inkonsistente Beschriftungen oder Moiré-/gitterartige falsche Texturen in Bereichen mit dichten Interferenzstreifen, bevor Sie es dem Benutzer zeigen.

Arbeitsablauf für eine neue Abbildung

1. Bestimmen Sie Region, Projektion und CPT anhand des obigen Spickzettels.
2. Wählen Sie die nächstgelegene Vorlage in GALLERY.md oder scripts/ aus und passen Sie sie an.
3. Zeichnen Sie innerhalb des Hausstil-config-Blocks; bauen Sie untere → obere Ebene auf (Relief → Küste → Daten → Annotationen → Farbskala).
4. fig.savefig(..., dpi=300) (dpi=400+ und die Pixelanzahl-Regel für Interferenz-/Speckle-Raster prüfen), dann das Bild lesen und selbst prüfen (Schritt 7 oben).

Referenzen

• REFERENCE.md — vollständige API: Figure-Lebenszyklus, coast/plot/text, grdimage/grdcontour/grdview, makecpt/colorbar, Datensätze, Gitterverarbeitung (grdcut/grdgradient/grdtrack/surface…), xarray, meca, velo, project, subplot/inset/shift_origin/legend.
• GOTCHAS.md — aus der Community zusammengetragene Fallstricke, die die API-Dokumentation nicht erwähnt: Region/Datumsgrenze/Projektionsfallen, Session-CPT-Überschreibung und „no z-slices“-Fehler, xarray gtype/registration-Reset nach Arithmetik, grdimage-ganz-schwarz, earth_relief-Cache, Font-Konfiguration-Gültigkeitsbereich, Mehrpanel-Farbskalen, 0.x-Parameterumbenennungen, Ghostscript/Conda-Installationskorrekturen. §8 praxiserprobte Fallen: Inset-Basemap verliert Annotationen/Beschriftungen (manuell zeichnen oder shift_origin verwenden); Inset erzwingt einen Standardrahmen, sodass box="+p" einen doppelten Rahmen erzeugt; meca +m Mw-Skalierung ist unsichtbar (Beachballs manuell skalieren); meca(cmap=True) bei negativen Tiefen führt zu Segfault; handgeschriebenes rasterio-tif → grdimage führt zu Segfault (stattdessen xarray verwenden); shading-Dimensionskonflikt (zuerst grdsample); Inset-Farbskalen-Beschriftungsüberlauf (+mal); fig.plot(fill="white") fügt einen unpassenden schwarzen Rand hinzu. §9 Vektorpfeilspitzen (style="v"): +g/+h sind NICHT kaputt – ein Kopf erscheint nur, wenn Sie auch +e/+b übergeben, ein Vektor, der kürzer als die Kopflänge ist, verliert still seinen Kopf (Behebung mit +n<len>), und +h nahe 1 degeneriert den Kopf, sodass die Füllung verschwindet. Lesen Sie dies, wenn eine PyGMT-Abbildung sich falsch verhält oder unerwartet einen Fehler ausgibt.
• CRAFT.md — wissenschaftliche Publikationshandwerkskunst aus der Community: Malermodell-Schichtenreihenfolge, wissenschaftliche Farbskalen (divergierend muss null-zentriert und symmetrisch sein), Schummerungs-Azimutkonventionen, Maßstabsleiste/Kompass/Gitternetz, Mehrpanel-Ausrichtung und gemeinsame Farbskalen, Vektor-vs-Rasterexport, seismotektonische Schichtung. Lesen Sie dies, um eine Abbildung gut aussehen und einreichungsbereit zu machen.
• GALLERY.md — 13 sofort anpassbare Szenariovorlagen (Basemap, Mehrpanel, Inset, klassifiziertes Streudiagramm, Geschwindigkeitsfeld, Histogramm, Rosendiagramm, 3D, Konturen, Querschnitt, Doppelachse).
• scripts/ — ausführbare, parametrisierte Vorlagen: displacement_map.py, seismicity_map.py, cross_section.py, multipanel_components.py. Jede läuft eigenständig mit Beispieldaten; bearbeiten Sie den CONFIG-Block oben.