wassname/sloth
1
0
Fork 0
mirror of https://github.com/wassname/sloth.git synced 2026-06-27 17:17:21 +08:00
Code Issues Packages Projects Releases Wiki Activity

edit and update the documentation

Browse Source
This commit is contained in:
Martin Baeuml
2014-04-16 22:48:45 +02:00
parent bde36785b6
commit 013a2a4bc3
9 changed files with 72 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/concepts.rst
+16 -16
View File
@@ -4,7 +4,7 @@
Concepts
========
In this section, we will introduce some high-level concepts of Sloth.
We start by introducing some high-level concepts of Sloth.
Labels
@@ -15,25 +15,25 @@ can contain any number of labels. Each label is a set of key-value pairs,
for example::
{
class: "rect",
id: "Martin",
x: 10,
y: 30,
width: 40,
height: 50,
"class": "rect",
"id": "Martin",
"x": 10,
"y": 30,
"width": 40,
"height": 50,
}
The only required key a label *has* to have is the "class" key. It will be used by the label tool
The only required key a label *has* to have is the "class" key. By convention, the value of "class" is used
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 class and visualization and how to
write your own visualizations.
We will later see, how the mapping between class and visualization can be customized and how custom visualizations
can be added.
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
Sloth provides support for a range of standard shape labels (for example rectangles, points and polygons).
In order for Sloth 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 simple geometric classes are supported out of the box, i.e.
@@ -76,7 +76,7 @@ Polygon
User defined labels
-------------------
In many cases, it will not be sufficient for your labeling needs to stick to those simple classes. Or,
In many cases, labeling requirements extend beyond 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
@@ -85,12 +85,12 @@ for the left or the right eye of a face::
{
"class": "point",
"type": "left_eye",
x: 50, y: 40,
"x": 50, "y": 40,
},
{
"class": "point",
"type": "right_eye",
x: 70, y: 40,
"x": 70, "y": 40,
}
Of course, you can also create new classes::
@@ -116,7 +116,7 @@ Of course, you can also create new classes::
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
create your own classes you will need to tell the Sloth in the
configuration how to display this label class. See section :doc:`configuration` on how to do that.
doc/configuration.rst
+12 -22
View File
@@ -78,7 +78,6 @@ different keys of the dictionary in detail:
* the value for one of keys matches and the other key is not present in
either ``attributes`` or the annotation.
Note that the comma at the end of the first tuple is mandatory. Otherwise the
outer tuple will not be recognized as one (it will be only parentheses around
an object, which will alone not be translated into a tuple object. This
@@ -101,7 +100,7 @@ Default::
)
Defines global keyboard shortcuts. Each hotkey is defined by a tuple with at
least 2 entries, where the first entry is the hotkey (sequence), and the second
least two entries, where the first entry is the hotkey (sequence), and the second
entry is the function that is called. The function should expect a single
parameter, the labeltool object. The optional third entry -- if present -- is
expected to be a string describing the action.
@@ -113,11 +112,13 @@ CONTAINERS
Default::
{
'*.txt': 'annotations.container.SimpleOneLinerTextContainer',
'*.yaml': 'annotations.container.YamlContainer',
'*.pickle': 'annotations.container.PickleContainer',
}
(
('*.json', 'sloth.annotations.container.JsonContainer'),
('*.msgpack', 'sloth.annotations.container.MsgpackContainer'),
('*.yaml', 'sloth.annotations.container.YamlContainer'),
('*.pickle', 'sloth.annotations.container.PickleContainer'),
('*.sloth-init', 'sloth.annotations.container.FileNameListContainer'),
)
Defines a mapping of which container should be used for loading a label file
matching the given filename pattern. This can of course also be a user defined
@@ -132,25 +133,14 @@ container. You can also define the class directly (instead of a module path)::
PLUGINS
-------
Did not think to much about this yet. This is rather for v2.0. Could image to be able to define some kind of
plugin that might do some preprocessing on an image, e.g. detect all faces and convert them into labels.
.. _SCENE_BACKGROUND:
SCENE_BACKGROUND
----------------
A list/tuple of classes implementing the sloth plugin interface. The
classes can either be given directly or their module path be specified as string.
By default, no plugins are active.
Default::
Qt.darkGray
()
Allows to set the scene background to a custom color or pattern. Expects a QBrush. A more
complex background could be a regular box pattern which might simplify the exact resizing of
annotations that extend over image boundaries::
from PyQt4.QtGui import QBrush
from PyQt4.QtCore import Qt
SCENE_BACKGROUND = QBrush(Qt.darkGray, Qt.CrossPattern)
Extending default values
doc/containers.rst
+14 -7
View File
@@ -34,8 +34,8 @@ A container is expected to implement (at least) these five functions:
``frame_number``.
The container base class ``AnnotationContainer`` provides default
implementations for all five function. It however deferes the
parsing and serialization of the labels from/to disk to the to functions
implementations for all five function. It however defers the
parsing and serialization of the labels from/to disk to the two functions
.. py:function:: parseFromFile(self, filename)
@@ -50,9 +50,9 @@ provide implementations for those two functions.
Default Containers
==================
A few containers are included in sloth. They can be found in the module
A few containers are included in Sloth. They can be found in the module
``sloth.annotations.container``. In the default configuration, these
containers are included for their respective default filename patter.
containers are included for their respective default filename pattern.
JsonContainer
-------------
@@ -62,7 +62,6 @@ Default pattern: ``*.json``
Writes and reads annotations in JSON format (needs the python module ``json``
to be installed).
YamlContainer
-------------
@@ -71,6 +70,14 @@ Default pattern: ``*.yaml``
Writes and reads annotations in YAML format (needs the python module ``yaml``
to be installed).
MsgpackContainer
----------------
Default pattern: ``*.msgpack``
Writes and reads annotations in Msgpack format (needs the python module ``msgpack``
to be installed).
PickleContainer
---------------
@@ -87,8 +94,8 @@ Default pattern: ``*.sloth-init``
A simple container that reads one image filename per line. No annotations
are supported. This container can be used for example for initializing
a labeling session. After adding labels, another container should be
used for saving though, otherwise the labels will be lost. (write support
not implemented yet anyway)
used for saving though, otherwise the labels will be lost (write support
is not implemented).
FeretContainer
--------------
doc/first_steps.rst
+12 -10
View File
@@ -117,7 +117,7 @@ Writing a custom configuration
==============================
We already briefly touch the subject of configuration. Sloth can be easily
tailored to once labeling needs by using different label types, adding own
tailored to ones 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
@@ -175,7 +175,7 @@ different keys of the dictionary in detail:
* ``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
This can either be a fixed key-value pair. 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.
@@ -200,23 +200,25 @@ pass it to Sloth with the ``--config`` command line parameter::
sloth --config myconfig.py examples/example1_labels.json
You can now start labeling head locations and eye positions. You'll see that for each
depending on the chosen annotation, you can either insert a rectangle (this is internally
You can now start labeling head locations and eye positions. You'll see that --
depending on the chosen annotation -- you can either insert a rectangle (this is internally
done by the ``RectItemInserter``) or points (using the ``PointItemInserter``). For
each annotation you can choose an identity between the two supplied options.
each annotation you can choose an identity from 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.
There are more possibilities to configure the labels, which we have not touched here.
For example, hotkeys can be defined to quick access to often used label types.
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
behaviour can be configured there as well, e.g. for supporting custom label formats (using
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>`,
You should quickly familiarize yourself with the :doc:`basic concepts and conventions <concepts>` in Sloth.
Continue then by reading about :doc:`all available configuration options <configuration>`,
how to write your own :doc:`visualization items <items>`, :doc:`custom inserters <inserters>` or
:doc:`custom label containers <containers>`.
doc/index.rst
+2 -2
View File
@@ -25,7 +25,7 @@ Feedback
*Please* provide feedback to us on this document and Sloth in general! We won't be able
to incorporate your required features if you do not talk to us. Also, use the bug tracker
at https://github.com/cvhciKIT/sloth/issues. Of course, similarly welcome are patches!
at https://github.com/cvhciKIT/sloth/issues. Of course, pull requests are always welcome!
Contents
========
@@ -34,8 +34,8 @@ Contents
:maxdepth: 2
installation
concepts
first_steps
concepts
configuration
items
inserters
doc/inserters.rst
+1 -1
View File
@@ -7,4 +7,4 @@ Inserters
Inserters are used for creating new labels interactively. When the users selects a label type in the button area,
the corresponding inserter for the label type (as defined in the :ref:`configuration`).
.. todo:: Write this. It's pretty similar to the items section.
.. todo:: Write this. It's pretty similar to the items section. Pull requests are welcome!
doc/installation.rst
+1 -2
View File
@@ -16,7 +16,7 @@ either `PIL`_ or okapy for image loading.
.. _PyQt4: http://www.riverbankcomputing.co.uk/software/pyqt/intro
.. _PIL: http://www.pythonware.com/products/pil/
To use okapy, make sure to make it's modules known to python, e.g. add
To use okapy, make sure to make its modules known to python, e.g. add
<okapibuild>/python/ to the PYTHONPATH environment variable::
export PYTHONPATH=<okapibuild>/python/:$PYTHONPATH
@@ -26,7 +26,6 @@ For compiling the docs, `Python Sphinx`_ is needed.
.. _Python Sphinx: http://pypi.python.org/pypi/Sphinx
Installing Sloth
================
doc/items.rst
+13 -3
View File
@@ -23,10 +23,20 @@ The label tool comes with a few predefined visualization items:
- ``items.PolygonItem``
Draws a rectangle. Expects the label to have keys ``xn`` and ``yn``, which are ``;``-separated
Draws a polygon. Expects the label to have keys ``xn`` and ``yn``, which are ``;``-separated
lists of point coordinates.
The predefined items can be used in different ways. If you give the class name in
- ``items.IDRectItem``
Extends ``RectItem``. Displays the value of ``id`` within the rectangle as text.
When an item is selected, the hotkey ``i`` can be used to cycle between numerical id values.
- ``items.OccludablePointItem``
Extends ``PointItems``. Draws the point in a different color (red) when the value of ``occluded`` is ``True``.
The hotkey ``o`` is defined to toggle the ``occluded`` property.
The predefined items can be used in different ways. If you specify the class name in
the configuration, the constructor will be called for initializing the item. However,
you can also create and instance of the item, configure for example the color, and then
use this instance in the configuration. The predefined items have their ``__call__`` operator
@@ -88,7 +98,7 @@ set the graphics items flags to allow interactive modfications of the item::
QGraphicsItem.ItemSendsGeometryChanges | \
QGraphicsItem.ItemSendsScenePositionChanges)
Then we catch the notifications about item changes by overriding ``ìtemChange``. We especially need
By overriding ``ìtemChange`` we get notified about item changes, such as a position change. Especially, we need
to inform the model about the modification::
def itemChange(self, change, value):
sloth/annotations/container.py
+1
View File
@@ -81,6 +81,7 @@ class AnnotationContainer:
self.clear()
def filename(self):
"""The current filename."""
return self._filename
def clear(self):