feat: switch to ansys tools and decouple requirements (#532)

## Description
Comply with [#901](ansys/pyansys#902)
Switch from native pyvista to ansys-tools-vizualization-interface

only basic implementation done additional steps will be coming

## Issue linked
#531 

## Checklist
- [x] I have tested my changes locally.
- [x] I have added necessary documentation or updated existing
documentation.
- [x] I have followed the coding style guidelines of this project.
- [x] I have added appropriate tests (unit, integration, system).
- [x] I have reviewed my changes before submitting this pull request.
- [x] I have linked the issue or issues that are solved by the PR if
any.
- [x] I have assigned this PR to myself.
- [x] I have made sure that the title of my PR follows [Conventional
commits style](https://www.conventionalcommits.org/en/v1.0.0/#summary)
(e.g. ``feat: add optical property``)
- [x] I have agreed with the Contributor License Agreement
([CLA](https://developer.ansys.com/form/cla-acceptance)).

---------

Co-authored-by: Sebastien Morais <[email protected]>
Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Sébastien Morais <[email protected]>
Co-authored-by: Pengyuan LU <[email protected]>

Author: 5 people

doc/changelog.d/532.added.md

@@ -0,0 +1 @@
+switch to ansys tools and decouple requirements

pyproject.toml

@@ -32,13 +32,18 @@ dependencies=[
     "grpcio-health-checking>=1.45.0,<1.68",
     "ansys-api-speos==0.14.2",
     "numpy>=1.20.3,<3",
-    "pyvista>=0.40.0,<0.45",
     "comtypes>=1.4,<1.5",
 ]
 
 [project.optional-dependencies]
+graphics = [
+    "pyvista>=0.40.0,<0.45",
+    "ansys-tools-visualization-interface>=0.8.3",
+]
 tests = [
     "pytest==8.3.5",
+    "pyvista>=0.40.0,<0.45",
+    "ansys-tools-visualization-interface>=0.8.3",
     "ansys-platform-instancemanagement>=1.0.3",
     "pytest-cov==6.0.0",
 ]
@@ -47,6 +52,7 @@ jupyter = [
     "jupyterlab>=3",
     "ipywidgets",
     "pyvista[jupyter]>=0.43,<0.45",
+    "ansys-tools-visualization-interface>=0.8.3",
     "notebook==7.3.3",
 ]
 doc = [
@@ -65,6 +71,7 @@ doc = [
     "jupyter-server==2.15.0",
     "nbconvert==7.16.6",
     "pyvista[jupyter]>=0.43,<0.45",
+    "ansys-tools-visualization-interface>=0.8.3",
 ]
 
 [project.urls]

src/ansys/speos/core/generic/general_methods.py

@@ -28,6 +28,12 @@
 from functools import wraps
 import warnings
 
+__GRAPHICS_AVAILABLE = None
+GRAPHICS_ERROR = (
+    "Preview unsupported without 'ansys-tools-visualization_interface' installed. "
+    "You can install this using `pip install ansys-speos-core[graphics]`."
+)
+
 
 def deprecate_kwargs(old_arguments: dict, removed_version="0.3.0"):
     """Issues deprecation warnings for arguments.
@@ -62,3 +68,43 @@ def wrapper(*args, **kwargs):
         return wrapper
 
     return decorator
+
+
+def run_if_graphics_required(warning=False):
+    """Check if graphics are available."""
+    global __GRAPHICS_AVAILABLE
+    if __GRAPHICS_AVAILABLE is None:
+        try:
+            import pyvista as pv  # noqa: F401
+
+            from ansys.tools.visualization_interface import Plotter  # noqa: F401
+
+            __GRAPHICS_AVAILABLE = True
+        except ImportError:  # pragma: no cover
+            __GRAPHICS_AVAILABLE = False
+
+    if __GRAPHICS_AVAILABLE is False and warning is False:  # pragma: no cover
+        raise ImportError(GRAPHICS_ERROR)
+    elif __GRAPHICS_AVAILABLE is False:  # pragma: no cover
+        warnings.warn(GRAPHICS_ERROR)
+
+
+def graphics_required(method):
+    """Decorate a method as requiring graphics.
+
+    Parameters
+    ----------
+    method : callable
+        Method to decorate.
+
+    Returns
+    -------
+    callable
+        Decorated method.
+    """
+
+    def wrapper(*args, **kwargs):
+        run_if_graphics_required()
+        return method(*args, **kwargs)
+
+    return wrapper

src/ansys/speos/core/lxp.py

@@ -30,14 +30,22 @@
 
 import os
 from pathlib import Path
-from typing import Optional, Union
-
-import pyvista as pv
+from typing import TYPE_CHECKING, Optional, Union
 
 import ansys.api.speos.lpf.v2.lpf_file_reader_pb2 as lpf_file_reader__v2__pb2
 import ansys.api.speos.lpf.v2.lpf_file_reader_pb2_grpc as lpf_file_reader__v2__pb2_grpc
+from ansys.speos.core.generic.general_methods import graphics_required
 from ansys.speos.core.project import Project, Speos
 
+if TYPE_CHECKING:  # pragma: no cover
+    from ansys.tools.visualization_interface import Plotter
+try:
+    from ansys.speos.core.generic.general_methods import run_if_graphics_required
+
+    run_if_graphics_required(warning=True)
+except ImportError as err:  # pragma: no cover
+    raise err
+
 ERROR_IDS = [7, 8, 9, 10, 11, 12, 13, 14, 15]
 """Intersection types indicating an error state."""
 
@@ -420,18 +428,21 @@ def remove_error_rays(self) -> LightPathFinder:
         return self
 
     @staticmethod
-    def __add_ray_to_pv(plotter: pv.Plotter, ray: RayPath, max_ray_length: float):
+    @graphics_required
+    def __add_ray_to_pv(plotter: Plotter, ray: RayPath, max_ray_length: float):
         """Add a ray to pyvista plotter.
 
         Parameters
         ----------
-        plotter : pv.Plotter
-            Pyvista plotter object to which rays should be added.
+        plotter : Plotter
+            Ansys plotter object to which rays should be added.
         ray : script.RayPath
             RayPath object which contains ray information to be added.
         max_ray_length : float
             Length of the last ray.
         """
+        import pyvista as pv
+
         temp = ray.impacts.copy()
         if not 7 <= ray.intersection_type[-1] <= 15:
             temp.append(
@@ -445,8 +456,9 @@ def __add_ray_to_pv(plotter: pv.Plotter, ray: RayPath, max_ray_length: float):
             mesh = pv.MultipleLines(temp)
         else:
             mesh = pv.Line(temp[0], temp[1])
-        plotter.add_mesh(mesh, color=wavelength_to_rgb(ray.wl), line_width=2)
+        plotter.plot(mesh, color=wavelength_to_rgb(ray.wl), line_width=2)
 
+    @graphics_required
     def preview(
         self,
         nb_ray: int = 100,
@@ -468,7 +480,8 @@ def preview(
         project : ansys.speos.core.project.Project
             Speos Project/Geometry to be added to pyvista visualisation.
         screenshot : str or Path or ``None``
-            Path to save a screenshot of the plotter.
+            Path to save a screenshot of the plotter. If defined Plotter will only create the
+            screenshot
 
         Returns
         -------
@@ -481,6 +494,8 @@ def preview(
         operating systems (namely Windows) will experience issues
         saving a screenshot if the exit button in the GUI is pressed.
         """
+        from ansys.tools.visualization_interface import Plotter
+
         if ray_filter:
             if len(self._filtered_rays) > 0:
                 temp_rays = self._filtered_rays
@@ -490,7 +505,7 @@ def preview(
         else:
             temp_rays = self._rays
         if not project:
-            plotter = pv.Plotter()
+            plotter = Plotter()
             if nb_ray > len(temp_rays):
                 for ray in temp_rays:
                     self.__add_ray_to_pv(plotter, ray, max_ray_length)

src/ansys/speos/core/project.py

@@ -26,15 +26,15 @@
 import os
 from pathlib import Path
 import re
-from typing import List, Mapping, Optional, Union
+from typing import TYPE_CHECKING, List, Mapping, Optional, Union
 import uuid
 
 from google.protobuf.internal.containers import RepeatedScalarFieldContainer
 import numpy as np
-import pyvista as pv
 
 import ansys.speos.core.body as body
 import ansys.speos.core.face as face
+from ansys.speos.core.generic.general_methods import graphics_required
 from ansys.speos.core.kernel.body import BodyLink
 from ansys.speos.core.kernel.face import FaceLink
 from ansys.speos.core.kernel.part import ProtoPart
@@ -59,6 +59,18 @@
 )
 from ansys.speos.core.speos import Speos
 
+try:
+    from ansys.speos.core.generic.general_methods import run_if_graphics_required
+
+    run_if_graphics_required(warning=True)
+except ImportError as err:  # pragma: no cover
+    raise err
+
+if TYPE_CHECKING:  # pragma: no cover
+    import pyvista as pv
+
+    from ansys.tools.visualization_interface import Plotter
+
 
 class Project:
     """A project describes all Speos features.
@@ -829,6 +841,7 @@ def __extract_part_mesh_info(
         pv.PolyData
             mesh data extracted.
         """
+        import pyvista as pv
 
         def local2absolute(local_vertice: np.ndarray, coordinates) -> np.ndarray:
             """Convert local coordinate to global coordinate.
@@ -888,7 +901,8 @@ def local2absolute(local_vertice: np.ndarray, coordinates) -> np.ndarray:
                     part_mesh_info = part_mesh_info.append_polydata(face_mesh_data)
         return part_mesh_info
 
-    def _create_preview(self, viz_args=None) -> pv.Plotter:
+    @graphics_required
+    def _create_preview(self, viz_args=None) -> Plotter:
         """Create preview pyvista plotter object.
 
         Parameters
@@ -900,6 +914,10 @@ def _create_preview(self, viz_args=None) -> pv.Plotter:
             - {'style': 'surface', 'color':'white'},
             - {'opacity': 0.7, 'color':'white', 'show_edges': False},
         """
+        import pyvista as pv
+
+        from ansys.tools.visualization_interface import Plotter
+
         if viz_args is None:
             viz_args = {}
         _preview_mesh = pv.PolyData()
@@ -921,10 +939,12 @@ def _create_preview(self, viz_args=None) -> pv.Plotter:
         poly_data = self.__extract_part_mesh_info(part_data=root_part_data)
         if poly_data is not None:
             _preview_mesh = _preview_mesh.append_polydata(poly_data)
-        p = pv.Plotter()
-        p.add_mesh(_preview_mesh, show_edges=True, **viz_args)
+        p = Plotter()
+        viz_args["show_edges"] = True
+        p.plot(_preview_mesh, **viz_args)
         return p
 
+    @graphics_required
     def preview(
         self,
         viz_args=None,
@@ -942,7 +962,8 @@ def preview(
             - {'opacity': 0.7, 'color':'white', 'show_edges': False}.
 
         screenshot : str or Path or ``None``
-            Path to save a screenshot of the plotter.
+            Path to save a screenshot of the plotter. If defined Plotter will only create the
+            screenshot
 
         """
         if viz_args is None: