Additions to cq.Face (#1752)

* Add Face paramAt

* Fix method definition

* Some tests for the new methods

* Add params and positions

* Add tests

* Add closest

* Add test

* Adjust API for consistency

* Fix typo

Co-authored-by: Jeremy Wright <[email protected]>

* Docstring fix

---------

Co-authored-by: adam-urbanczyk <[email protected]>
Co-authored-by: Jeremy Wright <[email protected]>

Author: adam-urbanczyk

cadquery/func.py

@@ -44,4 +44,5 @@
     sweep,
     loft,
     check,
+    closest,
 )

cadquery/occ_impl/shapes.py

@@ -243,7 +243,11 @@
 
 from OCP.TopAbs import TopAbs_ShapeEnum, TopAbs_Orientation
 
-from OCP.ShapeAnalysis import ShapeAnalysis_FreeBounds, ShapeAnalysis_Wire
+from OCP.ShapeAnalysis import (
+    ShapeAnalysis_FreeBounds,
+    ShapeAnalysis_Wire,
+    ShapeAnalysis_Surface,
+)
 from OCP.TopTools import TopTools_HSequenceOfShape
 
 from OCP.GCPnts import (
@@ -2829,6 +2833,90 @@ def _uvBounds(self) -> Tuple[float, float, float, float]:
 
         return BRepTools.UVBounds_s(self.wrapped)
 
+    def paramAt(self, pt: VectorLike) -> Tuple[float, float]:
+        """
+        Computes the (u,v) pair closest to a given vector.
+
+        :returns: (u, v) tuple
+        :param pt: the location to compute the normal at.
+        :type pt: a vector that lies on or close to the surface.
+        """
+        # get the geometry
+        surface = self._geomAdaptor()
+
+        # project point on surface
+        projector = GeomAPI_ProjectPointOnSurf(Vector(pt).toPnt(), surface)
+
+        u, v = projector.LowerDistanceParameters()
+
+        return u, v
+
+    def params(
+        self, pts: Iterable[VectorLike], tol: float = 1e-9
+    ) -> Tuple[List[float], List[float]]:
+        """
+        Computes (u,v) pairs closest to given vectors.
+
+        :returns: list of (u, v) tuples
+        :param pts: the points to compute the normals at.
+        :type pts: a list of vectors that lie on the surface.
+        """
+
+        us = []
+        vs = []
+
+        # get the geometry
+        surface = self._geomAdaptor()
+
+        # construct the projector
+        projector = ShapeAnalysis_Surface(surface)
+
+        # get the first point
+        it = iter(pts)
+        pt = next(it)
+
+        uv = projector.ValueOfUV(Vector(pt).toPnt(), tol)
+        us.append(uv.X())
+        vs.append(uv.Y())
+
+        for pt in it:
+            uv = projector.NextValueOfUV(uv, Vector(pt).toPnt(), tol)
+            us.append(uv.X())
+            vs.append(uv.Y())
+
+        return us, vs
+
+    def positionAt(self, u: Real, v: Real) -> Vector:
+        """
+        Computes the position vector at the desired location in the u,v parameter space.
+
+        :returns: a vector representing the position
+        :param u: the u parametric location to compute the normal at.
+        :param v: the v parametric location to compute the normal at.
+        """
+        p = gp_Pnt()
+        vn = gp_Vec()
+        BRepGProp_Face(self.wrapped).Normal(u, v, p, vn)
+
+        return Vector(p)
+
+    def positions(self, uvs: Iterable[Tuple[Real, Real]]) -> List[Vector]:
+        """
+        Computes position vectors at the desired locations in the u,v parameter space.
+
+        :returns: list of vectors corresponding to the requested u,v positions
+        :param uvs: iterable of u,v pairs.
+        """
+        p = gp_Pnt()
+        vn = gp_Vec()
+        rv = []
+
+        for u, v in uvs:
+            BRepGProp_Face(self.wrapped).Normal(u, v, p, vn)
+            rv.append(Vector(p))
+
+        return rv
+
     @multimethod
     def normalAt(self, locationVector: Optional[VectorLike] = None) -> Vector:
         """
@@ -5805,3 +5893,15 @@ def check(s: Shape, results: Optional[List[Tuple[List[Shape], Any]]] = None) ->
             )
 
     return rv
+
+
+#%% properties
+
+
+def closest(s1: Shape, s2: Shape) -> Tuple[Vector, Vector]:
+    """
+    Closest points between two shapes.
+    """
+    ext = BRepExtrema_DistShapeShape(s1.wrapped, s2.wrapped)
+
+    return Vector(ext.PointOnShape1(1)), Vector(ext.PointOnShape2(1))

tests/test_free_functions.py

@@ -44,6 +44,7 @@
     _adaptor_curve_to_edge,
     check,
     Vector,
+    closest,
 )
 
 from OCP.BOPAlgo import BOPAlgo_CheckStatus
@@ -697,3 +698,14 @@ def test_check():
 
     assert not check(s2, res)
     assert res[0][1] == BOPAlgo_CheckStatus.BOPAlgo_SelfIntersect
+
+
+# %% properties
+def test_closest():
+
+    s1 = plane(1, 1)
+    s2 = plane(1, 1).moved(x=5, y=0.5)
+
+    p1, p2 = closest(s1, s2)
+
+    assert (p1 - p2).Length == approx(4)

tests/test_shapes.py

@@ -1,25 +1,26 @@
 from cadquery.occ_impl.shapes import (
+    Vector,
+    Shape,
+    Solid,
     wire,
     segment,
     polyline,
-    Vector,
     box,
-    Solid,
     compound,
     circle,
     plane,
     torus,
-    Shape,
     cylinder,
     ellipse,
+    closest,
 )
 
 from pytest import approx, raises
 
 from math import pi
 
 
-def test_paramAt():
+def test_edge_paramAt():
 
     # paramAt for a segment
     e = segment((0, 0), (0, 1))
@@ -53,6 +54,60 @@ def test_paramAt():
     assert p8 == approx(w2.paramAt(0.1 / 2))
 
 
+def test_face_paramAt():
+
+    f = plane(1, 1)
+
+    u, v = f.paramAt((0.5, 0))
+
+    assert u == approx(0.5)
+    assert v == approx(0.0)
+
+
+def test_face_params():
+
+    f = plane(1, 1)
+
+    us, vs = f.params([(0.49, 0.0), (0.5, 0)])
+
+    u1, u2 = us
+    v1, v2 = vs
+
+    assert u1 == approx(0.49)
+    assert v1 == approx(0.0)
+
+    assert u2 == approx(0.5)
+    assert v2 == approx(0.0)
+
+
+def test_face_positionAt():
+
+    f = plane(1, 1)
+
+    p = f.positionAt(0.5, 0.5)
+
+    assert p.x == approx(0.5)
+    assert p.y == approx(0.5)
+    assert p.z == approx(0)
+
+
+def test_face_positions():
+
+    f = plane(1, 1)
+
+    ps = f.positions([(0, 0), (0.5, 0.5)])
+
+    p1, p2 = ps
+
+    assert p1.x == approx(0)
+    assert p1.y == approx(0)
+    assert p1.z == approx(0)
+
+    assert p2.x == approx(0.5)
+    assert p2.y == approx(0.5)
+    assert p2.z == approx(0)
+
+
 def test_isSolid():
 
     s = box(1, 1, 1)