update documentation

doc/first_steps.rst

@@ -11,63 +11,116 @@ covered in the next section :doc:`configuration`.
 Using the default configuration
 ===============================
 
-The easiest way to start sloth is by using a supported label format and
-supported label types only.  In this case we just need to start sloth and
-supply the label file on the command line::
+The easiest way to start Sloth is by using a supported label format and
+supported label types only.  In that case we just need to start Sloth and
+supply the label file as parameter on the command line::
 
     sloth examples/example1_labels.json
 
+``example1_labels.json`` comes with Sloth in the example directory for you
+to try out directly.  Once the label file is loaded, Sloth should look
+somewhat similar to the following image.
+
+.. image:: _static/example_labels_gui.png
+    :width: 100%
+
 Let's take look at the example label file::
 
     [
         {
-            "type": "image", 
+            "class": "image",
+            "filename": "image1.jpg",
             "annotations": [
                 {
+                    "class": "rect",
                     "height": 60.0, 
                     "width": 46.0, 
                     "y": 105.0, 
-                    "x": 346.0, 
-                    "type": "rect"
+                    "x": 346.0
                 }, 
                 {
+                    "class": "rect",
                     "height": 58.0, 
                     "width": 56.0, 
                     "y": 119.0, 
-                    "x": 636.0, 
-                    "type": "rect"
+                    "x": 636.0
                 }
-            ], 
-            "filename": "image1.jpg"
+            ] 
         }, 
         {
-            "type": "image", 
+            "class": "image", 
+            "filename": "image2.jpg",
             "annotations": [
                 {
+                    "class": "point",
                     "y": 155.0, 
-                    "x": 409.0, 
-                    "type": "point"
+                    "x": 409.0
                 }
-            ], 
-            "filename": "image2.jpg"
+            ] 
         }
     ]
 
-We have labeled two images, with two rectangles in image1 and one point in
-image 2.  Since we launched sloth without a custom configuration, the standard
-visualizations for ``rect`` and ``point`` will be used. Sloth displays two
-rectangles at the labeled positions in image1, and a point in image2.
+We have labeled two images with filenames ``image1.jpg`` and ``image2.jpg``,
+with two rectangles in image 1 and one point in image 2.  Since we launched
+Sloth without a custom configuration, the standard visualizations for ``rect``
+and ``point`` will be used. Sloth displays two rectangles at the labeled
+positions in image1, and a point in image2.
 
-Adding and editing annotation in the GUI
-========================================
 
-TODO
+Adding and editing annotations in the GUI
+=========================================
+
+Editing existing annotations
+----------------------------
+
+Let's start by editing existing labels.  There are several ways in which 
+existing labels can be modified.  You first need to select the label which
+you want to modify.  You can do this by clicking on the label, e.g. in our
+example label file you can click somewhere inside the area of one of the
+rectangles in image 1.  The label outline changes to a dashed line, indicating
+that is has been selected.  Another way to select labels is to press the TAB-key
+multiple times.  This cycles the selection through all labels in the current
+image. Here too, the currently selected item is indicated by a dashed outline.
+
+Once the label is selected, we can modify its position dragging the item to its
+new location while holding the left mouse button down.  This applies to both
+rectangle and point labels.
+
+In order to modify the width and height of the rectangle, you can click inside
+the rectangle with the right mouse button and drag while holding down the right
+mouse button.  This changes the width and height of the rectangle.
+
+We strongly belief that in many cases a labeling task can be carried out more
+efficiently by using the keyboard instead of the mouse.  Therefore, the
+builtin standard label items can all be modified using the keyboard only.
+
+The position of a label item can be modified with the LEFT, RIGHT, UP and DOWN
+keys with pixel-accuracy.  If you hold down the SHIFT-key, the step size is
+increased to 5-pixel steps.
+
+The width and height of a rectangle can further be modified by holding down the
+CTRL-key, and then using the LEFT, RIGHT, UP and DOWN buttons, respectively.
+Again, holding in addition also the SHIFT key increases the step size to 5 pixels
+
+Adding new annotations
+----------------------
+
+For each of the label types, there is a button in the Properties dock (by default
+on the left of the window).  Click on this button to change into *insert*-mode.
+You will now be able to add new label item by clicking and drawing on the current
+image.
+
+The insert-mode for a particular label type can also be activated by a hotkey.
+The standard hotkeys for rectangle labels is ``r``, and for point labels ``p``.
 
 Writing a custom configuration
 ==============================
 
-The configuration file is a python module where the module-level variables
-represent the settings.  The most important variable is
+We already briefly touch the subject of configuration.  Sloth can be easily
+tailored to once labeling needs by using different label types, adding own
+visualization items and container formats.  All of this can be specified in the
+configuration file.  The configuration file is a python module where the
+module-level variables represent the settings.  The most important variable is
 
 * :ref:`LABELS`:    This defines how sloth will display annotations and how the
   user can insert new ones.
@@ -80,7 +133,7 @@ We start with a quick example::
                         "id":    ["Martin", "Mika"]},
          "item":     "sloth.items.RectItem",
          "inserter": "sloth.items.RectItemInserter",
