feat: Adapt PyMAPDL to common plotter (#2799)

* feat: Adapt PyMAPDL to common plotter

* fix: Remove manual test file

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* doc: Add docstrings

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: small changes

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: set default bg color

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: Adapt to latest changes

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Apply suggestions from code review

Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com>

* feat: Use visualizer global variables

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: plotter calls

* fix: Plotting calls

* fix: Empty labels

* fix: Plotting tests

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update the image cache

* fix: pre-commit

* Update the image cache

* fix: Remove unused import

* Update the image cache

* fix: codacy issues

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: Plotting issues

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* temp: pass tests

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: Bugs in implementation

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update the image cache

* fix: imports

* fix: remove off_screen

* fix: Doc changes

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: Add missing comma

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: Dependencies

* fix: Dependencies

* fix: Add missing function in plotter

* fix: Wrong override

* Update the image cache

* fix: rename built in shadowing variables

* fix: Built in shadowing

* fix: more built in shadowing

* fix: pre-commit

* fix: Missed shadowing

* fix: remove subplot in example

* Apply suggestions from code review

Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com>

* fix: remove pyvista import in example

* fix: Docs

* fix: Incorrect warning

* fix: Remove import helper from __init__

* fix: Imports

* fix: import plotting if it has pyvista

* fix: minimal dependencies

* fix: Add missing import

* fix: Missing minimal setup

* fix: Tests

* fix: Rework plotting imports

* fix: remove unneeded import

* fix: plotting imports

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: plotting typing

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Adding changelog entry: 2799.miscellaneous.md

* Update doc/source/conf.py

Co-authored-by: German <28149841+germa89@users.noreply.github.com>

* Update src/ansys/mapdl/core/plotting/plotting.py

Co-authored-by: German <28149841+germa89@users.noreply.github.com>

* Update src/ansys/mapdl/core/plotting/plotting.py

Co-authored-by: German <28149841+germa89@users.noreply.github.com>

* Update src/ansys/mapdl/core/plotting/plotting.py

Co-authored-by: German <28149841+germa89@users.noreply.github.com>

* Update tests/conftest.py

Co-authored-by: German <28149841+germa89@users.noreply.github.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Adding changelog entry: 2799.added.md

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: Revert upper limit

* fix: ratio, CHRGS

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: revert opacity

* fix: revert deleted comment

* fix: delete uneeded theme file

* fix: Remove chained calls to plotter

* fix: Missing plotter calls

* fix: Remove beartype

* chore: adding changelog file 2799.dependencies.md

* fix: Add lazy imports due to minimal requirements

* fix: Parameter issues

* fix: Add kwargs to plot

* fix: remove theme import from core

* fix: core init

* fix: Separate consts

* fix: Consts

* fix: wrong method

* fix: Bug in screenshot

* fix: bug in assertion

* fix: multiple test fixes

* fix: Warning no longer required

* fix: plotter input test

* fix: picking tests fixes

* TEMP: Comment test

* fix: type checking

* Update the image cache

* fix: codacy issues

* fix: Add missing docstrings

* fix: remove duplicated import

* fix: remove {} defaults

* tmp: remove failing test

* fix: kwargs defaults

* fix: default kwargs

* fix: remove pyvista dependencies

* fix: Remove uneeded plot and plot_iter

* fix: Improve dependency management in tests

* fix: Change requires pyvista to  visualization tool

* fix: labels font

* fix: Use @require_dependency decorator

* fix: revert unimplemented methods

* fix: Update cache

* fix: bug in legend check

* fix: Update cache

* fix: requires import

* Update the image cache

* fix: bug in picker

* doc: Change general_plotter to MapdlPlotter

* doc: Fix import in docs

* fix: Several small fixes

* fix: Docstring test

* Update the image cache

* test: printing skipped tests

* fix: pyvista requirements

* test: printing all output

* Update the image cache

* Update pyproject.toml

Co-authored-by: German <28149841+germa89@users.noreply.github.com>

* fix: revert pick test changes, revert hook deletion

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: Theme inheritance

* feat: fully support passing plotter

* fix: bad indentation

* fix: Force arial in labels

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: pre-commit

* fix: Wrong legend

* fix: update cache

* Update the image cache

* feat: Add support for passing PyVista plotters

* fix: Force arial and reset cache

* Update the image cache

* fix: Add missing docstring

* fix: Simplify plotter selection

* fix: Delete unused return, fix changelog label

* chore: adding changelog file 2799.dependencies.md

* chore: adding changelog file 2799.added.md

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: German <28149841+germa89@users.noreply.github.com>
Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: AlejandroFernandezLuces <AlejandroFernandezLuces@users.noreply.github.com>
Co-authored-by: German <germanmartinezayuso@gmail.com>
Co-authored-by: pyansys-ci-bot <pyansys.github.bot@ansys.com>
Co-authored-by: germa89 <germa89@users.noreply.github.com>
Co-authored-by: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com>

.devcontainer/codespaces-dev/requirements.txt

@@ -1,4 +1,5 @@
 ansys-dpf-core==0.10.1
+ansys-tools-visualization-interface==0.2.6
 autopep8==2.3.1
 matplotlib==3.9.0
 pandas==2.2.2
@@ -9,6 +10,5 @@ pytest-memprof<0.3.0
 pytest-pyvista==0.1.9
 pytest-rerunfailures==14.0
 pytest==8.2.2
-pyvista==0.43.10
 scipy==1.14.0
 vtk==9.3.0

.devcontainer/codespaces-docs/requirements.txt

@@ -1,6 +1,7 @@
 ansys-dpf-core==0.10.1
 ansys-mapdl-reader==0.53.0
 ansys-sphinx-theme==0.16.6
+ansys-tools-visualization-interface==0.2.6
 grpcio==1.64.1
 imageio-ffmpeg==0.5.1
 imageio==2.34.2
@@ -14,7 +15,6 @@ pyiges[full]==0.3.1
 pypandoc==1.13
 pytest-sphinx==0.6.3
 pythreejs==2.4.2
-pyvista[trame]==0.43.10
 sphinx-autobuild==2024.4.16
 sphinx-autodoc-typehints==1.25.2
 sphinx-copybutton==0.5.2

.devcontainer/devcontainer-local/requirements.txt

@@ -1,6 +1,7 @@
 ansys-dpf-core==0.10.1
 ansys-mapdl-reader==0.53.0
 ansys-sphinx-theme==0.16.6
+ansys-tools-visualization-interface==0.2.6
 autopep8==2.3.1
 grpcio==1.64.1
 imageio-ffmpeg==0.5.1
@@ -21,8 +22,6 @@ pytest-rerunfailures==14.0
 pytest-sphinx==0.6.3
 pytest==8.2.2
 pythreejs==2.4.2
-pyvista[jupyter]==0.43.10
-pyvista==0.43.10
 scipy==1.14.0
 sphinx-autobuild==2024.4.16
 sphinx-autodoc-typehints==1.25.2

.github/dependabot.yml

@@ -53,7 +53,7 @@ updates:
             - "matplotlib"
             - "pexpect"
             - "pyiges"
-            - "pyvista"
+            - "ansys-tools-visualization-interface"
             - "scipy"
             - "tqdm"
             - "vtk"

doc/changelog.d/2799.added.md

@@ -0,0 +1 @@
+feat: Adapt PyMAPDL to common plotter

doc/source/api/plotting.rst

@@ -9,7 +9,7 @@ Various PyMAPDL specific plotting commands.
 .. autosummary::
    :toctree: _autosummary
 
-   plotting.general_plotter
+   plotting.MapdlPlotter
    plotting.MapdlTheme
    Mapdl.aplot
    Mapdl.eplot

doc/source/conf.py

@@ -5,6 +5,7 @@
 from pathlib import Path
 import warnings
 
+import ansys.tools.visualization_interface as viz_interface
 from ansys_sphinx_theme import ansys_favicon, get_version_match
 import numpy as np
 import pyvista
@@ -14,11 +15,14 @@
 from ansys.mapdl import core as pymapdl
 from ansys.mapdl.core import __version__
 
+viz_interface.DOCUMENTATION_BUILD = True
+pyvista.BUILDING_GALLERY = True
+pyvista.OFF_SCREEN = True
+
 # Manage errors
 pyvista.set_error_output_file("errors.txt")
 
 # Ensure that offscreen rendering is used for docs generation
-pyvista.OFF_SCREEN = True
 
 # must be less than or equal to the XVFB window size
 try:

doc/source/examples/extended_examples/gui/executable.rst

@@ -161,7 +161,7 @@ Add a PyVista plotting frame in the window
 ==========================================
 
 Start by importing the `QtInteractor <https://qtdocs.pyvista.org/api_reference.html#qtinteractor>`_
-class from the ``pyvistaqt`` package and the :class:`MapdlTheme <ansys.mapdl.core.theme.MapdlTheme>`
+class from the ``pyvistaqt`` package and the :class:`MapdlTheme <ansys.mapdl.core.plotting.theme.MapdlTheme>`
 class from the ``ansys-mapdl-core`` package:
 
 .. code:: python

doc/source/user_guide/plotting.rst

@@ -12,7 +12,7 @@ transfer the geometry to Python to visualize it:
 - :func:`Mapdl.vplot() <ansys.mapdl.core.Mapdl.vplot>`
 - :func:`Mapdl.eplot() <ansys.mapdl.core.Mapdl.eplot>`). 
 
