Get nearest graphics indices (#699)

FlynnOConnell · web-flow · commit c734f02d5521 · 2025-02-16T04:37:45.000-05:00
* get_nearest_graphics_indices plot helper

* map_screen_to_world can return None

* black format source dir only
diff --git a/fastplotlib/layouts/_plot_area.py b/fastplotlib/layouts/_plot_area.py
@@ -299,7 +299,7 @@ def get_rect(self) -> tuple[float, float, float, float]:
 
     def map_screen_to_world(
         self, pos: tuple[float, float] | pygfx.PointerEvent
-    ) -> np.ndarray:
+    ) -> np.ndarray | None:
         """
         Map screen position to world position
 
diff --git a/fastplotlib/utils/_plot_helpers.py b/fastplotlib/utils/_plot_helpers.py
@@ -6,13 +6,14 @@
 from ..graphics._collection_base import GraphicCollection
 
 
-def get_nearest_graphics(
+def get_nearest_graphics_indices(
     pos: tuple[float, float] | tuple[float, float, float],
     graphics: Sequence[Graphic] | GraphicCollection,
-) -> np.ndarray[Graphic]:
+) -> np.ndarray[int]:
     """
-    Returns the nearest ``graphics`` to the passed position ``pos`` in world space.
-    Uses the distance between ``pos`` and the center of the bounding sphere for each graphic.
+    Returns indices of the nearest ``graphics`` to the passed position ``pos`` in world space
+    in order of closest to furtherst. Uses the distance between ``pos`` and the center of the
+    bounding sphere for each graphic.
 
     Parameters
     ----------
@@ -25,11 +26,10 @@ def get_nearest_graphics(
 
     Returns
     -------
-    tuple[Graphic]
-        nearest graphics to ``pos`` in order
+    ndarray[int]
+        indices of the nearest nearest graphics to ``pos`` in order
 
     """
-
     if isinstance(graphics, GraphicCollection):
         graphics = graphics.graphics
 
@@ -50,4 +50,31 @@ def get_nearest_graphics(
     distances = np.linalg.norm(centers[:, : len(pos)] - pos, ord=2, axis=1)
 
     sort_indices = np.argsort(distances)
+    return sort_indices
+
+
+def get_nearest_graphics(
+    pos: tuple[float, float] | tuple[float, float, float],
+    graphics: Sequence[Graphic] | GraphicCollection,
+) -> np.ndarray[Graphic]:
+    """
+    Returns the nearest ``graphics`` to the passed position ``pos`` in world space.
+    Uses the distance between ``pos`` and the center of the bounding sphere for each graphic.
+
+    Parameters
+    ----------
+    pos: (x, y) | (x, y, z)
+        position in world space, z-axis is ignored when calculating L2 norms if ``pos`` is 2D
+
+    graphics: Sequence, i.e. array, list, tuple, etc. of Graphic | GraphicCollection
+        the graphics from which to return a sorted array of graphics in order of closest
+        to furthest graphic
+
+    Returns
+    -------
+    ndarray[Graphic]
+        nearest graphics to ``pos`` in order
+
+    """
+    sort_indices = get_nearest_graphics_indices(pos, graphics)
     return np.asarray(graphics)[sort_indices]
