We decided to write a kind of tutorial like those yellow "Dummies" books. We
wrote it for our lab members initially but thought it might be useful for
anyone getting started in Linux AR toolkit - especially those without much
Linux experience like we were :).
Thanks a lot to Mark and Dr Kato for checking it first, but if there are any
more errors the errors are my fault so please tell me if you find any.
If you would like to add to this tutorial please send me more info and we
will publish newer versions, of course you will be fully acknowledged at the
start of the tutorial :)
LINUX AR TOOLKIT FOR DUMMIES (named after the book series
Version 1.0 October 18th 2001
Written by the Mixed Reality group at National University of Singapore
(if you find any errors or for more information please contact Adrian Cheok
Acknowledgements: Thanks to all the brilliant people who developed the AR
especially Hirokazu Kato and Mark Billinghurst!
*** The AR Toolkit home page is at
H.Kato, M. Billinghurst, I. Poupyrev, K. Imamoto, K. Tachibana.Virtual
Object Manipulation on a Table-Top AR Environment. In Proceedings of ISAR
2000, Oct 5th-6th, 2000.
M. Billinghurst, H.Kato, M. Billinghurst, I. Poupyrev. The MagicBook: Moving
Seamlessly between Reality and Virtuality In IEEE Computer Graphics and
Applications, May/June, 2001, pp. 2-4.
BASIC TUTORIAL PART 1
4 Easy steps
ii)Update Mesa (This part may not be needed on some machines)
iii)Install graphics card drivers
iv)Compile and run ARToolKit
By right, this part is outside the scope of this guide. There are already
plenty of better guides to installation than this one, so you are strongly
encourage to read them in addition to reading this guide. A good URL to
start is http://www.redhat.com/support/docs/new.html
Any flavour of linux should work fine. As I have only tried Redhat and
Mandrake, I recommend Redhat 7.1; you can't go wrong with it. As different
distributions of linux have subtle differences, the intricate details in
this guide will mostly apply to RH7.1. Of course the concepts will be the
same. Try to get a distribution with kernel version 2.4.x, as it contains
quite new drivers for the wintv card.
You can download ISO images of the 2 CDs from several local sites.
One anonymous ftp I know of is ftp.hjc.edu.sg.
To install from CDs, you need to boot up with your CDRom drive. Check your
motherboard manual on how to do that. Once installation gets underway, most
options will be pretty straight-forward. However there are some things to
take note of.
One problem for newbies is partitioning. If you ask 10 linux experts on the
best way to partition, you will get 10 different answers. We shall do it the
simplest way, ie with the least number of physical partitions. (It's
possible to not have any dedicated linux partitions, but it's outside the
scope of this guide). Linux itself needs at least 2 partitions. One to put
the swap partition(much like the swap file in windows), and the other to
hold everything else.
Next you need to find some space on your harddisk(s) to put these 2
partitions. If you are already using windows, you will probably
want to keep using it. Dual booting is easy.
For RH7.1, you'll need about 1.0GB for all the files, and then anything from
128MB to more for the swap partitions. So it's reasonable to set aside 1.5
to 2GB for linux.
For some versions of Linux, the linux kernel has to reside within the first
1024 cylinders of
a hard drive. Roughly, that's about 8GB. So if your partition is within the
first 8GB of your harddisk, you should be fine. It's easier if you have 2
harddrives and then use the beginning of the 2nd harddrive for linux. Note
that Win95/98/ME will need to be on the primary partition of the first
If however, you have only one harddrive, then you'll need to perhaps assign
the first 2GB for windows, the next 2GB for linux and the remaining for
windows, ending up with 3 or more partitions.
A reliable tool for changing partitions on your harddisk without destroying
data is of course Partition Magic. It is also perhaps the easiest to use.
Both the DOS and linux Fdisk will destroy data when changing partitions.
It's possible to use fips(found on the cds) and defragmentating to do
non-destructive partitioning. fips is a command line tool, and it works
well. Read its documentation for more info. It doesn't matter what
filesystem the partition in which you will install linux is at the moment,
because the linux installation will do the proper formatting to change it to
the ext2 filesystem for linux.
Another thing to note when installing is X configuration. Unless you are a
console fan, you'll probably want some windows to work with. Btw, ARToolKit
needs the X windows to run! X Windows is the GUI for linux. The linux
install will be able to detect most graphics card and then you select the
desired resolution and color depth. Make sure you do the X Configuration
test, and can see the test screen. Otherwise, if you select graphical bootup
and if the configuration is wrong, you'll see nothing on your screen, not
even a cursor.
If this is your first time installing, choosing the default choice for most
options is a safe bet. The thing to note if you plan to keep your old OS is
that of choosing to manually partition using Disk Druid when asked for
partitioning. If you allow the installation to auto partition for you, it
will erase everything.
For Disk druid, click on the partition you assigned for linux and create 2
partitions. The mount point for one will be '/' while the other will be
Other than that, make sure you don't skip the X configuration.
If you are using lilo(you should, unless you don't want to mess around with
your MBR and are booting up from a diskette), you can select what is the
default OS to boot up. You may also want to rename 'dos' to 'win' or
whatever you like. Next time you boot up, you will either be presented with
a lilo prompt or a graphical menu for choosing which OS to boot up. For the
lilo prompt, press 'TAB' to stop the countdown as well as to display what
are the options available. For eg, if you want to boot up to windows you
just type 'dos'(or 'win' if you so named it) or 'linux'.
To boot up in console mood, you type 'linux 3' at the lilo prompt. This
means you start linux at runlevel 3. If you are at the graphical menu, just
press Ctrl-X to get to the lilo prompt. The default is graphical logon,
which is equivalent to runlevel 5 ('linux 5'). You will need to get to
runlevel 3 when you install your graphics card drivers.
BASIC TUTORIAL PART 2
Many of the ideas in the this part is taken from the following document:
You might want to read it too. There is no need to update XFree86 as the
stock RH7.1 is already at 4.0.3.
Mesa is supposed to be a free OpenGL implementation for linux, as OpenGL is
licensed by SGI.
First download Mesa3.5 from http://www.mesa3d.org . Download both
MesaLib*.gz & MesaDemos*.gz. The reason for this is that the VRML4ATK uses
some functions found in GLU 1.2. The default Mesa in the stock RH7.1
installation is 1.1 only. Mesa3.5 is supposedly SGI GLU 1.3 and is fully
compliant to OpenGL1.2 . Backup the glx.h
file to somewhere, eg, your home folder. If you are in graphical mode, you
can just 'find file' and copy and paste. The file's location varies from
system to system, but it should be under /usr/... and is in a folder called
'GL'. The reason for doing this can be found in the above
all.html#INSTMESA). I cannot confirm what the author said in that document
but no harm backing it up. If you wish to, you can later overwrite the glx.h
from Mesa(backup it first of course).
While you are about it, you may want to download your graphics card drivers
too. For nvidia cards, goto to http://www.nvidia.com and select linux
drivers. Select NVIDIA_kernel-x.x-xxxx.rh71up.i386 and
If for any reasons, you don't want to download Mesa3.5, you may want to then
try downloading only the SGI GLU1.3 from
http://www.mesa3d.org/downloads/sgi.html . We haven't tried this, but if it
works, one advantage is that it
is in rpm format, so uninstalling next time is easy.
Now before installing Mesa, it's very important to uninstall any existing
version of it first. Otherwise, you are gonna have a lot of trouble later if
you have mixed versions on your system.
Boot up into console mode first by typing 'linux 3' at the lilo prompt(see
previous section). Login as root.
To uninstall, type 'rpm -e --test Mesa' at the console to test uninstall
Mesa first. Probably it will tell you there are a couple of dependencies,
ie, some software need to have Mesa there before it can work. To force
uninstall anyway, type 'rpm -e -nodeps Mesa'. This tells rpm not to check
for dependencies before uninstalling. Btw, RPM stands for Redhat Package
Manager(http://www.rpm.org). It is something like the Add/Remove Programs
in windows, except much better. If you do not use '-nodeps', then you will
need to uninstall those applications that depend on Mesa first, before you
can uninstall Mesa itself.
Now that Mesa is gone, if you haven't unzipped the Mesa*.gz, do so by typing
'tar -zxvf MesaLib-3.5.tar.gz' and 'tar -zxvf MesaDemos-3.5.tar.gz'. Both
these commands should unzip the 2 gz files into the local dir. Type 'ls' to
check. Now cd to Mesa-3.5 dir and type './configure --prefix=/usr'. The
reason for doing this is to allow autoconfig(a program) to configure the
installation details and create the appropriate makefiles for you. The
'--prefix=/usr' is to install it into the '/usr' dir, as specified in the
OpenGL standard. Next you will need to type 'make'. This will compile the
source codes and then type 'make install' to actually install them. These 3
steps are fairly common. Finally, very importantly, you need to update the
/etc/ld.so.conf file by typing 'ldconfig'. This file basically tells linux
where the shared libraries are.
Anytime you are not sure how to use a command in linux, check its man(ual)
pages. For eg, to see the list of options for 'ls', type 'man ls'. Press
spacebar, PageUp, PageDown or arrow keys. Press 'q' to quit.
BASIC TUTORIAL PART 3
Install graphics card drivers
Many of the ideas in the this part is also taken from the installation guide
for the linux nvidia drivers.You might want to read it too.
This section will only pertain to nvidia cards, as I only have experience
with it under linux. For graphics card using different chipsets, please
check the internet. http://www.google.com is good.
If you haven't already done so, download the latest nvidia drivers for your
linux distributions. Using rpm files is both easy and safe. For nvidia
cards, goto to http://www.nvidia.com and select linux drivers. Select
NVIDIA_kernel-x.x-xxxx.rh71up.i386 and NVIDIA_GLX-x.x-xxxx.i386.rpm.
Now you need to be in console mode(no X windows running). Boot up to
runlevel 3 if you have not done so. If you are already at runlevel 3(which
you should be if you continue from the previous section), then you are ready
to proceed. Check that you have a non X windows text editor first. You can
use any you like, Emacs, vi etc. An easy to use and small editor is joe. To
check whether you have joe installed, just type 'joe'. If not, you can type
'init 5' to go into X windows and then insert the RH cd(forgot which one,
but there's only 2 anyway). The cd should autorun and then some kind of rpm
management program should come out. Select install and choose joe from the
text editor list. Then to go back to console(runlevel 3), type 'init 3'.
Type 'rpm -ivh NVIDIA_kernel-x.x-xxxx.rh71up.i386.rpm'. If previously, you
have already updated your drivers, and you have installed Mesa after that,
then some files will have been overwritten by Mesa. In this case, you need
to force install by 'rpm -ivh --force
NVIDIA_kernel-x.x-xxxx.rh71up.i386.rpm'. Do the same for the GLX rpm file.
Next, you need to edit your XFree86 Config file. The file should be
/etc/X11/XF86Config-4 . Open it up using your favourite text editor. There
are 3 lines you need to edit. Go thru' the file and remove the following 2
You can remove them by commenting them out using '#'.
Next check that you have
Under device section, change
Driver "nv" to
"nv" is the default driver for nvidia cards under linux and is not hardware
accelerated, that's why performance is poor.
Now you are ready to restart X Windows. To do that, 'init 5'.
BASIC TUTORIAL PART 4
Compile and run ARToolKit
Now the final part. First settle ARToolKit.
Unzip it by using 'tar -zxvf ARToolKit2.431.tar.gz'.
We use "~ATKRoot" to represent ARToolKit top directory.
Then, go to ~ATKRoot/include/AR/, and modify config.h file.
Depending on what the television standard of the video-grabbing hardware,
you may want need to change the DEFAULT_VIDEO_MODE from VIDEO_MODE_NTSC to
VIDEO_MODE_PAL. Probably this will depend what country you bought it in:
NTSC countries are: USA, Antigua, Bahamas, Barbados, Belize, Bermuda,
Bolivia, Burma, Canada, Chile, Colombia, Costa Rica, Cuba, Dominican
Republic, Ecuador, El Salvador, Greenland, Guam, Guatemala, Guyana,
Honduras, Jamaica, Japan, South Korea, Mexico, Netherlands Antilles,
Nicaragua, Panama, Peru, Philippines, Puerto Rico, St. Vincent &
the Grenadines, St. Kitts, Saipan, Samoa, Surinam, Taiwan, Tobago,
Trinidad, Venezuela, Virgin Islands.
PAL countries include: Afghanistan, Algeria, Argentina (PAL-N), Australia,
Austria, Bahrain, Bangladesh, Belgium, Brunei, Cameroon, Canary Islands,
China, Cyprus, Denmark, Finland, Germany, Ghana, Gibralter, Greece (also
SECAM), Hong Kong, Iceland, India, Indonesia, Ireland, Israel, Italy,
Jordan, Kenya, North Korea, Kuwait, Liberia, Luxembourg (also SECAM),
Madeira, New Zealand, Nigeria, Norway, Oman, Pakistan, Paraguay (PAL-N),
Portugal, Qatar, Saudi Arabia (also SECAM), Siera Leone, Singapore,
South Africa, Spain, Sri Lanka, Sudan, Swaziland, Tanzania, Thailand,
Turkey, Uganda, United Arab Emirates, United Kingdom, Uruguay (PAL-N),
Yeman (the former Yeman Arab Republic was PAL, and the former People's
Democratic Republic of Yeman was NTSC ), Yugoslavia, Zambia, Zimbabwe.
Next you may need to change the DEFAULT_VIDEO_DEVICE to "/dev/video0", if
you try running simpleTest later on and get the error message 'can't open
Type "make clean" at $(ARToolKitRoot)
This command deletes all libraries, *.o files and executable files in
Type "make" at $(ARToolKitRoot). This is to recompile everything.
Please note, there is a file named "config.Linux", which contents the
options for configure command.
Type' ./simpleTest '
You can include the bin dir in your path so that you don't have to type './'
The picture should come out.
It should be in color and frame rates shouldn't be too low. If it's too low
or it crashes, that means optimized drivers are not used or installed.
As usual, there are many ways to achieve the same results, and what is
contained in this guide is but one way. For many of the administrative
stuffs, you need to login as root. For normal artoolkit usage, a normal user
account is sufficient.
FULL SCREEN TUTORIAL
"How to get AR toolkit Linux working in full screen mode"
Please note that, all the code line numbers shown below are referring to the
original downloaded Linux version codes without any modification. For
windows codes, the position of each section of code may be slightly
different from this.
Go to ../Example (../ is the directory where you put your
uncompressed VRML parser files)
Open the simpleTest.c using any editor (eg. joe or vi)
This simpleTest.c is the core file in this simple program. The main function
is from line 57 to line 63, which basically does three jobs: Initialization,
Start Video Capturing, and the Main Processing Loop.
In the Initialization part (from line 152 to line 207), a function argInit
is called at line 204, which is to open the graphics window.
There are 6 parameters used in this function. To understand the meaning of
each parameter, we have to go to
Open the gsub.c file, and the description of this argInit function is shown
in line 89 to line 125. From the code, we can see that, the second parameter
is actually the zoom ratio of the graphics window. Because the default
camera capturing resolution is 640 x 480, and our monitor is running at 1024
x 768, a zoom ratio of 1.6 is needed in our case in order to make it run in
full screen mode.
So, we have to go back to ../Example, open the simpleTest.c, go
to line 204, and change
argInit (&cparam, 1.0, 0, 0, 0, 0)
argInit (&cparam, 1.6, 0, 0, 0, 0)
Save and quit the editor.
Type "make" in ../VRML4ATK1.01/Example to compile it, and then we can run
the program already.
"Use of Cy-Visor HMD in Linux with AR toolkit Linux programs"
In our case, the Cy-Visor HMD was used.
We had a lot of trouble getting this device running smoothly with
the GUI under Linux. In particular, we failed to run the device
with nVidia GeForce 2 MMX video cards. The symptom was a horizontal
flickering. In the end, we just started using an nVidia GeForce 2 GLS
video card on which there are no problems.
The parameters which control the display resolution are in the file
/usr/X11/XF86Config-4. Back up this file before changing it or running
Xconfigurator just in case something goes wrong.
In order to use the Cy-Visor, you need to set the paramters of the display
properly. We use:
Horizontal Sync: 45-50
Vertical Sync: 75-75
and it works fine. You can either directly change these parameters in
/usr/X11/XF86Config-4 file, or you can run Xconfigurator, which edits
the file for you and put in the parameters when it asks you. Note that the
changes won't be implemented until you restart X windows.
MAKE PATTERN TUTORIAL
"How to make new patterns for AR toolkit Linux programs"
1. The use of pattern recognition files
The "simple" program uses template matching to recognize the different
patterns inside the marker squares. Squares in the video input stream
are matched against pre-trained patterns. These patterns are loaded at
run time and are contained in the Data directory of the bin directory.
In this directory, the text file object_data specifies which marker
objects are to be recognized and the patterns associated with each
object. The object_data file begins with the number of objects to
be specified and then a text data structure for each object.
Each of the markers in the object_data file in ARToolKit2.431 Linux
version are specified by the following structure:
# Pattern number
3-D object name
Pattern Recognition File Name and directory
For example the structure corresponding to the marker with the virtual cube
However, in the ARToolKit2.431 Linux version, the Scale factor is not used.
We can just ignore the last scale number 80.0 here.
2. Recognizing different patterns
In order to change the patterns that are recognized, the sampPatt1 filename
must be replaced with a different template file name, eg. dsa in the
These template files are simply a set of sample images of the desired
The program to create these template files is called mk_patt and is
in the bin directory. The source code for mk_patt can be found in the util
To create a new template pattern, we need to follow the following few steps:
Step 1: We need to print out the file blankPatt.gif found in the patterns
directory. This is just a black square with an empty white square in the
Then create a black and white or color image of the desired pattern that
in the middle of this square and print it out. The best patterns are those
are asymmetric and do not have fine detail on them.
Step 2: Once the new pattern has been made, change to the bin directory and
run the mk_patt program. You will be prompted to enter a camera parameter
filename. Enter the filename camera_para.dat. This is the default camera
Enter camera parameter filename: Data/camera_para.dat
The program will then open up a video window.
Step 3: Place the pattern to be trained on a flat surface in similar
conditions as will exist when the recognition application will be running.
Step 4: Hold the video camera above the pattern, pointing directly down at
the pattern, and turn it until a red and green square appears around the
This indicates that the mk_patt software has found the square around the
test pattern. The camera should be rotated until the red corner of the
highlighted square is the top left hand corner of the square in the video
Step 5: Once the square has been found and oriented correctly hit the left
mouse button, you will then be prompted for a pattern filename. After a
(eg. dsa) has been entered, a bitmap image of the pattern is created and
into this file.
Once one pattern has been trained, others can be trained simply by pointing
the camera at new patterns and repeating the process, or the right mouse
button can be hit to quit the application. In order to use the new pattern
files they need to be copied to the bin/Data directory and the Pattern
File Name and Directory in the object_data file need to be edited to
the patterns with virtual objects.