feat: use service colors in plotter (upon request) (#1376)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: pyansys-ci-bot <[email protected]>

Author: 3 people

doc/changelog.d/1376.added.md

@@ -0,0 +1 @@
+use service colors in plotter (upon request)

doc/source/_static/thumbnails/service_colors.png

@@ -279,6 +279,7 @@ def intersphinx_pyansys_geometry(switcher_version: str):
     "examples/03_modeling/revolving": "_static/thumbnails/revolving.png",
     "examples/03_modeling/export_design": "_static/thumbnails/export_design.png",
     "examples/03_modeling/design_tree": "_static/thumbnails/design_tree.png",
+    "examples/03_modeling/service_colors": "_static/thumbnails/service_colors.png",
     "examples/04_applied/01_naca_airfoils": "_static/thumbnails/naca_airfoils.png",
     "examples/04_applied/02_naca_fluent": "_static/thumbnails/naca_fluent.png",
 }

doc/source/conf.py

@@ -46,6 +46,7 @@ These examples demonstrate service-based modeling operations.
     examples/03_modeling/revolving.mystnb
     examples/03_modeling/export_design.mystnb
     examples/03_modeling/design_tree.mystnb
+    examples/03_modeling/service_colors.mystnb
 
 Applied examples
 ----------------

doc/source/examples.rst

@@ -0,0 +1,158 @@
+---
+jupytext:
+  text_representation:
+    extension: .mystnb
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.14.1
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+---
+# Modeling: Body color assignment and usage
+
+In PyAnsys Geometry, a *body* represents solids or surfaces organized within the ``Design`` assembly.
+As users might be already familiar with, Ansys CAD products (like SpaceClaim, Ansys Discovery and the
+Geometry Service), allow to assign colors to bodies. This example shows how to assign colors to a body,
+retrieve their value and how to use them in the client-side visualization.
+
+## Perform required imports
+
+Perform the required imports.
+
+```{code-cell} ipython3
+import ansys.geometry.core as pyansys_geometry
+
+from ansys.geometry.core import Modeler
+from ansys.geometry.core.math import Point2D, UNITVECTOR3D_X, UNITVECTOR3D_Y
+from ansys.geometry.core.sketch import Sketch
+```
+
+## Create a box sketch
+
+Create a ``Sketch`` instance and insert a box sketch with a width and height of 10
+in the default plane.
+
+```{code-cell} ipython3
+sketch = Sketch()
+sketch.box(Point2D([0, 0]), 10, 10)
+```
+
+## Initiate design on server
+
+Establish a server connection and initiate a design on the server.
+
+```{code-cell} ipython3
+modeler = Modeler()
+design = modeler.create_design("ServiceColors")
+```
+
+## Extrude the box sketch to create the matrix style design
+
+Given our initial sketch, we will extrude it to create a matrix style design.
+We will create a 2x3 matrix of bodies. Each body will be separated by 30 units
+in the X direction and 30 units in the Y direction. We will have a total of 6 bodies.
+
+```{code-cell} ipython3
+translate = [[0, 30, 60], [0, 30, 60]]
+
+for r_idx, row in enumerate(translate):
+    comp = design.add_component(f"Component{r_idx}")
+
+    for b_idx, dist in enumerate(row):
+        body = comp.extrude_sketch(f"Component{r_idx}_Body{b_idx}", sketch, distance=10)
+        body.translate(UNITVECTOR3D_Y, r_idx*30)
+        body.translate(UNITVECTOR3D_X, dist)
+
+design.plot()
+```
+
+## Assign colors to the bodies
+
+Given our previous design, we will assign a color to each body. We will assign
+a different color to each one of them. We could have done this assignment while
+creating the bodies, but we will do it now for the sake of encapsulating the
+color assignment logic.
+
+```{code-cell} ipython3
+
+colors = [["red", "blue", "yellow"], ["orange", "green", "purple"]]
+
+for c_idx, comp in enumerate(design.components):
+    for b_idx, body in enumerate(comp.bodies):
+        body.color = colors[c_idx][b_idx]
+        print(f"Body {body.name} has color {body.color}")
+```
+
+## Plotting the design with colors
+
+By default, the plot method will **not** use the colors assigned to the bodies.
+To plot the design with the assigned colors, we need to specifically request it.
+
+Users have two options for plotting with the assigned colors:
+
+* Pass the parameter ``use_service_colors=True`` to the plot method.
+* Set the global parameter ``USE_SERVICE_COLORS`` to ``True``.
+
+It is important to note that the usage of colors when plotting might slow down the
+plotting process, as it requires additional information to be sent from the server
+to the client and processed in the client side.
+
+If we just request the plot without setting the global parameter, the plot will
+be displayed without the colors, as shown below.
+
+```{code-cell} ipython3
+design.plot()
+```
+
+As stated previously, if we pass the parameter ``use_service_colors=True`` to the plot
+method, the plot will be displayed with the assigned colors.
+
+```{code-cell} ipython3
+design.plot(use_service_colors=True)
+```
+
+However, if we set the global parameter to ``True``, the plot will be displayed
+with the assigned colors without the need to pass the parameter to the plot method.
+
+```{code-cell} ipython3
+import ansys.geometry.core as pyansys_geometry
+
+pyansys_geometry.USE_SERVICE_COLORS = True
+
+design.plot()
+
+# Reverting the global parameter to its default value
+pyansys_geometry.USE_SERVICE_COLORS = False
+```
+
+This last method is useful when the user wants to plot all the designs with the
+assigned colors without the need to pass the parameter to the plot method in
+every call.
+
+
+## Plotting specific bodies or components with colors
+
+If the user wants to plot specific bodies with the assigned colors, the user can
+follow the same approach as before. The user can pass the parameter ``use_service_colors=True``
+to the plot method or set the global parameter ``USE_SERVICE_COLORS`` to ``True``.
+
+In the following examples, we will just demonstrate how to do this using the
+``use_service_colors=True`` parameter.
+
+Let's plot the first body of the first component with the assigned colors.
+
+```{code-cell} ipython3
+body = design.components[0].bodies[0]
+
+body.plot(use_service_colors=True)
+```
+
+Now, let's plot the second component with the assigned colors.
+
+```{code-cell} ipython3
+comp = design.components[1]
+
+comp.plot(use_service_colors=True)
+```

