From 013a2a4bc30fee83143c4f79b53a223ff6f97fb2 Mon Sep 17 00:00:00 2001 From: Martin Baeuml Date: Wed, 16 Apr 2014 22:48:45 +0200 Subject: [PATCH] edit and update the documentation --- doc/concepts.rst | 32 ++++++++++++++++---------------- doc/configuration.rst | 34 ++++++++++++---------------------- doc/containers.rst | 21 ++++++++++++++------- doc/first_steps.rst | 22 ++++++++++++---------- doc/index.rst | 4 ++-- doc/inserters.rst | 2 +- doc/installation.rst | 3 +-- doc/items.rst | 16 +++++++++++++--- sloth/annotations/container.py | 1 + 9 files changed, 72 insertions(+), 63 deletions(-) diff --git a/doc/concepts.rst b/doc/concepts.rst index d06f6ab..c2e51bc 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -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. diff --git a/doc/configuration.rst b/doc/configuration.rst index 8452060..c8cfbce 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -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 diff --git a/doc/containers.rst b/doc/containers.rst index f811a28..459cf4b 100644 --- a/doc/containers.rst +++ b/doc/containers.rst @@ -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 -------------- diff --git a/doc/first_steps.rst b/doc/first_steps.rst index c3850e0..77604d9 100644 --- a/doc/first_steps.rst +++ b/doc/first_steps.rst @@ -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 ` for the full +behaviour can be configured there as well, e.g. for supporting custom label formats (using +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 `, +You should quickly familiarize yourself with the :doc:`basic concepts and conventions ` in Sloth. +Continue then by reading about :doc:`all available configuration options `, 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 391fc58..3764849 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -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 diff --git a/doc/inserters.rst b/doc/inserters.rst index 026e5ac..8235d08 100644 --- a/doc/inserters.rst +++ b/doc/inserters.rst @@ -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! diff --git a/doc/installation.rst b/doc/installation.rst index edbc0fd..9d33791 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -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 /python/ to the PYTHONPATH environment variable:: export PYTHONPATH=/python/:$PYTHONPATH @@ -26,7 +26,6 @@ For compiling the docs, `Python Sphinx`_ is needed. .. _Python Sphinx: http://pypi.python.org/pypi/Sphinx - Installing Sloth ================ diff --git a/doc/items.rst b/doc/items.rst index e72cc07..b7023bb 100644 --- a/doc/items.rst +++ b/doc/items.rst @@ -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): diff --git a/sloth/annotations/container.py b/sloth/annotations/container.py index 9512586..618240d 100644 --- a/sloth/annotations/container.py +++ b/sloth/annotations/container.py @@ -81,6 +81,7 @@ class AnnotationContainer: self.clear() def filename(self): + """The current filename.""" return self._filename def clear(self):