feat: helix detection

doc/changelog.d/2232.added.md

@@ -0,0 +1 @@
+Helix detection

src/ansys/geometry/core/_grpc/_services/base/prepare_tools.py

@@ -78,3 +78,8 @@ def find_and_remove_logos(self, **kwargs) -> dict:
     def remove_logo(self, **kwargs) -> dict:
         """Remove logos in geometry."""
         pass
+
+    @abstractmethod
+    def detect_helixes(self, **kwargs) -> dict:
+        """Detect helixes in geometry."""
+        pass

src/ansys/geometry/core/_grpc/_services/v0/prepare_tools.py

@@ -23,6 +23,14 @@
 
 import grpc
 
+from ansys.geometry.core._grpc._services.base.conversions import (
+    from_measurement_to_server_length,
+    to_distance,
+)
+from ansys.geometry.core._grpc._services.v0.conversions import (
+    from_grpc_curve_to_curve,
+    from_grpc_point_to_point3d,
+)
 from ansys.geometry.core.errors import protect_grpc
 
 from ..base.prepare_tools import GRPCPrepareToolsService
@@ -214,3 +222,55 @@ def remove_logo(self, **kwargs):  # noqa: D102
 
         # Return the response - formatted as a dictionary
         return {"success": response.success}
+
+    @protect_grpc
+    def detect_helixes(self, **kwargs):  # noqa: D102
+        from ansys.api.dbu.v0.dbumodels_pb2 import EntityIdentifier
+        from ansys.api.geometry.v0.models_pb2 import DetectHelixesOptions
+        from ansys.api.geometry.v0.preparetools_pb2 import DetectHelixesRequest
+
+        from ansys.geometry.core.shapes.parameterization import Interval
+
+        # Create the request - assumes all inputs are valid and of the proper type
+        request = DetectHelixesRequest(
+            body_ids=[EntityIdentifier(id=body.id) for body in kwargs["bodies"]],
+            options=DetectHelixesOptions(
+                min_radius=from_measurement_to_server_length(kwargs["min_radius"]),
+                max_radius=from_measurement_to_server_length(kwargs["max_radius"]),
+                fit_radius_error=from_measurement_to_server_length(kwargs["fit_radius_error"]),
+            ),
+        )
+
+        # Call the gRPC service
+        response = self.stub.DetectHelixes(request)
+
+        # If no helixes, return empty dictionary
+        if len(response.helixes) == 0:
+            return {"helixes": []}
+
+        # Return the response - formatted as a dictionary
+        return {
+            "helixes": [
+                {
+                    "trimmed_curve": {
+                        "geometry": from_grpc_curve_to_curve(helix.trimmed_curve.curve),
+                        "start": from_grpc_point_to_point3d(helix.trimmed_curve.start),
+                        "end": from_grpc_point_to_point3d(helix.trimmed_curve.end),
+                        "interval": Interval(
+                            helix.trimmed_curve.interval_start, helix.trimmed_curve.interval_end
+                        ),
+                        "length": to_distance(helix.trimmed_curve.length).value,
+                    },
+                    "edges": [
+                        {
+                            "id": edge.id,
+                            "parent_id": edge.parent.id,
+                            "curve_type": edge.curve_type,
+                            "is_reversed": edge.is_reversed,
+                        }
+                        for edge in helix.edges
+                    ],
+                }
+                for helix in response.helixes
+            ]
+        }

src/ansys/geometry/core/_grpc/_services/v1/prepare_tools.py

@@ -78,3 +78,7 @@ def find_and_remove_logos(self, **kwargs) -> dict:  # noqa: D102
     @protect_grpc
     def remove_logo(self, **kwargs) -> dict:  # noqa: D102
         raise NotImplementedError
+
+    @protect_grpc
+    def detect_helixes(self, **kwargs):  # noqa: D102
+        raise NotImplementedError

src/ansys/geometry/core/shapes/curves/procedural.py

@@ -0,0 +1,32 @@
+# Copyright (C) 2023 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Provides for creating and managing a procedural curve."""
+
+from ansys.geometry.core.shapes.curves.curve import Curve
+
+
+class ProceduralCurve(Curve):
+    """Provides a 3D procedural curve representation."""
+
+    def __init__(self):
+        """Initialize the procedural curve."""
+        super().__init__()

src/ansys/geometry/core/tools/prepare_tools.py

@@ -24,17 +24,21 @@
 from typing import TYPE_CHECKING
 
 from beartype import beartype as check_input_types
+from pint import Quantity
 
 from ansys.geometry.core.connection import GrpcClient
 from ansys.geometry.core.connection.backend import BackendType
 from ansys.geometry.core.errors import GeometryRuntimeError
 from ansys.geometry.core.logger import LOG
 from ansys.geometry.core.misc.auxiliary import (
     get_bodies_from_ids,
+    get_design_from_body,
     get_design_from_edge,
     get_design_from_face,
 )
 from ansys.geometry.core.misc.checks import check_type_all_elements_in_iterable, min_backend_version
+from ansys.geometry.core.misc.measurements import Distance
+from ansys.geometry.core.shapes.curves.trimmed_curve import TrimmedCurve
 from ansys.geometry.core.tools.problem_areas import LogoProblemArea
 from ansys.geometry.core.tools.repair_tool_message import RepairToolMessage
 from ansys.geometry.core.typing import Real
@@ -412,3 +416,86 @@ def find_and_remove_logos(
         )
 
         return response.get("success")