doc/source/examples/03_modeling/service_colors.mystnb

@@ -50,10 +50,9 @@
 
 # Global config constants
 # ------------------------------------------------------------------------------
-
-USE_TRAME: bool = False
-"""Global constant for checking whether to use `trame <https://kitware.github.io/trame/>`_
-for visualization."""
+USE_SERVICE_COLORS: bool = False
+"""Global constant for checking whether to use service colors for plotting
+purposes. If set to False, the default colors will be used (speed gain)."""
 
 DISABLE_MULTIPLE_DESIGN_CHECK: bool = False
 """Global constant for disabling the ``ensure_design_is_active`` check.

src/ansys/geometry/core/__init__.py

@@ -54,6 +54,7 @@
     ProjectCurvesRequest,
 )
 from ansys.api.geometry.v0.commands_pb2_grpc import CommandsStub
+from ansys.geometry.core.connection.backend import BackendType
 from ansys.geometry.core.connection.client import GrpcClient
 from ansys.geometry.core.connection.conversions import (
     frame_to_grpc_frame,
@@ -81,6 +82,7 @@
 from ansys.geometry.core.misc.measurements import DEFAULT_UNITS, Angle, Distance
 from ansys.geometry.core.sketch.sketch import Sketch
 from ansys.geometry.core.typing import Real
+from ansys.tools.visualization_interface.utils.color import Color
 
 if TYPE_CHECKING:  # pragma: no cover
     from pyvista import MultiBlock, PolyData
@@ -546,6 +548,7 @@ def plot(
         merge: bool = False,
         screenshot: str | None = None,
         use_trame: bool | None = None,
+        use_service_colors: bool | None = None,
         **plotting_options: dict | None,
     ) -> None:
         """Plot the body.
