Packageat.imagination.flare
Classpublic class FlareNFT
InheritanceFlareNFT Inheritance Object
Implements IFlareTracker

FlareNFT is a wrapper class providing convenient methods to use the functions provided by libFlareNFT. For an example on how to use it see samples/TestNFT.


Public Methods
 MethodDefined By
  
FlareNFT()
FlareNFT
  
addButton(targetID:uint, x0:Number, y0:Number, x1:Number, y1:Number, minCoverage:Number = 0, minBlockedFrames:uint = 0, historyLength:uint = 0):int
Adds a virtual button to a target.
FlareNFT
  
getProjectionMatrix():ByteArray
Returns the projection matrix.
FlareNFT
  
getTrackerResults():ByteArray
Returns the tracking results.
FlareNFT
  
getTrackerResults2D():ByteArray
Returns the 2d-tracking results.
FlareNFT
  
getVersion():String
Returns the version of flareNFT
FlareNFT
  
init(stage:Stage, dataPath:String, camFile:String, camWidth:uint, camHeight:uint, camFPS:uint, featureSetFile:String, multiTargets:Boolean, initDoneCB:Function):void
Initializes the tracker.
FlareNFT
  
setButtonHandler(obj:Object, handler:Function):void
Sets a button handler that will be invoked if a virtual button that was defined with the function addButton() was pressed or released.
FlareNFT
  
setLogger(obj:Object, logger:Function, level:uint):void
Sets a logging function: Use this to display logging output from libFlareNFT.
FlareNFT
  
update(image:BitmapData):uint
This method needs to be called every frame to obtain the tracking results.
FlareNFT
Constructor Detail
FlareNFT()Constructor
public function FlareNFT()



Method Detail
addButton()method
public function addButton(targetID:uint, x0:Number, y0:Number, x1:Number, y1:Number, minCoverage:Number = 0, minBlockedFrames:uint = 0, historyLength:uint = 0):int

Adds a virtual button to a target. A virtual button is a rectangular area on the target that will be checked at runtime for occlusion.

If this area is covered (e.g. by moving your finger over the button), a button press event is generated and the button handler function that was defined with setButtonHandler() is called. A release event is triggered when the button is uncovered again.

Parameters

targetID:uint — The id of the target to add a button for. To find out the id of a target image, look at the assignments in the feature-set file.
 
x0:Number — The x-coordinate of the upper-left corner of the button
 
y0:Number — The y-coordinate of the upper-left corner of the button
 
x1:Number — The x-coordinate of the lower-right corner of the button
 
y1:Number — The y-coordinate of the lower-right corner of the button
 
minCoverage:Number (default = 0) — The percentage of the area that needs to be covered to set the button's state to "blocked". This is a float value greater than 0 (0%) and smaller than 1 (100%). If 0 is passed or the value is omitted, a default coverage value of 0.7 (70%) is assumed.
 
minBlockedFrames:uint (default = 0) — Number of frames during an observation period of historyLength frames the button has to be in blocked state in order to trigger a button press event. If 0 is passed or the value is omitted, a default value of 12 is assumed.
 
historyLength:uint (default = 0) — Length of the observation period of a button's state. The shorter the history, the faster the button will react with a press or release event. However, if the history is too short, "false" events may occur, resulting in a jitter-like behavior. If the history is to long, the events will be very stable, but the button will react with a considerable delay. The length of the delay is historyLength/frameRate seconds. If 0 is passed or the value is omitted, a default value of 15 is assumed.

Returns
int — The id of the new button is returned. If the function fails, -1 is returned.
getProjectionMatrix()method 
public function getProjectionMatrix():ByteArray

Returns the projection matrix. Since the camera doesn't move during tracking, this needs to be called only once after init() to obtain the projection matrix.

Returns
ByteArray — The matrix is retured as a ByteArray containing 4x4 Numbers.

Example
To set the projection matrix for a camera in papervison3D, you would do the following: 
	    var mat:ByteArray = flareTrackerNFT.getProjectionMatrix();
	    var proj:Matrix3D = (_camera as Camera3D).projection;
	   
	    proj.n11 =  mat.readFloat();
	    proj.n21 = -mat.readFloat();
	    proj.n31 =  mat.readFloat();
	    proj.n41 =  mat.readFloat();
	   
	    proj.n12 =  mat.readFloat();
	    proj.n22 = -mat.readFloat();
	    proj.n32 =  mat.readFloat();
	    proj.n42 =  mat.readFloat();
	   
	    proj.n13 =  mat.readFloat();
	    proj.n23 = -mat.readFloat();
	    proj.n33 =  mat.readFloat();
	    proj.n43 =  mat.readFloat();
	   
	    proj.n14 =  mat.readFloat();
	    proj.n24 = -mat.readFloat();
	    proj.n34 =  mat.readFloat();
	    proj.n44 =  mat.readFloat();
Note that the 2nd row is inverted, because we need to convert from a right-handed coordinate system (used by flare) to a left-handed coordinate system (used by papervison3D).
getTrackerResults()method 
public function getTrackerResults():ByteArray

Returns the tracking results. Call this method after update() found one or more targets.

