rookieplayerjr/pygmt-plotting-skill

PyGMT Plotting

PyGMT encapsule les outils Generic Mapping Tools. Chaque paramètre de méthode accepte à la fois un nom complet Python (projection) et l'alias d'une lettre GMT (J) — cette compétence utilise les noms complets. Les fonctions de traitement de grille retournent xarray.DataArray quand outgrid=None, ce qui permet d'enchaîner les résultats directement dans les fonctions de traçage.

Format de figure requis (style maison)

Toutes les figures scientifiques DOIVENT suivre ces règles de mise en forme :

• Cadre : MAP_FRAME_TYPE='plain', MAP_FRAME_PEN='1p,black'. Ne jamais dessiner le cadre deux fois (pas de basemap + plot qui définissent tous deux le cadre).
• Étiquettes de panneaux : lettre MAJUSCULE (A, B, C...) dans le coin supérieur gauche à l'intérieur du cadre, sans parenthèses, gras ≥10p, boîte carrée (remplissage blanc + trait noir 0,8p, clearance='1.5p/1.5p/1.5p/1.5p'). Distance égale des bords gauche et supérieur. Le texte du titre (ex. "Est") centré en haut séparément.
• Étiquettes de graduation : uniquement sur les bords gauche (W) et inférieur (S).
• Barre de couleur : horizontale en bas, avec étiquette d'unité, décalage suffisant par rapport aux étiquettes d'axe (+o0c/0.8c).
• Échelle de couleur : vik pour les données divergentes de déplacement, séquentielle : inferno ou roma.
• Les axes de profondeur se lisent POSITIFS, vers le bas (règle stricte pour les figures de failles/coupes/3D) : l'axe de profondeur doit être étiqueté 0, 20, 40 … (kilomètres positifs), jamais 0, -20, -40. Stocker la profondeur comme une valeur positive (la profondeur augmente vers le bas), définir la plage de profondeur de la région sur [0, zmax], et inverser l'axe avec une hauteur négative : les coupes 2D utilisent projection="X<w>c/-<h>c" (hauteur négative → y croît vers le bas) ; les perspectives 3D utilisent zsize="-<h>c" (négatif → profond en bas, étiquettes positives). Ne jamais émettre de données z négatives pour obtenir "haut = positif" — cela mettrait des signes moins sur l'axe de profondeur. Lorsque vous inversez un axe z 3D de cette manière, la composante verticale de tout vecteur dans le plan pointant vers le haut change également de signe (vers le haut signifie maintenant une diminution de la profondeur positive).
• Pas de double cadre : le sous-plot gère le cadre → ne PAS appeler basemap(frame=) à l'intérieur des panneaux.
• Auto-vérification : après avoir généré chaque figure, la lire/inspecter. Corriger les doubles cadres, le contenu tronqué, les étiquettes incohérentes avant de montrer à l'utilisateur.

Démarrage rapide

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])          # définit la CPT de session
    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() prévisualise ; fig.savefig("f.pdf") (vectoriel) ou .png/.tif (raster, passer dpi=).

Les trois paramètres universels

Chaque commande de carte les prend ; la première commande les définit et les suivantes les réutilisent.

