Habilidade de Plotagem PyGMT

Plotagem com PyGMT

PyGMT é um invólucro para o Generic Mapping Tools. Cada parâmetro de método aceita tanto o nome completo em Python (projection) quanto o alias de uma letra do GMT (J) — esta habilidade usa nomes completos. Funções de processamento de grade retornam xarray.DataArray quando outgrid=None, então os resultados podem ser encadeados diretamente em funções de plotagem.

Formato de figura obrigatório (estilo do periódico)

Todas as figuras científicas DEVEM seguir estas regras de formatação:

• Moldura: MAP_FRAME_TYPE='plain', MAP_FRAME_PEN='1p,black'. Nunca desenhe a moldura duas vezes (sem basemap + plot ambos configurando frame).
• Rótulos dos painéis: Letra MAIÚSCULA (A, B, C...) no canto superior esquerdo dentro da moldura, sem parênteses, negrito ≥10p, caixa quadrada (preenchimento branco + caneta preta 0.8p, clearance='1.5p/1.5p/1.5p/1.5p'). Distância igual das bordas esquerda e superior. O texto do título (por exemplo, "Leste") centralizado na parte superior separadamente.
• Rótulos dos ticks: Apenas nas bordas esquerda (W) e inferior (S).
• Barra de cores: Horizontal na parte inferior, com rótulo de unidade, deslocamento suficiente dos rótulos dos eixos (+o0c/0.8c).
• Escala de cores: vik para divergente (deslocamento), sequencial: inferno ou roma.
• Eixos de profundidade lidos POSITIVOS PARA BAIXO (regra rígida para figuras de falhas/cortes transversais/3D): o eixo de profundidade deve ser rotulado 0, 20, 40 … (quilômetros positivos), nunca 0, -20, -40. Armazene a profundidade como um valor positivo (a profundidade aumenta para baixo), defina o intervalo de profundidade da região como [0, zmax] e inverta o eixo com uma altura negativa: cortes transversais 2D usam projection="X<w>c/-<h>c" (altura negativa → y aumenta para baixo); gráficos de perspectiva 3D usam zsize="-<h>c" (negativo → profundo na parte inferior, rótulos positivos). Nunca emita dados z negativos apenas para obter "para cima = positivo" — isso coloca sinais de menos no eixo de profundidade. Ao inverter um eixo z 3D dessa forma, a componente vertical de qualquer vetor com mergulho para cima no plano também inverte o sinal (mergulho para cima agora significa diminuição da profundidade positiva).
• Sem molduras duplas: subplot gerencia a moldura → NÃO chame basemap(frame=) dentro dos painéis.
• Autoverificação: Após gerar cada figura, leia/inspecione-a. Corrija molduras duplas, conteúdo cortado, rótulos inconsistentes antes de mostrar ao usuário.

Início rápido

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])         # define a CPT da sessão
    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é-visualiza; fig.savefig("f.pdf") (vetorial) ou .png/.tif (raster, passe dpi=).

Os três parâmetros universais

Todo comando de mapa aceita estes; o primeiro comando os define e os comandos subsequentes os reutilizam.

• region (R) — [W, E, S, N] (observe a ordem: Oeste, Leste, Sul, Norte). "g"/"d" = global; "JP" = código ISO do país; anexe +r para coordenadas de canto.
• projection (J) — code[params/]width, width deve ter uma unidade (c/i/p): "M12c" Mercator, "X10c/6c" linear, "L-100/35/33/45/12c" cônica de Lambert, "G-120/40/12c" ortográfica.
• frame (B) — ["WSne", "xaf", "yaf+lLabel", "+tTitle"]. Maiúscula na borda = eixo+ticks+anotações, minúscula = sem anotações. a=anotação/principal, f=ticks secundários, g=grade. Rótulos de eixo +l funcionam apenas em projeções Cartesianas (X), não geográficas.

Escolhendo uma projeção / CPT (folha de consulta)

Necessidade	Projeção
Mapa de região (latitude baixa–média, InSAR/swarm)	M Mercator "M12c"
Continental, baixa distorção	L Cônica de Lambert "L lon0/lat0/lat1/lat2/w"
Inseto localizador / hemisfério	G Ortográfica "G lon0/lat0/w"
Global	W Mollweide / N Robinson / H Hammer
Seção profundidade/distância	X linear, altura negativa → y aponta para baixo: "X12c/-4c"

Tipo de dado	CPT
Divergente (deslocamento, velocidade, anomalia; centrado em zero)	vik, roma, broc, polar
Escalar sequencial	inferno, roma, batlow, viridis, turbo
Topografia	geo (terra), oleron/relief (terra+oceano), gray (sombreado)
Cíclico (fase enrolada, azimute)	romaO, vikO

Crie uma CPT com pygmt.makecpt(cmap="vik", series=[-50, 50, 5]) — sem output= ela se torna a CPT da sessão, então comandos subsequentes grdimage/plot(cmap=True)/colorbar a usam automaticamente. Equalize o histograma das cores de uma grade com pygmt.grd2cpt(grid=g, cmap="geo").

