feat: allow plotting of individual faces (#1757)

Co-authored-by: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com>
Co-authored-by: Maxime Rey <87315832+MaxJPRey@users.noreply.github.com>

Author: 3 people

doc/changelog.d/1757.added.md

@@ -0,0 +1 @@
+allow plotting of individual faces

src/ansys/geometry/core/designer/body.py

@@ -1223,9 +1223,12 @@ def tessellate(  # noqa: D102
         # cache tessellation
         if not self._tessellation:
             resp = self._bodies_stub.GetTessellation(self._grpc_id)
-            self._tessellation = resp.face_tessellation.values()
+            self._tessellation = {
+                str(face_id): tess_to_pd(face_tess)
+                for face_id, face_tess in resp.face_tessellation.items()
+            }
 
-        pdata = [tess_to_pd(tess).transform(transform) for tess in self._tessellation]
+        pdata = [tess.transform(transform, inplace=False) for tess in self._tessellation.values()]
         comp = pv.MultiBlock(pdata)
 
         if merge:

src/ansys/geometry/core/designer/face.py

@@ -65,6 +65,8 @@
 from ansys.tools.visualization_interface.utils.color import Color
 
 if TYPE_CHECKING:  # pragma: no cover
+    import pyvista as pv
+
     from ansys.geometry.core.designer.body import Body
 
 
@@ -564,3 +566,70 @@ def setup_offset_relationship(
         )
 
         return result.success
+
+    def tessellate(self) -> "pv.PolyData":
+        """Tessellate the face and return the geometry as triangles.
+
+        Returns
+        -------
+        ~pyvista.PolyData
+            :class:`pyvista.PolyData` object holding the face.
+        """
+        # If tessellation has not been called before... call it
+        if self._body._template._tessellation is None:
+            self._body.tessellate()
+
+        # Search the tessellation of the face - if it exists
+        # ---> We need to used the last element of the ID since we are looking inside
+        # ---> the master body tessellation.
+        red_id = self.id.split("/")[-1]
+        mb_pdata = self.body._template._tessellation.get(red_id)
+        if mb_pdata is None:  # pragma: no cover
+            raise ValueError(f"Face {self.id} not found in the tessellation.")
+
+        # Return the stored PolyData
+        return mb_pdata.transform(self.body.parent_component.get_world_transform(), inplace=False)
+
+    def plot(
+        self,
+        screenshot: str | None = None,
+        use_trame: bool | None = None,
+        use_service_colors: bool | None = None,
+        **plotting_options: dict | None,
+    ) -> None:
+        """Plot the face.
+
+        Parameters
+        ----------
+        screenshot : str, default: None
+            Path for saving a screenshot of the image that is being represented.
+        use_trame : bool, default: None
+            Whether to enable the use of `trame <https://kitware.github.io/trame/index.html>`_.
+            The default is ``None``, in which case the
+            ``ansys.tools.visualization_interface.USE_TRAME`` global setting is used.
+        use_service_colors : bool, default: None
+            Whether to use the colors assigned to the face in the service. The default
+            is ``None``, in which case the ``ansys.geometry.core.USE_SERVICE_COLORS``
+            global setting is used.
+        **plotting_options : dict, default: None
+            Keyword arguments for plotting. For allowable keyword arguments, see the
+            :meth:`Plotter.add_mesh <pyvista.Plotter.add_mesh>` method.
+
+        """
+        # lazy import here to improve initial module loading time
+        import ansys.geometry.core as pyansys_geometry
+        from ansys.geometry.core.plotting import GeometryPlotter
+        from ansys.tools.visualization_interface.types.mesh_object_plot import (
+            MeshObjectPlot,
+        )
+
+        use_service_colors = (
+            use_service_colors
+            if use_service_colors is not None
+            else pyansys_geometry.USE_SERVICE_COLORS
+        )
+
+        mesh_object = self if use_service_colors else MeshObjectPlot(self, self.tessellate())
+        pl = GeometryPlotter(use_trame=use_trame, use_service_colors=use_service_colors)
+        pl.plot(mesh_object, **plotting_options)
+        pl.show(screenshot=screenshot, **plotting_options)

src/ansys/geometry/core/plotting/plotter.py

@@ -35,6 +35,7 @@
 from ansys.geometry.core.designer.component import Component
 from ansys.geometry.core.designer.design import Design
 from ansys.geometry.core.designer.designpoint import DesignPoint
+from ansys.geometry.core.designer.face import Face
 from ansys.geometry.core.logger import LOG
 from ansys.geometry.core.math.frame import Frame
 from ansys.geometry.core.math.plane import Plane
@@ -243,21 +244,18 @@ def add_body(self, body: Body, merge: bool = False, **plotting_options: dict | N
 
         if self.use_service_colors:
             faces = body.faces
-            dataset = body.tessellate(merge=merge)
             body_color = body.color
             if not merge:
-                # ASSUMPTION: the faces returned by the service are in the same order
-                # as the tessellation information returned by the service...
-                elems = [elem for elem in dataset]
-                for face, block in zip(faces, elems):
+                for face in faces:
                     face_color = face.color
                     if face_color != Color.DEFAULT.value:
                         plotting_options["color"] = face_color
                     else:
                         plotting_options["color"] = body_color
-                    self._backend.pv_interface.plot(block, **plotting_options)
+                    self._backend.pv_interface.plot(face.tessellate(), **plotting_options)
                 return
             else:
+                dataset = body.tessellate(merge=True)
                 plotting_options["color"] = body_color
                 self._backend.pv_interface.plot(dataset, **plotting_options)
                 return
@@ -281,6 +279,32 @@ def add_body(self, body: Body, merge: bool = False, **plotting_options: dict | N
         if self._backend._allow_picking:
             self.add_body_edges(body_plot)
 
+    def add_face(self, face: Face, **plotting_options: dict | None) -> None:
+        """Add a face to the scene.
+
+        Parameters
+        ----------
+        face : Face
+            Face to add.
+        **plotting_options : dict, default: None
+            Keyword arguments. For allowable keyword arguments, see the
+            :meth:`Plotter.add_mesh <pyvista.Plotter.add_mesh>` method.
+        """
+        self._backend.pv_interface.set_add_mesh_defaults(plotting_options)
+        dataset = face.tessellate()
+        if self.use_service_colors:
+            face_color = face.color
+            if face_color != Color.DEFAULT.value:
+                plotting_options["color"] = face_color
+            else:
+                plotting_options["color"] = face.body.color
+            self._backend.pv_interface.plot(dataset, **plotting_options)
+            return
+
+        # Otherwise...
+        face_plot = MeshObjectPlot(custom_object=face, mesh=dataset)
+        self._backend.pv_interface.plot(face_plot, **plotting_options)
+
     def add_component(
         self,
         component: Component,
@@ -438,6 +462,8 @@ def plot(self, plottable_object: Any, name_filter: str = None, **plotting_option
             self.add_sketch(plottable_object, **plotting_options)
         elif isinstance(plottable_object, (Body, MasterBody)):
             self.add_body(plottable_object, merge_bodies, **plotting_options)
+        elif isinstance(plottable_object, Face):
+            self.add_face(plottable_object, **plotting_options)
         elif isinstance(plottable_object, (Design, Component)):
             self.add_component(plottable_object, merge_component, merge_bodies, **plotting_options)
         elif (
@@ -492,7 +518,7 @@ def show(
 
     def export_glb(
         self, plotting_object: Any = None, filename: str | Path | None = None, **plotting_options
-    ) -> None:
+    ) -> Path:
         """Export the design to a glb file. Does not support picked objects.
 
         Parameters

tests/integration/test_plotter.py

@@ -936,7 +936,7 @@ def test_export_glb(modeler: Modeler, verify_image_cache):
     sketch.box(Point2D([10, 10], UNITS.mm), Quantity(10, UNITS.mm), Quantity(10, UNITS.mm))
 
     # Create your design on the server side
-    design = modeler.create_design("BoxExtrusions")
+    design = modeler.create_design("GLBBox")
 
     # Extrude the sketch to create a body
     box_body = design.extrude_sketch("JustABox", sketch, Quantity(10, UNITS.mm))
@@ -956,7 +956,7 @@ def test_export_glb_with_color(modeler: Modeler, verify_image_cache):
     sketch.box(Point2D([10, 10], UNITS.mm), Quantity(10, UNITS.mm), Quantity(10, UNITS.mm))
 
     # Create your design on the server side
-    design = modeler.create_design("BoxExtrusions")
+    design = modeler.create_design("GLBBoxWithColor")
 
     # Extrude the sketch to create a body
     box_body = design.extrude_sketch("JustABox", sketch, Quantity(10, UNITS.mm))
@@ -970,14 +970,14 @@ def test_export_glb_with_color(modeler: Modeler, verify_image_cache):
 
 
 @skip_no_xserver
-def test_export_glb_with_face_color(modeler: Modeler, verify_image_cache):
+def test_export_glb_with_face_color(modeler: Modeler):
     """Test exporting a box to glb."""
     # Create a Sketch
     sketch = Sketch()
     sketch.box(Point2D([10, 10], UNITS.m), Quantity(10, UNITS.m), Quantity(10, UNITS.m))
 
     # Create your design on the server side
-    design = modeler.create_design("BoxExtrusions")
+    design = modeler.create_design("GLBBoxWithFaceColors")
 
     # Extrude the sketch to create a body
     box_body = design.extrude_sketch("JustABox", sketch, Quantity(10, UNITS.m))
@@ -995,7 +995,7 @@ def test_export_glb_with_face_color(modeler: Modeler, verify_image_cache):
 def test_export_glb_cylinder_with_face_color(modeler: Modeler, verify_image_cache):
     """Test exporting a cylinder to glb."""
     # Create your design on the server side
-    design = modeler.create_design("BoxExtrusions")
+    design = modeler.create_design("GLBCylinderWithFaceColors")
 
     # Create a sketch of a circle (overlapping the box slightly)
     sketch_circle = Sketch().circle(Point2D([20, 0], unit=UNITS.m), radius=3 * UNITS.m)
@@ -1009,3 +1009,70 @@ def test_export_glb_cylinder_with_face_color(modeler: Modeler, verify_image_cach
 
     output_glb_path = Path(IMAGE_RESULTS_DIR, "plot_cylinder_glb_face_colored")
     pl.export_glb(cyl, filename=output_glb_path)
+
+
+@skip_no_xserver
+def test_plot_face_colors_from_service(modeler: Modeler, verify_image_cache):
+    """Test exporting a box to glb."""
+    # Create a Sketch
+    sketch = Sketch()
+    sketch.box(Point2D([10, 10], UNITS.m), Quantity(10, UNITS.m), Quantity(10, UNITS.m))
+
+    # Create your design on the server side
+    design = modeler.create_design("BoxWithColors")
+
+    # Extrude the sketch to create a body
+    box_body = design.extrude_sketch("JustABox", sketch, Quantity(10, UNITS.m))
+    # Let's assign colors to the faces...
+    # 1) Box at large
+    box_body.set_color((255, 0, 0))
+    # 2) +Z face
+    box_body.faces[1].set_color((0, 255, 0))
+    # 3) +X face
+    box_body.faces[2].set_color((0, 0, 255))
+
+    box_body.plot(
+        screenshot=Path(IMAGE_RESULTS_DIR, "test_plot_face_colors_from_service.png"),
+        use_service_colors=True,
+    )
+
+
+@skip_no_xserver
+def test_plot_single_face(modeler: Modeler, verify_image_cache):
+    """Test plotting a single face."""
+    # Create your design on the server side
+    design = modeler.create_design("SingleFace")
+
+    # Create a sketch of a box
+    sketch = Sketch()
+    sketch.box(Point2D([10, 10], UNITS.m), Quantity(10, UNITS.m), Quantity(10, UNITS.m))
+
+    # Extrude the sketch to create a body
+    box_body = design.extrude_sketch("JustABox", sketch, Quantity(10, UNITS.m))
+
+    # Test the plotting of the body
+    box_body.faces[1].plot(screenshot=Path(IMAGE_RESULTS_DIR, "plot_single_face.png"))
+
+
+@skip_no_xserver
+def test_plot_single_face_with_service_color(
+    modeler: Modeler, use_service_colors: None, verify_image_cache
+):
+    """Test plotting a single face with service colors."""
+    # Create your design on the server side
+    design = modeler.create_design("SingleFaceWithServiceColor")
+
+    # Create a sketch of a box
+    sketch = Sketch()
+    sketch.box(Point2D([10, 10], UNITS.m), Quantity(10, UNITS.m), Quantity(10, UNITS.m))
+
+    # Extrude the sketch to create a body
+    box_body = design.extrude_sketch("JustABox", sketch, Quantity(10, UNITS.m))
+
+    # Assign color to the body
+    box_body.color = "red"
+
+    # Test the plotting of the body
+    box_body.faces[1].plot(
+        screenshot=Path(IMAGE_RESULTS_DIR, "plot_single_face_with_service_color.png")
+    )