feat: Add optional graphical target and rework graphics backend selection

doc/changelog.d/3820.fixed.md

@@ -0,0 +1 @@
+feat: Add optional graphical target and rework graphics backend selection

doc/source/api/mapdl.rst

@@ -75,7 +75,7 @@
    Mapdl.screenshot
    Mapdl.set_log_level
    Mapdl.thermal_result
-   Mapdl.use_vtk
+   Mapdl.graphics_backend
    Mapdl.version
 
 

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.MAPDL`` 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.plotting import GraphicsBackend
+    >>> mapdl.aplot(graphics_backend=GraphicsBackend.MAPDL)
+    >>> mapdl.lplot(graphics_backend=GraphicsBackend.MAPDL)
+    >>> mapdl.kplot(graphics_backend=GraphicsBackend.MAPDL)
 
 
 .. 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:

examples/00-mapdl-examples/2d_magnetostatic_solenoid-BodyFlux_Averaging.py

@@ -84,6 +84,7 @@
 import pyvista as pv
 
 from ansys.mapdl.core import launch_mapdl
+from ansys.mapdl.core.plotting import GraphicsBackend
 
 ###############################################################################
 # Launch MAPDL service
@@ -182,7 +183,7 @@
 mapdl.pnum("MAT", 1)  # Turn material numbers on
 mapdl.allsel("ALL")
 
-mapdl.aplot(vtk=False)
+mapdl.aplot(graphics_backend=GraphicsBackend.MAPDL)
 
 ###############################################################################
 # Mesh

examples/00-mapdl-examples/2d_plate_with_a_hole.py

