Wrap GMT_Read_VirtualFile

Author: seisman

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