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:
- 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
- collections of filtered images from multiple imagesets
- image metadata (e.g. robot pose, camera parameters)
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}
}
ImageTagger can be installed and run locally (best for development), in a docker container or in Kubernetes (used in our deployment).
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.
-
You need to have Pipenv installed on your system.
Replace
v…
with the latest release tag.git checkout v… cd imagetagger pipenv sync
-
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;
-
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
andProd
export DJANGO_CONFIGURATION=Prod
-
Please see the lower Configuration section on how to configure ImageTagger for your specific database credentials.
-
Run the following to create and setup all necessary database tables:
./manage.py migrate
-
./manage.py createsuperuser
-
./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
-
git checkout v…
-
Note: the Dockerfile has been tested with podman as well.
docker build -t imagetagger .
-
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.
-
Note: This step requires a container running in the background.
docker exec -it imagetagger /app/src/imagetagger/manage.py createsuperuser
Kind | Description |
---|---|
Volume | /app/data is where persistent data (like images) are stored |
Volume | /app/config is where additional custom configuration files can be placed. See the Configuration section below |
Environment | ImageTagger can mostly be configured via environment variables |
Ports | The container internal webserver listens on port 80 for incoming connections. |
-
Follow the steps for In-Docker on how to build a container image
-
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
Kind | Name | Description |
---|---|---|
Namespace | imagetagger | The namespace in which each resource resides |
Deployment + Service | imagetagger-postgres | postgresql server which is required by ImageTagger. The replica count can be dialed down to 0 if an the usage of an external server is desired. |
PersistentVolumeClaim | imagetagger-database | Where the postgresql server stores its data |
ConfigMap | imagetagger-postgres | Configuration of the postgresql server. Also available inside the application server deployment so that settings can be referenced. |
Deployment + Service | imagetagger-web | application server. Per default this deployment references the image imagetagger:local which is probably not resolvable and should be replaced by a reference to where your previously built container image is available. |
PersistentVolumeClaim | imagetagger-image-data | Where the application server stores its images (and tools). |
ConfigMap | imagetagger-web | Configuration of the application server. Mounted as environment variables. See Configuration for details. |
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.
In production, the following configuration values must be defined (as environment variables)
Key | Description |
---|---|
IT_SECRET_KEY |
The django secret key used by ImageTagger. It is used for password hashing and other cryptographic operations. |
IT_ALLOWED_HOSTS |
django ALLOWED_HOSTS as comma separated list of values. It defines the hostnames which this application will allow to be used under. |
IT_DB_HOST |
Hostname (or IP-address) of the postgresql server. When deploying on kubernetes, the provided Kustomization sets this to reference the database deployment. |
IT_DB_PASSWORD |
Password used for authenticating against the postgresql server. |
IT_DOWNLOAD_BASE_URL |
Base-URL under which this application is reachable. It defines the prefix for generated download links. |
The following environment variables configure how the postgresql server is accessed
Key | Required | Default | Description |
---|---|---|---|
IT_DB_HOST |
yes | Hostname (or IP-address) of the postgresql server. When deploying on kubernetes, the provided Kustomization sets this to reference the database deployment. | |
IT_DB_PORT |
no | 5432 | Port on which the postgresql server listens. |
IT_DB_NAME |
no | imagetagger | Database name on the postgresql server. ImageTagger requires full access to it. |
IT_DB_USER |
no | imagetagger | User as which to authenticate on the postgresql server. |
IT_DB_PASSWORD |
yes | Password used for authentication. |
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.