transmote speaks…

<– Tracking Engines | FLARManager Miscellany –>
 
You’ve made little cubes, you’ve made sophisticated collada models, and you want to get more out of your tracking library. More fine-tuning, more control. FLARManager offers it in spades.

Read on to learn how to fully customize FLARManager to work exactly how you want it to, for your custom flash augmented reality applications.

 

Creating custom markers (FLARToolkit)

Many people have been asking about best practices for customizing FLARToolkit markers. I think squidder pretty much nailed it with this post, but i’ll provide a quick digest below.

Start with tarotaro’s most excellent online marker generator. This tool allows you to either capture printed patterns with your camera or load them from image files. Loading from a non-lossy format (like PNG or GIF) is the best option, and will give the cleanest results. I highly recommend loading an image file, rather capturing from a camera.

Make sure you select the proper resolution for your pattern. This refers to the resolution of the pattern image, and has nothing to do with the physical size of the marker. Lower pattern resolutions result in faster and more accurate marker detection. I don’t recommend you go above 16×16; performance degrades noticeably above that. FLARManager’s examples and tutorials use 8×8 patterns — I found this to be the best balance of pattern variety and appearance with performance and reliability of marker detection. Specify your chosen resolution via the ‘Marker segments’ dropdown in the marker generator.

Once you’ve created your pattern files and chosen your resolution, you need to add your new pattern file to FLARManager’s external configuration xml file (named flarConfig.xml by default). In the <trackerSettings><flarToolkitSettings><patterns> element, enter the pattern resolution as the resolution attribute. Note that *all* of the patterns specified in flarConfig.xml must have the same resolution. This is a restriction imposed by FLARToolkit. If any of the patterns are not of the same resolution as the others, FLARToolkit will throw a runtime error.

There is also a thread on the FLARToolkit forums that goes a bit more in-depth into the process of creating custom markers here.

 

Creating a custom smoother

FLARManager applies smoothing to the transformation matrices generated by the tracker, in order to ease jitter and even out jerkiness in marker motion. Smoothing is executed, by default, by FLARMatrixSmoother_Average, but developers can implement their own smoothing algorithms.

To create a custom smoothing algorithm, create a new class that implements IFLARMatrixSmoother. The interface requires three methods:

• initFromXML accepts an object containing name-value pairs used for initialization. This method is required, but implementation can be left empty.
• smoothMatrices is the workhorse of any custom smoothing algorithm; it is called every time a marker updates its position.
• dispose frees the algorithm instance for garbage collection, so that a FLARManager instance can be properly disposed.

To implement a custom smoothing algorithm, create an instance of the custom smoothing class, and store it as FLARManager.smoother.

Alternatively, add a <flarManagerSettings><smoother> element to your configuration xml file. Specify the name of the new class as a className attribute of this node. (If the class resides somewhere other than com.transmote.flar.utils.smoother, a fully-qualified class name must be used.) Specify name-value pairs to be sent to initFromXML as attributes of this node. For example, FLARManager’s default setup is equivalent to adding:
<smoother className='FLARMatrixSmoother_Average'>
to the configuration xml file.

NOTE: if you choose to specify a custom smoother class via the configuration xml file, you must create a reference to the class somewhere in your project, to ensure that it is compiled in your SWF. Otherwise, instantiation will fail. For example, add:
MyCustomSmoother;
anywhere in your code.

Creating a custom threshold adapter

FLARManager employs an algorithm to automatically change the threshold value applied by FLARToolkit as the first step in analyzing the camera image every frame. This is called “adaptive thresholding”, and can result in better marker detection across a range of illumination. This is desirable for applications with low lighting, or in which the developer has little control over lighting conditions, such as with web applications. By default, FLARManager uses DrunkHistogramThresholdAdapter, but developers can implement their own adaptive thresholding algorithms.

NOTE: flare*tracker and flare*NFT perform adaptive thresholding internally, and the thresholdAdapter is disabled when using these tracking libraries.

To create a custom adaptive thresholding algorithm, create a new class that implements IThresholdAdapter. The interface requires five methods:

• initFromXML accepts an object containing name-value pairs used for initialization. this method is required, but implementation can be left empty.
• calculateThreshold is the workhorse of any custom adaptive thresholding algorithm. It can either calculate a new threshold to pass into the tracker, or apply thresholding directly to the BitmapData source instead of allowing the tracker to do so. If it directly modifies the source, this method should return -1 to signal the tracker to skip its internal thresholding.
• resetCalculations is called when marker confidence levels increase (e.g. when a new marker is detected).
• runsEveryFrame determines the frequency at which calculateThreshold will be called.
• dispose frees the algorithm instance for garbage collection, so that a FLARManager instance can be properly disposed.

To implement a custom adaptive thresholding algorithm, create an instance of the custom adaptive thresholding class, and store it as FLARManager.thresholdAdapter. Alternatively, add a <flarManagerSettings><thresholdAdapter> element to your configuration xml file. Specify the name of the new class as a className attribute of this element. (If the class resides somewhere other than com.transmote.flar.utils.threshold, a fully-qualified class name must be used.) Specify name-value pairs to be sent to initFromXML as attributes of this node. For example, FLARManager’s default setup is equivalent to adding:
<thresholdAdapter className='DrunkHistogramThresholdAdapter'>
to the configuration xml file.

Note that if you choose to specify a custom threshold adapter class via the configuration xml file, you must create a reference to the class somewhere in your project, to ensure that it is compiled in your SWF. Otherwise, instantiation will fail. For example, add:
MyCustomThresholdAdapter;
anywhere in your code.

 
 
<– Tracking Engines | FLARManager Miscellany –>