feat: add screenshot in pyvista related methods (#521)

## Description
Adding `screenshot` option to `preview` methods. On top of it, the CI
and test configuration has been updated to allow this kind of test to
without issues. This will allow us to increase the code coverage !!!

## Issue linked
None

## 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``)
- [ ] I have agreed with the Contributor License Agreement
([CLA](https://developer.ansys.com/form/cla-acceptance)).

## Previous PR content, kept for visibility

~To increase code coverage (and fix bugs, see
#520) this PR starts to add test(s)
on a method using pyvista rendering.~
~Three options are available to do so:~
- ~leverage an external github action to use [headless
display](https://github.com/pyvista/setup-headless-display-action);~
- ~use the python package `vtk-osmesa` from vtk, see [available python
wheels]~(https://docs.vtk.org/en/latest/advanced/available_python_wheels.html);
- ~patch the call to `show` so that we don't really trigger them.~

~While I like the two first options as they would let us really test
everything, they also come with a security risk as we don't maintain the
solution associated (tbh, I see little risk in using them though).
Therefore, I'm following the third option. Depending on what you think
about this, we could make this PR evolve.~

---------

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: sthoene <[email protected]>
Co-authored-by: Pengyuan LU <[email protected]>
Co-authored-by: Stefan Thöne <[email protected]>

Author: 5 people

.github/workflows/ci_cd.yml

@@ -85,6 +85,7 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
       - name: Start container
+        shell: bash
         env:
           ANSYSLMD_LICENSE_FILE: 1055@${{ secrets.LICENSE_SERVER }}
         run: |
@@ -99,6 +100,7 @@ jobs:
           dependencies: "pandoc"
           needs-quarto: true
       - name: Stop container
+        shell: bash
         run: |
           docker kill speos-rpc
           docker rm speos-rpc
@@ -112,18 +114,26 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Installing OS packages
+        shell: bash
+        run: |
+          sudo apt-get update
+          sudo apt install -y libgl1 libglx-mesa0 xvfb libgomp1
+
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: ${{ env.MAIN_PYTHON_VERSION }}
 
       - name: Create Python virtual environment
+        shell: bash
         run: |
           python -m venv .venv
           source .venv/bin/activate
           python -c "import sys; print(sys.executable)"
 
       - name: Install packages for testing
+        shell: bash
         run: |
           . .venv/bin/activate
           python -m pip install --upgrade pip
@@ -140,13 +150,15 @@ jobs:
       - name: Start container
         env:
           ANSYSLMD_LICENSE_FILE: 1055@${{ secrets.LICENSE_SERVER }}
+        shell: bash
         run: |
           docker run --detach --name speos-rpc -p 50098:50098 -e SPEOS_LOG_LEVEL=2 -e ANSYSLMD_LICENSE_FILE=${{ env.ANSYSLMD_LICENSE_FILE }} -v "${{ github.workspace }}/tests/assets:/app/assets" --entrypoint /app/SpeosRPC_Server.x ghcr.io/ansys/speos-rpc:dev
 
       - name: Run pytest
+        shell: bash
         run: |
           . .venv/bin/activate
-          pytest -xs
+          xvfb-run pytest -xs
 
       - name: Upload Coverage Results
         if: always()
@@ -164,6 +176,7 @@ jobs:
           files: .cov/xml
 
       - name: Stop container
+        shell: bash
         run: |
           docker kill speos-rpc
           docker rm speos-rpc

doc/changelog.d/521.added.md

@@ -0,0 +1 @@
+add screenshot in pyvista related methods

src/ansys/speos/core/lxp.py

@@ -29,7 +29,8 @@
 from __future__ import annotations
 
 import os
-from typing import Union
+from pathlib import Path
+from typing import Optional, Union
 
 import pyvista as pv
 
@@ -431,7 +432,7 @@ def __add_ray_to_pv(plotter: pv.Plotter, ray: RayPath, max_ray_length: float):
         max_ray_length : float
             Length of the last ray.
         """
-        temp = ray.impacts
+        temp = ray.impacts.copy()
         if not 7 <= ray.intersection_type[-1] <= 15:
             temp.append(
                 [
@@ -452,6 +453,7 @@ def preview(
         max_ray_length: float = 50.0,
         ray_filter: bool = False,
         project: Project = None,
+        screenshot: Optional[Union[str, Path]] = None,
     ) -> LightPathFinder:
         """Preview LPF file with pyvista.
 
@@ -465,11 +467,19 @@ def preview(
             Boolean to decide if filtered rays or all rays should be shown.
         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.
 
         Returns
         -------
         ansys.speos.core.lxp.LightPathFinder
             LightPathFinder Instance.
+
+        Notes
+        -----
+        Please use the ``q``-key to close the plotter as some
+        operating systems (namely Windows) will experience issues
+        saving a screenshot if the exit button in the GUI is pressed.
         """
         if ray_filter:
             if len(self._filtered_rays) > 0:
@@ -495,10 +505,10 @@ def preview(
             else:
                 for i in range(nb_ray):
                     self.__add_ray_to_pv(plotter, temp_rays[i], max_ray_length)
-        if os.environ.get("DOCUMENTATION_BUILDING", "true") == "true":
-            plotter.show(jupyter_backend="html")
+        if os.environ.get("DOCUMENTATION_BUILDING", "false") == "true":
+            plotter.show(screenshot=screenshot, jupyter_backend="html")
         else:
-            plotter.show()
+            plotter.show(screenshot=screenshot)
         return self
 
 

src/ansys/speos/core/project.py

@@ -24,6 +24,7 @@
 from __future__ import annotations
 
 import os
+from pathlib import Path
 import re
 from typing import List, Mapping, Optional, Union
 import uuid
@@ -924,7 +925,11 @@ def _create_preview(self, viz_args=None) -> pv.Plotter:
         p.add_mesh(_preview_mesh, show_edges=True, **viz_args)
         return p
 
-    def preview(self, viz_args=None) -> None:
+    def preview(
+        self,
+        viz_args=None,
+        screenshot: Optional[Union[str, Path]] = None,
+    ) -> None:
         """Preview cad bodies inside the project's scene.
 
         Parameters
@@ -934,12 +939,19 @@ def preview(self, viz_args=None) -> None:
             e.g.
             - {'style': 'wireframe'},
             - {'style': 'surface', 'color':'white'},
-            - {'opacity': 0.7, 'color':'white', 'show_edges': False},
+            - {'opacity': 0.7, 'color':'white', 'show_edges': False}.
+
+        screenshot : str or Path or ``None``
+            Path to save a screenshot of the plotter.
+
         """
         if viz_args is None:
             viz_args = {"opacity": 1}
+        if screenshot is not None:
+            screenshot = Path(screenshot)
+
         p = self._create_preview(viz_args=viz_args)
         if os.environ.get("DOCUMENTATION_BUILDING", "true") == "true":
-            p.show(jupyter_backend="html")
+            p.show(screenshot=screenshot, jupyter_backend="html")
         else:
-            p.show()
+            p.show(screenshot=screenshot)

tests/conftest.py

@@ -38,6 +38,16 @@
 from ansys.speos.core import LOG
 from ansys.speos.core.speos import Speos
 
+try:
+    import pyvista as pv
+
+    pv.OFF_SCREEN = True
+    pv.global_theme.window_size = [500, 500]
+except ImportError:
+    pass
+
+IMAGE_RESULTS_DIR = Path(Path(__file__).parent, "image_results")
+
 
 @pytest.fixture(scope="session")
 def speos():

tests/core/test_lxp.py

@@ -25,14 +25,17 @@
 from pathlib import Path
 
 import ansys.speos.core.lxp as lxp
+from ansys.speos.core.project import Project
 from ansys.speos.core.speos import Speos
-from tests.conftest import test_path
+from tests.conftest import IMAGE_RESULTS_DIR, test_path
 
 
 def test_light_path_finder_direct(speos: Speos):
     """Test for direct simulation lpf."""
     path = str(Path(test_path) / "basic_DirectSimu.lpf")
     lpf = lxp.LightPathFinder(speos=speos, path=path)
+    screenshot = Path(IMAGE_RESULTS_DIR, "test_light_path_finder_preview.png")
+    lpf.preview(screenshot=screenshot)
     expected_ray = {
         "nb_impacts": 4,
         "impacts": [
@@ -123,3 +126,32 @@ def test_light_path_finder_inverse(speos: Speos):
     lpf.filter_error_rays()
     assert len(lpf.filtered_rays) == 0
     assert lpf.rays[50].get() == expected_ray
+
+
+def test_lpf_preview_with_project(speos: Speos):
+    """Test for visualizing lpf data."""
+    path = str(Path(test_path) / "basic_DirectSimu.lpf")
+    screenshot = Path(IMAGE_RESULTS_DIR, "test_light_path_finder_direct.png")
+    p = Project(
+        speos=speos,
+        path=str(
+            Path(test_path) / "LG_50M_Colorimetric_short.sv5" / "LG_50M_Colorimetric_short.sv5"
+        ),
+    )
+    lpf = lxp.LightPathFinder(speos=speos, path=path)
+    lpf.preview(project=p, screenshot=screenshot)
+    assert screenshot.exists()
+    assert screenshot.stat().st_size > 0
+
+
+def test_lpf_preview_without_project(speos: Speos):
+    """Test for visualizing lpf data."""
+    path = str(Path(test_path) / "basic_DirectSimu.lpf")
+    screenshot = Path(IMAGE_RESULTS_DIR, "test_lpf_preview_without_project.png")
+    lpf1 = lxp.LightPathFinder(speos=speos, path=path)
+    lpf1.filter_by_body_ids([3601101451])
+    lpf1.filter_by_face_ids([3866239813], new=False)
+    lpf1.remove_error_rays()
+    lpf1.preview(ray_filter=True, screenshot=screenshot)
+    assert screenshot.exists()
+    assert screenshot.stat().st_size > 0

tests/image_results/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore