DOC: addressed docs review from @skoudoro

fury/actor.py

@@ -1,7 +1,8 @@
 import numpy as np
-import fury.primitive as fp
-from fury.material import _create_mesh_material
+
 from fury.geometry import buffer_to_geometry, create_mesh
+from fury.material import _create_mesh_material
+import fury.primitive as fp
 
 
 def sphere(
@@ -12,8 +13,8 @@ def sphere(
     phi=16,
     theta=16,
     opacity=None,
-    material='phong',
-    enable_picking=True
+    material="phong",
+    enable_picking=True,
 ):
     """
     Visualize one or many spheres with different colors and radii.
@@ -28,17 +29,17 @@ def sphere(
         Sphere radius. Can be a single value for all spheres or an array of
         radii for each sphere.
     phi : int, optional
-        The number of segments in the longitude direction. Default is 16.
+        The number of segments in the longitude direction.
     theta : int, optional
-        The number of segments in the latitude direction. Default is 16.
+        The number of segments in the latitude direction.
     opacity : float, optional
-        Takes values from 0 (fully transparent) to 1 (opaque). Default is None
-        (fully opaque).
+        Takes values from 0 (fully transparent) to 1 (opaque).
+        If both `opacity` and RGBA are provided, the final alpha will be:
+        final_alpha = alpha_in_RGBA * opacity
     material : str, optional
-        The material type for the spheres. Options are 'phong' (default)
-        and 'basic'.
+        The material type for the spheres. Options are 'phong' and 'basic'.
     enable_picking : bool, optional
-        Whether the spheres should be pickable in a 3D scene. Defaults to True.
+        Whether the spheres should be pickable in a 3D scene.
 
     Returns
     -------
@@ -74,26 +75,24 @@ def sphere(
 
     prim_count = len(centers)
 
-    big_colors = big_colors / 255.
+    big_colors = big_colors / 255.0
 
     if isinstance(opacity, (int, float)):
         if big_colors.shape[1] == 3:
             big_colors = np.hstack(
-                (big_colors, np.full(
-                    (big_colors.shape[0], 1), opacity)))
+                (big_colors, np.full((big_colors.shape[0], 1), opacity))
+            )
         else:
             big_colors[:, 3] *= opacity
 
     geo = buffer_to_geometry(
-        indices=big_faces.astype('int32'),
-        positions=big_vertices.astype('float32'),
-        texcoords=big_vertices.astype('float32'),
-        colors=big_colors.astype('float32'),
+        indices=big_faces.astype("int32"),
+        positions=big_vertices.astype("float32"),
+        texcoords=big_vertices.astype("float32"),
+        colors=big_colors.astype("float32"),
     )
 
-    mat = _create_mesh_material(
-        material=material,
-        enable_picking=enable_picking)
+    mat = _create_mesh_material(material=material, enable_picking=enable_picking)
     obj = create_mesh(geometry=geo, material=mat)
     obj.local.position = centers[0]
     obj.prim_count = prim_count

fury/geometry.py

@@ -13,6 +13,11 @@ def buffer_to_geometry(positions, **kwargs):
         A dict of attributes to define on the geometry object. Keys can be
         "colors", "normals", "texcoords",
         "indices", ...
+
+    Returns
+    -------
+    geo : Geometry
+        The geometry object.
     """
     geo = Geometry(positions=positions, **kwargs)
     return geo
@@ -28,6 +33,11 @@ def create_mesh(geometry, material):
         The geometry object.
     material : Material
         The material object.
+
+    Returns
+    -------
+    mesh : Mesh
+        The mesh object.
     """
     mesh = Mesh(geometry=geometry, material=material)
     return mesh

fury/material.py

@@ -2,27 +2,27 @@
 
 
 def _create_mesh_material(
-
-        material='phong',
-        enable_picking=True,
-        color=None,
-        opacity=1.0):
+    *, material="phong", enable_picking=True, color=None, opacity=1.0, mode="vertex"
+):
     """
     Create a mesh material.
 
     Parameters
     ----------
-    material : str
+    material : str, optional
         The type of material to create. Options are 'phong' (default) and
         'basic'.
-    enable_picking : bool
-        Whether the material should be pickable in a scene. Defaults to True.
-    color : tuple or None
+    enable_picking : bool, optional
+        Whether the material should be pickable in a scene.
+    color : tuple or None, optional
         The color of the material, represented as an RGBA tuple. If None, the
-        default color is used. Defaults to None.
-    opacity : float
+        default color is used.
+    opacity : float, optional
         The opacity of the material, from 0 (transparent) to 1 (opaque).
-        Defaults to 1.0.
+        If RGBA is provided, the final alpha will be:
+        final_alpha = alpha_in_RGBA * opacity
+    mode : str, optional
+        The color mode of the material. Options are 'auto' and 'vertex'.
 
     Returns
     -------

fury/utils.py

@@ -26,8 +26,7 @@ def map_coordinates_3d_4d(input_array, indices):
     if input_array.ndim == 4:
         values_4d = []
         for i in range(input_array.shape[-1]):
-            values_tmp = map_coordinates(
-                input_array[..., i], indices.T, order=1)
+            values_tmp = map_coordinates(input_array[..., i], indices.T, order=1)
             values_4d.append(values_tmp)
         return np.ascontiguousarray(np.array(values_4d).T)
 
@@ -152,8 +151,7 @@ def get_grid_cells_position(shapes, *, aspect_ratio=16 / 9.0, dim=None):
 
     # Use indexing="xy" so the cells are in row-major (C-order). Also,
     # the Y coordinates are negative so the cells are order from top to bottom.
-    X, Y, Z = np.meshgrid(np.arange(n_cols), -
-                          np.arange(n_rows), [0], indexing="xy")
+    X, Y, Z = np.meshgrid(np.arange(n_cols), -np.arange(n_rows), [0], indexing="xy")
     return cell_shape * np.array([X.flatten(), Y.flatten(), Z.flatten()]).T