Returns
ByteArray — The tracking results are returned as a ByteArray structure of the following form: 
	    reserved:int;            // reserved for later use
	    targetID:int;            // unique identifier of the target
	   
	    poseMatrix_11:Number;    // pose matrix: model view matrix of target in 3D space
	    poseMatrix_21:Number;
	    poseMatrix_31:Number;
	    poseMatrix_41:Number;
	   
	    poseMatrix_12:Number;
	    poseMatrix_22:Number;
	    poseMatrix_32:Number;
	    poseMatrix_42:Number;
	   
	    poseMatrix_13:Number;
	    poseMatrix_23:Number;
	    poseMatrix_33:Number;
	    poseMatrix_43:Number;
	   
	    poseMatrix_14:Number;
	    poseMatrix_24:Number;
	    poseMatrix_34:Number;
	    poseMatrix_44:Number;
This structure is repeated in the ByteArray for every target found.

Example
This example shows how the tracker results can be parsed. 
	    var targetID:int;
	    var mat:Matrix3D = new Matrix3D();
	    var numTargets:uint = flareTrackerNFT.update(bitmap);
	    var targetData:ByteArray = flareTrackerNFT.getTrackerResults();
       
	    // iterate over all visible targets
	    for (var i:uint = 0; i < numTargets; i++)
	    {
	      targetData.readInt();		// unused
	      targetID = targetData.readInt();
       
	      // read pose matrix (= model view matrix)
	      mat.n11 =  targetData.readFloat();
	      mat.n21 = -targetData.readFloat();
	      mat.n31 =  targetData.readFloat();
	      mat.n41 =  targetData.readFloat();
       
	      mat.n12 =  targetData.readFloat();
	      mat.n22 = -targetData.readFloat();
	      mat.n32 =  targetData.readFloat();
	      mat.n42 =  targetData.readFloat();
       
	      mat.n13 =  targetData.readFloat();
	      mat.n23 = -targetData.readFloat();
	      mat.n33 =  targetData.readFloat();
	      mat.n43 =  targetData.readFloat();
       
	      mat.n14 =  targetData.readFloat();
	      mat.n24 = -targetData.readFloat();
	      mat.n34 =  targetData.readFloat();
	      mat.n44 =  targetData.readFloat();
       
	      // show target object and apply transformation
	      showObject(targetID, mat);
	    }
The 2nd row of the pose matrix is inverted to convert from a right-handed coordinate system to a left-handed coordinate system.
getTrackerResults2D()method 
public function getTrackerResults2D():ByteArray

Returns the 2d-tracking results. Call this method after update() found one or more targets.

Returns
ByteArray — The 2d-tracking results are returned as a ByteArray structure of the following form: 
	    reserved:int;        // reserved for later use
	    targetID:int;        // unique identifier of the target
	   
	                    // corner points of the target in image space
	    cornerUL_x:Number;   // upper left corner point
	    cornerUL_y:Number;
	   
	    cornerUR_x:Number;   // upper right corner point
	    cornerUR_y:Number;
	   
	    cornerLR_x:Number;   // lower right corner point
	    cornerLR_y:Number;
	   
	    cornerLL_x:Number;   // lower left corner point
	    cornerLL_y:Number;
This structure is repeated in the ByteArray for every target found.
getVersion()method 
public function getVersion():String

Returns the version of flareNFT

Returns
String — Version number as String formatted as major.minor.build
init()method 
public function init(stage:Stage, dataPath:String, camFile:String, camWidth:uint, camHeight:uint, camFPS:uint, featureSetFile:String, multiTargets:Boolean, initDoneCB:Function):void

Initializes the tracker. This needs to be called before update()

Parameters

stage:Stage — Path were all the datafiles (camera ini-file, feature-set file, database files and pgm-files) are located.
 
dataPath:String — The application's stage.
 
camFile:String — Name of the camera initalization file.
 
camWidth:uint — Width of the camera input in pixels.
 
camHeight:uint — Height of the camera input in pixels.
 
camFPS:uint — Frames per second.
 
featureSetFile:String — Name of the feature set file.
 
multiTargets:Boolean — Set this to true if multiple targets should be tracked. This is only necessary, if we want to display more than one targets at the same time.
 
initDoneCB:Function — Callback function to be invoked, when initialization has finished. This is necessary, because all input files will be loaded asynchronously before libFlareNFT can initialize the tracker. The function must be of type function():void

setButtonHandler()method 
public function setButtonHandler(obj:Object, handler:Function):void

Sets a button handler that will be invoked if a virtual button that was defined with the function addButton() was pressed or released.

Parameters

obj:Object — If the button handler is a method of an object, set this to the method's object. Otherwise pass null
 
handler:Function — The callback function that will be invoked whenever a virtual button was pressed or released. The function must be of type function(uint, uint, Boolean):void.

As first argument to the callback function the id of the button's target will be passed. The second argument is the button's id. The third argument is either true (button was pressed) or false (button was released).

setLogger()method 
public function setLogger(obj:Object, logger:Function, level:uint):void

Sets a logging function: Use this to display logging output from libFlareNFT.

Parameters

obj:Object — If the logging function is a method of an object, set this to the method's object. Otherwise pass null
 
logger:Function — The logging function that will be called from libFlareNFT. The function must be of type function(int, String):void
 
level:uint — Only produce logging output for log-levels <= level

update()method 
public function update(image:BitmapData):uint

This method needs to be called every frame to obtain the tracking results.

Parameters

image:BitmapData — The bitmap grabbed from the camera.

Returns
uint — Number of targets found.



FLARManager is released under the GNU GPL: http://www.gnu.org/licenses

Sun Jan 30 2011, 04:49 PM -08:00