Estilo do periódico (aplique em toda figura)

Estes são os padrões opinativos desta habilidade — substitua-os quando um periódico alvo disser o contrário:

1. Envolva o desenho em with pygmt.config(MAP_FRAME_TYPE="plain", MAP_FRAME_PEN="1p,black"):. Nunca desenhe a moldura duas vezes (subplot/basemap gerencia — não repasse frame= dentro dos painéis).
2. Rótulos dos ticks apenas nas bordas W (esquerda) e S (inferior) → frame=["WSne", ...].
3. Rótulos dos painéis: letra MAIÚSCULA (A, B, C…), sem parênteses, negrito ≥10p, em uma caixa quadrada branca (preenchimento branco + caneta preta 0.8p), deslocamento igual da esquerda e do topo:

   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. Barra de cores: horizontal na parte inferior, com rótulo de unidade, deslocamento generoso dos rótulos dos eixos: position="JBC+w8c/0.4c+h+o0c/0.8c", frame="x+lQuantity (unit)".
5. Deslocamento divergente → vik; sequencial → inferno/roma.
6. Resolução raster — sem moiré (regra rígida): ao imagear grades de franjas/speckle (interferogramas enrolados, coerência), a contagem de pixels do painel renderizado DEVE ser ≥ o número de colunas nativas da grade: panel_cm × dpi / 2.54 >= n_columns. Padrão: painel único ≥16 cm a dpi=400 (modo moderno GMT: gmt begin fig png E400). Se um layout de vários painéis subamostrar, divida em figuras de painel único em vez de encolher. Franjas densas subamostradas se transformam em ondulações de moiré — um modo de falha recorrente em painéis de fase enrolada ScanSAR.
7. Autoverificação: após salvar, Leia a imagem de saída e corrija molduras duplas, conteúdo cortado, rótulos inconsistentes ou textura falsa tipo moiré/grid em áreas de franjas densas antes de mostrar ao usuário.

Fluxo de trabalho para uma nova figura

1. Decida região, projeção e CPT a partir da folha de consulta acima.
2. Escolha o modelo mais próximo em GALLERY.md ou scripts/ e adapte-o.
3. Desenhe dentro do bloco de config do estilo do periódico; construa da camada inferior para a superior (relevo → costa → dados → anotações → barra de cores).
4. fig.savefig(..., dpi=300) (dpi=400+ e verifique a regra de contagem de pixels para rasters de franjas/speckle), então Leia a imagem e faça a autoverificação (passo 7 acima).

Referências

• REFERENCE.md — API completa: ciclo de vida da figura, coast/plot/text, grdimage/grdcontour/grdview, makecpt/colorbar, conjuntos de dados, processamento de grade (grdcut/grdgradient/grdtrack/surface…), xarray, meca, velo, project, subplot/inset/shift_origin/legend.
• GOTCHAS.md — armadilhas fornecidas pela comunidade que a documentação da API não menciona: armadilhas de região/linha internacional de data/projeção, sobrescrita da CPT da sessão e erro "no z-slices", reset de gtype/registration do xarray após aritmética, grdimage-all-black, cache earth_relief, escopo de font-config, barras de cores em vários painéis, renomeações de parâmetros 0.x, correções de instalação Ghostscript/conda. §8 armadilhas testadas em campo: inset basemap descarta anotações/rótulos (desenhe manualmente ou use shift_origin); inset força uma moldura padrão, então box="+p" cria moldura dupla; meca +m escala Mw é invisível (tamanhe beachballs manualmente); meca(cmap=True) em profundidades negativas causa segfault; tif rasterio escrito à mão → grdimage causa segfault (use xarray em vez disso); incompatibilidade de dimensão shading (grdsample primeiro); transbordamento de rótulo da barra de cores do inset (+mal); fig.plot(fill="white") adiciona uma borda preta extra. §9 Pontas de seta vetoriais (style="v"): +g/+h NÃO estão quebrados — uma ponta só aparece se você também passar +e/+b, um vetor mais curto que o comprimento da ponta perde a ponta silenciosamente (corrija com +n<len>), e +h próximo de 1 degenera a ponta e o preenchimento desaparece. Leia isto quando uma figura PyGMT se comportar mal ou gerar erro inesperado.
• CRAFT.md — artefato de publicação da comunidade: ordem de camadas do modelo do pintor, mapas de cores científicos (divergente deve ser centrado em zero e simétrico), convenções de azimute de sombreamento, escala/rosa dos ventos/graticula, alinhamento de vários painéis e barras de cores compartilhadas, exportação vetorial vs. raster, camadas sismotectônicas. Leia isto para fazer uma figura parecer boa e pronta para submissão.
• GALLERY.md — 13 modelos de cenário prontos para adaptar (basemap, vários painéis, inset, dispersão classificada, campo de velocidade, histograma, rosa dos ventos, 3D, contornos, corte transversal, eixo duplo).
• scripts/ — modelos executáveis e parametrizados: displacement_map.py, seismicity_map.py, cross_section.py, multipanel_components.py. Cada um roda de forma independente com dados de demonstração; edite o bloco CONFIG no topo.