+
+    @min_backend_version(26, 1, 0)
+    def detect_helixes(
+        self,
+        bodies: list["Body"],
+        min_radius: Distance | Quantity | Real = 0.0,
+        max_radius: Distance | Quantity | Real = 100.0,
+        fit_radius_error: Distance | Quantity | Real = 0.01,
+    ) -> dict["TrimmedCurve", list["Edge"]]:
+        """Detect helixes in the given bodies.
+
+        Parameters
+        ----------
+        bodies : list[Body]
+            List of bodies to detect helixes in.
+        min_radius : Distance, Quantity, or Real, default: 0.0
+            Minimum radius of the helix to be detected.
+        max_radius : Distance, Quantity, or Real, default: 1e6
+            Maximum radius of the helix to be detected.
+        fit_radius_error : Distance, Quantity, or Real, default: 0.01
+            Maximum fit radius error of the helix to be detected.
+
+        Returns
+        -------
+        dict
+            Dictionary with key "helixes" containing a list of detected helixes.
+            Each helix is represented as a dictionary with keys "trimmed_curve" and "edges".
+
+        Warnings
+        --------
+        This method is only available starting on Ansys release 26R1.
+        """
+        from ansys.geometry.core.designer.body import Body
+        from ansys.geometry.core.designer.edge import CurveType, Edge
+
+        if not bodies:
+            self._grpc_client.log.info("No bodies provided...")
+            return {"helixes": []}
+
+        # Verify inputs
+        check_type_all_elements_in_iterable(bodies, Body)
+        min_radius = min_radius if isinstance(min_radius, Distance) else Distance(min_radius)
+        max_radius = max_radius if isinstance(max_radius, Distance) else Distance(max_radius)
+        fit_radius_error = (
+            fit_radius_error
+            if isinstance(fit_radius_error, Distance)
+            else Distance(fit_radius_error)
+        )
+
+        response = self._grpc_client._services.prepare_tools.detect_helixes(
+            bodies=bodies,
+            min_radius=min_radius,
+            max_radius=max_radius,
+            fit_radius_error=fit_radius_error,
+        )
+
+        parent_design = get_design_from_body(bodies[0])
+
+        return {
+            "helixes": [
+                {
+                    "trimmed_curve": TrimmedCurve(
+                        helix.get("trimmed_curve").get("geometry"),
+                        helix.get("trimmed_curve").get("start"),
+                        helix.get("trimmed_curve").get("end"),
+                        helix.get("trimmed_curve").get("interval"),
+                        helix.get("trimmed_curve").get("length"),
+                        grpc_client=self._grpc_client,
+                    ),
+                    "edges": [
+                        Edge(
+                            edge.get("id"),
+                            CurveType(edge.get("curve_type")),
+                            get_bodies_from_ids(parent_design, [edge.get("parent_id")])[0],
+                            self._grpc_client,
+                            edge.get("is_reversed"),
+                        )
+                        for edge in helix.get("edges")
+                    ],
+                }
+                for helix in response.get("helixes")
+            ]
+        }

tests/_incompatible_tests.yml

@@ -28,6 +28,7 @@ backends:
       - tests/integration/test_prepare_tools.py::test_volume_extract_bad_faces
       - tests/integration/test_prepare_tools.py::test_volume_extract_bad_edges
       - tests/integration/test_prepare_tools.py::test_volume_extract_bad_edges
+      - tests/integration/test_prepare_tools.py::test_helix_detection
       - tests/integration/test_repair_tools.py::test_fix_small_face
       - tests/integration/test_repair_tools.py::test_find_interference
       - tests/integration/test_repair_tools.py::test_fix_interference
@@ -137,6 +138,7 @@ backends:
       - tests/integration/test_prepare_tools.py::test_volume_extract_bad_faces
       - tests/integration/test_prepare_tools.py::test_volume_extract_bad_edges
       - tests/integration/test_prepare_tools.py::test_volume_extract_bad_edges
+      - tests/integration/test_prepare_tools.py::test_helix_detection
       - tests/integration/test_repair_tools.py::test_fix_small_face
       - tests/integration/test_repair_tools.py::test_find_interference
       - tests/integration/test_repair_tools.py::test_fix_interference
@@ -222,6 +224,7 @@ backends:
       # Model used is too new for this version
       - tests/integration/test_design.py::test_import_component_named_selections
       - tests/integration/test_design.py::test_component_make_independent
+      - tests/integration/test_prepare_tools.py::test_helix_detection
       - tests/integration/test_spaceclaim_tutorial_examples.py::test_combine_example
       - tests/integration/test_spaceclaim_tutorial_examples.py::test_pull_example
       - tests/integration/test_spaceclaim_tutorial_examples.py::test_intersect_example

tests/integration/test_prepare_tools.py

@@ -207,3 +207,30 @@ def test_volume_extract_bad_edges(modeler: Modeler):
         sealing_edges,
     )
     assert len(created_bodies) == 0
+
+
+def test_helix_detection(modeler: Modeler):
+    """Test helix detection."""
+    design = modeler.open_file(FILES_DIR / "bolt.scdocx")
+
+    bodies = design.bodies
+    assert len(bodies) == 2
+
+    search_bodies = [bodies[0]]
+    assert len(search_bodies) == 1
+
+    # Test default parameters
+    result = modeler.prepare_tools.detect_helixes(search_bodies)
+    assert len(result["helixes"]) == 1
+
+    # Test with non-default parameters
+    result = modeler.prepare_tools.detect_helixes(search_bodies, 0, 10, 100)
+    assert len(result["helixes"]) == 1
+
+    # Test parameters that should yield no results
+    result = modeler.prepare_tools.detect_helixes(search_bodies, 5.0, 10.0, 0.01)
+    assert len(result["helixes"]) == 0
+
+    # Test with multiple bodies
+    result = modeler.prepare_tools.detect_helixes(bodies)
+    assert len(result["helixes"]) == 2