Domain: explicit kwargs for create/solve/build; expand docs. Export: add find_unionable_pairs and union_tubes_balanced with progress bar; defer remesh to final step.

Author: zasexton

docs/api/domain.html

@@ -251,34 +251,44 @@ <h4>Parameters</h4>
 
                         <div class="api-method">
                             <div class="api-method-signature">
-                                <code>create(**kwargs)</code>
+                                <code>create(min_patch_size=10, max_patch_size=20, overlap=0.2, feature_angle=30)</code>
                             </div>
                             <p>Create patches for the domain. This is the first step in building the implicit function.</p>
                             <div class="api-method-params">
                                 <h4>Parameters</h4>
                                 <ul>
-                                    <li><code>**kwargs</code>: Parameters passed to the allocation algorithm</li>
+                                    <li><code>min_patch_size</code> (int, default=10): Minimum number of points required to form a patch.</li>
+                                    <li><code>max_patch_size</code> (int, default=20): Target maximum number of points per patch (nearest-neighbor window).</li>
+                                    <li><code>overlap</code> (float, default=0.2): Fraction [0, 1] controlling allowed overlap of points between patches.</li>
+                                    <li><code>feature_angle</code> (float, default=30): Maximum angle in degrees between point-wise normal vectors for inclusion in the same patch (used only when normals are provided).</li>
                                 </ul>
                             </div>
                         </div>
 
                         <div class="api-method">
                             <div class="api-method-signature">
-                                <code>solve(**kwargs)</code>
+                                <code>solve(method="L-BFGS-B", precision=9)</code>
                             </div>
                             <p>Solve the individual patch interpolation problems prior to blending.</p>
+                            <div class="api-method-params">
+                                <h4>Parameters</h4>
+                                <ul>
+                                    <li><code>method</code> (str, default="L-BFGS-B"): Optimization method for SciPy's minimize (see Patch.solve).</li>
+                                    <li><code>precision</code> (int, default=9): Decimal places to round the solved constants.</li>
+                                </ul>
+                            </div>
                         </div>
 
                         <div class="api-method">
                             <div class="api-method-signature">
-                                <code>build(**kwargs)</code>
+                                <code>build(resolution=25, skip_boundary=False)</code>
                             </div>
-                            <p>Build the implicit function describing the domain.</p>
+                            <p>Build the implicit function describing the domain and optionally extract boundary/mesh artifacts.</p>
                             <div class="api-method-params">
                                 <h4>Parameters</h4>
                                 <ul>
-                                    <li><code>resolution</code> (int, default=25): Grid resolution for boundary extraction</li>
-                                    <li><code>skip_boundary</code> (bool, default=False): Skip boundary generation</li>
+                                    <li><code>resolution</code> (int, default=25): Grid resolution for boundary extraction.</li>
+                                    <li><code>skip_boundary</code> (bool, default=False): If true, only assemble fast-evaluation structures and skip boundary and interior mesh generation.</li>
                                 </ul>
                             </div>
                         </div>
@@ -479,6 +489,34 @@ <h3>Creating a Domain from STL File</h3>
 print(f"Convexity: {domain.convexity:.3f}")</code></pre>
                     </div>
 
+                    <div class="api-example">
+                        <h3>Customized Patch Allocation</h3>
+                        <pre data-copy><code class="language-python">import pyvista as pv
+from svv.domain.domain import Domain
+
+mesh = pv.read('vessel.stl')
+domain = Domain(mesh)
+
+# Tune patch allocation for dense data with noisy normals
+domain.create(
+    min_patch_size=8,      # allow smaller patches in sparse areas
+    max_patch_size=32,     # include more neighbors in dense regions
+    overlap=0.35,          # increase overlap for smoother blending
+    feature_angle=45       # be more tolerant to normal variation/noise
+)
+domain.solve()
+domain.build(resolution=30)</code></pre>
+                        <div class="callout tip">
+                            <strong>When to adjust defaults:</strong>
+                            <ul>
+                                <li><em>Dense point clouds:</em> increase <code>max_patch_size</code> to capture local context and reduce edge artifacts.</li>
+                                <li><em>Sparse/heterogeneous sampling:</em> decrease <code>min_patch_size</code> so isolated regions still form patches.</li>
+                                <li><em>Noisy or inconsistent normals:</em> raise <code>feature_angle</code> to admit neighbors with larger normal differences; lower it to preserve sharp features.</li>
+                                <li><em>Smoother blends vs. speed:</em> higher <code>overlap</code> yields smoother transitions across patches but increases compute.</li>
+                            </ul>
+                        </div>
+                    </div>
+
                     <div class="api-example">
                         <h3>Boolean Operations on Domains</h3>
                         <pre data-copy><code class="language-python"># Create two domains

svv/domain/domain.py

@@ -167,17 +167,63 @@ def set_random_generator(self):
         self.random_generator = np.random.Generator(np.random.PCG64(seed=self.random_seed))
         return None
 
