0
# Figure and Plotting
1

2
Core plotting interface providing all GMT visualization capabilities. The Figure class serves as the main plotting canvas and provides methods for creating basemaps, plotting data, adding annotations, and managing figure display and output.
3

4
## Capabilities
5

6
### Figure Management
7

8
Create and manage GMT figures with display and output capabilities.
9

10
```python { .api }
11
class Figure:
12
    def __init__(self) -> None:
13
        """Initialize a new Figure instance with unique name and preview directory."""
14
    
15
    @property
16
    def region(self) -> np.ndarray:
17
        """Return the geographic WESN bounding box for the current figure."""
18
    
19
    def show(self, method: Literal["external", "notebook", "none", None] = None, 
20
             dpi: int = 300, width: int = 500, waiting: float = 0.5, **kwargs) -> None:
21
        """
22
        Display a preview of the figure.
23
        
24
        Parameters:
25
        - method: Display method ("external", "notebook", "none", or None for default)
26
        - dpi: Image resolution for notebook display
27
        - width: Image width in pixels for notebook display  
28
        - waiting: Wait time after launching external viewer
29
        """
30
    
31
    def savefig(self, fname: PathLike, transparent: bool = False, crop: bool = True,
32
                anti_alias: bool = True, show: bool = False, worldfile: bool = False, 
33
                **kwargs) -> None:
34
        """
35
        Save the figure to an image file.
36
        
37
        Parameters:
38
        - fname: Output file path with extension (BMP, JPEG, GeoTIFF, PNG, PPM, TIFF, EPS, PDF, KML)
39
        - transparent: Enable transparent background (PNG/KML only)
40
        - crop: Crop figure canvas to plot area
41
        - anti_alias: Enable anti-aliasing for raster images
42
        - show: Display figure in external viewer after saving
43
        - worldfile: Create companion world file for georeferencing
44
        """
45
```
46

47
### Basic Mapping and Plotting
48

49
Fundamental mapping functions for creating basemaps, coastlines, and data plots.
50

51
```python { .api }
52
def basemap(self, **kwargs) -> None:
53
    """
54
    Plot base maps and frames.
55
    
56
    Parameters (via kwargs):
57
    - region: Required if this is the first plot command [west, east, south, north]
58
    - projection: Map projection (e.g., "M15c", "X10c/8c")
59
    - frame: Frame/axes configuration (bool or str)
60
    - map_scale: Draw a simple map scale (str)
61
    - rose: Draw a map directional rose (str) 
62
    - compass: Draw a map magnetic rose (str)
63
    """
64

65
def coast(self, resolution: Literal["auto", "full", "high", "intermediate", "low", "crude", None] = None, 
66
          **kwargs) -> None:
67
    """
68
    Plot continents, countries, shorelines, rivers, and borders.
69
    
70
    Parameters:
71
    - resolution: Coastline dataset resolution
72
    - region: Geographic extent [west, east, south, north]
73
    - projection: Map projection
74
    - frame: Frame configuration
75
    - land: Fill color/pattern for dry areas (str)
76
    - water: Fill color/pattern for wet areas (str)
77
    - shorelines: Draw shorelines (bool, int, str, or list)
78
    - rivers: Draw rivers (int, str, or list)
79
    - borders: Draw political boundaries (int, str, or list)
80
    - area_thresh: Area threshold for features
81
    """
82

83
def plot(self, data: PathLike | TableLike | None = None, x=None, y=None, size=None,
84
         symbol=None, direction=None, straight_line: bool | Literal["x", "y"] = False, 
85
         **kwargs) -> None:
86
    """
87
    Plot lines, polygons, and symbols in 2-D.
88
    
89
    Parameters:
90
    - data: File name or data table (dict, array, DataFrame, etc.)
91
    - x: x coordinates or arrays
92
    - y: y coordinates or arrays  
93
    - size: Size of data points (1-D array)
94
    - symbol: Symbols for data points (1-D array)
95
    - direction: Vector directions (list of two 1-D arrays)
96
    - straight_line: Control line segment drawing
97
    - region: Geographic extent
98
    - projection: Map projection
99
    - style: Plot symbols/vectors (str)
100
    - pen: Pen attributes for outlines
101
    - fill: Fill color (can be 1-D array)
102
    - cmap: Color palette for colored symbols
103
    """
104

105
def plot3d(self, data: PathLike | TableLike | None = None, **kwargs) -> None:
106
    """
107
    Plot lines, polygons, and symbols in 3-D.
108
    
109
    Parameters:
110
    - data: File name or 3-D data table
111
    - region: 3-D extent [west, east, south, north, bottom, top]
112
    - projection: Map projection
113
    - zscale/zsize: Z-axis scaling or size
114
    - perspective: 3-D perspective parameters
115
    - style: 3-D plot symbols/vectors
116
    """
117
```
118

