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 thewith
block. Because of this, no wrapper forGMT_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 beNone
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: ... lib.call_module("info", [vfile, f"->{ofile.name}"]) ... print(ofile.read().strip()) <vector memory>: N = 5 <0/4> <5/9>