-    def create(self, **kwargs):
+    def create(self,
+               min_patch_size: int = 10,
+               max_patch_size: int = 20,
+               overlap: float = 0.2,
+               feature_angle: float = 30) -> None:
         """
-        Create the patches for the domain. This is the first step in the process.
-        :param kwargs:
-        :return:
+        Partition input data into spatial patches and initialize Patch objects.
+
+        This is the first step of the domain pipeline (create → solve → build).
+        It groups the input point cloud (and optional normals) into overlapping
+        local neighborhoods (“patches”) and instantiates a Patch for each one.
+        Internally this delegates to `svv.domain.routines.allocate.allocate`,
+        which performs the neighbor search, duplicate handling, and optional
+        feature‑angle filtering.
+
+        Parameters
+        ----------
+        min_patch_size : int, optional
+            Minimum number of points required to form a patch. Default 10.
+        max_patch_size : int, optional
+            Target maximum points per patch (nearest‑neighbor window). Default 20.
+        overlap : float, optional
+            Fraction [0, 1] controlling allowed overlap of point indices between
+            patches; higher permits more shared points. Default 0.2.
+        feature_angle : float, optional
+            Maximum allowed angle in degrees between point‑wise normal vectors
+            for inclusion in the same patch as the seed point. Used only when
+            normals are provided. Default 30.
+
+        Side Effects
+        ------------
+        - Populates `self.patches` with Patch instances. Each Patch receives its
+          subset of points (and normals if available) and, by default, builds a
+          Kernel and sets initial values in `Patch.set_data`.
+
+        Notes
+        -----
+        - If `self.normals` is None, patches are created using spatial proximity only.
+        - If normals are provided, the `feature_angle` criterion is enforced and
+          duplicate points with incompatible normals are handled by `allocate`.
+        - No solving or function assembly happens here; call `solve()` next to fit
+          per‑patch coefficients, then `build()` to assemble the global implicit
+          function and precompute fast‑evaluation arrays.
         """
         self.patches = []
         if self.normals is None:
-            patch_data = allocate(self.points, **kwargs)
+            patch_data = allocate(self.points,
+                                  min_patch_size=min_patch_size,
+                                  max_patch_size=max_patch_size,
+                                  overlap=overlap,
+                                  feature_angle=feature_angle)
         else:
-            patch_data = allocate(self.points, self.normals, **kwargs)
+            patch_data = allocate(self.points, self.normals,
+                                  min_patch_size=min_patch_size,
+                                  max_patch_size=max_patch_size,
+                                  overlap=overlap,
+                                  feature_angle=feature_angle)
         for i in trange(len(patch_data), desc='Creating patches', unit='patch', leave=False):
             self.patches.append(Patch())
             if self.normals is None:
@@ -186,29 +232,46 @@ def create(self, **kwargs):
                 self.patches[-1].set_data(patch_data[i][0], patch_data[i][1])
         return None
 
-    def solve(self, **kwargs):
+    def solve(self, method: str = "L-BFGS-B", precision: int = 9) -> None:
         """
-        Solve the individual patch interpolation problems prior to blending.
+        Solve each Patch's interpolation problem before blending.
 
         Parameters
         ----------
-            None
+        method : str, optional
+            Optimization method passed to the underlying SciPy optimizer via
+            `Patch.solve`. Default "L-BFGS-B".
+        precision : int, optional
+            Number of decimal places for rounding the solved constants per patch.
+            Default 9.
 
-        Returns
-        -------
-            None
+        Notes
+        -----
+        This step computes per‑patch coefficients used later by `build()` to
+        assemble the global implicit function and fast‑evaluation arrays.
         """
         for i in trange(len(self.patches), desc='Solving patches', unit='patch', leave=False):
-            self.patches[i].solve(**kwargs)
+            self.patches[i].solve(method=method, precision=precision)
         return None
 
-    def build(self, **kwargs):
+    def build(self, resolution: int = 25, skip_boundary: bool = False) -> None:
         """
-        Build the implicit function describing the domain.
-        :return:
+        Assemble the global implicit function and optional boundary/mesh artifacts.
+
+        This combines per‑patch solutions into a structure that supports fast
+        evaluation of the implicit field via `evaluate_fast`/`__call__`. When a
+        Domain is loaded from a .dmn file, precomputed arrays may be present and
+        this method will reuse them, only rebuilding missing lightweight indices.
+
+        Parameters
+        ----------
+        resolution : int, optional
+            Grid resolution used when extracting the boundary surface/curve.
+            Higher values yield finer boundaries at increased cost. Default 25.
+        skip_boundary : bool, optional
+            When True, skip building boundary and interior mesh artifacts and
+            only assemble fast‑evaluation structures. Default False.
         """
-        resolution = kwargs.get('resolution', 25)
-        skip_boundary = kwargs.get('skip_boundary', False)
         # If this Domain was loaded from a .dmn file, it already has
         # A/B/C/D/PTS and possibly a function_tree. In that case, skip
         # rebuilding from patches (which will be empty) and only ensure