Tracking Configuration

→Return to Overview

The tracking configuration file (also known as TrackingData file) is used by the Unifeye Viewer to configure the tracking system. It configures the tracking approach to be used (currently only planar markerless tracking also known as feature tracking) and the targets/pattern to be tracked. The format of this file is the exact same format as in other Unifeye products like Unifeye SDK, Unifeye Design or the Unifeye Mobile SDK with the exception that Unifeye Viewer only accepts encrypted tracking configuration files which you can't edit/create by yourself. But the Unifeye Viewer package contains sample tracking configuration files which you can use during your development phase. Before deployment you will need to purchase the deployment license and metaio will encrypt your specific tracking pattern for you. For more details, please refer to development and deployment section and the Sending the tracking configuration to metaio section.

Unifeye Viewer Shockwave Xtra

In case of the Unifeye Viewer Shockwave Xtra, a path/URL to the tracking configuration file is passed to the Unifeye Viewer Shockwave Xtra upon instantiation and is basically an XML file.

The Xtra function getTrackingDataAndImage() returns the tracking values for every defined coordinates systems (COS) within your tracking configuration file. The tracking values are used to place 3D objects in space. The function returns Transforms that can be used directly within Shockwave to place your 3D objects.
In case of planar markerless tracking, each defined COS is bound to a tracking pattern (i.e. a reference image). For more details please refer to the provided examples (e.g. the ShockwaveSimpleAR application which is covered in the examples section).

Unifeye Viewer for Flash

In case of the Unifeye Viewer SWC library for Flash you will have to download the tracking configuration file using Flash e.g. using an URLLoaderDataFormat in BINARY format. Once the download is finished the resulting byte array can be passed to the function initTrackingSystemEncrypted().

In contrast to the Unifeye Viewer Shockwave Xtra you will have to activate and manage the image source (usually a webcam) in Flash by yourself. We recommend using a resolution of 320x240 for tracking. Please pass the images to the Unifeye Viewer Flash library using the function trackImage(). The function getTrackingValues() returns the tracking values for every defined coordinates systems (COS) within your tracking configuration file. The tracking values are used to place 3D objects in space. The function returns an array of 16 values containing the tracking values as a row driven 4x4 matrix that can be used to place the 3D objects in space. Please refer to the provided examples for more details, e.g. the FlashSimpleAR application (which is also covered in the examples section).

Choosing the right tracking pattern

In general you can use arbitrary images which are sufficiently well textured, for tracking purposes.

Input data

Planar markerless tracking (also known as feature tracking) is based on unique features identified in the given reference image. To assure good quality tracking, several rules should be taken into account:

• The reference image has to be suitable with respect to its texture and content.
• Depending on how close the reference image is put in front of the camera, the resolution should be chosen accordingly. As a rule of thumb, the resolution of the reference image should be similar as it is seen from a "default position".
  For example: If you want to track a DIN A4 (210mmx297mm) sized print-out and the default resolution of the camera is 640x480 pixel (the normal resolution for Unifeye Viewer Shockwave applications), the reference image should be scaled to e.g. 350x495 pixel. Looking at the whole page with the camera, the printed image seen in the current camera view will have approximately the same size as the reference image. The reference image should not be high-resolution.
  For Unifeye Viewer Flash usually the webcam resolution used for tracking is 320x240 which also means that the reference image has to be down scaled accordingly. So taking the above example with the DIN A4 page the reference image should be scaled down to e.g. 100x141 pixel.
• The digital version should have the same aspect ratio as the printed version (e.g. no severe stretching of the image).

In this example the pixel aspect ratio is the same in the reference image and the printed version: Rx/Ry = Px/Py. When measuring the dimension of the printed version, make sure that it is not rotated 90°.

• Tracking Performance: to get a good tracking performance, choose a reference image size verifying:
  1. The image size of the reference image should NOT be high resolution but be a little lower than the resolution of the webcam. So for a DIN A4 (210x297mm) pattern the resolution of the reference image should be e.g. 350x495 for a 640x480 webcam used in Unifeye Viewer Shockwave or 100x141 for a 320x240 webcam used in Unifeye Viewer Flash. See also the notes above.
  2. Some reference images (especially for Unifeye Viewer Flash) might require some tweaking if they are not working well. An easy approach is to take only a certain part of the image (so cut it out using an image editing software like Paint.NET) for tracking. Usually you should take a region which is sufficiently well textured. When doing this make sure to also adjust the width and height (in mm) values inside the tracking configuration file to reflect to potential change in the aspect ratio when cutting out the image:
     
  3. (A x B) such that min(A,B) = pow(2,n)*25, where n is a positive integer. “Good sizes” would be: (A x B) where min(A,B) is equal to 25, 50, 100, 200, 400,... or slightly above, i.e. (A x B) where min(A,B) is equal to 26, 52, 105, 1606,... Avoid using sizes in-between or sizes that are slightly below these values. "Bad sizes" would be: (A x B) where min(A,B) is, for example, equal to: 47, 98, 300, 1500, …
  4. For optimal performance, additionally, choose min(A,B) close to max(A,B). Example of optimal sizes are: (100 x 100), (200 x 200), …. Please note that condition 2. only makes sense if condition 1. is fulfilled.

Hotspot-based gesture tracking (Flash only!)

You can use gesture tracking to add interaction by "touching" virtual buttons with your hands. You can create a virtual button by creating a "hotspot". A "hotspot" is basically a rectangular area in the tracking image which is analyzed in order to detect changes.

Examples:

In Flash/examples/FlashSimpleGesture there is an example project, that uses the hotspot-based gesture tracking.

Important:

• Note: At the moment this feature is available in the Flash version of Unifeye Viewer only.

How to setup hotspot gesture tracking:

1. Setup a camera to get images from.
   • Note: You can e.g. use the metaio.camera.ARCamera-class or any other class that provides an appropriate interface. You will need your image as ByteArray later on.
2. Create a new metaio.tracking.HotspotTracker.
3. Create one or more hotspots using the createCamHotspot()-method of your HotspotTracker-instance.
   • Note: Don't create instances of the Hotspot-class on your own - always use this method.
4. Create callback-functions for each Hotspot using addEventListener() with the following events:
   1. HotspotEvent.HAND_ENTER
   2. HotspotEvent.HAND_OVER
   3. HotspotEvent.HAND_LEAVE
5. In the onEnterFrame-function of your application (or wherever you check for new pictures from your camera):
   1. Grab an image from the camera as ByteArray.
      • Note: If you are using the ARCamera-class: use getCurrentFrame().
   2. Call the trackFrame()-method of the HotspotTracker-instance.
      • Note: The tracking is based on a reference image, which is taken automatically on the first call of trackFrame(). You can also do this manually by calling takeReferenceSnapshot() with your desired reference image as parameter.
   3. Wait for events.

→Return to Overview

-- SupportMetaio - 2010-08-12