add callback system

Author: ianhi

docs/examples/callbacks.py

@@ -0,0 +1,51 @@
+"""
+---------
+Callbacks
+---------
+
+Demonstration of how to set up callback functions.
+
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from typing import Tuple
+from mpl_point_clicker import clicker
+
+from pathlib import Path
+
+image = np.load(Path(__file__).parent / "example_image.npy")
+
+fig, ax = plt.subplots()
+ax.imshow(image, cmap='gray')
+klicker = clicker(ax, ['cells', 'pdms', 'media'], markers=['o', 'x', '*'])
+
+
+def class_changed_cb(new_class: str):
+    print(f'The newly selected class is {new_class}')
+
+
+def point_added_cb(position: Tuple[float, float], klass: str):
+    x, y = position
+    print(f"New point of class {klass} added at {x=}, {y=}")
+
+
+def point_removed_cb(position: Tuple[float, float], klass: str, idx):
+    x, y = position
+
+    suffix = {1: 'st', 2: 'nd', 3: 'rd'}.get(idx, 'th')
+    print(
+        f"The {idx}{suffix} point of class {klass} with position {x=:.2f}, {y=:.2f}  was removed"
+    )
+
+
+klicker.on_class_changed(class_changed_cb)
+klicker.on_point_added(point_added_cb)
+klicker.on_point_removed(point_removed_cb)
+
+
+plt.show()
+
+
+print(klicker.get_positions())

examples/callbacks.py

@@ -0,0 +1,51 @@
+"""
+---------
+Callbacks
+---------
+
+Demonstration of how to set up callback functions.
+
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from typing import Tuple
+from mpl_point_clicker import clicker
+
+from pathlib import Path
+
+image = np.load(Path(__file__).parent / "example_image.npy")
+
+fig, ax = plt.subplots()
+ax.imshow(image, cmap='gray')
+klicker = clicker(ax, ['cells', 'pdms', 'media'], markers=['o', 'x', '*'])
+
+
+def class_changed_cb(new_class: str):
+    print(f'The newly selected class is {new_class}')
+
+
+def point_added_cb(position: Tuple[float, float], klass: str):
+    x, y = position
+    print(f"New point of class {klass} added at {x=}, {y=}")
+
+
+def point_removed_cb(position: Tuple[float, float], klass: str, idx):
+    x, y = position
+
+    suffix = {1: 'st', 2: 'nd', 3: 'rd'}.get(idx, 'th')
+    print(
+        f"The {idx}{suffix} point of class {klass} with position {x=:.2f}, {y=:.2f}  was removed"
+    )
+
+
+klicker.on_class_changed(class_changed_cb)
+klicker.on_point_added(point_added_cb)
+klicker.on_point_removed(point_removed_cb)
+
+
+plt.show()
+
+
+print(klicker.get_positions())

mpl_point_clicker/_clicker.py

@@ -10,6 +10,7 @@
 
 import numpy as np
 from matplotlib.backend_bases import MouseButton
+from matplotlib.cbook import CallbackRegistry
 
 
 class clicker:
@@ -100,6 +101,7 @@ class in *classes*
         self._fig.canvas.mpl_connect("pick_event", self._on_pick)
         self._positions = {c: [] for c in self._classes}
         self._update_legend_alpha()
+        self._observers = CallbackRegistry()
 
     def get_positions(self, copy=True):
         return {k: np.asarray(v) for k, v in self._positions.items()}
@@ -114,6 +116,7 @@ def _on_pick(self, event):
             return
         self._current_class = klass
         self._update_legend_alpha()
+        self._observers.process('class-changed', klass)
 
     def _update_legend_alpha(self):
         for c in self._classes:
@@ -122,13 +125,25 @@ def _update_legend_alpha(self):
                 a.set_alpha(alpha)
         self._fig.canvas.draw()
 
+    def _has_cbs(self, name):
+        """return whether there are callbacks registered for the current class"""
+        try:
+            return len(self._observers.callbacks[name]) > 0
+        except KeyError:
+            return False
+
     def _clicked(self, event):
         if not self._fig.canvas.widgetlock.available(self):
             return
         if event.inaxes is self.ax:
             if event.button is MouseButton.LEFT:
                 self._positions[self._current_class].append((event.xdata, event.ydata))
                 self._update_points(self._current_class)
+                self._observers.process(
+                    'point-added',
+                    (event.xdata, event.ydata),
+                    self._current_class,
+                )
             elif event.button is MouseButton.RIGHT:
                 pos = self._positions[self._current_class]
                 if len(pos) == 0:
@@ -139,8 +154,14 @@ def _clicked(self, event):
                     axis=-1,
                 )
                 idx = np.argmin(dists[0])
-                pos.pop(idx)
+                removed = pos.pop(idx)
                 self._update_points(self._current_class)
+                self._observers.process(
+                    'point-removed',
+                    removed,
+                    self._current_class,
+                    idx,
+                )
 
     def _update_points(self, klass=None):
         if klass is None:
@@ -154,3 +175,57 @@ def _update_points(self, klass=None):
                 new_off = np.zeros([0, 2])
             self._lines[c].set_data(new_off.T)
         self._fig.canvas.draw()
+
+    def on_point_added(self, func):
+        """
+        Connect *func* as a callback function to new points being added.
+        *func* will receive the the position of the new point as a tuple (x, y), and
+        the class of the new point.
+
+        Parameters
+        ----------
+        func : callable
+            Function to call when a point is added.
+
+        Returns
+        -------
+        int
+            Connection id (which can be used to disconnect *func*).
+        """
+        return self._observers.connect('point-added', lambda *args: func(*args))
+
+    def on_point_removed(self, func):
+        """
+        Connect *func* as a callback function when points are removed.
+        *func* will receive the the position of the new point, the class of the removed point,
+        the point's index in the old list of points of that class, and the updated dictionary of
+        all points.
+
+        Parameters
+        ----------
+        func : callable
+            Function to call when a point is removed
+
+        Returns
+        -------
+        int
+            Connection id (which can be used to disconnect *func*).
+        """
+        return self._observers.connect('point-removed', lambda *args: func(*args))
+
+    def on_class_changed(self, func):
+        """
+        Connect *func* as a callback function when the current class is changed.
+        *func* will receive the new class.
+
+        Parameters
+        ----------
+        func : callable
+            Function to call when *set_positions* is called.
+
+        Returns
+        -------
+        int
+            Connection id (which can be used to disconnect *func*).
+        """
+        self._observers.connect('class-changed', lambda klass: func(klass))