Chilitags are a C++ cross-platform software library for the detection and identification of 2D fiducial markers (a.k.a. tags). Their purpose is to be printed and placed on objects from the real world, to form the basis of Robotics or Augmented Reality (AR) applications. Using a camera, the position of the tagged objects can be acquired by a computer.
Chilitags were developed internally for projects of the CHILI lab (Computer-Human Interaction in Learning and Instruction, formerly CRAFT), such as Metroscope or TapaCarp. There are already many alternatives (e.g. ARToolKit, or reacTIVision, among many others), but we decided to release Chilitags anyway, as there seemed to be a demand for it.
The following videos show real applications of Chilitags for research in tangible learning or paper-based interfaces.
Chilitags features two main functionalities:
-
Detecting tags on images, i.e. finding their position on an input image.
-
Estimating the pose in 3D, i.e. finding their position and orientation and in the real world.
Additionnally, Chilitags features various utilities to deal with imperfect detection, such as filters to smooth the position of tags/3Dobjects.
The characteristics of Chilitags come from their original use:
-
Illumination tolerance: Chilitags were developed for use in projector/camera systems, which required the detection to be robust to the illumination constraints of the projector.
-
Precision: Chilitags were used in applications to teach geometry, which required the detection to be as precise as possible to match the requirement on the quality of work of the students.
-
Reliability: Chilitags were used for long experiments in ecologically valid conditions, which required to build systems stable even in various, uncontrolled settings.
Chilitags can be recognized even from low resolution images (tags as narrow as 12 pixels are recognized). However, they are very sensitive to occlusions: if a border is occluded, the tag will not be detected.
The Chilitags demonstration video gives a worst case scenario for the sample code running in real time on a single thread of an Intel Core i7-620m, with a camera set for 960x720x30fps, in an unevenly lit, large scene. The detection has been improved since this video was made.
This release of Chilitags consists of five components:
-
platforms, the source code to expose the Chilitags API in various languages, -
includeandsrc, the library itself, -
tools, containing a utility to generate tags, -
samplesandsamples-android, sample programs illustrating how to use the library, -
test, a suite of automated tests.
Chilitags have been developed on Linux (Ubuntu 64 bits), and are known to run on Windows, MacOS X and Android.
Chilitags rely on OpenCV 2.4+ and C++11. They have has been recently tested with OpenCV 2.4 and on Ubuntu (64 bits) 13.04, 13.10 and 14.04. The documentation on how to install OpenCV can be found for various platforms and IDE.
On Ubuntu 12.04, you need to manually install a compiler supporting enough of
C++11 (for instance, gcc-4.7) and opencv >= 2.4. The .travis.yml file
contains commands to do this, in the before_install section
CMake can be used to generate configuration files of the most popular IDE's of the main platforms. A CMakeLists file is provided in the release. Please refer to online documentation on how to use CMake.
For example on Ubuntu, the software can be compiled via makefile with the following commands:
sudo apt-get install libopencv-dev cmake
to install the OpenCV libraries and cmake
mkdir build && cd build
to create the build folder where the compilation output will be placed
ccmake ..
to configure the build. Activate the WITH_SAMPLES option.
make
to build the library, the tag creation tool and the sample programs
sudo make install
to install the library system-wide (see CMake options to install in another
prefix).
./samples/detect-live
to start the sample program with default parameters for the camera.
Once the software is up and running, the tags can be generated using the
creator executable in tools. We also generated sets of
tags with various settings.
The README file accompanying creator gives important guidelines on how to
design and print chilitags. It also explains the usage of creator.
The main design principles for tags are summarized below:
The documentation regarding the usage of chilitags is provided under the form
of the sample code detect-live. Please refer to its README file and comments
in its source code.
Specific instructions for building Chilitags for Android can be found under README-ANDROID.md.
This repository uses uncrustify, a tool that does automatic code formatting based on a predefined configuration defined in uncrustify.cfg.
In order to keep the code formatting consistent, it is useful to uncrustify before committing.
You may consider using a git pre-commit hook to remind you of this.
For example, you can add a pre-commit hook that inhibits you from committing if the source files are not formatted correctly.
Simply add a file .git/hooks/pre-commit that contains the following
#!/bin/sh
exec uncrustify -c uncrustify.cfg --check src/* include/*More complex hooks can be built, such as this one that runs uncrustify before every commit and stores the diff in a patch.
Chilitags is released under the LGPL3.
In short, it means that you can do more or less what you want with Chilitags, as long as you publish the modifications you make to Chilitags under the same terms (but you don't have to share the sources of the rest of your software).
You should also credit the authors.
We especially appreciate a reference in your paper, should you use Chilitags for a research project. Let us make that easy for you:
- Chilitags: Robust Fiducial Markers for Augmented Reality. Q. Bonnard, S.
Lemaignan, G. Zufferey, A. Mazzei, S. Cuendet, N. Li, P. Dillenbourg.
CHILI, EPFL, Switzerland.
http://chili.epfl.ch/software. 2013.
@misc{chilitags,
title = {Chilitags 2: Robust Fiducial Markers for Augmented Reality and Robotics.},
author={Bonnard, Quentin and Lemaignan, S\'{e}verin and Zufferey, Guillaume and Mazzei, Andrea and Cuendet, S\'{e}bastien and Li, Nan and \"{O}zg\"{u}r, Ayberk and Dillenbourg, Pierre},
publisher={CHILI, EPFL, Switzerland},
url={http://chili.epfl.ch/software},
year={2013}
}
Should you require a different licence, please contact CHILI.