Suggested doc enhancements

docs/design.rst

@@ -0,0 +1,84 @@
+#################
+Design Decisions
+#################
+
+Jupyter Notebook all the way down
+=========
+
+Jupyter Notebook is used by many researcher relaying on open source software 
+to create and document their work. Ipyannotator not only runs directly in 
+Jupyter Notebook but is also developed as a collection of notebooks. This 
+collection constitues a library, user documentation, and executable tutorials. 
+This workflow is enabled by the innovative fastai library that turns 
+Jupyter Notebook into a literate programming environment.
+
+For the development of the user interface (UI) the Ipywidget library was used 
+to build a graphical user interface (GUI) in Jupyter Notebook. 
+Furthermore, the voila library, which uses Jupyter Notebook as a web-app, was 
+also incorporated in the Ipyannotator project to create the GUI for an easy 
+access to a web application.
+
+Architecture
+=========
+
+Ipyannotator's architecture consists of three main systems components that 
+comprise the user interface (UI), the server, and the data storage. These 
+components are targeted at two different user types. A non-code architecture 
+is included for non-technical annotators. The setup for a wide range of 
+technically experienced annotators target users typically involved in research 
+projects, e.g. data scientists, domain experts, and software developer.
+
+.. image:: img/non-technical-user-architecture.png
+
+.. image:: img/technical-user-architecture.png
+
+For the technical user multiple tutorials are provided, demonstrating 
+Ipyannotator's utilization. The tutorials make it easier for new users 
+get started and adapt the notebooks to their tasks. They also 
+demonstrate annotation workflow and different features.
+
+Layers
+=========
+
+The layering design leads to loosely coupled systems, isolating 
+responsibilities and allows to easier implement changes. Ipyannotator is 
+separated into multiple layers to provide an architecture that allows the 
+annotator to easier add extensions. The library uses four layers: view, 
+controller, storage, and state. Each layer can be rewritten, extended and 
+customized.
+
+- The *View* layer is responsible for rendering the visualizations. Ipyannotator uses ipycanvas and ipywidgets to structure and mount the visualization layer. Additionally, internal components such as the navigation menue were developed which helps the users to navigate through the images that need to be annotated.
+- The *Storage* layer is the layer that receives the data and stores it. Ipyannotator uses different types of storage formats like .txt and .SQLite.
+- The *Controller* layer acts as a mediator between state, storage and view. This layer tells when the information from the state will be stored.
+- *Model/State (in memory)* is the central function of the Ipyannotator layer structure. It is assigned to centralize the data and ensures the syncronization across the applications. If something changes in the Model/State layer, the information is passed on to other layers, ensuring  synchronization of information.
+
+.. image:: img/layer-communication.png
+
+In the present state, Ipyannotator uses SQLite and JSON files as storage 
+formats. Due to the project setup, the storage layer can be customized by 
+other users to implement different storage formats. 
+
+The Ipyannotator comprises four annotation types: bounding box annotator, 
+video annotator, capture annotator, and explore annotator. 
+All types can be combined in the data analysis. 
+
+- Bounding box annotator: Allow users to investigate and produce annotations on images, the annotations are limited to the bounding boxes format.
+- Video annotator: Designed to work with multiple frames of a video, this annotator allow users to inspect objects over the frames, visualizing the object's trajectories and improving it. The annotations it's also limited to the bounding box format.
+- Capture annotator: Enables users to navigate across a grid of images or labels and select multiple options. This annotator can be used in Ipyannotator's improve step to check if image classification is correct, for example.
+- Explore annotator: Aims to be a quickly, easy configuration annotator, it can be used to navigate across images without worring about the Output in the Annotator API.
+
+.. image:: img/bounding-box-annotator.png
+
+The bounding box annotator tool, displayed in the image above, contains three 
+rectangluar annotations exemplifying how the user can draw on the canvas. 
+The navigation menu at the bottom of the image allows users to explore all 
+images. The navigation menu is common to all annotator tools. After an 
+annotation is drawn, the tool allows the association with a semantic label 
+located at the dropdown menue on the right. Additionally to the labeling, 
+the annotator tool also permits to apply change to the coordinates of the 
+drawing, enabling users to improve annotations.
+
+It has to be emphasized that the entire interactive UI has been implemented 
+using Python code only and without additional complex build steps. This allows 
+every user with Python scripting experience to customize the annotation 
+interface for domain specific requirements.

ipyannotator/docs/api.py

@@ -10,14 +10,14 @@
 # Internal Cell
 show_doc(Annotator, title_level=3)
 
-# Internal Cell
-show_doc(Settings, title_level=4)
-
 # Internal Cell
 show_doc(Annotator.explore)
 
 # Internal Cell
 show_doc(Annotator.create)
 
 # Internal Cell
-show_doc(Annotator.improve)
+show_doc(Annotator.improve)
+
+# Internal Cell
+show_doc(Settings, title_level=4)

nbs/21_api_doc.ipynb

