sloth/doc/first_steps.rst

.. highlight:: python

===========
First Steps
===========

In this section, you will learn with a simple example, how to load labels and write a simple configuration file.
The full configuration options will be covered in the next section :doc:`configuration`.

Using the default configuration
===============================

The easiest way to start is using a supported label format, and supported label types only.  In this case
we just need to start the label tool and supply the label file on the command line::

    ./labeltool.py examples/examplelabels.txt

Let's take look at the example label file::

    image1.jpg type rect x 50 y 80 width 20 height 20 type rect x 50 y 80 width 20 height 80
    image2.jpg type point x 70 y 80

We have labeled two images, with two rectangles in image1 and one point in image 2.  Since we did not launch
the label tool with a custom configuration, the standard visualizations for rect and point will be used. The
label tool displays the two given image, and draw two rectangle at the labeled position in image1, and a
point in image2.

Writing a custom configuration
==============================

The configuration file is a python module where the module-level variables represent the settings.  The
most important variables are

* :ref:`ITEMS`:     This defines how a given label is visualized by the label tool.
* :ref:`LABELS`:    This defines *which* new labels can be created interactively by the user.
* :ref:`INSERTERS`: This defines *how* new labels are created by the user.

We start with a quick example::

    ITEMS = {
        'rect':  'items.RectItem',
        'point': 'items.PointItem',
        'bbox':  'items.RectItem',
    }

    LABELS = (
        ("Rect",          {"type":  "rect",
                           "class": "head",
                           "id":    ["Martin", "Mika"]}),
        ("Bounding Box",  {"type":  "bbox",
                           "class": "body",
                           "id":    ["Martin", "Mika"]}),
    )

In ``ITEMS`` we specify that all labels of type ``rect`` will be visualized by the class ``items.RectItem``
(which is one of the predefined visualization items that comes with the label tool).  All labels of type
``point`` will be visualized by ``items.PointItem``.  Note that we can use any type basically.  The type 
``bbox`` will also be visualized by a ``items.RectItem``.

In ``LABELS`` we defined which `new` labels the user can create with the label tool.  The variable is
expected to be a list/tuple of tuples.  Each of the inner tuples contains first a description of the
label (this will be on the button displayed to the user), and the a description of the label to be 
created.  In our case, we create a label of type ``rect`` if the user hits the ``Rect`` button.  Further,
the newly created label will have the class ``head`` (which is fixed), and the user can choose between
one of the ids from the given list.

Similarly, the user now can create Bounding Box labels of type ``bbox`` with class ``body``.

There is a difference between the visualization items and the way the labels are created by the user 
interactively.  For example, the label tool does *not* know out of the box how to create a label of
type ``bbox``.  We have to explicitly specify how to insert this type.  We can do this by setting
the ``INSERTERS`` variable::

    INSERTERS = {
        'rect':  'items.inserters.RectItemInserter',
        'bbox':  'items.inserters.RectItemInserter',
    }

The ``RectItemInserter`` lets the user draw a rectangle with the mouse, and then sets the ``x``,
``y``, ``width`` and ``height`` members of the label accordingly.  By mapping the type ``bbox``
to ``RectItemInserter``, the user will be able to draw a rectangle each time a new Bounding Box
label is created.  Note that we also have to add the ``RectItemInserter`` for the type ``rect``
as well (which would also be in the default configuration)  due to the fact that we override
the ``INSERTERS`` variable completely.  Otherwise the label tool would not know anymore, how
to insert labels of type ``rect``.

In order to extend the default configuration and avoid overriding the default values, you can
first import the default configuration and then append your custom mappings (remember that
the configuration is a python module, you can basically execute any valid python code)::

    from conf.default_configuration import INSERTERS
    INSERTERS['bbox'] = 'items.inserters.RectItemInserter'

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>`.