-These methods rely on the :func:`ansys.mapdl.core.plotting.general_plotter`
+These methods rely on the :class:`ansys.mapdl.core.plotting.visualizer.MapdlPlotter`
 method. Combined with the MAPDL geometry commands, you can
 generate and visualize geometry from scratch without opening the GUI
 using the :func:`open_gui() <ansys.mapdl.core.Mapdl.open_gui>` method.
@@ -171,7 +171,7 @@ to view the XY plane with ``cpos='xy'``.
     >>> mapdl.eplot(cpos="xy")
 
 For all general plotting options, see the
-:func:`ansys.mapdl.core.plotting.general_plotter` method.
+:class:`ansys.mapdl.core.plotting.visualizer.MapdlPlotter` class.
 
 
 Plotting boundary conditions

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

@@ -312,7 +312,7 @@
 #
 # The plot is then shown and it recreates the native plot quite well.
 
-from ansys.mapdl.core.theme import PyMAPDL_cmap
+from ansys.mapdl.core.plotting.theme import PyMAPDL_cmap
 
 plotter = pv.Plotter()
 

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

@@ -38,7 +38,6 @@
 
 # sphinx_gallery_thumbnail_number = 3
 import numpy as np
-import pyvista as pv
 
 from ansys.mapdl.core import launch_mapdl
 
