pygmt.clib.Session.open_virtualfile

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

Open a GMT virtual file to pass data to and from a module.

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 (int or None) – The ctypes void pointer to your 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 (str) – The name of the virtual file that you can pass to a GMT module.

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, 1, 0],  # columns, lines, segments, type
...     )
...     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:
...             args = f"{vfile} ->{ofile.name}"
...             lib.call_module("info", args)
...             print(ofile.read().strip())
<vector memory>: N = 5 <0/4> <5/9>