feat: Add optional graphical target and rework graphics backend selection

doc/changelog.d/3820.fixed.md

@@ -0,0 +1 @@
+fix: Optional graphics dependency

doc/source/user_guide/plotting.rst

@@ -10,7 +10,7 @@ transfer the geometry to Python to visualize it:
 
 - :func:`Mapdl.kplot() <ansys.mapdl.core.Mapdl.kplot>`
 - :func:`Mapdl.vplot() <ansys.mapdl.core.Mapdl.vplot>`
-- :func:`Mapdl.eplot() <ansys.mapdl.core.Mapdl.eplot>`). 
+- :func:`Mapdl.eplot() <ansys.mapdl.core.Mapdl.eplot>`).
 
 These methods rely on the :class:`ansys.mapdl.core.plotting.visualizer.MapdlPlotter`
 method. Combined with the MAPDL geometry commands, you can
@@ -91,10 +91,10 @@ some element types, performs meshing, and then displays the mesh:
 Plotting non-interactively using MAPDL
 --------------------------------------
 You can also plot using MAPDL's native plotting tools. To use the
-native tools, pass ``vtk=False`` when running plotting commands such
+native tools, pass ``graphics_backend=GraphicsBackend.MATPLOTLIB`` when running plotting commands such
 as the :func:`Mapdl.aplot <ansys.mapdl.core.Mapdl.aplot>` and
 :func:`Mapdl.eplot <ansys.mapdl.core.Mapdl.eplot>` methods. Plots are
-generated within MAPDL and then shown using 
+generated within MAPDL and then shown using
 `Matplotlib <matplotlib_main_>`_.
 
 
@@ -132,15 +132,16 @@ Each of these creates a Matplotlib figure and pause execution.
 
 .. code:: pycon
 
-    >>> mapdl.aplot(vtk=False)
-    >>> mapdl.lplot(vtk=False)
-    >>> mapdl.kplot(vtk=False)
+    >>> from ansys.mapdl.core import GraphicsBackend
+    >>> mapdl.aplot(graphics_backend=GraphicsBackend.MATPLOTLIB)
+    >>> mapdl.lplot(graphics_backend=GraphicsBackend.MATPLOTLIB)
+    >>> mapdl.kplot(graphics_backend=GraphicsBackend.MATPLOTLIB)
 
 
 .. figure:: ../images/aplot.png
     :width: 400pt
 
-    Area Plot from MAPDL displayed using 
+    Area Plot from MAPDL displayed using
     `Matplotlib <matplotlib_main_>`_
 
 
@@ -149,7 +150,7 @@ For more information on plotting functions, see :ref:`ref_plotting_api`.
 
 Plotting keyword options
 ------------------------
-When ``vtk=True``, which is the default, all MAPDL plotting
+When ``graphics_backend=GraphicsBackend.PYVISTA``, which is the default, all MAPDL plotting
 methods allow you to enter in additional keyword arguments to better
 control the plot. For example, you can automatically generate a
 screenshot of an area plot or element plot with this code:

pyproject.toml

