View this PageEdit this PageUploads to this PageVersions of this PageHomeRecent ChangesSearchHelp Guide

The DART Data Directory

Welcome to the DART Data Directory...Although the when neglected, the Data directory can be a painful thorn in your side... in the same way, when treated with care and respect, the Data directory will be your vigilant ally! Let's take a quick look at the data directory, and it's many facets!

A Typical Data Directory
Uploaded Image: maindatadirectory.jpg

The Dart Data Path
That's all well and good, but let's take a closer look. First things first: Where are we? The DART Data Path! We are going to need this to tell DART where to find all this stuff. Here's mine:
Uploaded Image: datapath.jpg

When you want to use live video in DART, you will have a behavior dialogue pop up, and you should enter your appropriate data path!
Uploaded Image: datapathDART.jpg

Camera Calibration Files
Next let's have a look at our camera calibration files. Every camera is different. Even cameras of the same type, will have slightly different characteristics to their lenses. We'll describe our camera calibration files a bit later. Here's the calibration files I currently have ready to use.
Uploaded Image: camerafiles.jpg

Now let's take a look in a typical camera calibration file. I'll open up "". This represents the camera of type "Fire-I", which serial number "0003888". All the lines starting with a "#" sign are "comment" lines that are ignored by the computer. We've used these lines to just make whatever notes we think are relavent. In this case we've just noted that this camera was calibrated by Brendan in the summer of 2003.

Next let's check out the actual meat of the calibration file. First is the #ID, this is just an integer that we use to identify the camera from other cameras. Next is the #size. Each camera is calibrated at a particular size. Even though many cameras support various sizes of video, when calibrating the camera, we typically choose the largest size (to get the most detail), and calibrate it using that size. This is important, becasue the focal length and principal point are measured in pixels, and the size of the video used to calibrate the camera determines these values. Next is the #focal lengths, which we have two of (vertical and horzontal focal lengths), followed by the #principal point (which tells us the "center" of our lens). Lastly we have our #distortion parameters, which describe how much lens distortion we will get in our video.

NOTE: The data categories (#ID, #size, #focal lengths, etc...), while technically we don't need these headings (they are just comments), the data MUST be ordered like you see here. ID, size, focal lengths, principal points, and last distortion parameters.
Uploaded Image: camcalibfileopen.jpg

When you want to use live video in DART, you will need to indicate which camera you are using, by putting the filename in your "Live Video" dialogue box in DART.
Uploaded Image: camcalibDART.jpg

ARToolkit Marker Files
When dealing with the ARToolkit, you need 2 things. First you need a raw description of each marker you are using. This is literally the "pattern" data that describes the marker. This data is encoded in boring looking files that we've tucked away into their own directory so we don't have to deal with them. I have tons of these things, and I keep mine here:
Uploaded Image: patternfiles.jpg

So after I have a description of the patterns, if i want to use some ARToolkit markers, I will need to build a .calib file which describes the size of the markers I have printed out, as well as the relative positions of markers that are grouped together on a single page. I have already defined quite a few of these in my data directory:
Uploaded Image: markerfiles.jpg

What I did next was I took 6 pattern images (not the pattern files that are in that directory, but the images that correspond to these. We'll look at how to generate patterns and images of those patterns later), and arranged them into a single image file and printed it out. The image file I made looks like this (NOTE: This is NOT inside the .calib file, this is just an image file that i made and printed out, and which does NOT reside in the data directory):
Uploaded Image: sheetimage.jpg

After I had this printed out and sitting on my desk, I had to make a .calib file to describe it. First, let's open up the final calib file that I made and take a look. It starts out with an integer that tells how many markers I am going to define in this .calib file (6 in my case). Next we take each marker in turn, and have it's pattern, size, center, and location.
Uploaded Image: markerfilesopen.jpg

The "pattern" is just the relative path and filename to the pattern file that describes this marker. I started with the upper-left marker, which is "3x4patt16_01.patt". It's in the "3x4patterns16" directory so the final line in my calib file is:

It is named this way because the ID of these special patterns are 3x4 binary barcodes, where the digits are ordered left-to-right, and top-to-bottom. Here's an example of another pattern. The ID of this pattern is 37, so the entry into the .calib file would be:
Uploaded Image: decoding.jpg

After the path to the pattern file, we put the size of the markers. I took out a ruler and measured my squares, and found it to be 6.35 cm to a side.
Uploaded Image: sizing.jpg

The next line is the "center point" of the marker. We typically keep our markers' "virtual centerpoint" at the true geometric centerpoint, so just leave this at "0.0 0.0". This put the "center" of the marker in the middle of the black square.

Finally we have the real meat of the calibration file, the 3x4 pose matrix. There are obviously entire volumes devoted to matrix theory, but we will try to keep it simple here. The first 3 columns of this matrix describe the rotation of the markers. If a marker is perfectly straight (like mine are, because i printed them that way), then we say it has the "identity" rotation. This means that that it essentially has no rotation, ie, it is perfectly straight. The "identity" rotation matrix is all zeros, except for a "1.0" going down along the "main diagonol". The last column is the "translation" component. This tells "where the marker is", in x-y-z coordinate space.
Uploaded Image: matrix.jpg

We have to tell DART where each marker is relative to the other markers in our group. To do this, we define a local coordinate system, that is the "anchor point", from which the positions of all our markers will be measured. I defined my coordinate system like this:
Uploaded Image: axes.jpg

...such that the "origin" (the point (0,0,0) in (x,y,z)) is directly in the center of my upper-left marker. Next I make my coordinate axes point X to the right, Y to the top, and Z points directly out of the page right at me. This is critical, as it will detemine how we measure the translations of our other markers.

So our first marker is now completely defined. It has the identity rotation, and it's translation is (0,0,0), because we defined our coordinate system right on top of it! Now we have to define the rest of our markers. They will all be identical in this case, except for the pattern (obviously), and their translations. And further, the only thing that will change in their translations will be the x-coordinate and the y-coordinate. The z-coordinate can't change, becasue there's no way to get a marker to come off of the paper it's printed on!

So next I got out my ruler and measured the offsets to the other markers. When measuring how far the other markers are "to the right", this translates into a POSITIVE X offset (because the positive X-axis points to the right). When measuring how far the markers are below my origin, this translates to a NEGATIVE Y offset (because our positive Y-axis points up off the top of the page).

Even though our origin is at the center of the marker, i found it difficult to measure the distance from the center of marker #1 to the center of the other markers. Instead, I measured the distance from the left edge of marker #1 to the left edge of marker #2, as this is the same distance, but is easier to measure. I did the same while measuring the "downward" offsets. I measured from the top edge of marker #1 to the top edge of the lower markers.
Uploaded Image: offsets.jpg

How to use the ARToolkit program
Creating your own pattern files

In this section we'll look at how to make your own patterns with any arbitrary design on them. (more on this later)

Links to this Page