Merge branch 'decoration-button' into 'master'

Decoration button

See merge request !10

bob/ip/annotator/gui.py

@@ -37,7 +37,7 @@ Keyboard shortcuts
   object
 
 ``i | <Shift>-Zero | <Shift>-KP_Zero``
-  inserts new point on a currently active object, before the current active
+  inserts new point on a currently active object, **before** the current active
   point
 
 ``d | <Del>``
@@ -68,6 +68,18 @@ Keyboard shortcuts
 ``p``
   moves to the previous image
 
+``t``
+  turns-on keypoint decoration (lines or polygon depending on current mode)
+
+``T``
+  turns-off keypoint decoration
+
+``f``
+  turns-on image filtering
+
+``F``
+  turns-off image filtering
+
 ``s``
   saves current annotations
 
@@ -203,7 +215,6 @@ class AnnotatorApp(tkinter.Tk):
     # setup internal variables
     self.curr_annotation = None #the currently annotated object
     self.annotation = [] #annotations existing on the current image
-    self.filter = False
 
     # builds the application interface - buttons, frames and the image canvas
     self.frames = {}
@@ -290,19 +301,29 @@ class AnnotatorApp(tkinter.Tk):
         text='Displays the number of annotated points in the current ' \
             'object being annotated (highlit)')
 
+    v = self.variables['decorations'] = tkinter.IntVar()
+    v.set(0)
+    b = self.buttons['decorations'] = tkinter.ttk.Checkbutton(f,
+        text="Decorations", variable=v, command=self.toggle_decorations)
+    b.grid(row=5, columnspan=2, sticky=tkinter.NSEW)
+    self.tooltips['decorations'] = widgets.Tooltip(b,
+        text='Shows line connectors or polygon fills depending on the ' \
+            'current drawing mode (keyboard: t/T - on/off)')
+
+
     f = self.frames['filters'] = tkinter.ttk.LabelFrame(self.frames['left'],
         text="Filters")
     f.grid(row=2, sticky=tkinter.NSEW)
 
     v = self.variables['adaheq'] = tkinter.IntVar()
     v.set(0)
-    b = self.buttons['adaheq'] = tkinter.ttk.Checkbutton(f,
-        text="CLAHE", command=self.toggle_filter, variable=v)
+    b = self.buttons['adaheq'] = tkinter.ttk.Checkbutton(f, text="CLAHE",
+        variable=v, command=self.toggle_filter)
     b.grid(row=0, columnspan=3, sticky=tkinter.W)
     self.tooltips['adaheq'] = widgets.Tooltip(b,
         text='Applies Contrast Limited Adaptive Histogram Equalization ' \
             '(CLAHE) to the displayed image. You can finetune parameters ' \
-            'on the text boxes below')
+            'on the text boxes below (keyboard: f/F - on/off)')
 
     v = self.variables['adaheq-kernel-size'] = tkinter.IntVar()
     v.set(18)
@@ -373,7 +394,7 @@ class AnnotatorApp(tkinter.Tk):
 
     # setup filter function
     filter_function = None
-    if self.filter:
+    if self.variables['adaheq'].get():
 
       def _clahe(img, kernel, clip):
         nimg = numpy.array(img)
@@ -467,6 +488,12 @@ class AnnotatorApp(tkinter.Tk):
     # sets the zoom level
     self.variables['zoom'].set('%g' % self.zoom)
 
+    # if decorations are to be shown, set them
+    if self.variables['decorations'].get():
+      self.on_show_all()
+    else:
+      self.on_hide_all()
+
 
   def save(self, *args, **kwargs):
     """Action executed when we need to save the current annotations"""
@@ -608,17 +635,28 @@ class AnnotatorApp(tkinter.Tk):
     self.create_new_annotation()  # adds a new base annotation object
 
 
-  def on_show_all(self, event):
+  def toggle_decorations(self, *args):
+    """Toggles current decoration status"""
+
+    if self.variables['decorations'].get():
+      self.on_show_all()
+    else:
+      self.on_hide_all()
+
+
+  def on_show_all(self, event=None):
     """Shows all elements"""
 
     logger.debug('Showing all...')
+    self.variables['decorations'].set(1)
     for k in self.annotation: k.show_decoration()
 
 
-  def on_hide_all(self, event):
+  def on_hide_all(self, event=None):
     """Hides all elements"""
 
     logger.debug('Hiding all...')
+    self.variables['decorations'].set(0)
     for k in self.annotation: k.hide_decoration()
 
 
@@ -680,15 +718,24 @@ class AnnotatorApp(tkinter.Tk):
     self._update_status()
 
 
