NF: Adding point actor and all its requirements.

fury/actor.py

@@ -1,7 +1,11 @@
 import numpy as np
 
-from fury.geometry import buffer_to_geometry, create_mesh
-from fury.material import _create_mesh_material
+from fury.geometry import buffer_to_geometry, create_mesh, create_point
+from fury.material import (
+    _create_marker_material,
+    _create_mesh_material,
+    _create_points_material,
+)
 import fury.primitive as fp
 
 
@@ -1127,3 +1131,139 @@ def star(
         material=material,
         enable_picking=enable_picking,
     )
+
+
+def point(
+    centers,
+    *,
+    size=4,
+    colors=(1.0, 0.0, 0.0),
+    material="basic",
+    map=None,
+    aa=True,
+    opacity=1.0,
+    enable_picking=True,
+):
+    """Visualize one or many points with different features.
+
+    Parameters
+    ----------
+    centers : ndarray, shape (N, 3), optional
+        The positions of the points. If None, random points will be generated.
+    size : float
+        The size (diameter) of the points in logical pixels. Default 4.
+    colors : ndarray (N,3) or (N,4) or tuple (3,) or tuple (4,), optional
+        RGB or RGBA values in the range [0, 1].
+    material : str, optional
+        The material type for the points. Options are 'basic', 'gaussian'.
+    map : TextureMap | Texture
+        The texture map specifying the color for each texture coordinate.
+    aa : bool
+        Whether or not the points are anti-aliased in the shader. Default True.
+    opacity : float, optional
+        Takes values from 0 (fully transparent) to 1 (opaque).
+    enable_picking : bool, optional
+        Whether the points should be pickable in a 3D scene.
+
+    Returns
+    -------
+    point_actor : Actor
+        An point actor containing the generated points with the specified material
+        and properties.
+
+    Examples
+    --------
+    >>> from fury import window, actor
+    >>> import numpy as np
+    >>> scene = window.Scene()
+    >>> centers = np.random.rand(1000, 3) * 10
+    >>> colors = np.random.rand(1000, 3)
+    >>> point_actor = actor.point(centers=centers, colors=colors)
+    >>> scene.add(point_actor)
+    >>> show_manager = window.ShowManager(scene=scene, size=(600, 600))
+    >>> show_manager.start()
+    """
+    geo = buffer_to_geometry(
+        positions=centers.astype("float32"),
+        colors=colors.astype("float32"),
+    )
+
+    mat = _create_points_material(
+        size=size,
+        material=material,
+        map=map,
+        aa=aa,
+        opacity=opacity,
+        enable_picking=enable_picking,
+    )
+
+    obj = create_point(geo, mat)
+    return obj
+
+
+def marker(
+    centers,
+    *,
+    size=15,
+    colors=(1.0, 0.0, 0.0),
+    marker="circle",
+    edge_color="black",
+    edge_width=1,
+    opacity=1.0,
+    enable_picking=True,
+):
+    """Visualize one or many marker with different features.
+
+    Parameters
+    ----------
+    centers : ndarray, shape (N, 3), optional
+        The positions of the points. If None, random points will be generated.
+    size : float
+        The size (diameter) of the points in logical pixels. Default 4.
+    colors : ndarray (N,3) or (N,4) or tuple (3,) or tuple (4,), optional
+        RGB or RGBA values in the range [0, 1].
+    marker : str | MarkerShape
+        The shape of the marker. Default 'circle'.
+    edge_color : str | tuple | Color
+        The color of line marking the edge of the markers. Default 'black'.
+    edge_width : float
+        The width of the edge of the markers. Default 1.
+    opacity : float, optional
+        Takes values from 0 (fully transparent) to 1 (opaque).
+    enable_picking : bool, optional
+        Whether the points should be pickable in a 3D scene.
+
+    Returns
+    -------
+    marker_actor : Actor
+        An marker actor containing the generated points with the specified material
+        and properties.
+
+    Examples
+    --------
+    >>> from fury import window, actor
+    >>> import numpy as np
+    >>> scene = window.Scene()
+    >>> centers = np.random.rand(1000, 3) * 10
+    >>> colors = np.random.rand(1000, 3)
+    >>> marker_actor = actor.marker(centers=centers, colors=colors)
+    >>> scene.add(marker_actor)
+    >>> show_manager = window.ShowManager(scene=scene, size=(600, 600))
+    >>> show_manager.start()
+    """
+    geo = buffer_to_geometry(
+        positions=centers.astype("float32"),
+        colors=colors.astype("float32"),
+    )
+
+    mat = _create_marker_material(
+        size=size,
+        marker=marker,
+        edge_color=edge_color,
+        edge_width=edge_width,
+        opacity=opacity,
+        enable_picking=enable_picking,
+    )
+
+    obj = create_point(geo, mat)
+    return obj

fury/geometry.py

@@ -1,4 +1,4 @@
-from pygfx import Geometry, Mesh
+from pygfx import Geometry, Mesh, Points
 
 
 def buffer_to_geometry(positions, **kwargs):
