feat: replace face

doc/changelog.d/1664.added.md

@@ -0,0 +1 @@
+replace face

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

@@ -39,6 +39,7 @@
     ModifyLinearPatternRequest,
     PatternRequest,
     RenameObjectRequest,
+    ReplaceFaceRequest,
 )
 from ansys.api.geometry.v0.commands_pb2_grpc import CommandsStub
 from ansys.geometry.core.connection import GrpcClient
@@ -842,3 +843,42 @@ def update_fill_pattern(
         )
 
         return result.result.success
+
+    @protect_grpc
+    @min_backend_version(25, 2, 0)
+    def replace_face(
+        self,
+        target_selection: Union["Face", list["Face"]],
+        replacement_selection: Union["Face", list["Face"]],
+    ) -> bool:
+        """Replace a face with another face.
+
+        Parameters
+        ----------
+        target_selection : Union[Face, list[Face]]
+            The face or faces to replace.
+        replacement_selection : Union[Face, list[Face]]
+            The face or faces to replace with.
+
+        Returns
+        -------
+        bool
+            ``True`` when successful, ``False`` when failed.
+        """
+        target_selection: list["Face"] = (
+            target_selection if isinstance(target_selection, list) else [target_selection]
+        )
+        replacement_selection: list["Face"] = (
+            replacement_selection
+            if isinstance(replacement_selection, list)
+            else [replacement_selection]
+        )
+
+        result = self._commands_stub.ReplaceFace(
+            ReplaceFaceRequest(
+                target_selection=[selection._grpc_id for selection in target_selection],
+                replacement_selection=[selection._grpc_id for selection in replacement_selection],
+            )
+        )
+
+        return result.success

tests/integration/test_geometry_commands.py

@@ -547,3 +547,28 @@ def test_fill_pattern(modeler: Modeler):
     assert success
     assert base.volume.m == pytest.approx(Quantity(1.60730091830, UNITS.m**3).m, rel=1e-6, abs=1e-8)
     assert len(base.faces) == 56
+
+
+def test_replace_face(modeler: Modeler):
+    """Test replacing a face with another face."""
+    design = modeler.create_design("replace_face")
+    base = design.extrude_sketch("box", Sketch().box(Point2D([0, 0]), 1, 1), 1)
+    cutout = design.extrude_sketch("cylinder", Sketch().circle(Point2D([-0.4, -0.4]), 0.05), 1)
+    base.subtract(cutout)
+
+    # replace face with a new face
+    new_face = design.extrude_sketch("new_face", Sketch().box(Point2D([0, 0]), 0.1, 0.1), 1)
+    success = modeler.geometry_commands.replace_face(base.faces[-1], new_face.faces[0])
+    assert success
+    assert base.volume.m == pytest.approx(
+        Quantity(0.992146018366, UNITS.m**3).m, rel=1e-6, abs=1e-8
+    )
+    assert len(base.faces) == 7
+
+    # replace face with an existing face
+    success = modeler.geometry_commands.replace_face(base.faces[-1], base.faces[0])
+    assert success
+    assert base.volume.m == pytest.approx(
+        Quantity(0.992146018366, UNITS.m**3).m, rel=1e-6, abs=1e-8
+    )
+    assert len(base.faces) == 7