Local and non-manifold sewing (#1808)

* Add extend and speed up distance calc

* Add conversion to NURBS

* Add checks to extend

* Remove checks

* Add test and defaults

* Better coverage

* Ignore coverege of a failed imprint

* Better coverage

* Remove pragma

* Fixture cleanup

* Add replace

* Fix replace and add remove to Shape

* Add addCavity

* Add more tests

* Coverage fix

* Actually faster distance

* Add local and non-manifold sewing

* Add history to sewing

* Rework local sewing and add a test

* Simplify history handling

* Add history to solid and reorganize tests

* Mypy fix

* add addHole

* Add test for addHole

* black fix

* Add project

* Test project

* Add some docs

* Add one more example

* Doc fix

* Fix typo

Co-authored-by: Jeremy Wright <wrightjmf@gmail.com>

* Typo fix

---------
Co-authored-by: Jeremy Wright <wrightjmf@gmail.com>

Author: adam-urbanczyk

cadquery/func.py

@@ -47,4 +47,5 @@
     check,
     closest,
     setThreads,
+    project,
 )

cadquery/occ_impl/shapes.py

@@ -294,7 +294,7 @@
 
 from OCP.ShapeCustom import ShapeCustom, ShapeCustom_RestrictionParameters
 
-from OCP.BRepAlgo import BRepAlgo
+from OCP.BRepAlgo import BRepAlgo, BRepAlgo_NormalProjection
 
 from OCP.ChFi2d import ChFi2d_FilletAPI  # For Wire.Fillet()
 
@@ -2216,15 +2216,15 @@ def project(
         self: T1D, face: "Face", d: VectorLike, closest: bool = True
     ) -> Union[T1D, List[T1D]]:
         """
-        Project onto a face along the specified direction
+        Project onto a face along the specified direction.
         """
 
-        bldr = BRepProj_Projection(self.wrapped, face.wrapped, Vector(d).toDir())
-        shapes = Compound(bldr.Shape())
-
         # select the closest projection if requested
         rv: Union[T1D, List[T1D]]
 
+        bldr = BRepProj_Projection(self.wrapped, face.wrapped, Vector(d).toDir())
+        shapes = Compound(bldr.Shape())
+
         if closest:
 
             dist_calc = BRepExtrema_DistShapeShape()