@@ -41,3 +41,23 @@ def create_mesh(geometry, material):
     """
     mesh = Mesh(geometry=geometry, material=material)
     return mesh
+
+
+def create_point(geometry, material):
+    """
+    Create a point object.
+
+    Parameters
+    ----------
+    geometry : Geometry
+        The geometry object.
+    material : Material
+        The material object.
+
+    Returns
+    -------
+    points : Points
+        The point object.
+    """
+    point = Points(geometry=geometry, material=material)
+    return point

fury/material.py

@@ -99,3 +99,162 @@ def _create_mesh_material(
         )
     else:
         raise ValueError(f"Unsupported material type: {material}")
+
+
+def _create_points_material(
+    *,
+    material="basic",
+    color=(1.0, 1.0, 1.0),
+    size=4,
+    map=None,
+    aa=True,
+    mode="vertex",
+    opacity=1.0,
+    enable_picking=True,
+):
+    """
+     Create a points material.
+
+     Parameters
+     ----------
+     material : str, optional
+         The type of material to create. Options are 'baisc' (default),
+         'gaussian', and 'marker'.
+    colors : ndarray (N,3) or (N,4) or tuple (3,) or tuple (4,), optional
+         RGB or RGBA values in the range [0, 1].
+     size : float
+         The size (diameter) of the points in logical pixels. Default 4.
+     map : TextureMap | Texture
+         The texture map specifying the color for each texture coordinate.
+     aa : bool
+         Whether or not the points are anti-aliased in the shader. Default True.
+     mode : str, optional
+         The color mode of the material. Options are 'auto' and 'vertex'.
+     opacity : float, optional
+         The opacity of the material, from 0 (transparent) to 1 (opaque).
+         If RGBA is provided, the final alpha will be:
+         final_alpha = alpha_in_RGBA * opacity
+     enable_picking : bool, optional
+         Whether the material should be pickable in a scene.
+
+     Returns
+     -------
+     PointsMaterial
+         A point material object of the specified type with the given properties.
+    """
+
+    if not (0 <= opacity <= 1):
+        raise ValueError("Opacity must be between 0 and 1.")
+
+    if color is None and mode == "auto":
+        raise ValueError("Color must be specified when mode is 'auto'.")
+
+    elif color is not None:
+        if len(color) == 3:
+            color = (*color, opacity)
+        elif len(color) == 4:
+            color = color
+            color = (*color[:3], color[3] * opacity)
+        else:
+            raise ValueError("Color must be a tuple of length 3 or 4.")
+
+    if mode == "vertex":
+        color = (1, 1, 1)
+
+    if material == "basic":
+        return gfx.PointsMaterial(
+            color=color,
+            size=size,
+            color_mode=mode,
+            map=map,
+            aa=aa,
+            pick_write=enable_picking,
+        )
+    elif material == "gaussian":
+        return gfx.PointsGaussianBlobMaterial(
+            color=color,
+            size=size,
+            color_mode=mode,
+            map=map,
+            aa=aa,
+            pick_write=enable_picking,
+        )
+    else:
+        raise ValueError(f"Unsupported material type: {material}")
+
+
+def _create_marker_material(
+    *,
+    material="marker",
+    color=(1.0, 1.0, 1.0),
+    size=4,
+    marker="circle",
+    edge_color="black",
+    edge_width=1,
+    mode="vertex",
+    opacity=1.0,
+    enable_picking=True,
+):
+    """
+     Create a marker material.
+
+     Parameters
+     ----------
+     material : str, optional
+         The type of material to create. Options are 'baisc' (default),
+         'gaussian', and 'marker'.
+    colors : ndarray (N,3) or (N,4) or tuple (3,) or tuple (4,), optional
+         RGB or RGBA values in the range [0, 1].
+     size : float
+         The size (diameter) of the points in logical pixels. Default 4.
+     marker : str | MarkerShape
+         The shape of the marker. Default 'circle'.
+     edge_color : str | tuple | Color
+         The color of line marking the edge of the markers. Default 'black'.
+     edge_width : float
+         The width of the edge of the markers. Default 1.
+     mode : str, optional
+         The color mode of the material. Options are 'auto' and 'vertex'.
+     opacity : float, optional
+         The opacity of the material, from 0 (transparent) to 1 (opaque).
+         If RGBA is provided, the final alpha will be:
+         final_alpha = alpha_in_RGBA * opacity
+     enable_picking : bool, optional
+         Whether the material should be pickable in a scene.
+
+     Returns
+     -------
+     MarkerMaterial
+         A marker material object of the specified type with the given properties.
+    """
+
+    if not (0 <= opacity <= 1):
+        raise ValueError("Opacity must be between 0 and 1.")
+
+    if color is None and mode == "auto":
+        raise ValueError("Color must be specified when mode is 'auto'.")
+
+    elif color is not None:
+        if len(color) == 3:
+            color = (*color, opacity)
+        elif len(color) == 4:
+            color = color
+            color = (*color[:3], color[3] * opacity)
+        else:
+            raise ValueError("Color must be a tuple of length 3 or 4.")
+
+    if mode == "vertex":
+        color = (1, 1, 1)
+
+    if material == "marker":
+        return gfx.PointsMarkerMaterial(
+            color=color,
+            size=size,
+            marker=marker,
+            edge_color=edge_color,
+            edge_width=edge_width,
+            pick_write=enable_picking,
+            color_mode=mode,
+        )
+    else:
+        raise ValueError(f"Unsupported material type: {material}")