docs: small example and docstring updates

Author: tomvanmele

src/compas/geometry/algorithms/hull_numpy.py

@@ -37,15 +37,56 @@ def convex_hull_numpy(points):
         Indices of the points on the hull.
         Faces of the hull.
 
-    Warning
-    -------
-    This function requires Numpy ands Scipy.
+    Notes
+    -----
+    The faces of the hull returned by this function do not necessarily have consistent
+    cycle directions. To obtain a mesh with consistent cycle directions, construct
+    a mesh from the returned vertices, this function should be used in combination
+    with :func:`compas.topology.unify_cycles`.
 
     Examples
     --------
     .. code-block:: python
 
-        #
+        import random
+
+        from compas.datastructures import Mesh
+
+        from compas.geometry import distance_point_point
+        from compas.geometry import convex_hull_numpy
+        from compas.topology import unify_cycles
+
+        from compas.viewers import MeshViewer
+
+        radius = 5
+        origin = (0., 0., 0.)
+        count = 0
+        points = []
+
+        while count < 10:
+            x = (random.random() - 0.5) * radius * 2
+            y = (random.random() - 0.5) * radius * 2
+            z = (random.random() - 0.5) * radius * 2
+            pt = x, y, z
+
+            if distance_point_point(origin, pt) <= radius:
+                points.append(pt)
+                count += 1
+
+        vertices, faces = convex_hull_numpy(points)
+
+        i_index = {i: index for index, i in enumerate(vertices)}
+
+        vertices = [points[index] for index in vertices]
+        faces = [[i_index[i] for i in face] for face in faces]
+        faces = unify_cycles(vertices, faces)
+
+        mesh = Mesh.from_vertices_and_faces(vertices, faces)
+
+        viewer = MeshViewer(mesh)
+
+        viewer.setup()
+        viewer.show()
 
     """
     points = asarray(points)
@@ -73,10 +114,18 @@ def convex_hull_xy_numpy(points):
 
     Returns
     -------
-    tuple
+    list
         Indices of the points on the hull.
+    list
         Faces of the hull.
 
+    Notes
+    -----
+    The faces of the hull returned by this function do not necessarily have consistent
+    cycle directions. To obtain a mesh with consistent cycle directions, construct
+    a mesh from the returned vertices, this function should be used in combination
+    with :func:`compas.topology.unify_cycles`.
+
     Examples
     --------
     .. code-block:: python
@@ -91,9 +140,6 @@ def convex_hull_xy_numpy(points):
 
     points = points[:, :2]
     hull = ConvexHull(points)
-    # temp = zeros((hull.vertices.shape[0], 1))
-    # temp[:, :-1] = points[hull.vertices]
-    # return temp
     return hull.vertices, hull.simplices
 
 
@@ -108,19 +154,19 @@ def convex_hull_xy_numpy(points):
 
     import random
 
-    from compas.geometry.distance import distance_point_point
+    from compas.geometry import distance_point_point
 
     from compas.datastructures import Mesh
     from compas.viewers import MeshViewer
 
-    from compas.topology import mesh_unify_cycles
+    from compas.topology import unify_cycles
 
     radius = 5
     origin = (0., 0., 0.)
     count = 0
     points = []
 
-    while count < 10:
+    while count < 1000:
         x = (random.random() - 0.5) * radius * 2
         y = (random.random() - 0.5) * radius * 2
         z = (random.random() - 0.5) * radius * 2
@@ -134,14 +180,16 @@ def convex_hull_xy_numpy(points):
 
     i_index = {i: index for index, i in enumerate(vertices)}
 
-    mesh = Mesh.from_vertices_and_faces(
-        [points[index] for index in vertices],
-        [[i_index[i] for i in face] for face in faces[1:]]
-    )
+    vertices = [points[index] for index in vertices]
+    faces = [[i_index[i] for i in face] for face in faces]
+    faces = unify_cycles(vertices, faces)
 
-    mesh_unify_cycles(mesh)
+    mesh = Mesh.from_vertices_and_faces(vertices, faces)
 
     viewer = MeshViewer(mesh)
 
+    viewer.axes_on = False
+    viewer.grid_on = False
+
     viewer.setup()
     viewer.show()

src/compas/plotters/plotter.py

@@ -31,13 +31,6 @@
 __all__ = ['Plotter', ]
 
 
-# https://matplotlib.org/faq/usage_faq.html#what-is-interactive-mode
-# https://matplotlib.org/api/pyplot_summary.html
-# https://matplotlib.org/api/figure_api.html#matplotlib.figure.Figure
-# https://matplotlib.org/api/axes_api.html
-# https://matplotlib.org/api/index.html
-
-
 class Plotter(object):
     """Definition of a plotter object based on matplotlib.
 
@@ -76,7 +69,6 @@ class Plotter(object):
            Computing In Science & Engineering (9) 3, p.90-95.
            Available at: http://ieeexplore.ieee.org/document/4160265/citations.
 
-
     """
     def __init__(self, figsize=(16.0, 12.0), dpi=100.0, interactive=False, tight=False, **kwargs):
         """Initialises a plotter object"""

src/compas/topology/traversal.py

@@ -256,6 +256,7 @@ def breadth_first_ordering(adjacency, root):
 
 
 def breadth_first_traverse(adjacency, root, callback=None):
+    """"""
     tovisit  = deque([root])
     visited  = set([root])
 

src/compas/viewers/meshviewer.py

@@ -71,22 +71,22 @@ def display(self):
                            'color' : (0.4, 0.4, 0.4),
                            'size'  : 5.0})
 
-        normals = []
-        for fkey in self.mesh.faces():
-            n  = self.mesh.face_normal(fkey, unitized=True)
-            sp = self.mesh.face_centroid(fkey)
-            ep = [sp[axis] + n[axis] for axis in (0, 1, 2)]
-            normals.append({
-                'start' : sp,
-                'end'   : ep,
-                'color' : (0.0, 1.0, 0.0),
-                'width' : 2.0 
-            })
+        # normals = []
+        # for fkey in self.mesh.faces():
+        #     n  = self.mesh.face_normal(fkey, unitized=True)
+        #     sp = self.mesh.face_centroid(fkey)
+        #     ep = [sp[axis] + n[axis] for axis in (0, 1, 2)]
+        #     normals.append({
+        #         'start' : sp,
+        #         'end'   : ep,
+        #         'color' : (0.0, 1.0, 0.0),
+        #         'width' : 2.0
+        #     })
 
         xdraw_polygons(polygons)
         xdraw_lines(lines)
         xdraw_points(points)
-        xdraw_lines(normals)
+        # xdraw_lines(normals)
 
     def keypress(self, key, x, y):
         """

src/compas/viewers/viewer.py

@@ -48,16 +48,27 @@ class Viewer(object):
         The width of the viewer window.
     height : int
         The height of the viewer window.
-    clear_color : sequence(4)
+    near : float
+        Distance of the near clipping plane. Default is `0.1`.
+    far : float
+        Distance of the far clipping plane. Default is `1000.0`.
+    fov : float
+        Field of view. Default is `50.0`.
+    clear_color : 4-tuple of float
         A sequence of 4 floats defining the background color of the scene.
+        Default is `(0.9, 0.9, 0.9, 1.0)`.
     grid_on : bool
         Grid on or off.
+    axes_on : bool
+        Grid on or off.
     mouse : Mouse
         A ``Mouse`` object.
     camera : Camera
         A ``Camera`` object.
     grid : Grid
         A ``Grid`` object.
+    displayfuncs : list of callable
+        A list of functions called by the display callback to render the scene.
 
     Notes
     -----