@@ -3555,6 +3555,20 @@ def extend(
 
         return self.__class__(rv)
 
+    def addHole(self, *inner: Wire | Edge) -> Self:
+        """
+        Add one or more holes.
+        """
+
+        bldr = BRepBuilderAPI_MakeFace(self.wrapped)
+
+        for w in inner:
+            bldr.Add(
+                TopoDS.Wire_s(w.wrapped if isinstance(w, Wire) else wire(w).wrapped)
+            )
+
+        return self.__class__(bldr.Face()).fix()
+
 
 class Shell(Shape):
     """
@@ -5082,6 +5096,8 @@ def _adaptor_curve_to_edge(crv: Adaptor3d_Curve, p1: float, p2: float) -> TopoDS
 
 #%% alternative constructors
 
+ShapeHistory = Dict[Union[Shape, str], Shape]
+
 
 @multimethod
 def wire(*s: Shape) -> Shape:
@@ -5131,21 +5147,54 @@ def face(s: Sequence[Shape]) -> Shape:
     return face(*s)
 
 
+def _process_sewing_history(
+    builder: BRepBuilderAPI_Sewing, faces: List[Face], history: Optional[ShapeHistory],
+):
+    """
+    Reusable helper for processing sewing history.
+    """
+
+    # fill history if provided
+    if history is not None:
+        # collect shapes present in the history dict
+        for k, v in history.items():
+            if isinstance(k, str):
+                history[k] = Face(builder.Modified(v.wrapped))
+
+        # store all top-level shape relations
+        for f in faces:
+            history[f] = Face(builder.Modified(f.wrapped))
+
+
 @multimethod
-def shell(*s: Shape, tol: float = 1e-6) -> Shape:
+def shell(
+    *s: Shape,
+    tol: float = 1e-6,
+    manifold: bool = True,
+    ctx: Optional[Sequence[Shape] | Shape] = None,
+    history: Optional[ShapeHistory] = None,
+) -> Shape:
     """
-    Build shell from faces.
+    Build shell from faces. If ctx is specified, local sewing is performed.
     """
 
-    builder = BRepBuilderAPI_Sewing(tol)
+    builder = BRepBuilderAPI_Sewing(tol, option4=not manifold)
+    if ctx:
+        if isinstance(ctx, Shape):
+            builder.Load(ctx.wrapped)
+        else:
+            builder.Load(compound(ctx).wrapped)
+
+    faces: list[Face] = []
 
     for el in s:
         for f in _get(el, "Face"):
             builder.Add(f.wrapped)
+            faces.append(f)
 
     builder.Perform()
-
     sewed = builder.SewedShape()
+    _process_sewing_history(builder, faces, history)
 
     # for one face sewing will not produce a shell
     if sewed.ShapeType() == TopAbs_ShapeEnum.TopAbs_FACE:
@@ -5162,16 +5211,24 @@ def shell(*s: Shape, tol: float = 1e-6) -> Shape:
 
 
 @shell.register
-def shell(s: Sequence[Shape], tol: float = 1e-6) -> Shape:
+def shell(
+    s: Sequence[Shape],
+    tol: float = 1e-6,
+    manifold: bool = True,
+    ctx: Optional[Sequence[Shape] | Shape] = None,
+    history: Optional[ShapeHistory] = None,
+) -> Shape:
     """
-    Build shell from a sequence of faces.
+    Build shell from a sequence of faces. If ctx is specified, local sewing is performed.
     """
 
-    return shell(*s, tol=tol)
+    return shell(*s, tol=tol, manifold=manifold, ctx=ctx, history=history)
 
 
 @multimethod
-def solid(s1: Shape, *sn: Shape, tol: float = 1e-6) -> Shape:
+def solid(
+    s1: Shape, *sn: Shape, tol: float = 1e-6, history: Optional[ShapeHistory] = None,
+) -> Shape:
     """
     Build solid from faces or shells.
     """
@@ -5186,7 +5243,7 @@ def solid(s1: Shape, *sn: Shape, tol: float = 1e-6) -> Shape:
     shells = [el.wrapped for el in shells_faces if el.ShapeType() == "Shell"]
     if not shells:
         faces = [el for el in shells_faces]
-        shells = [shell(*faces, tol=tol).wrapped]
+        shells = [shell(*faces, tol=tol, history=history).wrapped]
 
     rvs = [builder.SolidFromShell(sh) for sh in shells]
 
@@ -5195,17 +5252,20 @@ def solid(s1: Shape, *sn: Shape, tol: float = 1e-6) -> Shape:
 
 @solid.register
 def solid(
-    s: Sequence[Shape], inner: Optional[Sequence[Shape]] = None, tol: float = 1e-6
+    s: Sequence[Shape],
+    inner: Optional[Sequence[Shape]] = None,
+    tol: float = 1e-6,
+    history: Optional[ShapeHistory] = None,
 ) -> Shape:
     """
     Build solid from a sequence of faces.
     """
 
     builder = BRepBuilderAPI_MakeSolid()
-    builder.Add(shell(*s, tol=tol).wrapped)
+    builder.Add(shell(*s, tol=tol, history=history).wrapped)
 
     if inner:
-        for sh in _get(shell(*inner, tol=tol), "Shell"):
+        for sh in _get(shell(*inner, tol=tol, history=history), "Shell"):
             builder.Add(sh.wrapped)
 
     # fix orientations
@@ -5741,7 +5801,7 @@ def imprint(
     *shapes: Shape,
     tol: float = 0.0,
     glue: GlueLiteral = "full",
-    history: Optional[Dict[Union[Shape, str], Shape]] = None,
+    history: Optional[ShapeHistory] = None,
 ) -> Shape:
     """
     Imprint arbitrary number of shapes.
@@ -6199,6 +6259,29 @@ def loft(
     return loft(s, cap, ruled, continuity, parametrization, degree, compat)
 
 
+def project(
+    s: Shape,
+    base: Shape,
+    continuity: Literal["C1", "C2", "C3"] = "C2",
+    degree: int = 3,
+    maxseg: int = 30,
+    tol: float = 1e-4,
+):
+    """
+    Project s onto base using normal projection.
+    """
+
+    bldr = BRepAlgo_NormalProjection(base.wrapped)
+    bldr.SetParams(tol, tol ** (2 / 3), _to_geomabshape(continuity), degree, maxseg)
+
+    for el in _get_edges(s):
+        bldr.Add(s.wrapped)
+
+    bldr.Build()
+
+    return _compound_or_shape(bldr.Projection())
+
+
 #%% diagnotics
 
 

doc/free-func.rst

@@ -1,4 +1,4 @@
-.. _freefuncapi:
+
 
 *****************
 Free function API
@@ -241,7 +241,8 @@ Placement and creation of arrays is possible using :meth:`~cadquery.Shape.move`
 Text
 ----
 
-The free function API has extensive text creation capabilities including text on planar curves and text on surfaces.
+The free function API has extensive text creation capabilities including text on
+planar curves and text on surfaces.
 
 
 .. cadquery::
@@ -275,3 +276,76 @@ The free function API has extensive text creation capabilities including text on
     r4 = offset(r3, TH).moved(z=S)
 
     result = compound(r1, r2, r3, r4)
+
+
+Adding features manually
+------------------------
+
+In certain cases it is desirable to add features such as holes or protrusions manually.
+E.g., for complicated shapes it might be beneficial performance-wise because it
+avoids boolean operations. One can add or remove faces, add holes to existing faces
+and last but not least reconstruct existing solids. 
+
+.. cadquery::
+    
+    from cadquery.func import *
+    
+    w = 1
+    r = 0.9*w/2
+    
+    # box
+    b = box(w, w, w)
+    # bottom face
+    b_bot = b.faces('<Z')
+    # top faces
+    b_top = b.faces('>Z')
+    
+    # inner face 
+    inner = extrude(circle(r), (0,0,w))
+    
+    # add holes to the bottom and top face
+    b_bot_hole = b_bot.addHole(inner.edges('<Z'))
+    b_top_hole = b_top.addHole(inner.edges('>Z'))
+    
+    # construct the final solid
+    result = solid(
+        b.remove(b_top, b_bot).faces(), #side faces
+        b_bot_hole, # bottom with a hole
+        inner, # inner cylinder face
+        b_top_hole, # top with a hole
+    )
+
+If the base shape is more complicated, it is possible to use local sewing that
+takes into account on indicated elements of the context shape. This, however,
+necessitates a two step approach - first a shell needs to be explicitly sewn
+and only then the final solid can be constructed.
+
+.. cadquery::
+
+    from cadquery.func import *
+    
+    w = 1
+    h = 0.1
+    r = 0.9*w/2
+    
+    # box
+    b = box(w, w, w)
+    # top face
+    b_top = b.faces('>Z')
+    
+    # protrusion
+    feat_side = extrude(circle(r).moved(b_top.Center()), (0,0,h))
+    feat_top = face(feat_side.edges('>Z'))
+    feat = shell(feat_side, feat_top) # sew into a shell
+    
+    # add hole to the box
+    b_top_hole = b_top.addHole(feat.edges('<Z'))
+    b = b.replace(b_top, b_top_hole)
+    
+    # local sewing - only two faces are taken into account
+    sh = shell(b_top_hole, feat.faces('<Z'), ctx=(b, feat))
+    
+    # construct the final solid
+    result = solid(sh)
+
+