Add ASCII gaussian cube data GaussianCubeReader

doc/source/api/readers/index.rst

@@ -34,6 +34,7 @@ Reader Classes
     FLUENTCFFReader
     FluentReader
     GambitReader
+    GaussianCubeReader
     GIFReader
     GLTFReader
     HDFReader

pyvista/core/utilities/__init__.py

@@ -181,6 +181,7 @@
     FLUENTCFFReader,
     FluentReader,
     GambitReader,
+    GaussianCubeReader,
     GIFReader,
     GLTFReader,
     HDFReader,

pyvista/core/utilities/reader.py

@@ -58,6 +58,8 @@ def get_reader(filename, force_ext=None):
     +----------------+---------------------------------------------+
     | ``.cgns``      | :class:`pyvista.CGNSReader`                 |
     +----------------+---------------------------------------------+
+    | ``.cube``      | :class:`pyvista.GaussianCubeReader`         |
+    +----------------+---------------------------------------------+
     | ``.dat``       | :class:`pyvista.TecplotReader`              |
     +----------------+---------------------------------------------+
     | ``.dcm``       | :class:`pyvista.DICOMReader`                |
@@ -2577,12 +2579,101 @@ class GambitReader(BaseReader):
     _vtk_class_name = "vtkGAMBITReader"
 
 
+class GaussianCubeReader(BaseReader):
+    """GaussianCubeReader for .cube files.
+
+    Examples
+    --------
+    >>> import pyvista as pv
+    >>> from pyvista import examples
+
+    >>> filename = examples.download_m4_total_density(load=False)
+    >>> filename.split("/")[-1]  # omit the path
+    'm4_TotalDensity.cube'
+
+    """
+
+    _vtk_module_name = "vtkIOChemistry"
+    _vtk_class_name = "vtkGaussianCubeReader"
+
+    def read(self, grid: bool = True):
+        """Read the file and return the output.
+
+        Parameters
+        ----------
+        grid : bool, default: False
+            Output as a grid if ``True``, otherwise return the polydata.
+        """
+        from pyvista.core.filters import _update_alg  # avoid circular import
+
+        _update_alg(self.reader, progress_bar=self._progress_bar, message=self._progress_msg)
+        data = (
+            wrap(self.reader.GetGridOutput()) if grid else wrap(self.reader.GetOutputDataObject(0))
+        )
+        if data is None:  # pragma: no cover
+            raise RuntimeError("File reader failed to read and/or produced no output.")
+        data._post_file_load_processing()  # type: ignore[union-attr]
+
+        # check for any pyvista metadata
+        data._restore_metadata()  # type: ignore[union-attr]
+        return data
+
+    @property
+    def hb_scale(self) -> float:
+        """Get the scaling factor to compute bonds with hydrogen atoms.
+
+        Returns
+        -------
+        float
+            The scaling factor to compute bonds with hydrogen atoms.
+
+        """
+        return self.reader.GetHBScale()
+
+    @hb_scale.setter
+    def hb_scale(self, hb_scale: float):
+        """Set the scaling factor to compute bonds with hydrogen atoms.
+
+        Parameters
+        ----------
+        hb_scale : float
+            The scaling factor to compute bonds with hydrogen atoms.
+
+        """
+        self.reader.SetHBScale(hb_scale)
+
+    @property
+    def b_scale(self) -> float:
+        """Get the scaling factor to compute bonds between non-hydrogen atoms.
+
+        Returns
+        -------
+        float
+            The scaling factor to compute bonds between non-hydrogen atoms.
+
+        """
+        return self.reader.GetBScale()
+
+    @b_scale.setter
+    def b_scale(self, b_scale: float):
+        """Set the scaling factor to compute bonds between non-hydrogen atoms.
+
+        Parameters
+        ----------
+        b_scale : float
+            The scaling factor to compute bonds between non-hydrogen atoms.
+
+        """
+        self.reader.SetBScale(b_scale)
+
+
 CLASS_READERS = {
     # Standard dataset readers:
     '.bmp': BMPReader,
     '.cas': FluentReader,
     '.case': EnSightReader,
     '.cgns': CGNSReader,
+    '.cube': GaussianCubeReader,
     '.dat': TecplotReader,
     '.dcm': DICOMReader,
     '.dem': DEMReader,

pyvista/examples/downloads.py

@@ -7675,6 +7675,58 @@ def _dataset_room_cff_files_func():
 _dataset_room_cff = _MultiFileDownloadableDatasetLoader(_dataset_room_cff_files_func)
 
 
+def download_m4_total_density(load=True):  # pragma: no cover
+    """Download a total density dataset of the chemistry.
+
+    Parameters
+    ----------
+    load : bool, default: True
+        Load the dataset after downloading it when ``True``.  Set this
+        to ``False`` and only the filename will be returned.
+
+    Returns
+    -------
+    pyvista.ImageData | str
+        DataSet or filename depending on ``load``.
+
+    Examples
+    --------
+    >>> import pyvista as pv
+    >>> from pyvista import examples
+
+    >>> filename = examples.download_m4_total_density(load=False)
+    >>> reader = pv.get_reader(filename)
+    >>> reader.hb_scale = 1.1
+    >>> reader.b_scale = 10.0
+
+    >>> grid = reader.read()
+    >>> poly = reader.read(grid=False)
+
+    Add the outline and volume to the plotter.
+
+    >>> pl = pv.Plotter()
+    >>> outline = pl.add_mesh(grid.outline(), color="black")
+    >>> volume = pl.add_volume(grid)
+
+    Add atoms and bonds to the plotter.
+
+    >>> atoms = pl.add_mesh(poly.glyph(geom=pv.Sphere()), color="red")
+    >>> bonds = pl.add_mesh(poly.tube(), color="white")
+
+    >>> pl.show(cpos="zx")
+
+    .. seealso::
+
+        :ref:`M4 Total Density Dataset <m4_total_density_dataset>`
+            See this dataset in the Dataset Gallery for more info.
+
+    """
+    return _download_dataset(_dataset_m4_total_density, load=load)
+
+
+_dataset_m4_total_density = _SingleFileDownloadableDatasetLoader('m4_TotalDensity.cube')
+
+
 def download_headsq(load=True):  # pragma: no cover
     """Download the headsq dataset.
 

tests/core/test_reader.py

@@ -1036,3 +1036,29 @@ def test_gambitreader():
 
     mesh = reader.read()
     assert all([mesh.n_points, mesh.n_cells])
+
+
+@pytest.mark.skipif(
+    pv.vtk_version_info < (9, 1, 0),
+    reason="Requires VTK>=9.1.0 for a concrete GaussianCubeReader class.",
+)
+def test_gaussian_cubes_reader():
+    filename = examples.download_m4_total_density(load=False)
+    reader = pv.get_reader(filename)
+    assert isinstance(reader, pv.GaussianCubeReader)
+    assert reader.path == filename
+
+    hb_scale = 1.1
+    b_scale = 10.0
+    reader.hb_scale = hb_scale
+    reader.b_scale = b_scale
+    assert reader.hb_scale == hb_scale
+    assert reader.b_scale == b_scale
+
+    grid = reader.read(grid=True)
+    assert isinstance(grid, pv.ImageData)
+    assert all([grid.n_points, grid.n_cells])
+
+    poly = reader.read(grid=False)
+    assert isinstance(poly, pv.PolyData)
+    assert all([poly.n_points, poly.n_cells])