mirror of
https://github.com/wassname/sloth.git
synced 2026-06-27 19:01:02 +08:00
start writing documentation
This commit is contained in:
Martin Baeuml
+130
@@ -0,0 +1,130 @@
|
||||
# Makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
PAPER =
|
||||
BUILDDIR = _build
|
||||
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||
PAPEROPT_letter = -D latex_paper_size=letter
|
||||
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
|
||||
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
|
||||
|
||||
help:
|
||||
@echo "Please use \`make <target>' where <target> is one of"
|
||||
@echo " html to make standalone HTML files"
|
||||
@echo " dirhtml to make HTML files named index.html in directories"
|
||||
@echo " singlehtml to make a single large HTML file"
|
||||
@echo " pickle to make pickle files"
|
||||
@echo " json to make JSON files"
|
||||
@echo " htmlhelp to make HTML files and a HTML help project"
|
||||
@echo " qthelp to make HTML files and a qthelp project"
|
||||
@echo " devhelp to make HTML files and a Devhelp project"
|
||||
@echo " epub to make an epub"
|
||||
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
||||
@echo " latexpdf to make LaTeX files and run them through pdflatex"
|
||||
@echo " text to make text files"
|
||||
@echo " man to make manual pages"
|
||||
@echo " changes to make an overview of all changed/added/deprecated items"
|
||||
@echo " linkcheck to check all external links for integrity"
|
||||
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
|
||||
|
||||
clean:
|
||||
-rm -rf $(BUILDDIR)/*
|
||||
|
||||
html:
|
||||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||
|
||||
dirhtml:
|
||||
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
|
||||
|
||||
singlehtml:
|
||||
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
|
||||
|
||||
pickle:
|
||||
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
|
||||
@echo
|
||||
@echo "Build finished; now you can process the pickle files."
|
||||
|
||||
json:
|
||||
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
|
||||
@echo
|
||||
@echo "Build finished; now you can process the JSON files."
|
||||
|
||||
htmlhelp:
|
||||
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run HTML Help Workshop with the" \
|
||||
".hhp project file in $(BUILDDIR)/htmlhelp."
|
||||
|
||||
qthelp:
|
||||
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
||||
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
|
||||
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Labeltool.qhcp"
|
||||
@echo "To view the help file:"
|
||||
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Labeltool.qhc"
|
||||
|
||||
devhelp:
|
||||
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
|
||||
@echo
|
||||
@echo "Build finished."
|
||||
@echo "To view the help file:"
|
||||
@echo "# mkdir -p $$HOME/.local/share/devhelp/Labeltool"
|
||||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Labeltool"
|
||||
@echo "# devhelp"
|
||||
|
||||
epub:
|
||||
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
|
||||
@echo
|
||||
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
|
||||
|
||||
latex:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo
|
||||
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
|
||||
@echo "Run \`make' in that directory to run these through (pdf)latex" \
|
||||
"(use \`make latexpdf' here to do that automatically)."
|
||||
|
||||
latexpdf:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through pdflatex..."
|
||||
make -C $(BUILDDIR)/latex all-pdf
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
text:
|
||||
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
|
||||
@echo
|
||||
@echo "Build finished. The text files are in $(BUILDDIR)/text."
|
||||
|
||||
man:
|
||||
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
|
||||
@echo
|
||||
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
|
||||
|
||||
changes:
|
||||
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
|
||||
@echo
|
||||
@echo "The overview file is in $(BUILDDIR)/changes."
|
||||
|
||||
linkcheck:
|
||||
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
|
||||
@echo
|
||||
@echo "Link check complete; look for any errors in the above output " \
|
||||
"or in $(BUILDDIR)/linkcheck/output.txt."
|
||||
|
||||
doctest:
|
||||
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
|
||||
@echo "Testing of doctests in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/doctest/output.txt."
|
||||
@@ -0,0 +1,6 @@
|
||||
API
|
||||
===
|
||||
|
||||
.. automodule:: annotationscene
|
||||
.. autoclass:: AnnotationScene
|
||||
:members:
|
||||
@@ -0,0 +1,88 @@
|
||||
.. highlight:: python
|
||||
|
||||
Concepts
|
||||
========
|
||||
|
||||
Labels
|
||||
------
|
||||
|
||||
The label tool is designed for labeling a set of image files or videos. Each image, or video frame,
|
||||
can contain any number of labels. The labels itself are expected to be sets key-value pairs. We can
|
||||
therefore represent a label for example in the following way::
|
||||
|
||||
{
|
||||
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 rect).
|
||||
We will later see, how you can customize the mapping between type and visualization and how to
|
||||
write your own visualizations.
|
||||
|
||||
Label type conventions
|
||||
----------------------
|
||||
|
||||
The label tool provides support for a range of standard shape label (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 the keys are for `x`- and `y`-coordinates, `width` and `height` and so on.
|
||||
|
||||
The following types are supported out of the box
|
||||
|
||||
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
|
||||
-------------------
|
||||
|
||||
For many cases, it might suffice to use the predefined labels. But as
|
||||
|
||||
|
||||
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.
|
||||
The label tool does not have *the one* in which way to store the labels. Again,
|
||||
there are some default formats with which the label tool can deal out of the box (one of
|
||||
which will be a yaml file, which resembles the textual representation above). However,
|
||||
you are free to define your own loading and saving routines for your labels (see ***). This
|
||||
allows you for example to support legacy third-party label formats without the need to convert
|
||||
them first.
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
=============
|
||||
Configuration
|
||||
=============
|
||||
|
||||
The configuration file is a python module where the module-level variables represent the settings.
|
||||
|
||||
Settings
|
||||
========
|
||||
|
||||
This is a list of all available settings.
|
||||
|
||||
.. _LABELS:
|
||||
|
||||
LABELS
|
||||
------
|
||||
|
||||
.. _ITEMS:
|
||||
|
||||
ITEMS
|
||||
-----
|
||||
|
||||
.. _HOTKEYS:
|
||||
|
||||
HOTKEYS
|
||||
-------
|
||||
|
||||
Default:: `()` (Empty tuple)
|
||||
|
||||
Hold a list of hotkeys for the label inserting. Example::
|
||||
|
||||
(
|
||||
("Point", "", "", "p"),
|
||||
("Rect", "Id", "Martin", "Ctrl+M"),
|
||||
)
|
||||
|
||||
.. todo:: This sucks! Please come up with a better way to reference the labels. Also it might be
|
||||
interesting to be able to assign hotkeys to other tasks, such as "copy all labels from the previous frame"
|
||||
May merge with LABELS, and assign hotkeys there!
|
||||
|
||||
.. _INSERTERS:
|
||||
|
||||
INSERTERS
|
||||
---------
|
||||
|
||||
Default::
|
||||
|
||||
{
|
||||
'rect': 'items.RectInserter',
|
||||
'point': 'items.PointInserter',
|
||||
'polygon': 'items.PolygonInserter',
|
||||
}
|
||||
|
||||
Defines a mapping of which inserter should be used for interactively inserting a new label
|
||||
into the image. The default inserters allow to draw the respective shape. Read more
|
||||
about how to write your own inserter in :ref:`Inserters`.
|
||||
|
||||
.. _LOADERS:
|
||||
|
||||
LOADERS
|
||||
-------
|
||||
|
||||
Default::
|
||||
|
||||
{
|
||||
'txt': 'loaders.SimpleOneLinerTextLoader',
|
||||
'yaml': 'loaders.YamlLoader',
|
||||
'pickle': 'loaders.PickleLoader',
|
||||
}
|
||||
|
||||
Defines a mapping of which loader should be used for loading a label file with the given extension.
|
||||
This can of course also be a user defined loader. You can also define the class directly (instead
|
||||
of a module path)::
|
||||
|
||||
{
|
||||
'foo': MyFooLoader
|
||||
}
|
||||
|
||||
.. todo::
|
||||
|
||||
What is a better name for LOADERS? SERIALIZERS? Because this class should take care of
|
||||
writing the labels to the file as well.
|
||||
|
||||
|
||||
.. _PLUGINS:
|
||||
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
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 z 20 type rect x 50 y 80 z 20
|
||||
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.
|
||||
|
||||
Writing a custom configuration
|
||||
------------------------------
|
||||
|
||||
The configuration file is a python module where the module-level variables represent the settings. The
|
||||
two most important variable are
|
||||
|
||||
* ITEMS:
|
||||
* LABELS: This defines which new labels can be created interactively by the users.
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
========================================
|
||||
Welcome to the label tool documentation!
|
||||
========================================
|
||||
|
||||
This is the documentation of the label tool. The label tool's purpose is to
|
||||
provide a versatile tool for various labeling tasks in the context of computer
|
||||
vision research. Since there are so many different label formats and
|
||||
requirements out there, we concluded that is virtually impossible to build *the
|
||||
one* label tool sufficient to handle all labeling tasks. Therefore, this
|
||||
project can be seen rather as a framework and set of standard components to
|
||||
quickly configure a label tool specificly tailored to ones needs.
|
||||
|
||||
In this documentation we will go over some of the key concepts of the label tool,
|
||||
how to configure the label tool using the standard components provided in the package,
|
||||
and finally how to go further and write specific visualization items and label format
|
||||
loaders to deal with specific labeling needs.
|
||||
|
||||
Contents
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
concepts
|
||||
first_steps
|
||||
configuration
|
||||
items
|
||||
inserters
|
||||
api
|
||||
|
||||
|
||||
TODOs
|
||||
=====
|
||||
|
||||
.. todolist::
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
Inserters
|
||||
=========
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
Items
|
||||
=====
|
||||
Reference in New Issue
Block a user