pygmt.clib.Session.read_virtualfile

Session.read_virtualfile(vfname, kind=None)

Read data from a virtual file and optionally cast into a GMT data container.

Parameters:

• vfname (str) – Name of the virtual file to read.

• kind (Literal['dataset', 'grid', 'image', 'cube', None], default: None) – Cast the data into a GMT data container. Valid values are "dataset", "grid", "image" and None. If None, will return a ctypes void pointer.

Returns:

pointer – Pointer to the GMT data container. If kind is None, returns a ctypes void pointer instead.

Examples

>>> from pathlib import Path
>>> from pygmt.clib import Session
>>> from pygmt.helpers import GMTTempFile
>>>
>>> # Read dataset from a virtual file
>>> with Session() as lib:
...     with GMTTempFile(suffix=".txt") as tmpfile:
...         with Path(tmpfile.name).open(mode="w") as fp:
...             print("1.0 2.0 3.0 TEXT", file=fp)
...         with lib.virtualfile_out(kind="dataset") as vouttbl:
...             lib.call_module("read", [tmpfile.name, vouttbl, "-Td"])
...             # Read the virtual file as a void pointer
...             void_pointer = lib.read_virtualfile(vouttbl)
...             assert isinstance(void_pointer, int)  # void pointer is an int
...             # Read the virtual file as a dataset
...             data_pointer = lib.read_virtualfile(vouttbl, kind="dataset")
...             assert isinstance(data_pointer, ctp.POINTER(_GMT_DATASET))
>>>
>>> # Read grid from a virtual file
>>> with Session() as lib:
...     with lib.virtualfile_out(kind="grid") as voutgrd:
...         lib.call_module("read", ["@earth_relief_01d_g", voutgrd, "-Tg"])
...         # Read the virtual file as a void pointer
...         void_pointer = lib.read_virtualfile(voutgrd)
...         assert isinstance(void_pointer, int)  # void pointer is an int
...         data_pointer = lib.read_virtualfile(voutgrd, kind="grid")
...         assert isinstance(data_pointer, ctp.POINTER(_GMT_GRID))