add docs

Author: Licini

docs/_images/cgal_boolean_split.jpg

@@ -0,0 +1,50 @@
+from compas.geometry import Point
+from compas.geometry import Box
+from compas.geometry import Sphere
+from compas.datastructures import Mesh
+from compas.colors import Color
+from random import random
+
+from compas_view2.app import App
+
+from compas_cgal.booleans import split
+from compas.topology import connected_components
+
+# ==============================================================================
+# Make a box and a sphere
+# ==============================================================================
+
+box = Box.from_width_height_depth(2, 2, 2)
+box = Mesh.from_shape(box)
+box.quads_to_triangles()
+
+A = box.to_vertices_and_faces()
+
+sphere = Sphere(Point(1, 1, 1), 1)
+sphere = Mesh.from_shape(sphere, u=20, v=20)
+sphere.quads_to_triangles()
+
+B = sphere.to_vertices_and_faces()
+
+# ==============================================================================
+# Compute the mesh split
+# ==============================================================================
+
+V, F = split(A, B)
+
+mesh = Mesh.from_vertices_and_faces(V, F)
+
+# ==============================================================================
+# Seperate disjoint faces and visualize
+# ==============================================================================
+
+viewer = App()
+
+fa = mesh.face_adjacency()
+parts = connected_components(fa)
+for face_indexes in connected_components(fa):
+    mesh = Mesh.from_vertices_and_faces(V, F[face_indexes])
+    mesh.remove_unused_vertices()
+    viewer.add(mesh, facecolor=Color.from_i(random()))
+
+viewer.run()

docs/examples/booleans_split.py

@@ -0,0 +1,11 @@
+********************************************************************************
+Mesh Split
+********************************************************************************
+
+.. figure:: /_images/cgal_boolean_split.jpg
+    :figclass: figure
+    :class: figure-img img-fluid
+
+
+.. literalinclude:: booleans_split.py
+    :language: python

docs/examples/mesh_split.rst

@@ -15,6 +15,7 @@
     booleans.boolean_union
     booleans.boolean_difference
     booleans.boolean_intersection
+    booleans.split
 
 Intersections
 =============

src/compas_cgal/__init__.py

@@ -165,6 +165,37 @@ def boolean_intersection(A, B):
 
 @plugin(category='booleans', pluggable_name='split_mesh_mesh')
 def split(A, B):
-    """
+    """Split one mesh with another.
+
+    Parameters
+    ----------
+    A : tuple[Sequence[[float, float, float] | :class:`~compas.geometry.Point`], Sequence[[int, int, int]]]
+        Mesh A.
+    B : tuple[Sequence[[float, float, float] | :class:`~compas.geometry.Point`], Sequence[[int, int, int]]]
+        Mesh B.
+    operation : Literal['union', 'difference', 'intersection']
+        The type of boolean operation.
+
+    Returns
+    -------
+    NDArray[(Any, 3), np.float64]
+        The vertices of the boolean mesh.
+    NDArray[(Any, 3), np.int32]
+        The faces of the boolean mesh.
+
+    Examples
+    --------
+    >>> from compas.geometry import Box, Sphere, Polyhedron
+    >>> from compas_cgal.booleans import split
+
+    >>> box = Box.from_width_height_depth(1, 1, 1)
+    >>> sphere = Sphere([1, 1, 1], 0.5)
+
+    >>> A = box.to_vertices_and_faces(triangulated=True)
+    >>> B = sphere.to_vertices_and_faces(u=32, v=32, triangulated=True)
+
+    >>> V, F = split(A, B)
+    >>> mesh = Mesh.from_vertices_and_faces(V, F)
+
     """
     return _boolean(A, B, 'split')