0
# PyGMT
1
2
A comprehensive Python library that provides a Pythonic interface for the Generic Mapping Tools (GMT), enabling processing of geospatial and geophysical data while creating publication-quality maps and figures. PyGMT integrates directly with GMT's C API using ctypes, avoiding system calls, and seamlessly works with the scientific Python ecosystem including NumPy, pandas, xarray, and geopandas.
3
4
## Package Information
5
6
- **Package Name**: pygmt
7
- **Language**: Python
8
- **Installation**: `pip install pygmt`
9
- **Dependencies**: Requires GMT 6.1.1 or newer
10
11
## Core Imports
12
13
```python
14
import pygmt
15
```
16
17
For direct access to specific functions:
18
19
```python
20
from pygmt import Figure, config, makecpt, load_earth_relief
21
import pygmt.datasets
22
```
23
24
## Basic Usage
25
26
```python
27
import pygmt
28
29
# Create a figure instance
30
fig = pygmt.Figure()
31
32
# Plot a simple basemap
33
fig.basemap(region="global", projection="W15c", frame=True)
34
35
# Add coastlines
36
fig.coast(shorelines=True, land="lightgray", water="lightblue")
37
38
# Add a simple plot
39
fig.plot(x=[10, 20, 30], y=[15, 25, 35], style="c0.2c", fill="red")
40
41
# Display the figure
42
fig.show()
43
44
# Save the figure
45
fig.savefig("my_map.png")
46
```
47
48
## Architecture
49
50
PyGMT is built around several key components:
51
52
- **Figure Class**: Main plotting interface that manages GMT sessions and provides all plotting methods
53
- **Processing Functions**: Direct wrappers around GMT command-line tools for data processing
54
- **Dataset Loaders**: Functions to load GMT's built-in datasets (Earth relief, planetary data, etc.)
55
- **Integration Layer**: xarray accessories and backends for seamless grid/image handling
56
- **Session Management**: Automatic GMT modern mode session handling
57
58
The library maintains GMT's powerful geospatial processing capabilities while providing a modern Python interface that integrates with scientific Python tools.
59
60
## Capabilities
61
62
### Figure and Plotting
63
64
Core plotting interface providing all GMT visualization capabilities including basemaps, coastlines, data plots, grids, and specialized plotting for geophysical data.
65
66
```python { .api }
67
class Figure:
68
def __init__(self) -> None: ...
69
def basemap(self, **kwargs) -> None: ...
70
def coast(self, resolution=None, **kwargs) -> None: ...
71
def plot(self, data=None, x=None, y=None, size=None, **kwargs) -> None: ...
72
def grdimage(self, grid, **kwargs) -> None: ...
73
def show(self, method=None, dpi=300, width=500, **kwargs) -> None: ...
74
def savefig(self, fname, transparent=False, crop=True, **kwargs) -> None: ...
75
```
76
77
[Figure and Plotting](./figure-plotting.md)
78
79
### Data Processing
80
81
Grid and table data processing functions that wrap GMT's powerful analysis capabilities including gridding, filtering, sampling, and mathematical operations.
82
83
```python { .api }
84
def surface(data=None, **kwargs): ...
85
def nearneighbor(data=None, **kwargs): ...
86
def triangulate(data=None, **kwargs): ...
87
def grdfilter(grid, **kwargs): ...
88
def grdsample(grid, **kwargs): ...
89
def grdcut(grid, **kwargs): ...
90
def blockmean(data=None, **kwargs): ...
91
def xyz2grd(data=None, **kwargs): ...
92
```
93
94
[Data Processing](./data-processing.md)
95
96
### Dataset Loading
97
98
Built-in access to GMT's extensive collection of global datasets including Earth relief, planetary data, geophysical grids, and sample datasets.
99
100
```python { .api }
101
def load_earth_relief(resolution="01d", region=None, **kwargs): ...
102
def load_earth_age(resolution="01d", region=None, **kwargs): ...
103
def load_mars_relief(resolution="01d", region=None, **kwargs): ...
104
def load_sample_data(name): ...
105
def list_sample_data(): ...
106
```
107
108
[Dataset Loading](./datasets.md)
109
110
### Configuration and Utilities
111
112
System configuration, session management, xarray integration, and utility functions for customizing GMT behavior and managing resources.
113
114
```python { .api }
115
def config(**kwargs): ...
116
def info(data, **kwargs): ...
117
def which(fname, **kwargs): ...
118
def show_versions(): ...
119
def set_display(method): ...
120
def load_dataarray(filename_or_obj, **kwargs): ... # Deprecated
121
class GMTDataArrayAccessor: ... # xarray.DataArray.gmt accessor
122
class GMTBackendEntrypoint: ... # xarray GMT backend
123
```
124
125
[Configuration and Utilities](./config-utilities.md)
126
127
## Types
128
129
```python { .api }
130
from typing import Literal, Union
131
import numpy as np
132
import pandas as pd
133
import xarray as xr
134
import geopandas as gpd
135
from pathlib import Path
136
137
# Common type aliases used throughout PyGMT
138
PathLike = Union[str, Path]
139
TableLike = Union[dict, np.ndarray, pd.DataFrame, xr.Dataset]
140
ArrayLike = Union[list, np.ndarray, pd.Series]
141
142
# Geographic region specification
143
Region = Union[list, str] # [west, east, south, north] or GMT region string
144
145
# Projection specifications
146
Projection = str # GMT projection codes like "M15c", "X10c/8c", etc.
147
148
# Grid registration types
149
GridRegistration = Literal["gridline", "pixel"]
150
151
# Resolution options for datasets
152
Resolution = Literal["01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m", "30s", "15s"]
153
```