@@ -88,30 +87,21 @@
 # plate_with_hole_anum = mapdl.asba(rect_anum, circ_anum)
 cut_area = mapdl.asba(rect_anum, "ALL")  # cut all areas except the plate
 
-plotter = pv.Plotter(shape=(1, 3))
 
-plotter.subplot(0, 0)
 mapdl.lsla("S")
-mapdl.lplot(vtk=True, show_keypoint_numbering=True, plotter=plotter)
+mapdl.lplot(vtk=True, show_keypoint_numbering=True)
 mapdl.lsel("all")
 
 # plot the area using vtk/pyvista
-plotter.subplot(0, 1)
-mapdl.aplot(
-    vtk=True, show_area_numbering=True, show_lines=True, cpos="xy", plotter=plotter
-)
+mapdl.aplot(vtk=True, 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
-plotter.subplot(0, 2)
-mapdl.vplot(
-    vtk=True, show_lines=True, show_axes=True, smooth_shading=True, plotter=plotter
-)
+mapdl.vplot(vtk=True, show_lines=True, show_axes=True, smooth_shading=True)
 
-plotter.show()
 
 ###############################################################################
 # Meshing

examples/00-mapdl-examples/geometry.py

@@ -42,6 +42,7 @@
 
 from ansys.mapdl import core as pymapdl
 from ansys.mapdl.core import examples
+from ansys.mapdl.core.plotting import MapdlTheme
 
 mapdl = pymapdl.launch_mapdl()
 
@@ -68,7 +69,7 @@
 # remotable (with 2021R1 and newer) interactive plotting.  The common
 # plotting methods (``kplot``, ``lplot``, ``aplot``, ``eplot``, etc.)
 # all have compatible commands that use the
-# :func:`ansys.mapdl.core.plotting.general_plotter` function.  You can
+# :class:`ansys.mapdl.core.plotting.visualizer.MapdlPlotter` class.  You can
 # configure this method with a variety of keyword arguments.  For example:
 
 mapdl.lplot(
@@ -88,7 +89,7 @@
 # multiple plots.  These theme parameters override any unset keyword
 # arguments.  For example:
 
-my_theme = pymapdl.MapdlTheme()
+my_theme = MapdlTheme()
 my_theme.background = "white"
 my_theme.cmap = "jet"  # colormap
 my_theme.axes.show = False

pyproject.toml

@@ -17,6 +17,7 @@ dependencies = [
     "ansys-mapdl-reader>=0.51.7",
     "ansys-math-core>=0.1.2",
     "ansys-platform-instancemanagement~=1.0",
+    "ansys-tools-visualization-interface>=0.2.6",
     "ansys-tools-path>=0.3.1",
     "click>=8.1.3", # for CLI interface
     "grpcio>=1.30.0",  # tested up to grpcio==1.35
@@ -30,7 +31,6 @@ dependencies = [
     "psutil>=5.9.4",
     "pyansys-tools-versioning>=0.3.3",
     "pyiges[full]>=0.3.1", # Since v0.3.0, the 'full' flag is needed in order to install 'geomdl'
-    "pyvista>=0.38.1",
     "scipy>=1.3.0",  # for sparse (consider optional?)
     "tabulate>=0.8.0", # for cli plotting
     "tqdm>=4.45.0",
@@ -54,11 +54,11 @@ classifiers = [
 jupyter = [
     "jupyterlab>=3",
     "ipywidgets",
-    "pyvista[jupyter]",
 ]
 
 tests = [
     "ansys-dpf-core==0.10.1",
+    "ansys-tools-visualization-interface==0.2.6",
     "autopep8==2.3.1",
     "matplotlib==3.9.1",
     "pandas==2.2.2",
@@ -69,13 +69,13 @@ tests = [
     "pytest-pyvista==0.1.9",
     "pytest-rerunfailures==14.0",
     "pytest==8.2.2",
-    "pyvista==0.43.10",
     "scipy==1.14.0",
     "vtk==9.3.1",
 ]
 doc = [
     "ansys-dpf-core==0.10.1",
     "ansys-mapdl-reader==0.53.0",
+    "ansys-tools-visualization-interface==0.2.6",
     "ansys-sphinx-theme==0.16.6",
     "grpcio==1.65.0",
     "imageio-ffmpeg==0.5.1",
@@ -90,7 +90,6 @@ doc = [
     "pypandoc==1.13",
     "pytest-sphinx==0.6.3",
     "pythreejs==2.4.2",
-    "pyvista[jupyter]==0.43.10",
     "sphinx-autobuild==2024.4.16",
     "sphinx-autodoc-typehints==1.25.2",
     "sphinx-copybutton==0.5.2",

src/ansys/mapdl/core/__init__.py

@@ -121,11 +121,12 @@
 from ansys.mapdl.core.mapdl_grpc import MapdlGrpc as Mapdl
 from ansys.mapdl.core.misc import Information, Report, _check_has_ansys
 from ansys.mapdl.core.pool import MapdlPool
-from ansys.mapdl.core.theme import MapdlTheme, _apply_default_theme
 
 _HAS_ANSYS = _check_has_ansys()
 
 if _HAS_PYVISTA:
+    from ansys.mapdl.core.plotting.theme import _apply_default_theme
+
     _apply_default_theme()
 
 BUILDING_GALLERY = False

src/ansys/mapdl/core/examples/examples.py

@@ -23,7 +23,7 @@
 """pymapdl examples"""
 import os
 
-from ansys.mapdl.core.theme import PyMAPDL_cmap
+from ansys.mapdl.core.plotting.theme import PyMAPDL_cmap
 
 # get location of this folder and the example files
 dir_path = os.path.dirname(os.path.realpath(__file__))