add examples

Author: tomvanmele

src/compas_cgal/booleans.py

@@ -8,9 +8,9 @@ def _boolean(A, B, operation):
 
     Parameters
     ----------
-    A : tuple[Sequence[[float, float, float] | :class:`compas.geometry.Point`], Sequence[[int, int, int]]]
+    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]]]
+    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.
@@ -53,9 +53,9 @@ def boolean_union(A, B):
 
     Parameters
     ----------
-    A : tuple[Sequence[[float, float, float] | :class:`compas.geometry.Point`], Sequence[[int, int, int]]]
+    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]]]
+    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.
@@ -67,6 +67,20 @@ def boolean_union(A, B):
     NDArray[(Any, 3), np.int32]
         The faces of the boolean mesh.
 
+    Examples
+    --------
+    >>> from compas.geometry import Box, Sphere, Polyhedron
+    >>> from compas_cgal.booleans import boolean_union
+
+    >>> 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)
+
+    >>> C = boolean_union(A, B)
+    >>> shape = Polyhedron(*C)
+
     """
     return _boolean(A, B, 'union')
 
@@ -77,9 +91,9 @@ def boolean_difference(A, B):
 
     Parameters
     ----------
-    A : tuple[Sequence[[float, float, float] | :class:`compas.geometry.Point`], Sequence[[int, int, int]]]
+    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]]]
+    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.
@@ -91,6 +105,20 @@ def boolean_difference(A, B):
     NDArray[(Any, 3), np.int32]
         The faces of the boolean mesh.
 
+    Examples
+    --------
+    >>> from compas.geometry import Box, Sphere, Polyhedron
+    >>> from compas_cgal.booleans import boolean_difference
+
+    >>> 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)
+
+    >>> C = boolean_difference(A, B)
+    >>> shape = Polyhedron(*C)
+
     """
     return _boolean(A, B, 'difference')
 
@@ -101,9 +129,9 @@ def boolean_intersection(A, B):
 
     Parameters
     ----------
-    A : tuple[Sequence[[float, float, float] | :class:`compas.geometry.Point`], Sequence[[int, int, int]]]
+    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]]]
+    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.
@@ -115,5 +143,19 @@ def boolean_intersection(A, B):
     NDArray[(Any, 3), np.int32]
         The faces of the boolean mesh.
 
+    Examples
+    --------
+    >>> from compas.geometry import Box, Sphere, Polyhedron
+    >>> from compas_cgal.booleans import boolean_intersection
+
+    >>> 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)
+
+    >>> C = boolean_intersection(A, B)
+    >>> shape = Polyhedron(*C)
+
     """
     return _boolean(A, B, 'intersection')

src/compas_cgal/intersections.py

@@ -9,16 +9,30 @@ def intersection_mesh_mesh(A, B):
 
     Parameters
     ----------
-    A : tuple[Sequence[[float, float, float] | :class:`compas.geometry.Point`], Sequence[[int, int, int]]]
+    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]]]
+    B : tuple[Sequence[[float, float, float] | :class:`~compas.geometry.Point`], Sequence[[int, int, int]]]
         Mesh B.
 
     Returns
     -------
     list[NDArray[(Any, 3), np.float64]]
         A list of intersection polylines, with each polyline an array of points.
 
+    Examples
+    --------
+    >>> from compas.geometry import Box, Sphere, Polyline
+    >>> from compas_cgal.intersections import intersection_mesh_mesh
+
+    >>> 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)
+
+    >>> result = intersection_mesh_mesh(A, B)
+    >>> polylines = [Polyline(points) for points in result]
+
     """
     VA, FA = A
     VB, FB = B

src/compas_cgal/measure.py

@@ -9,14 +9,25 @@ def volume(mesh):
 
     Parameters
     ----------
-    mesh : tuple[Sequence[[float, float, float] | :class:`compas.geometry.Point`], Sequence[[int, int, int]]]
+    mesh : tuple[Sequence[[float, float, float] | :class:`~compas.geometry.Point`], Sequence[[int, int, int]]]
         The mesh.
 
     Returns
     -------
     float
         The volume of the mesh.
 