@@ -560,8 +563,12 @@ def plot(
             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 ``USE_TRAME`` global setting
-            is used.
+            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 body 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.
@@ -757,24 +764,27 @@ def fill_style(self, value: FillStyle):  # noqa: D102
     @property
     def color(self) -> str:  # noqa: D102
         """Get the current color of the body."""
-        if self._color is None:
-            if self._grpc_client.backend_version < (25, 1, 0):  # pragma: no cover
+        if self._color is None and self.is_alive:
+            # Assigning default value first
+            self._color = Color.DEFAULT.value
+
+            # TODO: Remove this check when the Linux service backend supports color setting
+            # https://github.com/ansys/pyansys-geometry/issues/1383
+            if self._grpc_client.backend_type == BackendType.LINUX_SERVICE:
+                self._grpc_client.log.warning(
+                    "Colors are not supported in the Linux backend. Default value assigned..."
+                )
+            elif self._grpc_client.backend_version < (25, 1, 0):  # pragma: no cover
                 # Server does not support color retrieval before version 25.1.0
                 self._grpc_client.log.warning(
-                    "Server does not support color retrieval. Assigning default."
+                    "Server does not support color retrieval. Default value assigned..."
                 )
-                self._color = "#000000"  # Default color
             else:
                 # Fetch color from the server if it's not cached
                 color_response = self._bodies_stub.GetColor(EntityIdentifier(id=self._id))
-
                 if color_response.color:
                     self._color = mcolors.to_hex(color_response.color)
-                else:  # pragma: no cover
-                    self._grpc_client.log.warning(
-                        f"Color could not be retrieved for body {self._id}. Assigning default."
-                    )
-                    self._color = "#000000"  # Default color
+
         return self._color
 
     @color.setter
@@ -980,6 +990,15 @@ def set_color(self, color: str | tuple[float, float, float]) -> None:
         """Set the color of the body."""
         self._grpc_client.log.debug(f"Setting body color of {self.id} to {color}.")
 
+        # TODO: Remove this check when the Linux service backend supports color setting
+        # https://github.com/ansys/pyansys-geometry/issues/1383
+        if self._grpc_client.backend_type == BackendType.LINUX_SERVICE:
+            self._grpc_client.log.warning(
+                "Setting color is not supported in the Linux service backend."
+            )
+            self._grpc_client.log.warning("Ignoring request...")
+            return
+
         try:
             if isinstance(color, tuple):
                 # Ensure that all elements are within 0-1 or 0-255 range
@@ -1125,6 +1144,7 @@ def plot(  # noqa: D102
         merge: bool = False,
         screenshot: str | None = None,
         use_trame: bool | None = None,
+        use_service_colors: bool | None = None,
         **plotting_options: dict | None,
     ) -> None:
         raise NotImplementedError(
@@ -1509,17 +1529,27 @@ def plot(  # noqa: D102
         merge: bool = False,
         screenshot: str | None = None,
         use_trame: bool | None = None,
+        use_service_colors: bool | None = None,
         **plotting_options: dict | None,
     ) -> None:
         # lazy import here to improve initial module load 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,
         )
 
-        meshobject = MeshObjectPlot(self, self.tessellate(merge=merge))
-        pl = GeometryPlotter(use_trame=use_trame)
-        pl.plot(meshobject, **plotting_options)
+        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(merge=merge))
+        )
+        pl = GeometryPlotter(use_trame=use_trame, use_service_colors=use_service_colors)
+        pl.plot(mesh_object, **plotting_options)
         pl.show(screenshot=screenshot, **plotting_options)
 
     def intersect(self, other: Union["Body", Iterable["Body"]], keep_other: bool = False) -> None:  # noqa: D102
@@ -1596,6 +1626,7 @@ def __repr__(self) -> str:
         if self.is_surface:
             lines.append(f"  Surface thickness    : {self.surface_thickness}")
             lines.append(f"  Surface offset       : {self.surface_offset}")
+        lines.append(f"  Color                : {self.color}")
 
         nl = "\n"
         return f"{nl}{nl.join(lines)}{nl}"

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

@@ -1388,6 +1388,7 @@ def plot(
         merge_bodies: bool = False,
         screenshot: str | None = None,
         use_trame: bool | None = None,
+        use_service_colors: bool | None = None,
         **plotting_options: dict | None,
     ) -> None:
         """Plot the component.
@@ -1406,8 +1407,12 @@ def plot(
             Path for saving a screenshot of the image 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 ``USE_TRAME`` global setting
-            is used.
+            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 body 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
 
@@ -1446,13 +1451,25 @@ def plot(
             N Coordinate Systems : 0
         >>> mycomp.plot(pbr=True, metallic=1.0)
         """
+        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
 
-        mesh_object = MeshObjectPlot(
-            custom_object=self, mesh=self.tessellate(merge_component, merge_bodies)
+        use_service_colors = (
+            use_service_colors
+            if use_service_colors is not None
+            else pyansys_geometry.USE_SERVICE_COLORS
         )
-        pl = GeometryPlotter(use_trame=use_trame)
+
+        mesh_object = (
+            self
+            if use_service_colors
+            else MeshObjectPlot(
+                custom_object=self,
+                mesh=self.tessellate(merge_component=merge_component, merge_bodies=merge_bodies),
+            )
+        )
+        pl = GeometryPlotter(use_trame=use_trame, use_service_colors=use_service_colors)
         pl.plot(mesh_object, **plotting_options)
         pl.show(screenshot=screenshot, **plotting_options)