Wrap GMT_Read_VirtualFile

doc/api/index.rst

@@ -308,5 +308,6 @@ Low level access (these are mostly used by the :mod:`pygmt.clib` package):
  clib.Session.put_vector
  clib.Session.write_data
  clib.Session.open_virtual_file
+ clib.Session.read_virtualfile
  clib.Session.extract_region
  clib.Session.get_libgmt_func

pygmt/clib/session.py

@@ -9,6 +9,7 @@
 import pathlib
 import sys
 import warnings
+from typing import Literal
 
 import numpy as np
 import pandas as pd
@@ -21,6 +22,7 @@
  vectors_to_arrays,
 )
 from pygmt.clib.loading import load_libgmt
+from pygmt.datatypes import _GMT_DATASET, _GMT_GRID
 from pygmt.exceptions import (
  GMTCLibError,
  GMTCLibNoSessionError,
@@ -1588,6 +1590,39 @@ def virtualfile_from_data( # noqa: PLR0912
 
  return file_context
 
+ def read_virtualfile(
+ self, vfname: str, kind: Literal["dataset", "grid", None] = None
+ ):
+ """
+ Read data from a virtual file and optionally cast into a GMT data container.
+
+ Parameters
+ ----------
+ vfname
+ Name of the virtual file to read.
+ kind
+ Cast the data into a GMT data container. Valid values are ``"dataset"``,
+ ``"grid"`` and ``None``. If ``None``, will return a ctypes void pointer.
+
+ Returns
+ -------
+ Pointer to the GMT data container. If ``kind`` is None, returns a ctypes void
+ pointer instead.
+ """
+ c_read_virtualfile = self.get_libgmt_func(
+ "GMT_Read_VirtualFile",
+ argtypes=[ctp.c_void_p, ctp.c_char_p],
+ restype=ctp.c_void_p,
+ )
+ pointer = c_read_virtualfile(self.session_pointer, vfname.encode())
+ # The GMT C API function GMT_Read_VirtualFile returns a void pointer. It usually
+ # needs to be cast into a pointer to a GMT data container (e.g., _GMT_GRID or
+ # _GMT_DATASET).
+ if kind is None: # Return the ctypes void pointer
+ return pointer
+ dtype = {"dataset": _GMT_DATASET, "grid": _GMT_GRID}[kind]
+ return ctp.cast(pointer, ctp.POINTER(dtype))
+
  def extract_region(self):
  """
  Extract the WESN bounding box of the currently active figure.

pygmt/datatypes/__init__.py

@@ -0,0 +1,5 @@
+"""
+Wrappers for GMT data types.
+"""
+from pygmt.datatypes.dataset import _GMT_DATASET
+from pygmt.datatypes.grid import _GMT_GRID

pygmt/datatypes/dataset.py

@@ -0,0 +1,7 @@
+"""
+Wrapper for the GMT_DATASET data type.
+"""
+
+
+class _GMT_DATASET: # noqa: N801
+ pass

pygmt/datatypes/grid.py

@@ -0,0 +1,7 @@
+"""
+Wrapper for the GMT_GRID data type.
+"""
+
+
+class _GMT_GRID: # noqa: N801
+ pass