+    Examples
+    --------
+    >>> from compas.geometry import Box
+    >>> from compas_cgal.measure import volume
+
+    >>> box = Box.from_width_height_depth(1, 1, 1)
+    >>> mesh = box.to_vertices_and_faces(triangulated=True)
+
+    >>> volume(mesh)
+    1.0
+
     """
     V, F = mesh
     V = np.asarray(V, dtype=np.float64)

src/compas_cgal/meshing.py

@@ -9,7 +9,7 @@ def remesh(mesh, target_edge_length, number_of_iterations=10, do_project=True):
 
     Parameters
     ----------
-    mesh : tuple[Sequence[[float, float, float] | :class:`compas.geometry.Point`], Sequence[[int, int, int]]]
+    mesh : tuple[Sequence[[float, float, float] | :class:`~compas.geometry.Point`], Sequence[[int, int, int]]]
         The mesh to remesh.
     target_edge_length : float
         The target edge length.
@@ -30,6 +30,17 @@ def remesh(mesh, target_edge_length, number_of_iterations=10, do_project=True):
     This remeshing function only constrains the edges on the boundary of the mesh.
     Protecting specific features or edges is not implemented yet.
 
+    Examples
+    --------
+    >>> from compas.geometry import Sphere, Polyhedron
+    >>> from compas_cgal.meshing import remesh
+
+    >>> sphere = Sphere([1, 1, 1], 0.5)
+    >>> mesh = sphere.to_vertices_and_faces(u=32, v=32, triangulated=True)
+
+    >>> result = remesh(mesh)
+    >>> shape = Polyhedron(*result)
+
     """
     V, F = mesh
     V = np.asarray(V, dtype=np.float64)

src/compas_cgal/slicer.py

@@ -9,16 +9,30 @@ def slice_mesh(mesh, planes):
 
     Parameters
     ----------
-    mesh : tuple[Sequence[[float, float, float] | :class:`compas.geometry.Point`], Sequence[[int, int, int]]]
+    mesh : tuple[Sequence[[float, float, float] | :class:`~compas.geometry.Point`], Sequence[[int, int, int]]]
         The mesh to slice.
-    planes : list[[point, normal] | :class:`compas.geometry.Plane`]
+    planes : list[[point, normal] | :class:`~compas.geometry.Plane`]
         The slicing planes.
 
     Returns
     -------
     list[NDArray[(Any, 3), np.float64]]
         A list of slice polylines, with each polyline an array of points.
 
+    Examples
+    --------
+    >>> from compas.geometry import Sphere, Plane, Polylines
+    >>> from compas.utilities import linspace
+    >>> from compas_cgal.slicer import slice_mesh
+
+    >>> sphere = Sphere([0, 0, 1.0], 1.0)
+    >>> mesh = sphere.to_vertices_and_faces(u=32, v=32, triangulated=True)
+
+    >>> planes = [Plane([0, 0, z], [0, 0, 1.0]) for z in linspace(0.1, 1.9, 19)]
+
+    >>> result = slice_mesh(mesh, planes)
+    >>> polylines = [Polyline(points) for points in result]
+
     """
     vertices, faces = mesh
     points, normals = zip(*planes)

src/compas_cgal/subdivision.py

@@ -7,7 +7,7 @@ def catmull_clark(mesh, k=1):
 
     Parameters
     ----------
-    mesh : tuple[Sequence[[float, float, float] | :class:`compas.geometry.Point`], Sequence[[int, int, int]]]
+    mesh : tuple[Sequence[[float, float, float] | :class:`~compas.geometry.Point`], Sequence[[int, int, int]]]
         The mesh to remesh.
     k : int, optional
         The number of subdivision steps.
@@ -19,6 +19,17 @@ def catmull_clark(mesh, k=1):
     NDArray[(Any, 4), np.int32]
         The faces of the subdivided mesh.
 
+    Examples
+    --------
+    >>> from compas.geometry import Box, Polyhedron
+    >>> from compas_cgal.subdivision import catmull_clark
+
+    >>> box = Box.from_width_height_depth(1, 1, 1)
+    >>> mesh = box.to_vertices_and_faces()
+
+    >>> result = catmull_clark(mesh, k=3)
+    >>> shape = Polyhedron(*result)
+
     """
     V, F = mesh
     V = np.asarray(V, dtype=np.float64)

src/compas_cgal/triangulation.py

@@ -9,17 +9,24 @@ def delaunay_triangulation(points):
 
     Parameters
     ----------
-    points : list of :class:`compas.geometry.Point`
+    points : list of :class:`~compas.geometry.Point`
         Points of the triangulation.
 
     Returns
     -------
-    list
+    NDArray[(Any, 3), np.int32]
         The faces of the triangulation.
 