-  def toggle_filter(self, event=None):
+  def toggle_filter(self, *args):
     """Togglers filter/no-filter on the displayed image"""
 
-    if self.filter:
-      self.filter = False
-      self._rebuild_interface()
-    else:
-      self.filter = True
-      self._rebuild_interface()
+    self._rebuild_interface()
+
+
+  def turn_filter_on(self, event=None):
+    """Turns filtering on"""
+
+    self.variables['adaheq'].set(1)
+    self._rebuild_interface()
+
+
+  def turn_filter_off(self, event=None):
+    """Turns filtering off"""
+
+    self.variables['adaheq'].set(0)
+    self._rebuild_interface()
 
 
   def _add_bindings(self):
@@ -713,6 +760,10 @@ class AnnotatorApp(tkinter.Tk):
       self.bind("<Button-3>", self.remove_point_from_active_annotation)
       self.bind("c", self.create_new_annotation)
 
+    self.bind("f", self.turn_filter_on)
+    self.bind("F", self.turn_filter_off)
+    self.bind("t", self.on_show_all)
+    self.bind("T", self.on_hide_all)
     self.bind("o", self.activate_next_annotation)
     self.bind("O", self.activate_previous_annotation)
     self.bind("m", self.toggle_active_annotation_mode)

doc/guide.rst

@@ -45,19 +45,50 @@ and, finally *Help*.  The *Objects* section show how many objects have been
 annotated on the image.  You may annotate any number of objects in each image.
 Each annotation is just a set of points clicked on the screen.  The sequence in
 which the points are clicked is preserved.  By pressing the ``ALT`` key on your
-keyboard (any of the two normally available), the application draws on the
-screen either a line or polygon connecting such dots so you can better
-visualize annotated objects.  The choice between drawing a line or polygon on
-connecting annotated objects can be selected using the button that says *mode*
-on the left pane.  You may optionally press the keyboard shortcut ``m`` to
-switch modes.  Notice that lines and polygons drawn at the screen are drawn
-only for informational purposes - such information is not recorded to the
+keyboard (any of the two normally available), the application *temporarily*
+draws on the screen either a line or polygon connecting such dots so you can
+better visualize annotated objects.  The choice between drawing a line or
+polygon on connecting annotated objects can be selected using the button that
+says *mode* on the left pane.  You may optionally press the keyboard shortcut
+``m`` to switch modes.  Notice that lines and polygons drawn at the screen are
+drawn only for informational purposes - such information is not recorded to the
 output files, which only preserve points and the order in which points were
 annotated.
 
+.. tip::
+
+   By using the check-button "Decorations" on the left pane, you may switch ON
+   or OFF the drawing of line/polygon connectors on the screen.  The keyboard
+   shortcuts ``t`` and ``T`` can be used to switch ON or OFF this functionality
+   as well.
+
+
 To annotate the image, click on the image using a mouse or trackpad.  If using
-a mouse, use its left button to add a key point to the current object being
-annotated.  You may switch between the objects annotated using the keyboard
+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
+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.
+
+.. 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.
+
+   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
 shortcuts ``o`` (next) or ``O`` (previous), or use the pane on the left.  If
 you'd like to annotate a new object on the current image, click on ``create``
 or use the keyboard shortcut ``c``.  To delete an object use the keyboard
@@ -81,11 +112,11 @@ the left pane.  Once an annotation set is highlit (in yellow), a single
 keypoint will be indicated in red - that is the *active* keypoint.  Keyboard
 commands apply only to the active keypoint.  To delete a single keypoint, use
 the ``d`` keyboard shortcut, or the right-button of your mouse.  To do so,
-first select the keypoint by simply approaching it with your mouse pointer,
+first select the keypoint by simply approaching it with your pointer cursor,
 *without* clicking.  Once you get close enough, the point of interest becomes
 red.  Once the point is red, you may delete it using the ``d`` keyboard
 shortcut.  You may also move the point using the arrow keys on your keyboard.
-The point from the current active set closest to the pointer is always the
+The point from the current active set closest to the cursor is always the
 active one.
 
 .. _annotate-objects:
@@ -202,7 +233,8 @@ Adaptive Histogram Equalization using
 size and clipping parameters using the text boxes under the filter heading.  If
 the filter is already on, and you wish to change its parameters, then click it
 off and then on back again.  Once the filter is active, it will remain active
-for the next images as well.
+for the next images as well.  Alternatively use the keyboard shortcuts ``f`` to
+toggle the filter ON or ``F`` to toggle it off.
 
 
 Further help