pygmt.clib.Session
- class pygmt.clib.Session[source]
A GMT API session where most operations involving the C API happen.
Works as a context manager (for use in a
with
block) to create a GMT C API session and destroy it in the end to clean up memory.Functions of the shared library are exposed as methods of this class. Most methods MUST be used with an open session (inside a
with
block). If creating GMT data structures to communicate data, put that code inside the samewith
block as the API calls that will use the data.By default, will let
ctypes
try to find the GMT shared library (libgmt
). If the environment variableGMT_LIBRARY_PATH
is set, will look for the shared library in the directory specified by it.A
GMTVersionError
exception will be raised if the GMT shared library reports a version older than the required minimum GMT version.The
session_pointer
attribute holds a ctypes pointer to the currently open session.- Raises
GMTCLibNotFoundError – If there was any problem loading the library (couldn’t find it or couldn’t access the functions).
GMTCLibNoSessionError – If you try to call a method outside of a ‘with’ block.
GMTVersionError – If the minimum required version of GMT is not found.
Examples
>>> from pygmt.helpers.testing import load_static_earth_relief >>> from pygmt.helpers import GMTTempFile >>> grid = load_static_earth_relief() >>> type(grid) <class 'xarray.core.dataarray.DataArray'> >>> # Create a session and destroy it automatically when exiting the "with" >>> # block. >>> with Session() as ses: ... # Create a virtual file and link to the memory block of the grid. ... with ses.virtualfile_from_grid(grid) as fin: ... # Create a temp file to use as output. ... with GMTTempFile() as fout: ... # Call the grdinfo module with the virtual file as input ... # and the temp file as output. ... ses.call_module("grdinfo", f"{fin} -C ->{fout.name}") ... # Read the contents of the temp file before it's deleted. ... print(fout.read().strip()) ... -55 -47 -24 -10 190 981 1 1 8 14 1 1
Attributes
- property Session.info
Dictionary with the GMT version and default paths and parameters.
- property Session.session_pointer
The
ctypes.c_void_p
pointer to the current open GMT session.- Raises
GMTCLibNoSessionError – If trying to access without a currently open GMT session (i.e., outside of the context manager).
Methods Summary
|
Call a GMT module with the given arguments. |
|
Create a new GMT C API session. |
|
Create an empty GMT data container. |
Destroy the currently open GMT API session. |
|
Extract the WESN bounding box of the currently active figure. |
|
|
Get the value of a GMT default parameter (library version, paths, etc). |
|
Get a ctypes function from the libgmt shared library. |
|
Open a GMT virtual file to pass data to and from a module. |
|
Attach a numpy 2-D array to a GMT dataset. |
|
Attach a numpy 1-D array of dtype str as a column on a GMT dataset. |
|
Attach a numpy 1-D array as a column on a GMT dataset. |
|
Store any data inside a virtual file. |
Store a grid in a virtual file. |
|
|
Store a 2-D array as a table inside a virtual file. |
|
Store 1-D arrays as columns of a table inside a virtual file. |
|
Write a GMT data container to a file. |