• region (R) — [W, E, S, N] (noter l'ordre : Ouest, Est, Sud, Nord). "g"/"d" = global ; "JP" = code pays ISO ; ajouter +r pour les coordonnées des coins.
• projection (J) — code[params/]width, la largeur doit porter une unité (c/i/p) : "M12c" Mercator, "X10c/6c" linéaire, "L-100/35/33/45/12c" conique de Lambert, "G-120/40/12c" orthographique.
• frame (B) — ["WSne", "xaf", "yaf+lLabel", "+tTitle"]. Lettre majuscule pour bord = axe+graduations+annotations, minuscule = pas d'annotations. a=annotation/majeure, f=mineure, g=grille. Les étiquettes d'axe +l fonctionnent uniquement sur les projections cartésiennes (X), pas géographiques.

Choisir une projection / CPT (aide-mémoire)

Besoin	Projection
Carte régionale (basses–moyennes latitudes, InSAR/essaim)	M Mercator "M12c"
Continentale, faible distorsion	L conique de Lambert "L lon0/lat0/lat1/lat2/w"
Encart de localisation / hémisphère	G orthographique "G lon0/lat0/w"
Globale	W Mollweide / N Robinson / H Hammer
Coupe profondeur/distance	X linéaire, hauteur négative → y vers le bas : "X12c/-4c"

Type de données	CPT
Divergentes (déplacement, vitesse, anomalie ; centrées sur zéro)	vik, roma, broc, polar
Scalaire séquentiel	inferno, roma, batlow, viridis, turbo
Topographie	geo (terre), oleron/relief (terre+océan), gray (ombrage)
Cycliques (phase enroulée, azimut)	romaO, vikO

Créer une CPT avec pygmt.makecpt(cmap="vik", series=[-50, 50, 5]) — sans output= elle devient la CPT de session, donc les grdimage/plot(cmap=True)/colorbar suivants l'utilisent automatiquement. Égaliser l'histogramme des couleurs d'une grille avec pygmt.grd2cpt(grid=g, cmap="geo").

Style maison (appliquer à chaque figure)

Ce sont les valeurs par défaut opinionnées de cette compétence — les remplacer si la revue cible dit autrement :

1. Envelopper le dessin dans with pygmt.config(MAP_FRAME_TYPE="plain", MAP_FRAME_PEN="1p,black"):. Ne jamais dessiner le cadre deux fois (subplot/basemap le gère — ne pas repasser frame= à l'intérieur des panneaux).
2. Étiquettes de graduation uniquement sur les bords W (gauche) et S (bas) → frame=["WSne", ...].
3. Étiquettes de panneaux : lettre MAJUSCULE (A, B, C…), sans parenthèses, gras ≥10p, dans une boîte blanche carrée (remplissage blanc + trait noir 0,8p), décalage égal par rapport à la gauche et au haut :

   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. Barre de couleur : horizontale en bas, avec étiquette d'unité, décalage généreux par rapport aux étiquettes d'axe : position="JBC+w8c/0.4c+h+o0c/0.8c", frame="x+lQuantity (unité)".
5. Données divergentes de déplacement → vik ; séquentielles → inferno/roma.
6. Résolution raster — pas de moiré (règle stricte) : lors de l'imagerie de grilles de franges/speckle (interférogrammes enroulés, cohérence), le nombre de pixels du panneau rendu DOIT être ≥ le nombre de colonnes natif de la grille : cm_panneau × dpi / 2.54 >= n_colonnes. Par défaut : panneau simple ≥16 cm à dpi=400 (mode moderne GMT : gmt begin fig png E400). Si une disposition multi-panneaux sous-échantillonnerait, diviser en figures à panneau unique au lieu de réduire la taille. Les franges denses sous-échantillonnées se replient en ondulations de moiré — un mode de défaillance récurrent sur les panneaux de phase enroulée ScanSAR.
7. Auto-vérification : après sauvegarde, lire l'image de sortie et corriger les doubles cadres, le contenu tronqué, les étiquettes incohérentes ou la texture de moiré/fausse grille dans les zones de franges denses avant de montrer à l'utilisateur.

Workflow pour une nouvelle figure

1. Déterminer la région, la projection et la CPT à partir de l'aide-mémoire ci-dessus.
2. Choisir le modèle le plus proche dans GALLERY.md ou scripts/ et l'adapter.
3. Dessiner à l'intérieur du bloc de configuration du style maison ; construire couche inférieure → couche supérieure (relief → côte → données → annotations → barre de couleur).
4. fig.savefig(..., dpi=300) (dpi=400+ et vérifier la règle du nombre de pixels pour les rasters de franges/speckle), puis lire l'image et s'auto-vérifier (étape 7 ci-dessus).

Références

• REFERENCE.md — API complète : cycle de vie de la figure, coast/plot/text, grdimage/grdcontour/grdview, makecpt/colorbar, jeux de données, traitement de grille (grdcut/grdgradient/grdtrack/surface…), xarray, meca, velo, project, subplot/inset/shift_origin/legend.
• GOTCHAS.md — pièges signalés par la communauté que la documentation de l'API ne mentionne pas : pièges région/ligne de changement de date/projection, écrasement de la CPT de session et erreur "pas de z-slices", réinitialisation du type/registration xarray après opération arithmétique, grdimage tout noir, cache earth_relief, portée de la configuration des polices, barres de couleur multi-panneaux, renommage des paramètres 0.x, correctifs d'installation Ghostscript/conda. §8 pièges testés sur le terrain : l'encart basemap supprime les annotations/étiquettes (les dessiner manuellement ou utiliser shift_origin) ; l'encart force un cadre par défaut donc box="+p" crée un double cadre ; meca +m le redimensionnement Mw est invisible (tailler les beachballs manuellement) ; meca(cmap=True) sur des profondeurs négatives provoque un segfault ; un geotiff rasterio écrit à la main → grdimage segfault (utiliser xarray à la place) ; décalage de dimension shading (utiliser grdsample d'abord) ; débordement d'étiquette de barre de couleur d'encart (+mal) ; fig.plot(fill="white") ajoute une bordure noire parasite. §9 pointes de flèches vecteurs (style="v") : +g/+h ne sont PAS cassés — une tête n'apparaît que si vous passez aussi +e/+b, un vecteur plus court que la longueur de la tête perd silencieusement sa tête (corriger avec +n<len>), et +h proche de 1 dégénère la tête donc le remplissage disparaît. Lire ceci quand une figure PyGMT se comporte mal ou génère une erreur inattendue.
• CRAFT.md — savoir-faire de publication communautaire : ordre des couches du modèle du peintre, cartes de couleurs scientifiques (divergentes doivent être centrées sur zéro et symétriques), conventions d'azimut d'ombrage, échelle/compas/graticule, alignement multi-panneaux et barres de couleur partagées, export vectoriel vs raster, stratification sismotectonique. Lire ceci pour rendre une figure belle et prête à soumettre.
• GALLERY.md — 13 modèles de scénarios prêts à adapter (basemap, multi-panneau, encart, nuage de points classifié, champ de vitesse, histogramme, rose, 3D, contours, coupe, double axe).
• scripts/ — modèles exécutables paramétrés : displacement_map.py, seismicity_map.py, cross_section.py, multipanel_components.py. Chacun s'exécute de manière autonome avec des données de démonstration ; éditer le bloc CONFIG en haut.