diff --git a/doc/concepts.rst b/doc/concepts.rst index 20029b3..d06f6ab 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -4,18 +4,18 @@ Concepts ======== -In this section, we will introduces some high-level concepts in sloth. +In this section, we will introduce some high-level concepts of 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, +can contain any number of labels. Each label is a set of key-value pairs, for example:: { - type: "rect", + class: "rect", id: "Martin", x: 10, y: 30, @@ -23,9 +23,9 @@ for example:: height: 50, } -The only required key a label *has* to have is the "type" key. It will be used by the label tool +The only required key a label *has* to have is the "class" 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 +You will later see, how you can customize the mapping between class and visualization and how to write your own visualizations. @@ -36,17 +36,18 @@ Sloth provides support for a range of standard shape labels (for example `rect`, 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. +The following simple geometric classes 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, + "class": "point", + "x": 10, + "y": 20, } Rect @@ -54,11 +55,11 @@ Rect :: { - "type": "rect", - "x": 10, - "y": 20, - "width": 20, - "height": 20, + "class": "rect", + "x": 10, + "y": 20, + "width": 20, + "height": 20, } Polygon @@ -66,46 +67,57 @@ Polygon :: { - "type": "polygon", - "xn": "10;20;30", - "yn": "20;30;40", + "class": "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:: +In many cases, it will not be sufficient for your labeling needs to stick to those simple classes. Or, +you might want to add further information. Since each label is just a set of key-value pairs, this +is easily possible by adding more key-value pairs that carry additional information. +For example you can add a key ``type`` that differentiates point labels to be either the label +for the left or the right eye of a face:: { - "type": "point", - "class": "left_eye", + "class": "point", + "type": "left_eye", x: 50, y: 40, - } + }, { - "type": "point", - "class": "right_eye", + "class": "point", + "type": "right_eye", x: 70, y: 40, } -Of course, you can also change the type:: +Of course, you can also create new classes:: { - "type": "triangle", + "class": "triangle", "x1": 10, "y1": 20, "x2": 30, "y2": 20, "x3": 20, "y3": 30, + }, + { + "class": "deathstar", + "x": 678, + "y": 890, + "z": 666, + "range": "very far", + "last_known_message": "What happens if I press *this* button?" } -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. +You see in the second example, that the label does not necessarily have to name +a geometric form of any sort. Neither do the key-value pairs have to denote +only coordinates or attributes. It can be anything you like. However, if you +create your own classes you will need to tell the label tool in the +configuration how to display this label class. See section :doc:`configuration` on how to do that. Representation is not storage @@ -113,11 +125,13 @@ 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 +very different. Sloth does not have *the one* way in which it stores the +labels on-disk. The labels could be stored as XML, as binary data or in a textual format. +In fact, the labels might not even be stored in a file, but uploaded to a web server. +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. +example to support legacy third-party label formats (for example one that comes +with a data set) without the need of converting them to JSON first. diff --git a/doc/index.rst b/doc/index.rst index cb9f6cf..216a332 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -43,12 +43,6 @@ Contents examples api/index - -TODOs -===== - -.. todolist:: - Indices and tables ================== diff --git a/doc/installation.rst b/doc/installation.rst index 3d76d4a..12155bb 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -9,8 +9,12 @@ Before you can install Sloth, make sure that you have all the prerequisites inst Prerequisites ============= -Sloth is implemented in Python and PyQt4, so it needs both. It further depends on Okapy -for image and video loading. +Sloth is implemented in `Python`_ and `PyQt4`_, so it needs both. It further depends on +either `PIL`_ or okapy for image loading. + +.. _Python: http://www.python.org +.. _PyQt4: http://www.riverbankcomputing.co.uk/software/pyqt/intro +.. _PIL: http://www.pythonware.com/products/pil/ Installing Sloth ================