@@ -120,7 +120,6 @@
 mapdl.esize(plate_esize)
 mapdl.amesh(plate_with_hole_anum)
 mapdl.eplot(
-    vtk=True,
     cpos="xy",
     show_edges=True,
     show_axes=False,

examples/00-mapdl-examples/3d_notch.py

@@ -89,18 +89,18 @@
 
 
 mapdl.lsla("S")
-mapdl.lplot(vtk=True, show_keypoint_numbering=True)
+mapdl.lplot(show_keypoint_numbering=True)
 mapdl.lsel("all")
 
 # plot the area using vtk/pyvista
-mapdl.aplot(vtk=True, show_area_numbering=True, show_lines=True, cpos="xy")
+mapdl.aplot(show_area_numbering=True, show_lines=True, cpos="xy")
 
 # Next, extrude the area to create volume
 thickness = 0.01
 mapdl.vext(cut_area, dz=thickness)
 
 # Checking volume plot
-mapdl.vplot(vtk=True, show_lines=True, show_axes=True, smooth_shading=True)
+mapdl.vplot(show_lines=True, show_axes=True, smooth_shading=True)
 
 
 ###############################################################################
@@ -126,7 +126,7 @@
 # line and area numbers identified using aplot
 
 mapdl.asel("S", "AREA", vmin=1, vmax=1)
-mapdl.aplot(vtk=True, show_line_numbering=True)
+mapdl.aplot(show_line_numbering=True)
 
 
 mapdl.lsel("NONE")
@@ -147,7 +147,7 @@
 mapdl.esize()  # this is tough to automate
 mapdl.et(1, "SOLID186")
 mapdl.vsweep("all")
-mapdl.eplot(vtk=True, show_edges=True, show_axes=False, line_width=2, background="w")
+mapdl.eplot(show_edges=True, show_axes=False, line_width=2, background="w")
 
 
 ###############################################################################

examples/00-mapdl-examples/bracket_static.py

@@ -215,7 +215,7 @@
 circle1_Y = (box1[2] + box1[3]) / 2
 mapdl.cyl4(circle1_X, circle1_Y, radius)
 
-mapdl.aplot(vtk=True, cpos="xy", show_lines=True)
+mapdl.aplot(cpos="xy", show_lines=True)
 
 
 ###############################################################################
@@ -233,7 +233,7 @@
 # as the first circle area.
 
 mapdl.cyl4(circle2_X, circle2_Y, radius)
-mapdl.aplot(vtk=True, cpos="xy", show_lines=True)
+mapdl.aplot(cpos="xy", show_lines=True)
 
 
 ###############################################################################
@@ -299,7 +299,7 @@
 line3 = mapdl.lfillt("line1", l2, fillet_radius)
 
 mapdl.allsel()
-mapdl.lplot(vtk=True, cpos="xy")
+mapdl.lplot(cpos="xy")
 
 ###############################################################################
 # Create fillet area
@@ -334,7 +334,7 @@
 mapdl.lsel("A", "LINE", "", line3)
 
 # plotting ares
-mapdl.lplot(vtk=True, cpos="xy", show_line_numbering=True)
+mapdl.lplot(cpos="xy", show_line_numbering=True)
 
 ###############################################################################
 # Then use :meth:`mapdl.al() <ansys.mapdl.core.Mapdl.al>` command to create the areas
@@ -355,7 +355,7 @@
 
 # Add the area to the main area
 mapdl.aadd("all")
-mapdl.aplot(vtk=True, cpos="xy", show_lines=True)
+mapdl.aplot(cpos="xy", show_lines=True)
 
 ###############################################################################
 # Create first pin hole
@@ -410,7 +410,7 @@
 # Remove pin hole areas from bracket
 mapdl.asba("all", pinhole1)
 bracket = mapdl.asba("all", pinhole2)
-mapdl.aplot(vtk=True, show_lines=True, cpos="xy")
+mapdl.aplot(show_lines=True, cpos="xy")
 
 ###############################################################################
 # Model definition
@@ -500,7 +500,6 @@
 mapdl.esize(element_size)
 mapdl.amesh(bracket)
 mapdl.eplot(
-    vtk=True,
     cpos="xy",
     show_edges=True,
     show_axes=False,
@@ -612,7 +611,7 @@
 #
 mapdl.lsel("R", "LOC", "X", 0, pinhole2_X)
 
-mapdl.lplot(vtk=True, cpos="xy")
+mapdl.lplot(cpos="xy")
 
 ###############################################################################
 #
@@ -634,7 +633,6 @@
 mapdl.lsel("R", "LOC", "X", pinhole2_X, pinhole2_X + pinhole_radius)
 
 mapdl.lplot(
-    vtk=True,
     cpos="xy",
     show_line_numbering=True,
 )

examples/00-mapdl-examples/lathe_cutter.py

@@ -94,6 +94,7 @@
 
 from ansys.mapdl.core import launch_mapdl
 from ansys.mapdl.core.examples.downloads import download_example_data
+from ansys.mapdl.core.plotting import GraphicsBackend
 
 # cwd = current working directory
 path = os.getcwd()
@@ -194,9 +195,9 @@
 #
 # VTK plots do not show MAPDL plot symbols.
 # However, to use MAPDL plotting capabilities, you can set the keyword
-# option ``vtk`` to ``False``.
-
-mapdl.lplot(vtk=False)
+# option ``backend`` to ``GraphicsBackend.MAPDL``.
+mapdl.set_graphics_backend(GraphicsBackend.MAPDL)
+mapdl.lplot()
 
 ###############################################################################
 # Step 4: Pressure load
@@ -244,7 +245,7 @@
 mapdl.nlgeom("On")
 mapdl.psf("PRES", "NORM", 3, 0, 1)
 mapdl.view(1, -1, 1, 1)
-mapdl.eplot(vtk=False)
+mapdl.eplot()
 
 ###############################################################################
 # Solve the model.

examples/00-mapdl-examples/mapdl_beam.py

@@ -69,7 +69,7 @@
 print(mapdl.mesh.nnum)
 
 # plot the nodes using VTK
-mapdl.nplot(vtk=True, nnum=True, cpos="xy", show_bounds=True, point_size=10)
+mapdl.nplot(nnum=True, cpos="xy", show_bounds=True, point_size=10)
 
 ###############################################################################
 # create elements between the nodes

examples/02-tips-n-tricks/01-smoothing-element-size-transitions.py

@@ -126,7 +126,7 @@
 for k in [k2, k3, k6, k7]:
     mapdl.kesize(k, 0.2)
 mapdl.amesh("ALL")
-mapdl.eplot(vtk=True, show_edges=True, show_axes=False, line_width=2, background="w")
+mapdl.eplot(show_edges=True, show_axes=False, line_width=2, background="w")
 
 
 ###############################################################################

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

@@ -73,7 +73,9 @@
 _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")
 
 
 # Setup directories

src/ansys/mapdl/core/_commands/graphics_/style.py

@@ -293,7 +293,7 @@ def eshape(
         warnings.warn(
             "pymapdl does not support /ESHAPE when plotting in "
             "Python using ``mapdl.eplot()``.  "
-            "Use ``mapdl.eplot(vtk=False)`` "
+            "Use ``mapdl.eplot(backend=GraphicsBackend.MAPDL)`` "
         )
         command = f"/ESHAPE,{scale},{key}"
         return self.run(command, **kwargs)

src/ansys/mapdl/core/_commands/post1_/controls.py

@@ -171,7 +171,7 @@ def efacet(self, num="", **kwargs):
 
         .. warning::
            This will not change element plotting within PyMAPDL with
-           ``eplot(vtk=True)``
+           ``eplot()``
 
         Parameters
         ----------

src/ansys/mapdl/core/cli/convert.py

@@ -24,6 +24,8 @@
 
 import click
 
+from ansys.mapdl.core.plotting import GraphicsBackend
+
 
 @click.command(
     short_help="Convert APDL code to PyMAPDL code.",
@@ -173,10 +175,10 @@
 Overrides ``header``, ``add_imports`` and ``auto_exit``.""",
 )
 @click.option(
-    "--use_vtk",
+    "--graphics_backend",
     default=None,
-    type=bool,
-    help="""It sets the `mapdl.use_vtk` argument equals True or False depending on
+    type=str,
+    help="""It sets the `mapdl.graphics_backend` argument depending on
 this value. Defaults to `None` which is Mapdl class default.""",
 )
 @click.option(
@@ -207,13 +209,32 @@
     header: str,
     print_com: bool,
     only_commands: bool,
-    use_vtk: bool,
+    graphics_backend: str,
     clear_at_start: bool,
     check_parameter_names: bool,
 ) -> None:
     """Convert MAPDL code to PyMAPDL"""
     from ansys.mapdl.core.convert import convert_apdl_block
 
+    allowed_backends = GraphicsBackend.__members__
+    backend = None
+
+    if graphics_backend is not None:
+        if (
+            isinstance(graphics_backend, str)
+            and graphics_backend.upper() in allowed_backends
+        ):
+            backend = GraphicsBackend[graphics_backend.upper()]
+        elif graphics_backend in list(allowed_backends.values()):
+            backend = graphics_backend
+        else:
+            allowed_backend_string = ", ".join(
+                [str(each) for each in allowed_backends.values()]
+            )
+            raise ValueError(
+                f"Invalid graphics backend '{graphics_backend}'. Allowed values are: {allowed_backend_string}."
+            )
+
     converted_code = convert_apdl_block(
         apdl_strings=file.read(),
         loglevel=loglevel,
@@ -229,7 +250,7 @@
         header=header,
         print_com=print_com,
         only_commands=only_commands,
-        use_vtk=use_vtk,
+        graphics_backend=backend,
         clear_at_start=clear_at_start,
         check_parameter_names=check_parameter_names,
     )