119
### Grid and Image Display
120

121
Functions for displaying grids, images, and creating contour maps.
122

123
```python { .api }
124
def grdimage(self, grid: PathLike | xr.DataArray, **kwargs) -> None:
125
    """
126
    Project and plot grids or images.
127
    
128
    Parameters:
129
    - grid: 2-D grid file path or xarray DataArray
130
    - region: Geographic extent
131
    - projection: Map projection  
132
    - frame: Frame configuration
133
    - cmap: Color palette (str)
134
    - shading: Illumination/intensity grid (str or xr.DataArray)
135
    - nan_transparent: Make NaN values transparent (bool or str)
136
    - no_clip: Control clipping at boundaries (bool)
137
    - dpi: Resolution of projected grid (int)
138
    """
139

140
def grdview(self, grid: PathLike | xr.DataArray, **kwargs) -> None:
141
    """
142
    Create 3-D perspective image or surface mesh from a grid.
143
    
144
    Parameters:
145
    - grid: 2-D grid file or xarray DataArray
146
    - region: 3-D extent
147
    - projection: Map projection
148
    - zscale/zsize: Z-axis scaling
149
    - perspective: 3-D viewing parameters
150
    - cmap: Color palette
151
    - shading: Illumination grid
152
    - surftype: Surface type (surface/mesh/image)
153
    """
154

155
def grdcontour(self, grid: PathLike | xr.DataArray, **kwargs) -> None:
156
    """
157
    Make contour map using a grid.
158
    
159
    Parameters:
160
    - grid: 2-D grid file or xarray DataArray
161
    - region: Geographic extent
162
    - projection: Map projection
163
    - frame: Frame configuration
164
    - interval: Contour interval (str or number)
165
    - levels: Specific contour levels (list)
166
    - cmap: Color palette for filled contours
167
    - pen: Pen attributes for contour lines  
168
    - label: Contour labeling options
169
    """
170

171
def contour(self, data: PathLike | TableLike | None = None, x=None, y=None, z=None, 
172
            **kwargs) -> None:
173
    """
174
    Contour table data by direct triangulation.
175
    
176
    Parameters:
177
    - data: File name or data table with x, y, z columns
178
    - x, y, z: Coordinate and data arrays
179
    - region: Geographic extent
180
    - projection: Map projection
181
    - interval: Contour interval
182
    - levels: Specific contour levels
183
    - triangulate: Triangulation method
184
    """
185

186
def image(self, imagefile: PathLike, **kwargs) -> None:
187
    """
188
    Place images or EPS files on maps.
189
    
190
    Parameters:
191
    - imagefile: Path to image file
192
    - region: Geographic extent  
193
    - projection: Map projection
194
    - position: Image position and size
195
    - justify: Image justification
196
    - box: Draw border around image
197
    """
198
```
199

200
### Data Visualization
201

202
Specialized plotting functions for different data types and visualization needs.
203

204
```python { .api }
205
def histogram(self, data: PathLike | TableLike, **kwargs) -> None:
206
    """
207
    Plot a histogram.
208
    
209
    Parameters:  
210
    - data: Data file or array
211
    - region: Plot extent
212
    - projection: Plot projection
213
    - series: Histogram range and bin width
214
    - pen: Pen attributes for histogram bars
215
    - fill: Fill color for bars
216
    - horizontal: Create horizontal histogram
217
    """
218

219
def ternary(self, data: PathLike | TableLike | None = None, **kwargs) -> None:
220
    """
221
    Plot data on ternary diagrams.
222
    
223
    Parameters:
224
    - data: Data file or table with 3 components
225
    - region: Ternary plot extent  
226
    - frame: Ternary axes configuration
227
    - style: Symbol style for data points
228
    - cmap: Color palette
229
    """
230

231
def rose(self, data: PathLike | TableLike | None = None, **kwargs) -> None:
232
    """
233
    Plot a polar histogram (rose diagram).
234
    
235
    Parameters:
236
    - data: Angular data file or array
237
    - region: Angular extent
238
    - frame: Circular frame configuration
239
    - sector: Angular sector width
240
    - radial_scale: Radial axis scaling
241
    - pen: Pen attributes
242
    - fill: Fill color
243
    """
244

245
def wiggle(self, data: PathLike | TableLike | None = None, **kwargs) -> None:
246
    """
247
    Plot z = f(x,y) anomalies along tracks.
248
    
249
    Parameters:
250
    - data: Track data with x, y, z columns
251
    - region: Geographic extent
252
    - projection: Map projection
253
    - scale: Amplitude scaling
254
    - pen: Pen attributes for wiggle traces
255
    - fill: Fill colors (positive/negative)
256
    """
257
```
258

