Put an event filter on the view

This is a clean solution for implementing "on-leave" behavior. In NDV's
case, it's needed to clear the hover info when the cursor leaves the
image.

Author: gselzer

examples/event_filters.py

@@ -2,7 +2,7 @@
 import numpy as np
 
 import scenex as snx
-from scenex.app.events import Event, MouseEvent
+from scenex.app.events import Event, MouseMoveEvent
 
 img = snx.Image(
     data=np.zeros((200, 200)).astype(np.uint8),
@@ -15,26 +15,33 @@
 view = snx.View(scene=snx.Scene(children=[img]))
 
 
-def _img_filter(event: Event, node: snx.Node) -> bool:
+def _view_filter(event: Event) -> bool:
     """Example event drawing a square that reacts to the cursor."""
-    # TODO: How might we remove the square when the mouse leaves the image?
-
-    if isinstance(event, MouseEvent) and isinstance(node, snx.Image):
-        data = np.zeros((200, 200), dtype=np.uint8)
-        x = int(event.world_ray.origin[0])
-        min_x = max(0, x - 5)
-        max_x = min(data.shape[0], x + 5)
-
-        y = int(event.world_ray.origin[1])
-        min_y = max(0, y - 5)
-        max_y = min(data.shape[1], y + 5)
-
-        data[min_x:max_x, min_y:max_y] = 255
-        node.data = data
+    if isinstance(event, MouseMoveEvent):
+        intersections = event.world_ray.intersections(view.scene)
+        if not intersections:
+            # Clear the image if the mouse is not over it
+            img.data = np.zeros((200, 200), dtype=np.uint8)
+            return True
+        for node, distance in intersections:
+            if not isinstance(node, snx.Image):
+                continue
+            intersection = event.world_ray.point_at_distance(distance)
+            data = np.zeros((200, 200), dtype=np.uint8)
+            x = int(intersection[0])
+            min_x = max(0, x - 5)
+            max_x = min(data.shape[0], x + 5)
+
+            y = int(intersection[1])
+            min_y = max(0, y - 5)
+            max_y = min(data.shape[1], y + 5)
+
+            data[min_x:max_x, min_y:max_y] = 255
+            node.data = data
     return True
 
 
-img.set_event_filter(_img_filter)
+view.set_event_filter(_view_filter)
 
 snx.show(view)
 snx.run()

src/scenex/app/events/_events.py

@@ -2,7 +2,10 @@
 
 from dataclasses import dataclass
 from enum import IntFlag, auto
-from typing import NamedTuple
+from typing import TYPE_CHECKING, NamedTuple, TypeAlias
+
+if TYPE_CHECKING:
+    from scenex import Node
 
 
 # Note that scenex follows the inheritance pattern for event subtypes.
@@ -24,6 +27,9 @@ class MouseButton(IntFlag):
     RIGHT = auto()
 
 
+Intersection: TypeAlias = tuple["Node", float]
+
+
 class Ray(NamedTuple):
     """A ray passing through the world."""
 
@@ -36,6 +42,19 @@ def point_at_distance(self, distance: float) -> tuple[float, float, float]:
         z = self.origin[2] + self.direction[2] * distance
         return (x, y, z)
 
+    def intersections(self, graph: Node) -> list[Intersection]:
+        """
+        Find all intersections of this ray with the given scene graph.
+
+        Returns a list of (node, distance) tuples, sorted by distance.
+        """
+        through: list[Intersection] = []
+        for child in graph.children:
+            if (d := child.passes_through(self)) is not None:
+                through.append((child, d))
+                through.extend(self.intersections(child))
+        return sorted(through, key=lambda inter: inter[1])
+
 
 @dataclass
 class ResizeEvent(Event):

src/scenex/model/_canvas.py

@@ -116,18 +116,19 @@ def handle(self, event: Event) -> bool:
         handled = False
         if isinstance(event, MouseEvent):
             if view := self._containing_view(event.canvas_pos):
-                through: list[tuple[Node, float]] = []
-                for child in view.scene.children:
-                    if (d := child.passes_through(event.world_ray)) is not None:
-                        through.append((child, d))
+                # Give the view a chance to observe the result
+                if view.filter_event(event):
+                    return True
 
+                intersections = event.world_ray.intersections(view.scene)
                 # FIXME: Consider only reporting the first?
                 # Or do we only report until we hit a node with opacity=1?
-                for node, _depth in sorted(through, key=lambda e: e[1]):
+                for node, _distance in intersections:
                     # Filter through parent scenes to child
-                    handled |= Canvas._filter_through(event, node, node)
+                    if Canvas._filter_through(event, node, node):
+                        return True
                 # No nodes in the view handled the event - pass it to the camera
-                if not handled and view.camera.interactive:
+                if view.camera.interactive:
                     handled |= view.camera.filter_event(event, view.camera)
         elif isinstance(event, ResizeEvent):
             # TODO: How might some event filter tap into the resize?

src/scenex/model/_view.py

@@ -13,9 +13,12 @@
 from ._nodes.scene import Scene
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     import numpy as np
 
     from scenex.adaptors._base import ViewAdaptor
+    from scenex.app.events import Event
 
     from ._canvas import Canvas
 
@@ -71,3 +74,24 @@ def render(self) -> np.ndarray:
         if adaptors := self._get_adaptors():
             return cast("ViewAdaptor", adaptors[0])._snx_render()
         raise RuntimeError("No adaptor found for View.")
+
+    _filter: Callable[[Event], bool] | None = PrivateAttr(default=None)
+
+    def set_event_filter(
+        self, callable: Callable[[Event], bool] | None
+    ) -> Callable[[Event], bool] | None:
+        old, self._filter = self._filter, callable
+        return old
+
+    def filter_event(self, event: Event) -> bool:
+        """
+        Filters the event.
+
+        This method allows the larger view to react to events that:
+        1. Require summarization of multiple smaller event responses.
+        2. Could not be picked up by a node (e.g. mouse leaving an image).
+
+        Note the name has parity with Node.filter_event, but there's much filtering
+        going on.
+        """
+        return self._filter(event) if self._filter else False

tests/model/_nodes/test_view.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import numpy as np
+
+import scenex as snx
+from scenex.app.events import MouseButton, MouseMoveEvent
+from scenex.utils import projections
+
+
+def test_events() -> None:
+    # Create a view with an image
+    img = snx.Image(data=np.ones((10, 10), dtype=np.uint8), interactive=True)
+    img_filter = MagicMock()
+    img.set_event_filter(img_filter)
+
+    view = snx.View(scene=snx.Scene(children=[img]))
+    view_filter = MagicMock()
+    view_filter.return_value = False
+    view.set_event_filter(view_filter)
+
+    # Set up the camera
+    # Such that the image is in the top right quadrant
+    view.camera.transform = snx.Transform().translated((-0.5, -0.5))
+    view.camera.projection = projections.orthographic(1, 1, 1)
+
+    # Put it on a canvas
+    canvas = snx.Canvas(width=int(view.layout.width), height=int(view.layout.height))
+    canvas.views.append(view)
+
+    # Mouse over that image in the top right corner
+    canvas_pos = (view.layout.width, 0)
+    world_ray = canvas.to_world(canvas_pos)
+    assert world_ray is not None
+    event = MouseMoveEvent(
+        canvas_pos=canvas_pos, world_ray=world_ray, buttons=MouseButton.NONE
+    )
+
+    # And show both the view and the image saw the event
+    canvas.handle(event)
+    view_filter.assert_called_once_with(event)
+    img_filter.assert_called_once_with(event, img)
+
+    # Reset the mocks
+    img_filter.reset_mock()
+    view_filter.reset_mock()
+
+    # Mouse over empty space in the top left corner
+    canvas_pos = (0, 0)
+    world_ray = canvas.to_world(canvas_pos)
+    assert world_ray is not None
+    event = MouseMoveEvent(
+        canvas_pos=canvas_pos, world_ray=world_ray, buttons=MouseButton.NONE
+    )
+
+    # And show that the image did not see the event
+    # but that the view still saw the event
+    canvas.handle(event)
+    img_filter.assert_not_called()
+    view_filter.assert_called_once_with(event)