From Tekkotsu Wiki

Revision as of 06:50, 6 November 2010 by Touretzky (Talk | contribs)
Jump to: navigation, search

AprilTags are an implementation of Augmented Reality Tags from Edwin Olson's APRIL Laboratory at the University of Michigan. They are visual markers designed for robust detection by machines. See the ARTag.net web site for basic information and alternative implementations of the augmented reality tag idea. Here are some YouTube demo videos. And here are the two 2004 technical reports by Mark Fiala describing his ARTag implementation: NRC-47166 and NRC-47419.


TagTest Demo Install Instructions

A C++ port of Edwin Olson's AprilTags code is built in to Tekkotsu, so no additional installation is necessary to use it. The instructions below are for installing Olson's Java-based TagTest real-time demo on Easy Peasy or Ubuntu Linux systems.

1. Install necessary packages.

sudo -s
apt-get update
apt-get install git-core ant libjogl-java libjogl-jni 
apt-get install subversion gtk-doc-tools libglib2.0-dev libusb-1.0-0-dev

2. Install libdc1394 (camera support).

cd /usr/local
svn co https://libdc1394.svn.sourceforge.net/svnroot/libdc1394 libdc1394
cd libdc1394/trunk/libdc1394
autoreconf -i -s
./configure   # Make sure you see "IIDC-over-USB support: Enabled"
make install

3. Install lcm. Download the source from Google Code into /tmp, then:

cd /opt
wget http://lcm.googlecode.com/files/lcm-0.5.1.tar.gz
tar -xvzf lcm-0.5.1.tar.gz
cd lcm-0.5.1
make install

4. Install April.

cd /usr/local
git clone git://april.eecs.umich.edu/home/git/april.git
cd april/java
export CLASSPATH=/usr/share/java/jogl.jar:/usr/share/java/gluegen-rt.jar:\

5. Install shell script to run the TagTest demo.

cd /usr/local/april/bin
cat >tagtest <<EOF
export CLASSPATH=/usr/share/java/jogl.jar:/usr/share/java/gluegen-rt.jar:\
export LD_LIBRARY_PATH=/usr/local/lib
cd /usr/local/april/java
java -ea -server -Djava.library.path=/usr/local/april/lib april.tag.TagTest
chmod +x tagtest

Running the TagTest Demo

The first four AprilTags in the 36h11 series.

To run the TagTest demo, type /usr/local/april/bin/tagtest. Click on the "Debug" checkbox and then control-right click on the display and go to "Select Buffers" to call up a menu of display options. Click on the "Detach" menu item. You can also click-and-drag in the 3D display (the right half of the main window) to rotate the view.

A few sample 36h11 tags are shown at right. this is the tag family that the TagTest demo recognizes. The name 36h11 indicates that these are 36 bit tags (6x6 array) with a minimum Hamming distance of 11 bits between codes. There are 518 tags in this tag family.

Generating Your Own AprilTags

To generate .png files for each tag in the 36h11 family, use the following commands:

cd /usr/local/april/java
export CLASSPATH=/usr/local/april/java/april.jar
java april.tag.TagFamily april.tag.Tag36h11 /tmp/tag36h11

You can then use a program like gv to display /tmp/tag36h11/alltags.ps, or use gimp or display to show the mosaic.png file or one of the individual tag .png files.

To generate a new tag family, such as the 16h5 family (the default family used by Tekkotsu), use the following commands:

cd /usr/local/april/java
export CLASSPATH=/usr/local/april/java/april.jar
java april.tag.TagFamilyGenerator 16 5 >/tmp/Tag16h5.java

Install the file Tag16h5.java in /usr/local/april/java/src/april/tag and then use the instructions above to generate the alltags.ps file and individual .png files.

Using AprilTags With Tekkotsu

See the AprilTest demo for instructions on using AprilTags with Tekkotsu.

How the Algorithm Works

The algorithm has nine steps:

  1. Convert the image to floating point grayscale (pixel values between 0.0 and 1.0) and apply a Gaussian blur.
  2. Calculate the local gradient (magnitude and direction) at each pixel.
  3. Generate a list of edges, grouping pixels with similar directions together.
  4. Create clusters from the edges.
  5. Loop over the clusters, fitting lines called Segments.
  6. For each Segment, find segments that begin where this segment ends.
  7. Search all connected segments to find loops of length 4, called Quads. Each quad represents the black border around a tag candidate.
  8. Decode the quads by looking at the pixels within the border to see if they represent a valid tag code.
  9. Search for overlapping quads and take the best ones (lowest Hamming distance or largest perimeter); discard the rest.