259
### Specialized Geophysical Plotting
260

261
Functions for plotting geophysical and geological data.
262

263
```python { .api }
264
def velo(self, data: PathLike | TableLike | None = None, **kwargs) -> None:
265
    """
266
    Plot velocity vectors, crosses, anisotropy bars and wedges.
267
    
268
    Parameters:
269
    - data: Velocity data file or table
270
    - region: Geographic extent
271
    - projection: Map projection
272
    - vector: Vector symbol specification
273
    - pen: Pen attributes for vectors
274
    - fill: Fill color for symbols
275
    - uncertainty: Plot error ellipses
276
    """
277

278
def meca(self, spec: PathLike | TableLike | None = None, **kwargs) -> None:
279
    """
280
    Plot focal mechanisms.
281
    
282
    Parameters:
283
    - spec: Focal mechanism data file or table
284
    - region: Geographic extent
285
    - projection: Map projection  
286
    - convention: Focal mechanism convention (aki/gcmt/partial/principal/mt/dc)
287
    - scale: Symbol scaling
288
    - pen: Pen attributes
289
    - fill: Fill color for compressive quadrants
290
    """
291

292
def solar(self, data: PathLike | TableLike | None = None, **kwargs) -> None:
293
    """
294
    Plot day-light terminators.
295
    
296
    Parameters:
297
    - data: Sun position data or datetime
298
    - region: Geographic extent
299
    - projection: Map projection
300
    - terminator: Terminator type (day/night/civil/nautical/astronomical)
301
    - pen: Pen attributes for terminator line
302
    - fill: Fill color for night areas
303
    """
304
```
305

306
### Lines and Text
307

308
Functions for adding lines, text, and annotations to figures.
309

310
```python { .api }
311
def hlines(self, y: float | list, **kwargs) -> None:
312
    """
313
    Plot horizontal lines.
314
    
315
    Parameters:
316
    - y: Y-coordinate(s) for horizontal lines
317
    - region: Plot extent
318
    - pen: Pen attributes for lines
319
    """
320

321
def vlines(self, x: float | list, **kwargs) -> None:
322
    """
323
    Plot vertical lines.
324
    
325
    Parameters:
326
    - x: X-coordinate(s) for vertical lines  
327
    - region: Plot extent
328
    - pen: Pen attributes for lines
329
    """
330

331
def text(self, textfiles: PathLike | TableLike | None = None, x=None, y=None,
332
          position: Literal["TL", "TC", "TR", "ML", "MC", "MR", "BL", "BC", "BR"] | None = None,
333
          **kwargs) -> None:
334
    """
335
    Plot or typeset text strings.
336
    
337
    Parameters:
338
    - textfiles: Text data file or table
339
    - x, y: Text position coordinates
340
    - position: Text anchor position
341
    - region: Geographic extent
342
    - projection: Map projection
343
    - font: Font specification
344
    - justify: Text justification
345
    - angle: Text rotation angle
346
    - fill: Text box fill color
347
    - pen: Text box outline
348
    """
349
```
350

351
### Figure Elements
352

353
Functions for adding colorbars, legends, logos, and other figure elements.
354

355
```python { .api }
356
def colorbar(self, **kwargs) -> None:
357
    """
358
    Plot colorbars on maps.
359
    
360
    Parameters:
361
    - position: Colorbar position and size
362
    - cmap: Color palette file
363
    - frame: Colorbar frame and annotations
364
    - scale: Value scaling
365
    - box: Colorbar background box
366
    """
367

368
def legend(self, spec: PathLike | list | None = None, **kwargs) -> None:
369
    """
370
    Plot a legend.
371
    
372
    Parameters:
373
    - spec: Legend specification file or list
374
    - position: Legend position
375
    - box: Legend background box
376
    - spacing: Line spacing
377
    """
378

379
def logo(self, **kwargs) -> None:
380
    """
381
    Place the GMT logo on a plot.
382
    
383
    Parameters:
384
    - position: Logo position
385
    - julia: Plot Julia logo instead of GMT
386
    """
387

388
def timestamp(self, **kwargs) -> None:
389
    """
390
    Plot time stamps on maps.
391
    
392
    Parameters:
393
    - position: Timestamp position
394
    - format: Time format string
395
    - font: Font specification
396
    """
397
```
398

