pygmt.clib.Session.open_virtualfile

Session.open_virtualfile(family, geometry, direction, data)[source]

Open a GMT virtual file associated with a data object for reading or writing.

GMT uses a virtual file scheme to pass in data or get data from API modules. Use it to pass in your GMT data structure (created using pygmt.clib.Session.create_data) to a module that expects an input file, or get the output from a module that writes to a file.

Use in a with block. Will automatically close the virtual file when leaving the with block. Because of this, no wrapper for GMT_Close_VirtualFile is provided.

Parameters:

  • family (str) – A valid GMT data family name (e.g., "GMT_IS_DATASET"). Should be the same as the one you used to create your data structure.

  • geometry (str) – A valid GMT data geometry name (e.g., "GMT_IS_POINT"). Should be the same as the one you used to create your data structure.

  • direction (str) – Either "GMT_IN" or "GMT_OUT" to indicate if passing data to GMT or getting it out of GMT, respectively. By default, GMT can modify the data you pass in. Add modifier "GMT_IS_REFERENCE" to tell GMT the data are read-only, or "GMT_IS_DUPLICATE" to tell GMT to duplicate the data.

  • data (c_void_p | None) – The ctypes void pointer to the GMT data structure. For output (i.e., direction="GMT_OUT"), it can be None to have GMT automatically allocate the output GMT data structure.

Yields:

vfname – The name of the virtual file that you can pass to a GMT module.

Return type:

Generator[str, None, None]

Examples

>>> from pygmt.helpers import GMTTempFile
>>> import numpy as np
>>> x = np.array([0, 1, 2, 3, 4])
>>> y = np.array([5, 6, 7, 8, 9])
>>> with Session() as lib:
...     family = "GMT_IS_DATASET|GMT_VIA_VECTOR"
...     geometry = "GMT_IS_POINT"
...     dataset = lib.create_data(
...         family=family,
...         geometry=geometry,
...         mode="GMT_CONTAINER_ONLY",
...         dim=[2, 5, lib["GMT_INT"], 0],  # ncolumns, nrows, dtype, unused
...     )
...     lib.put_vector(dataset, column=0, vector=x)
...     lib.put_vector(dataset, column=1, vector=y)
...     # Add the dataset to a virtual file
...     vfargs = (family, geometry, "GMT_IN|GMT_IS_REFERENCE", dataset)
...     with lib.open_virtualfile(*vfargs) as vfile:
...         # Send the output to a temp file so that we can read it
...         with GMTTempFile() as ofile:
...             lib.call_module("info", [vfile, f"->{ofile.name}"])
...             print(ofile.read().strip())
<vector memory>: N = 5 <0/4> <5/9>