or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

config-utilities.mddata-processing.mddatasets.mdfigure-plotting.mdindex.md
tile.json

tessl/pypi-pygmt

A Python interface for the Generic Mapping Tools

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pygmt@0.16.x

To install, run

npx @tessl/cli install tessl/pypi-pygmt@0.16.0

index.mddocs/

PyGMT

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.

Package Information

  • Package Name: pygmt
  • Language: Python
  • Installation: pip install pygmt
  • Dependencies: Requires GMT 6.1.1 or newer

Core Imports

import pygmt

For direct access to specific functions:

from pygmt import Figure, config, makecpt, load_earth_relief
import pygmt.datasets

Basic Usage

import pygmt

# Create a figure instance
fig = pygmt.Figure()

# Plot a simple basemap
fig.basemap(region="global", projection="W15c", frame=True)

# Add coastlines
fig.coast(shorelines=True, land="lightgray", water="lightblue")

# Add a simple plot
fig.plot(x=[10, 20, 30], y=[15, 25, 35], style="c0.2c", fill="red")

# Display the figure
fig.show()

# Save the figure
fig.savefig("my_map.png")

Architecture

PyGMT is built around several key components:

  • Figure Class: Main plotting interface that manages GMT sessions and provides all plotting methods
  • Processing Functions: Direct wrappers around GMT command-line tools for data processing
  • Dataset Loaders: Functions to load GMT's built-in datasets (Earth relief, planetary data, etc.)
  • Integration Layer: xarray accessories and backends for seamless grid/image handling
  • Session Management: Automatic GMT modern mode session handling

The library maintains GMT's powerful geospatial processing capabilities while providing a modern Python interface that integrates with scientific Python tools.

Capabilities

Figure and Plotting

Core plotting interface providing all GMT visualization capabilities including basemaps, coastlines, data plots, grids, and specialized plotting for geophysical data.

class Figure:
    def __init__(self) -> None: ...
    def basemap(self, **kwargs) -> None: ...
    def coast(self, resolution=None, **kwargs) -> None: ...
    def plot(self, data=None, x=None, y=None, size=None, **kwargs) -> None: ...
    def grdimage(self, grid, **kwargs) -> None: ...
    def show(self, method=None, dpi=300, width=500, **kwargs) -> None: ...
    def savefig(self, fname, transparent=False, crop=True, **kwargs) -> None: ...

Figure and Plotting

Data Processing

Grid and table data processing functions that wrap GMT's powerful analysis capabilities including gridding, filtering, sampling, and mathematical operations.

def surface(data=None, **kwargs): ...
def nearneighbor(data=None, **kwargs): ...
def triangulate(data=None, **kwargs): ...
def grdfilter(grid, **kwargs): ...
def grdsample(grid, **kwargs): ...
def grdcut(grid, **kwargs): ...
def blockmean(data=None, **kwargs): ...
def xyz2grd(data=None, **kwargs): ...

Data Processing

Dataset Loading

Built-in access to GMT's extensive collection of global datasets including Earth relief, planetary data, geophysical grids, and sample datasets.

def load_earth_relief(resolution="01d", region=None, **kwargs): ...
def load_earth_age(resolution="01d", region=None, **kwargs): ...
def load_mars_relief(resolution="01d", region=None, **kwargs): ...
def load_sample_data(name): ...
def list_sample_data(): ...

Dataset Loading

Configuration and Utilities

System configuration, session management, xarray integration, and utility functions for customizing GMT behavior and managing resources.

def config(**kwargs): ...
def info(data, **kwargs): ...
def which(fname, **kwargs): ...
def show_versions(): ...
def set_display(method): ...
def load_dataarray(filename_or_obj, **kwargs): ...  # Deprecated
class GMTDataArrayAccessor: ...  # xarray.DataArray.gmt accessor
class GMTBackendEntrypoint: ...  # xarray GMT backend

Configuration and Utilities

Types

from typing import Literal, Union
import numpy as np
import pandas as pd
import xarray as xr
import geopandas as gpd
from pathlib import Path

# Common type aliases used throughout PyGMT
PathLike = Union[str, Path]
TableLike = Union[dict, np.ndarray, pd.DataFrame, xr.Dataset]
ArrayLike = Union[list, np.ndarray, pd.Series]

# Geographic region specification
Region = Union[list, str]  # [west, east, south, north] or GMT region string

# Projection specifications
Projection = str  # GMT projection codes like "M15c", "X10c/8c", etc.

# Grid registration types
GridRegistration = Literal["gridline", "pixel"]

# Resolution options for datasets
Resolution = Literal["01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m", "30s", "15s"]