Commit de7487cf authored by André Anjos's avatar André Anjos 💬

[doc] Wrote-down better user guide

parent a57bcc00
......@@ -4,7 +4,7 @@
Annotator Guide
=================
This guide explains step by step, how to annotate images using the built-in
This guide explains how to annotate keypoints in images using the built-in
annotation app. We will use an example image from Lenna_ for this tutorial.
The annotator app is agnostic to images and can load anything that is supported
by :py:mod:`bob.io.image`.
......@@ -16,7 +16,7 @@ Image annotation
The application is launched via command-line, which means you need a command
prompt, pre-configured with the conda_ environment containing this package.
Open such prompt (e.g. via a *Terminal* application) and pass the root path
containing the image you would like to annotate:
containing the images you would like to annotate:
.. code-block:: sh
......@@ -24,18 +24,90 @@ containing the image you would like to annotate:
(myenv) $ bob annotate -vv /path/to/images /path/to/annotations
The output path, marked on the above example with ``/path/to/annotations`` is
the directory where annotated points will be written to. This path is created
if it does not exist. If it does exist, annotations are preloaded for each
image inside ``/path/to/images`` if they exist and annotation is resumed from
the point it was stopped.
The app will scan for image files with a given extension name (``.png`` by
default) on the input path provided (e.g.: ``/path/to/images``). Images will
then be sorted and displayed in alphabetical order, one after the other so you
can annotate or review their annotation. Annotations are saved to the output
directory copying the *same folder structure* found on the input path. For
example, if the images were lying like this on the input path:
Once started, you should see a window that looks like the image in
:numref:`annotate-main`.
.. _annotate-main:
.. figure:: img/annotate-main.*
:alt: Main annotation window
Main annotation window
The application scans the input folder (``/path/to/images`` in the example
above), looking for files ending in ``.png``. It loads them one by one as you
push the directional buttons on the top left of the window, under the heading
*Images*. The total number of images and the current image being edited are
shown on the window title and under this part of the application.
The other sections of the left pane show *Objects*, *Filters*, *Pointer [x,y]*
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
output files, which only preserve points and the order in which points were
annotated.
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
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
shortcut ``D`` or click on the ``del`` button.
.. warning::
The application has no undo functionality currently implemented. In case
you make a mistake, but previously saved the annotations, exit pusing the
``ESC`` button on your keyboard. This will cause the application **not** to
save any of the current image annotations.
:numref:`annotate-objects` shows an example in which the user annotated two
objects: the top of Lenna_'s hat and her face. The number of keypoints
annotated per object is variable. The current set of points being annotated is
highlit in yellow, while the sets not being updated are drawn in white. You
cannot change a set unless it is highlit. To highlight an annotation set for
edition, use ``o`` or ``O`` as indicated before, or click on the buttons on the
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,
*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
active one.
.. _annotate-objects:
.. figure:: img/annotate-objects.*
:alt: Annotating objects
Annotating objects
When you change images pushing either ``n`` or ``p``, annotations for the
current image are first saved before switching images. You do not need to push
a save button of any sort using this application. The output path, marked on
the above example with ``/path/to/annotations`` is the directory where
annotated points will be written to. This path is created if it does not
exist. If it does exist, annotations are preloaded for each image inside
``/path/to/images`` if they exist and annotation is resumed from the point it
was stopped. You may use this technique to continue your previous work, if you
quit the application.
Annotations are saved to the output directory copying the *same folder
structure* found on the input path. For example, if the images were lying like
this on the input path:
.. code-block:: text
......@@ -60,7 +132,8 @@ Annotation format
Annotations are saved in JSON_ format, which is easily readable and loadable in
a variety of programming environments. The specific format used by the
annotator application may change, but it essentially just lists annotated
points, in the order objects are created.
points, in the order objects are created. It is a list of lists, in which each
sublist contains coordinates in ``(y, x)`` format (height, width).
Zoom
......@@ -95,6 +168,19 @@ For example, to start the application with a zoom factor of ``2.0`` do:
possible precision.
Filtering
---------
The application provides a simple filtering option for images being displayed.
If you click on the CLAHE_ option, the application will apply Contrast Limited
Adaptive Histogram Equalization using
:py:func:`skimage.exposure.equalize_adapthist`. You may control the kernel
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.
Further help
------------
......@@ -106,11 +192,13 @@ app:
(myenv) $ bob annotate --help
Read the annotator application help message, which lists all known keyboard and
pointer/mouse bindings. Familiarise yourself with these shortcuts as that
improves annotation performance, reducing the time you spend annotating images.
You can check the contents of the help dialog through this documentation,
looking at the docstring of the :py:mod:`bob.ip.annotator.gui` module.
Read the annotator application help message, by clicking on the keyboard
shortcut ``?`` or the button on the left pane. The help message lists all
known keyboard and pointer/mouse bindings. Familiarise yourself with these
shortcuts as that improves annotation performance, reducing the time you spend
annotating images. You can check the contents of the help dialog through this
documentation, looking at the docstring of the :py:mod:`bob.ip.annotator.gui`
module.
.. include:: links.rst
......@@ -9,3 +9,4 @@
.. _lenna: https://en.wikipedia.org/wiki/Lenna
.. _conda: https://conda.io/en/latest/
.. _json: https://en.wikipedia.org/wiki/JSON
.. _clahe: https://en.wikipedia.org/wiki/Adaptive_histogram_equalization
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment