pygmt.GMTBackendEntrypoint

class pygmt.GMTBackendEntrypoint[source]

Xarray backend to read raster grid/image files using ‘gmt’ engine.

Internally, GMT uses the netCDF C library to read netCDF files, and GDAL for GeoTIFF and other raster formats. See https://docs.generic-mapping-tools.org/6.5/reference/features.html#grid-file-format for more details about supported formats. This GMT engine can also read GMT remote datasets (file names starting with an @) directly, and pre-loads pygmt.GMTDataArrayAccessor properties (in the ‘.gmt’ accessor) for easy access to GMT-specific metadata and features.

When using xarray.open_dataarray or xarray.load_dataarray with engine="gmt", the raster_kind parameter is required and can be either:

"grid": for reading single-band raster grids
"image": for reading multi-band raster images

Optionally, you can pass in a region in the form of a sequence [xmin, xmax, ymin, ymax] or an ISO country code.

Examples

Read a single-band netCDF file using raster_kind="grid"

>>> import pygmt
>>> import xarray as xr
>>>
>>> da_grid = xr.open_dataarray(
...     "@static_earth_relief.nc", engine="gmt", raster_kind="grid"
... )
>>> da_grid
<xarray.DataArray 'z' (lat: 14, lon: 8)>...
[112 values with dtype=float32]
Coordinates:
  * lat      (lat) float64... -23.5 -22.5 -21.5 -20.5 ... -12.5 -11.5 -10.5
  * lon      (lon) float64... -54.5 -53.5 -52.5 -51.5 -50.5 -49.5 -48.5 -47.5
Attributes:...
    Conventions:   CF-1.7
    title:         Produced by grdcut
    history:       grdcut @earth_relief_01d_p -R-55/-47/-24/-10 -Gstatic_eart...
    description:   Reduced by Gaussian Cartesian filtering (111.2 km fullwidt...
    actual_range:  [190. 981.]
    long_name:     elevation (m)

Read a multi-band GeoTIFF file using raster_kind="image"

>>> da_image = xr.open_dataarray(
...     "@earth_night_01d", engine="gmt", raster_kind="image"
... )
>>> da_image
<xarray.DataArray 'z' (band: 3, y: 180, x: 360)>...
[194400 values with dtype=uint8]
Coordinates:
  * y        (y) float64... 89.5 88.5 87.5 86.5 ... -86.5 -87.5 -88.5 -89.5
  * x        (x) float64... -179.5 -178.5 -177.5 -176.5 ... 177.5 178.5 179.5
  * band     (band) uint8... 1 2 3
Attributes:...
    long_name:  z

Load a single-band netCDF file using raster_kind="grid" over a bounding box region.

>>> da_grid = xr.load_dataarray(
...     "@tut_bathy.nc", engine="gmt", raster_kind="grid", region=[-64, -62, 32, 33]
... )
>>> da_grid
<xarray.DataArray 'z' (lat: 13, lon: 25)>...
array([[-4369., -4587., -4469., -4409., -4587., -4505., -4403., -4405.,
        -4466., -4595., -4609., -4608., -4606., -4607., -4607., -4597.,
...
        -4667., -4642., -4677., -4795., -4797., -4800., -4803., -4818.,
        -4820.]], dtype=float32)
Coordinates:
  * lat      (lat) float64... 32.0 32.08 32.17 32.25 ... 32.83 32.92 33.0
  * lon      (lon) float64... -64.0 -63.92 -63.83 ... -62.17 -62.08 -62.0
Attributes:...
    Conventions:   CF-1.7
    title:         ETOPO5 global topography
    history:       grdreformat -fg bermuda.grd bermuda.nc=ns
    description:   /home/elepaio5/data/grids/etopo5.i2
    actual_range:  [-4968. -4315.]
    long_name:     Topography
    units:         m

Attributes

Methods Summary

`GMTBackendEntrypoint.guess_can_open`(...)	Backend open_dataset method used by Xarray in `open_dataset`.
`GMTBackendEntrypoint.open_dataset`(...[, ...])	Backend open_dataset method used by Xarray in `open_dataset`.
`GMTBackendEntrypoint.open_datatree`(...[, ...])	Backend open_datatree method used by Xarray in `open_datatree`.
`GMTBackendEntrypoint.open_groups_as_dict`(...)	Opens a dictionary mapping from group names to Datasets.