.. highlight:: python

========
Concepts
========

In this section, we will introduces some high-level concepts in sloth.


Labels
------

Sloth is designed for labeling a set of images or videos.  Each image, or video frame,
can contain any number of labels.  The labels itself are represented as key-value pairs,
for example::

    {
        type:   "rect",
        id:     "Martin",
        x:      10,
        y:      30,
        width:  40,
        height: 50,
    }

The only required key a label *has* to have is the "type" key.  It will be used by the label tool
to determine the appropriate visualization for this label (in our example it will draw a rectangle).
You will later see, how you can customize the mapping between type and visualization and how to
write your own visualizations.


Label type conventions
----------------------

Sloth provides support for a range of standard shape labels (for example `rect`, `point`, `polygon` etc.).
In order for the label tool to correctly visualize these labels, the labels have to follow
a convention, which keys represent the `x`- and `y`-coordinates, `width` and `height` and so on.

The following types are supported out of the box, i.e. corresponding visualization items
and inserters will be avaible in the default configuration.

Point
.....
::

    {
        "type": "point",
        "x":    10,
        "y":    20,
    }

Rect
....
::

    {
        "type":   "rect",
        "x":      10,
        "y":      20,
        "width":  20,
        "height": 20,
    }

Polygon
.......
::

    {
        "type":   "polygon",
        "xn":     "10;20;30",
        "yn":     "20;30;40",
    }


User defined labels
-------------------

In many cases, it will not be sufficient for your labeling needs to stick to those simple types.  Or
your might want to add further information.  Since each label is just a set of key-value pairs, this
is easily possible.  For example, by adding an additional ``class`` key, denoting that these points
are the left and right eye, respectively::

    {
        "type": "point",
        "class": "left_eye",
        x: 50, y: 40,
    }
    {
        "type": "point",
        "class": "right_eye",
        x: 70, y: 40,
    }

Of course, you can also change the type::

    {
        "type": "triangle",
        "x1": 10,
        "y1": 20,
        "x2": 30,
        "y2": 20,
        "x3": 20,
        "y3": 30,
    }

However, if you do this you will need to tell the label tool in the
configuration how to display this type as well.  See section
:doc:`configuration` on how to do that.


Representation is not storage
-----------------------------

In the sections above we introduced the labels as sets of key-value pairs with
a textual representation.  The storage on disk of the labels however can be
very different.  Sloth does not have *the one* way in which way to store the
labels.  Again, there are some default formats which the label tool can deal
with out of the box (among others YAML and JSON, which resemble the textual
representation above).  However, you are free to define your own loading and
saving routines for your labels (see :doc:`containers`). This allows you for
example to support legacy third-party label formats without the need of
converting them to JSON first.

