[widgets] Implement smarter keypoint insertion (closes #5)

bob/ip/annotator/widgets.py

@@ -225,7 +225,7 @@ class Annotation(object):
   def _highlight_widget(self, k):
     """Highlights a given widget on the screen"""
 
-    if not self.active: return
+    if (not self.active) or (not self.point) or (k is None): return
     self._deemphasize_widgets()
     self.canvas.itemconfig(self.widget[k], fill=COLOR_ACTIVE)
 
@@ -238,7 +238,7 @@ class Annotation(object):
     annotated point.
     """
 
-    if self.active: return  #ignore
+    if self.active or (not self.point): return  #ignore
 
     self.active = True
 
@@ -289,8 +289,19 @@ class Annotation(object):
     ``(y,x)`` format
     """
 
-    return numpy.argmin(scipy.spatial.distance.cdist(self.point,
-      [unzoom_point(self.zoom, p)]))
+    if not self.point: return None
+    return self._k_closest_annotations(p, 1)[0]
+
+
+  def _k_closest_annotations(self, p, k):
+    """Returns the ``k`` closest elements to the location provided (in
+    ``(y,x)`` format)
+    """
+
+    distances = scipy.spatial.distance.cdist(self.point,
+        [unzoom_point(self.zoom, p)])[:,0]
+    if len(distances) == 1: return [0]
+    return numpy.argsort(distances)[:k]
 
 
   def insert_point(self, p):
@@ -302,7 +313,23 @@ class Annotation(object):
     # can't insert if no points are there...
     if not self.point: return
 
-    closest_point = self._closest_annotation(p)
+    # finds first and second closest points
+    closest_points = self._k_closest_annotations(p, 2)
+    closest_point = None
+    second_closest = None
+    if len(closest_points) >= 1:
+      closest_point = closest_points[0]
+    if len(closest_points) >= 2:
+      second_closest = closest_points[1]
+
+    if closest_point is None:  # no points yet, just append
+      return self.append_point(p)
+
+    if second_closest is not None:  # there are two points, choose
+      if closest_point < second_closest:
+        # the pointer is in highlighting the annotation before
+        closest_point = second_closest
+
     self.point.insert(closest_point, p)
 
     self.widget.insert(closest_point, self._make_cross(p))
@@ -417,7 +444,7 @@ class Annotation(object):
   def _remove_point(self, k):
     """Removes the active annotation"""
 
-    if not self.point:
+    if (not self.point) or (k is None):
       return
 
     self.point.pop(k)

doc/guide.rst

@@ -67,25 +67,20 @@ To annotate the image, click on the image using a mouse or trackpad.  If using
 a mouse, use its left button to append a key point to the current object being
 annotated.  Alternatively, use the ``a`` keyboard key to append a new keypoint,
 under the pointer cursor, to the active annotation set.  When you append a new
-keypoint, it becomes automatically the last keypoint on the set.  You may also
-*insert* a new keypoint **before** another existing keypoint (notice order is
+keypoint, it becomes automatically the last keypoint on the set.  Appending a
+keypoint adds it to the **end** of the current keypoint trail.  You may also
+*insert* a new keypoint between other existing keypoints (notice order is
 an important factor here).  If you wish to insert a new keypoint **before** an
 existing one, in the middle of a sequence, move the cursor so it highlights the
-closest keypoint that will come **after** the keypoint you wish to insert.
-Once you have it highlit, press ``i`` or use the ``SHIFT`` key combined with a
-left-mouse button or trackpad click.
+closest keypoint that will come before or after the keypoint you wish to
+insert.  Once you have it highlit, press ``i`` or, alternatively use the
+``SHIFT`` key combined with a left-mouse button or trackpad click.
 
-.. warning::
-
-   Currently, keypoint insertion only works this way.  If you wish to insert a
-   keypoint such that it would be closer to an existing keypoint that must come
-   before the new entry, highlight the keypoint that comes immediately after,
-   insert the keypoint using the keyboard, mouse or trackpad and then move it
-   to the desired location.
+.. tip::
 
-   To better visualize the order of keypoints, enable drawing of
-   *Decorations* by either click the check-button on the left pane or pushing
-   the keyboard key ``t``.
+   To better visualize the order of keypoints, enable drawing of *Decorations*
+   by either click the check-button on the left pane or pushing the keyboard
+   key ``t``.
 
 
 You may switch between the objects annotated using the keyboard