399
### Layout and Subplots
400

401
Functions for managing figure layout and creating multi-panel plots.
402

403
```python { .api }
404
def inset(self, **kwargs) -> None:
405
    """
406
    Create and manage figure insets.
407
    
408
    Parameters:
409
    - position: Inset position and size
410
    - box: Inset border
411
    - margin: Inset margins
412
    - translate: Coordinate translation
413
    """
414

415
def subplot(self, nrows: int = 1, ncols: int = 1, **kwargs) -> None:
416
    """
417
    Create multi-panel subplot figures.
418
    
419
    Parameters:
420
    - nrows: Number of subplot rows
421
    - ncols: Number of subplot columns
422
    - figsize: Overall figure size
423
    - frame: Subplot frame configuration
424
    - margins: Subplot margins and spacing
425
    - title: Overall figure title
426
    """
427

428
def set_panel(self, panel=None, **kwargs) -> None:
429
    """
430
    Activate a specific subplot panel.
431
    
432
    Parameters:
433
    - panel: Panel identifier (row, col) or index
434
    - fixedlabel: Set fixed subplot labels
435
    """
436
```
437

438
### Utility Functions
439

440
Figure utility functions for coordinate transformation and output processing.
441

442
```python { .api }
443
def shift_origin(self, xshift: str | None = None, yshift: str | None = None, 
444
                 **kwargs) -> None:
445
    """
446
    Shift plot origin in x and/or y directions.
447
    
448
    Parameters:
449
    - xshift: X-direction shift amount (with units)
450
    - yshift: Y-direction shift amount (with units)
451
    """
452

453
def psconvert(self, **kwargs) -> None:
454
    """
455
    Convert PostScript to other formats using Ghostscript.
456
    
457
    Parameters:
458
    - format: Output format (jpg/png/pdf/eps/tif/etc.)
459
    - prefix: Output file prefix
460
    - dpi: Output resolution
461
    - crop: Crop to bounding box
462
    - background: Background color
463
    """
464

465
def tilemap(self, region: str | list, **kwargs) -> None:
466
    """
467
    Plot web map tiles as a basemap or overlay.
468
    
469
    Parameters:
470
    - region: Geographic extent for tiles
471
    - projection: Map projection
472
    - source: Tile source (OpenStreetMap/ESRI/etc.)
473
    - zoom: Zoom level
474
    - alpha: Tile transparency
475
    """
476
```
477

478
## Usage Examples
479

480
### Basic Map Creation
481

482
```python
483
import pygmt
484

485
# Create figure and basic map
486
fig = pygmt.Figure()
487
fig.basemap(region="global", projection="W15c", frame="a30f15")
488
fig.coast(shorelines=True, land="tan", water="lightblue")
489
fig.show()
490
```
491

492
### Data Plotting with Grid
493

494
```python
495
import pygmt
496

497
# Load sample grid data
498
grid = pygmt.datasets.load_earth_relief(resolution="05m", region=[-180, 180, -60, 60])
499

500
# Plot the grid
501
fig = pygmt.Figure()
502
fig.grdimage(grid=grid, projection="W15c", cmap="geo", frame=True)
503
fig.coast(shorelines=True)
504
fig.colorbar(frame='a2000+l"Elevation (m)"')
505
fig.show()
506
```
507

508
### Multi-Panel Figure
509

510
```python
511
import pygmt
512
import numpy as np
513

514
# Create subplot figure
515
fig = pygmt.Figure()
516
fig.subplot(nrows=2, ncols=2, figsize="15c", frame="WSen")
517

518
# Panel 1
519
fig.set_panel(panel=0)
520
fig.basemap(region="global", projection="W?", frame="a60f30")
521
fig.coast(land="gray")
522

523
# Panel 2  
524
fig.set_panel(panel=1)
525
x = np.arange(0, 10, 0.1)
526
y = np.sin(x)
527
fig.plot(x=x, y=y, region=[0, 10, -1.5, 1.5], projection="X?/5c", 
528
         pen="2p,blue", frame="ag")
529

530
fig.show()
531
```