ImageTagger

This is a collaborative online tool for labeling image data.

If you are participating in RoboCup, you should not install your own instance but rather use the one provided by the Hamburg Bit-Bots (https://imagetagger.bit-bots.de). This enables you to use already labeled images from other teams and to share your own.

For a short overview of the functions please have a look at the following poster: https://robocup.informatik.uni-hamburg.de/wp-content/uploads/2017/11/imagetagger-poster.pdf

Table of Contents:

• ImageTagger

  • Features

  • Planned Features

  • Reference

  • Installing and running ImageTagger

    • Locally
    • In-Docker
    • On Kubernetes

  • Configuration

  • Used dependencies

Features

• team creation
• image sets
• bounding box, polygon, line and point labeling
• imageset download
• export format creation
• label export
• image preloading for labeling and verification
• label verification
• upload of existing labels
• tools exchange

Planned Features

• collections of filtered images from multiple imagesets
• image metadata (e.g. robot pose, camera parameters)

Reference

This paper describes the Bit-Bots ImageTagger more in depth. Please cite if you use this tool in your research:

FIEDLER, Niklas, et al. ImageTagger: An Open Source Online Platform for Collaborative Image Labeling. In: RoboCup 2018: Robot World Cup XXII. Springer, 2018.

@inproceedings{imagetagger2018,
   author={Fiedler, Niklas and Bestmann, Marc and Hendrich, Norman},
   year={2018},
   title={ImageTagger: An Open Source Online Platform for Collaborative Image Labeling},
   booktitle={RoboCup 2018: Robot World Cup XXII},
   organization={Springer}
}

Installing and running ImageTagger

ImageTagger can be installed and run locally (best for development), in a docker container or in Kubernetes
(used in our deployment).

Locally

In some of the following code snippets, the DJANGO_CONFIGURATION environment variable is exported.
This defines the type of deployment by selecting one of our predefined configuration presets.
If ImageTagger is running in a development environment, no export is necessary.

1. Install the latest release

   You should probably do this in a virtual environment

   Replace v… with the latest release tag.

   git checkout v…
   cd imagetagger
   pip3 install -r requirements.txt
   

2. Setup a database server

   As a database server postgresql is required.
   Please seek a guide specific to your operating system on how to install a server and get it running.

   Once postgresql is installed, a user and database need to be set up for ImageTagger.
   Of course, the user and password can be changed to something else.

   CREATE USER imagetagger PASSWORD 'imagetagger';
   CREATE DATABASE imagetagger WITH OWNER imagetagger;
   

3. Select a Configuration preset

   When running ImageTagger as a developer, no step is necessary because a development configuration is used per
   default when not running as a docker based deployment.
   However if this is supposed to be a production deployment, export the following environment variable.

   Currently available presets are Dev and Prod

   export DJANGO_CONFIGURATION=Prod
   

4. Configuring ImageTagger to connect to the database

   Please see the lower Configuration section on how to configure ImageTagger for your specific
   database credentials.

5. Initialize the database

   Run the following to create and setup all necessary database tables:

   ./manage.py migrate
   

6. Create a user

   ./manage.py createsuperuser
   

7. Run the server

   ./manage.py runserver
   

In a production deployment it is necessary to run the following commands after each upgrade:

./manage.py migrate
./manage.py compilemessages
./manage.py collectstatic

for additional steps on some releases see instructions in UPGRADE.md

In-Docker

1. Checkout the latest release

   git checkout v…
   

2. Build the container image

   Note: the Dockerfile has been tested with podman as well.

   docker build -t imagetagger .
   

3. Run the container

   docker run -it -p 8000:80 --name imagetagger imagetagger
   

   This step will not work out of the box because configuration still needs to be done.
   See the lower section about configuring ImageTagger on how to fix this.

4. Create a user

   Note: This step requires a container running in the background.

   docker exec -it imagetagger /app/src/imagetagger/manage.py createsuperuser
   

About the Container

On Kubernetes

1. Follow the steps for In-Docker on how to build a container image

2. Apply kubernetes configuration

   Note: This assumes you have access to a kubernetes cluster configured and can use kubectl

   We use kustomize for management of our kubernetes configuration.
   It can be applied by running the following commands:

   kustomize build . > k8s.yml
   kubectl apply -f k8s.yml
   

Generated Kubernetes resources

Configuration

ImageTagger is a Django application and uses django-configurations
for better configuration management.

ImageTagger is configured to use a Dev configuration when running locally and Prod when running in a container.
This can be overridden via the environment variable DJANGO_CONFIGURATION.

For a list of available configuration values see settings.py.
Towards the bottom is a list of values. These are taken from environment variables where the key is the variable name
but with an IT_ prefix.

If completely custom configuration is desired, imagetagger/imagetagger/settings_local.py can be created in which
a custom configuration class may be created. In Docker this file may be located at /app/config/settings.py so that
mounting it should be simple.
To use this custom configuration class, the environment variables DJANGO_SETTINGS_MODULE=imagetagger.settings_local
and DJANGO_CONFIGURATION=MyCustomClass must be set.

If downloading zip files of Imagesets is desired, the feature can be enabled by settings IT_ENABLE_ZIP_DOWNLOAD to true.
A separate zip generation daemon must then be started via the following command.
This feature is enabled and running automatically in Docker based deployments.

export DJANGO_CONFIGURATION=Prod
./manage.py runzipdaemon

To create annotation types, log into the application and click on Administration at the very bottom of the home page.

Minimal production Configuration

In production, the following configuration values must be defined (as environment variables)

Database Configuration

The following environment variables configure how the postgresql server is accessed

Used dependencies

The ImageTagger relies on the following plugins, libraries and frameworks:

• Bootstrap
• Django
• Django REST Framework
• django-registration
• django-widget-tweaks
• imgAreaSelect
• jCanvas
• jQuery
• jQuery-Autocomplete
• jQuery-File-Upload
• Pillow
• PostgreSQL

We are grateful to the maintainers and contributors of the respective projects.