From 3ff1393294fdad308d62bb44d398e46723fb0a42 Mon Sep 17 00:00:00 2001 From: Martin Baeuml Date: Sun, 11 Dec 2011 19:19:24 +0100 Subject: [PATCH] update documentation --- doc/first_steps.rst | 159 +++++++++++++++++++++++++++++++------------- doc/index.rst | 2 +- 2 files changed, 112 insertions(+), 49 deletions(-) diff --git a/doc/first_steps.rst b/doc/first_steps.rst index 4c0d603..c3850e0 100644 --- a/doc/first_steps.rst +++ b/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 ` for the full +reference of all configuration options. + Next steps ========== You can now continue by reading about :doc:`all available configuration options `, -how to write your own :doc:`visualization items ` or how to write :doc:`custom inserters `. +how to write your own :doc:`visualization items `, :doc:`custom inserters ` or +:doc:`custom label containers `. diff --git a/doc/index.rst b/doc/index.rst index 216a332..391fc58 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -33,8 +33,8 @@ Contents .. toctree:: :maxdepth: 2 - concepts installation + concepts first_steps configuration items