@@ -18,10 +18,8 @@ dependencies = [
     "ansys-math-core>=0.1.2",
     "ansys-platform-instancemanagement~=1.0",
     "ansys-tools-path>=0.3.1",
-    "ansys-tools-visualization-interface>=0.2.6",
     "click>=8.1.3", # for CLI interface
     "grpcio>=1.30.0",  # tested up to grpcio==1.35
-    "matplotlib>=3.0.0",  # for colormaps for pyvista
     "numpy>=1.14.0,<3.0.0",
     "pexpect>=4.8.0 ; platform_system=='Linux'",
     "platformdirs>=3.6.0",
@@ -53,6 +51,18 @@ jupyter = [
     "ipywidgets",
 ]
 
+graphics = [
+    "ansys-tools-visualization-interface>=0.2.6",
+    "matplotlib>=3.0.0",  # for colormaps for pyvista
+]
+
+all = [
+    "ansys-tools-visualization-interface>=0.2.6",
+    "matplotlib>=3.0.0",  # for colormaps for pyvista
+    "jupyterlab>=3",
+    "ipywidgets",
+]
+
 tests = [
     "ansys-dpf-core==0.10.1",
     "ansys-tools-visualization-interface==0.8.3",

src/ansys/mapdl/core/__init__.py

@@ -20,6 +20,8 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+from enum import Enum
+
 ###############################################################################
 # Imports
 # =======
@@ -73,7 +75,19 @@
 _HAS_PYVISTA: bool = is_installed("pyvista")
 _HAS_REQUESTS: bool = is_installed("requests")
 _HAS_TQDM: bool = is_installed("tqdm")
-_HAS_VISUALIZER: bool = is_installed("ansys.tools.visualization_interface")
+_HAS_VISUALIZER: bool = is_installed(
+    "ansys.tools.visualization_interface"
+) and is_installed("matplotlib")
+
+
+class GraphicsBackend(Enum):
+    """Graphics backend for PyMAPDL.
+
+    This enum is used to set the graphics backend for PyMAPDL.
+    """
+
+    PYVISTA: str = "pyvista"
+    MATPLOTLIB: str = "matplotlib"
 
 
 # Setup directories

src/ansys/mapdl/core/mapdl_core.py

@@ -42,6 +42,7 @@
 import numpy as np
 
 from ansys.mapdl import core as pymapdl
+from ansys.mapdl.core import GraphicsBackend
 from ansys.mapdl.core import LOG as logger
 from ansys.mapdl.core import _HAS_VISUALIZER
 from ansys.mapdl.core.commands import (
@@ -70,6 +71,7 @@
     check_valid_routine,
     last_created,
     random_string,
+    requires_graphics,
     requires_package,
     run_as,
     supress_logging,
@@ -254,7 +256,7 @@ class _MapdlCore(Commands):
     def __init__(
         self,
         loglevel: DEBUG_LEVELS = "DEBUG",
-        use_vtk: Optional[bool] = None,
+        graphics_backend: Optional[GraphicsBackend] = None,
         log_apdl: Optional[str] = None,
         log_file: Union[bool, str] = False,
         local: bool = True,
@@ -283,18 +285,16 @@ def __init__(
         self._save_selection_obj = None
 
         if _HAS_VISUALIZER:
-            if use_vtk is not None:  # pragma: no cover
-                self._use_vtk = use_vtk
+            if graphics_backend is not None:  # pragma: no cover
+                self._graphics_backend = graphics_backend
             else:
-                self._use_vtk = True
+                self._graphics_backend = GraphicsBackend.PYVISTA
         else:  # pragma: no cover
-            if use_vtk:
+            if graphics_backend:
                 raise ModuleNotFoundError(
-                    "Using the keyword argument 'use_vtk' requires having "
-                    "'ansys-tools-visualization_interface' installed."
+                    "Graphic libraries are required to use this class.\n"
+                    "You  can install this using `pip install ansys-mapdl-core[graphics]`."
                 )
-            else:
-                self._use_vtk = False
 
         self._log_filehandler = None
         self._local: bool = local
@@ -1035,14 +1035,14 @@ def solution(self) -> "Solution":
         return self._solution
 
     @property
-    def use_vtk(self):
+    def graphics_backend(self):
         """Returns if using VTK by default or not."""
-        return self._use_vtk
+        return self._graphics_backend
 
-    @use_vtk.setter
-    def use_vtk(self, value: bool):
+    @graphics_backend.setter
+    def graphics_backend(self, value: GraphicsBackend):
         """Set VTK to be used by default or not."""
-        self._use_vtk = value
+        self._graphics_backend = value
 
     @property
     @requires_package("ansys.mapdl.reader", softerror=True)
@@ -1862,16 +1862,10 @@ def __init__(self, parent: "MapdlBase", pixel_res: int) -> None:
             self._parent = weakref.ref(parent)
             self._pixel_res = pixel_res
 
+        @requires_graphics
         def __enter__(self) -> None:
             self._parent()._log.debug("Entering in 'WithInterativePlotting' mode")
 
-            if not self._parent()._has_matplotlib:  # pragma: no cover
-                raise ModuleNotFoundError(
-                    "Install matplotlib to display plots from MAPDL ,"
-                    "from Python.  Otherwise, plot with vtk with:\n"
-                    "``vtk=True``"
-                )
-
             if not self._parent()._store_commands:
                 if not self._parent()._png_mode:
                     self._parent().show("PNG", mute=True)