-    Notes
-    -----
-    ...
+    Examples
+    --------
+    >>> from compas.geometry import Pointcloud
+    >>> from compas.datastructures import Mesh
+    >>> from compas_cgal.triangulation import delaunay_triangulation
+
+    >>> points = Pointcloud.from_bounds(8, 5, 0, 17)
+    >>> triangles = delaunay_triangulation(points)
+
+    >>> mesh = Mesh.from_vertices_and_faces(points, triangles)
 
     """
     vertices = np.asarray(points, dtype=np.float64)
@@ -32,23 +39,21 @@ def constrained_delaunay_triangulation(boundary, points=None, holes=None, curves
 
     Parameters
     ----------
-    boundary : :class:`compas.geometry.Polygon`
+    boundary : :class:`~compas.geometry.Polygon`
         The boundary of the triangulation.
-    points : list of :class:`compas.geometry.Point`, optional
+    points : list of :class:`~compas.geometry.Point`, optional
         Additional internal points.
-    holes : list of :class:`compas.geometry.Polygon`, optional
+    holes : list of :class:`~compas.geometry.Polygon`, optional
         Internal boundary polygons.
-    curves : list of :class:`compas.geometry.Polyline`, optional
+    curves : list of :class:`~compas.geometry.Polyline`, optional
         Internal constraint curves.
 
     Returns
     -------
-    list
-        The vertices and faces of the triangulation.
-
-    Notes
-    -----
-    ...
+    NDArray[(Any, 3), np.float64]
+        The vertices of the triangulation.
+    NDArray[(Any, 3), np.int32]
+        The faces of the triangulation.
 
     """
     boundary = np.asarray(boundary, dtype=np.float64)
@@ -75,20 +80,20 @@ def conforming_delaunay_triangulation(boundary, points=None, holes=None, curves=
 
     Parameters
     ----------
-    boundary : :class:`compas.geometry.Polygon`
+    boundary : :class:`~compas.geometry.Polygon`
         The boundary of the triangulation.
-    points : list[:class:`compas.geometry.Point`], optional
+    points : list[:class:`~compas.geometry.Point`], optional
         Additional internal points.
-    holes : list[:class:`compas.geometry.Polygon`], optional
+    holes : list[:class:`~compas.geometry.Polygon`], optional
         Internal boundary polygons.
-    curves : list[:class:`compas.geometry.Polyline`], optional
+    curves : list[:class:`~compas.geometry.Polyline`], optional
         Internal constraint curves.
 
     Returns
     -------
-    (V, 3) np.array[float]
+    NDArray[(Any, 3), np.float64]
         The vertices of the triangulation.
-    (F, 3) np.array[int]
+    NDArray[(Any, 3), np.int32]
         The faces of the triangulation.
 
     """
@@ -115,13 +120,13 @@ def refined_delaunay_mesh(boundary, points=None, holes=None, curves=None, maxlen
 
     Parameters
     ----------
-    boundary : :class:`compas.geometry.Polygon`
+    boundary : :class:`~compas.geometry.Polygon`
         The boundary of the triangulation.
-    points : list[:class:`compas.geometry.Point`], optional
+    points : list[:class:`~compas.geometry.Point`], optional
         Additional internal points.
-    holes : list[:class:`compas.geometry.Polygon`], optional
+    holes : list[:class:`~compas.geometry.Polygon`], optional
         Internal boundary polygons.
-    curves : list[:class:`compas.geometry.Polyline`], optional
+    curves : list[:class:`~compas.geometry.Polyline`], optional
         Internal constraint curves.
     maxlength : float, optional
         The maximum length of the triangle edges.

src/compas_cgal/trimesh.py

@@ -221,7 +221,7 @@ def from_mesh(cls, mesh):
 
         Parameters
         ----------
-        mesh : :class:`compas.datastructures.Mesh`
+        mesh : :class:`~compas.datastructures.Mesh`
             A COMPAS mesh data structure.
 
         Returns
@@ -237,7 +237,7 @@ def to_mesh(self):
 
         Returns
         -------
-        :class:`compas.datastructures.Mesh`
+        :class:`~compas.datastructures.Mesh`
 
         """
         return Mesh.from_vertices_and_faces(self.vertices, self.faces)
@@ -258,7 +258,7 @@ def transform(self, T):
 
         Parameters
         ----------
-        T : :class:`compas.geometry.Transformation`
+        T : :class:`~compas.geometry.Transformation`
             A 4x4 transformation matrix.
 
         Returns
@@ -273,7 +273,7 @@ def transformed(self, T):
 
         Parameters
         ----------
-        T : :class:`compas.geometry.Transformation`
+        T : :class:`~compas.geometry.Transformation`
             A 4x4 transformation matrix.
 
         Returns