@@ -7,15 +7,64 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# default_exp docs.api"
+    "#default_exp docs.api"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "adaf876a",
+   "metadata": {},
+   "source": [
+    "# API"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "65bd4919",
+   "metadata": {},
+   "source": [
+    "## A simple but flexible API to define annotation tasks\n",
+    "\n",
+    "Ipyannotator provides a simple API (application programming interface) which is based on three steps describing general tasks in the data annotation process. These are denoted as the explore, create, and improve phase.\n",
+    "\n",
+    "These three steps in conjuction with domain-specific annotation types, define the inputs and outputs of the annotation process, providing a very flexible and extendable API to set up annotation tasks."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "028f4f0e",
+   "metadata": {},
+   "source": [
+    "### API example\n",
+    "\n",
+    "The following code examples illustrate the main actions around which the Ipyannotator API is built. \n",
+    "\n",
+    "Please keep in mind that Ipyannotator aims to be flexible enought so that these generic aspects can be extented to much complexer and domain-specific tasks and interfaces.\n",
+    "\n",
+    "To set up Ipyannotator in Jupyter Notebook the library has to be imported with three main components: the pair of input/output data, the settings structure, and the generic annotator module. The following example uses the  `InputImage/OutputImageLabel` associated with the image classification task. It imports the settings pointing to a folder called 'data' and configures the annotator module with the entries. Once the annotator module is configured it can be used to call the explore, create and improve steps.\n",
+    "\n",
+    "```python\n",
+    "from pathlib import Path\n",
+    "from ipyannotator.base import Settings\n",
+    "from ipyannotator.annotator import Annotator\n",
+    "from ipyannotator.mltypes import InputImage, OutputImageLabel\n",
+    "\n",
+    "input = InputImage(image_dir='images', image_width=200, image_height=200)\n",
+    "output = OutputImageLabel(label_dir='labels', label_width=30, label_height=30)\n",
+    "settings = Settings(project_path=Path('data'))\n",
+    "\n",
+    "annotator = Annotator(input, output, settings)\n",
+    "```\n",
+    "\n",
+    "For a full investigation of image classification task check [our tutorial](https://palaimon.github.io/ipyannotator/nbs/01b_tutorial_image_classification.html)."
    ]
   },
   {
    "cell_type": "markdown",
    "id": "8ae283ca",
    "metadata": {},
    "source": [
-    "# API Reference\n",
+    "## API Reference\n",
     "\n",
     "Detailed information about Ipyannotator API. To see usage please check [Ipyannotator tutorials](https://palaimon.github.io/ipyannotator/nbs/22_input_output_doc.html)."
    ]
@@ -59,42 +108,15 @@
    "source": [
     "The pairs of input/output available are listed on the [Input/Output Types](https://palaimon.github.io/ipyannotator/nbs/22_input_output_doc.html) section. \n",
     "\n",
-    "When working with the `Annotator` class the input type is always required, but the output type has a `NoOutput` default option that returns an annotator to explore the input images. `NoOutput` usage can be found on the [Bounding Box Annotator Tutorial](https://palaimon.github.io/ipyannotator/nbs/01c_tutorial_bbox.html#explore).\n",
-    "\n",
-    "The final piece of the configuration to access the Ipyannotator API is the `Settings` class that can be imported using `from ipyannotator.base import Settings`. Ipyannotator `Settings` class allow users to customize the folder structure to get the images, read annotations and store results, but also provides a default folder structure:\n",
-    "\n",
-    "```\n",
-    "user_project\n",
-    "│   annotation.json\n",
-    "│\n",
-    "└───images\n",
-    "│   │   00001.png\n",
-    "│   │   00002.png\n",
-    "│   │   ...    \n",
-    "│\n",
-    "└───results\n",
-    "    │ annotations.json\n",
-    "\n",
-    "```"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "747d6bc4",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "#exporti\n",
-    "show_doc(Settings, title_level=4)"
+    "When working with the `Annotator` class the input type is always required, but the output type has a `NoOutput` default option that returns an annotator to explore the input images. `NoOutput` usage can be found on the [Bounding Box Annotator Tutorial](https://palaimon.github.io/ipyannotator/nbs/01c_tutorial_bbox.html#explore)."
    ]
   },
   {
    "cell_type": "markdown",
    "id": "6e53ec99",
    "metadata": {},
    "source": [
-    "## Actions"
+    "### Actions"
    ]
   },
   {
@@ -155,7 +177,34 @@
    "id": "b19da654",
    "metadata": {},
    "source": [
-    "## Settings"
+    "### Settings\n",
+    "\n",
+    "The final piece of the configuration to access the Ipyannotator API is the `Settings` class that can be imported using `from ipyannotator.base import Settings`. Ipyannotator `Settings` class allow users to customize the folder structure to get the images, read annotations and store results, but also provides a default folder structure:\n",
+    "\n",
+    "```\n",
+    "user_project\n",
+    "│   annotation.json\n",
+    "│\n",
+    "└───images\n",
+    "│   │   00001.png\n",
+    "│   │   00002.png\n",
+    "│   │   ...    \n",
+    "│\n",
+    "└───results\n",
+    "    │ annotations.json\n",
+    "\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "be811874",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#exporti\n",
+    "show_doc(Settings, title_level=4)"
    ]
   }
  ],