-         "text:      "Head"
+         "text":     "Head"
         },
 
         {"attributes": {"type":  "point",
@@ -88,7 +141,7 @@ We start with a quick example::
                         "id":    ["Martin", "Mika"]},
          "item":     "sloth.items.PointItem",
          "inserter": "sloth.items.PointItemInserter",
-         "text:      "Left Eye"
+         "text":     "Left Eye"
         },
 
         {"attributes": {"type":  "point",
@@ -96,53 +149,54 @@ We start with a quick example::
                         "id":    ["Martin", "Mika"]},
          "item":     "sloth.items.PointItem",
          "inserter": "sloth.items.PointItemInserter",
-         "text:      "Right Eye"
+         "text":     "Right Eye"
         },
     )
 
-``LABELS`` is a tuple/list of dictionaries.  Each dictionary describe how one
-annotation type is visualized, newly inserted and modified.  Let's go over the
+``LABELS`` is a tuple/list of dictionaries.  Each dictionary describes how one
+annotation type is (i) inserted, (ii) visualized and (iii) modified.  Let's go over the
 different keys of the dictionary in detail:
 
 * ``text``:  This is a text that describes the label type, and will be
-  displayed to the user in the GUI.
+  used as label description in the Properties dock.
 
 * ``item`` specifies which class is responsible for visualizing the annotation.
-  For the first annotation type we chose to use the predefined
-  ``sloth.items.RectItem`` class, which will draw a rectangle as given by the
+  For the first annotation type in our example, the predefined
+  ``sloth.items.RectItem`` class is used, which will draw a rectangle as given by the
   coordinates in the annotation.  Sloth comes with several predefined
   visualization classes, such as ``sloth.items.RectItem`` and
   ``sloth.items.PointItem`` (see :ref:`items` for a full list).  However, it is
   also very easy to define your own visualization class (see :ref:`items`).
 
 * ``inserter`` specifies which class is responsible for creating new
-  annotations based on user input.  When the user enters insert mode with a
-  given label type, the corresponding inserter is instantiated and captures all
-  user input for the creation of a new annotation.  The inserter is passed the
-  current state of the button area.
+  annotations based on user input.  When the user enters insert-mode with a
+  given label type, the corresponding inserter is captures all
+  user input and takes care of the creation of a new annotation.
 
-* ``attributes`` has three functions:
-  1. It defines how a new annotation can be initialized.  Fixed
-     key-value pairs are used directly.  If the value is a list of items, the
-     user can choose interactively which one of the values he wants to use for
-     a new label.  The current state is then passed to the inserter.
+* ``attributes`` has three purposes:
+  1. It defines which key-values pairs are inserted into a new annotation directly.
+     This can either be a fixed key-value pair.  Or, if the value is a list of
+     items, the user can choose interactively in the Properties dock which one
+     of the values he wants to use for a new label.  The current state is then
+     passed to the inserter.
 
   2. It defines how a existing annotations can be edited.  Fixed
-     key-value are not allowed to be edited.  If the value is a list of items, the
-     user can choose interactively between the values for the corresponding key.
-     The annotation is then updated accordingly.
+     key-value pairs, are not allowed to be edited.  If the value for a given
+     key is a list of items, the user can choose interactively between the
+     values for the corresponding key.  The annotation is then updated
+     accordingly.
 
   3. It defines how to match an existing annotation to one of the entries in ``LABELS``.
      Sloth uses a soft matching based on the two keys ``class`` and ``type``.  It checks
      each item in ``LABELS`` starting from the beginning and stops if it finds the first
      match.  An entry matches an annotation if:
 
-       * the values for both keys match, or
+       * the values for both the ``class`` and ``type`` keys match, or
        * the value for one of keys matches and the other key is not present in
          either ``attributes`` or the annotation.
 
-You need to save your custom configuration in a file ending with ".py".  To use it
-pass it to sloth using the ``--config`` command line parameter::
+You need to save your custom configuration in a file ending with ``.py``.  To use it,
+pass it to Sloth with the ``--config`` command line parameter::
 
     sloth --config myconfig.py examples/example1_labels.json
 
@@ -151,9 +205,18 @@ depending on the chosen annotation, you can either insert a rectangle (this is i
 done by the ``RectItemInserter``) or points (using the ``PointItemInserter``).  For
 each annotation you can choose an identity between the two supplied options.
 
+There are more possibilities to configure the labels, e.g. defining hotkeys, which we
+have not touched here.  Refer to :ref:`LABELS` for the full documentation.
+
+Apart from defining the supported labels in the configuration, other parts of Sloth's
+behaviour can be configured there as well, e.g. for supporting own label formats with
+custom containers.  See :doc:`Configuration <configuration>` for the full
+reference of all configuration options.
+
 Next steps
 ==========
 
 You can now continue by reading about :doc:`all available configuration options <configuration>`,
-how to write your own :doc:`visualization items <items>` or how to write :doc:`custom inserters <inserters>`.
+how to write your own :doc:`visualization items <items>`, :doc:`custom inserters <inserters>` or
+:doc:`custom label containers <containers>`.
 

doc/index.rst

@@ -33,8 +33,8 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   concepts
    installation
+   concepts
    first_steps
    configuration
    items