diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..bbb9748 --- /dev/null +++ b/doc/Makefile @@ -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 ' where 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." diff --git a/doc/api.rst b/doc/api.rst new file mode 100644 index 0000000..f7e21a1 --- /dev/null +++ b/doc/api.rst @@ -0,0 +1,6 @@ +API +=== + +.. automodule:: annotationscene +.. autoclass:: AnnotationScene + :members: diff --git a/doc/concepts.rst b/doc/concepts.rst new file mode 100644 index 0000000..196a7c6 --- /dev/null +++ b/doc/concepts.rst @@ -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. + diff --git a/doc/configuration.rst b/doc/configuration.rst new file mode 100644 index 0000000..521e3f8 --- /dev/null +++ b/doc/configuration.rst @@ -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. + diff --git a/doc/first_steps.rst b/doc/first_steps.rst new file mode 100644 index 0000000..d0b2170 --- /dev/null +++ b/doc/first_steps.rst @@ -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. + diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..fd3d709 --- /dev/null +++ b/doc/index.rst @@ -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` + diff --git a/doc/inserters.rst b/doc/inserters.rst new file mode 100644 index 0000000..2c3af6c --- /dev/null +++ b/doc/inserters.rst @@ -0,0 +1,3 @@ +Inserters +========= + diff --git a/doc/items.rst b/doc/items.rst new file mode 100644 index 0000000..449d364 --- /dev/null +++ b/doc/items.rst @@ -0,0 +1,2 @@ +Items +=====