Packageat.imagination.flare
Classpublic class FlareTracker
InheritanceFlareTracker Inheritance Object
Implements IFlareTracker

FlareTracker is a wrapper class providing convenient methods to use the functions provided by libFlareTracker. For an example on how to use it see samples/TestTracker.


Public Methods
 MethodDefined By
  
FlareTracker()
constructor
FlareTracker
  
addMarkerDetector(markerType:uint, param1:Number = 0, param2:Number = 0):Boolean
Adds a marker detector to the tracker.
FlareTracker
  
getDataMatrixMessage(index:uint):String
Returns the message encoded in a data matrix marker.
FlareTracker
  
getProjectionMatrix():ByteArray
Returns the projection matrix.
FlareTracker
  
getTrackerResults():ByteArray
Returns the tracking results.
FlareTracker
  
getTrackerResults2D():ByteArray
Returns the 2d-tracking results.
FlareTracker
  
getVersion():String
Returns the version of flareTracker
FlareTracker
  
init(stage:Stage, dataPath:String, camFile:String, camWidth:uint, camHeight:uint, initDoneCB:Function):void
Initializes the tracker.
FlareTracker
  
setLogger(obj:Object, logger:Function, level:uint):void
Sets a logging function: Use this to display logging output from libFlareTracker.
FlareTracker
  
update(image:BitmapData):uint
This method needs to be called every frame to obtain the tracking results.
FlareTracker
Public Constants
 ConstantDefined By
  MARKER_BCH : int = 2
[static] The FlareTracker.MARKER_BCH constant defines the value of the markerType property returned by getTrackerResults() when a BCH marker is found.
FlareTracker
  MARKER_BCH2 : int = 3
[static] The FlareTracker.MARKER_BCH2 constant defines the value of the markerType property returned by getTrackerResults() when a BCH2 marker is found.
FlareTracker
  MARKER_DATAMATRIX : int = 6
[static] The FlareTracker.MARKER_DATAMATRIX constant defines the value of the markerType property returned by getTrackerResults() when a data matrix marker is found.
FlareTracker
  MARKER_FRAME : int = 4
[static] The FlareTracker.MARKER_FRAME constant defines the value of the markerType property returned by getTrackerResults() when a frame marker is found.
FlareTracker
  MARKER_SIMPLE_ID : int = 1
[static] The FlareTracker.MARKER_SIMPLE_ID constant defines the value of the markerType property returned by getTrackerResults() when a simple-id marker is found.
FlareTracker
  MARKER_SPLIT : int = 5
[static] The FlareTracker.MARKER_SPLIT constant defines the value of the markerType property returned by getTrackerResults() when a split marker is found.
FlareTracker
  MARKER_UNDEFINED : int = 0
[static] The FlareTracker.MARKER_UNDEFINED constant defines the value of the markerType property returned by getTrackerResults() when a marker of an unkown type is found.
FlareTracker
Constructor Detail
FlareTracker()Constructor
public function FlareTracker()

constructor

Method Detail
addMarkerDetector()method
public function addMarkerDetector(markerType:uint, param1:Number = 0, param2:Number = 0):Boolean

Adds a marker detector to the tracker. The following marker types are supported: simple id, BCH, BCH2, frame marker, split marker, data matrix marker. Call this method once for every marker type you want to track for.

Parameters

markerType:uint — Type of marker to track for. Pass one of the following values:
  • FlareTracker::MARKER_SIMPLE_ID to detect simple id markers.

    param1 specifies the border width of the marker - more precisely this is the ratio borderWidth/markerWidth. If this parameter is not passed, a default value of 0.125 is used.

    param2 specifies the width of the marker in millimeters. If this parameter is not passed, a default value of 80 is used.

  • FlareTracker::MARKER_BCH to detect BCH markers.

    param1 specifies the border width ratio (defaults to 0.125)

    param2 specifies the width of the marker in millimeters (defaults to 80)

  • FlareTracker::MARKER_BCH2 to detect BCH2 markers.

    param1 specifies the border width ratio (defaults to 0.1875)

    param2 specifies the width of the marker in millimeters (defaults to 80)

  • FlareTracker::MARKER_FRAME to detect frame markers.

    param1 specifies the border width ratio (defaults to 0.04545)

    param2 specifies the width of the marker in millimeters (defaults to 100)

  • FlareTracker::MARKER_SPLIT to detect split markers.

    param1 specifies the width of the marker in millimeters (defaults to 61)

    param2 specifies the height of the marker in millimeters (defaults to 90)

  • FlareTracker::MARKER_DATAMATRIX to detect data matrix markers.

    param1 specifies the border width ratio (defaults to 0.035)

    param2 is not used.

 
param1:Number (default = 0) — The use of this parameter depends on the marker type (see description above).
 
param2:Number (default = 0) — The use of this parameter depends on the marker type (see description above).

Returns
Boolean — true on success.
getDataMatrixMessage()method 
public function getDataMatrixMessage(index:uint):String

Returns the message encoded in a data matrix marker. Call this method after update() found one or more targets.

Parameters

index:uint — Retrieves the message for the data matrix marker at position index. Where index is smaller than the number of targets returned by update().

Returns
String — Message encoded in data matrix marker, or null if no message is found. null is also returned if index doesn't point to a marker of type data matrix.
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 = flareTrackerTracker.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: 
	    markerType:int;          // type of marker, can be one of the following:
	                             //   MARKER_SIMPLE_ID
	                             //   MARKER_BCH
	                             //   MARKER_BCH2
	                             //   MARKER_FRAME
	                             //   MARKER_SPLIT
	                             //   MARKER_DATAMATRIX
	    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 markerType:int;
	    var targetID:int;
	    var mat:Matrix3D = new Matrix3D();
	    var numTargets:uint = flareTrackerTracker.update(bitmap);
	    var targetData:ByteArray = flareTrackerTracker.getTrackerResults();
       
	    // iterate over all visible targets
	    for (var i:uint = 0; i < numTargets; i++)
	    {
	      markerType = targetData.readInt();
	      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(markerType, 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: 
	    markerType:int;      // type of marker, can be one of the following:
	                         //   MARKER_SIMPLE_ID
	                         //   MARKER_BCH
	                         //   MARKER_BCH2
	                         //   MARKER_FRAME
	                         //   MARKER_SPLIT
	                         //   MARKER_DATAMATRIX
	    targetID:int;        // unique identifier of the target
	   
	                    // corner points of the rectangular marker 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 flareTracker

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, initDoneCB:Function):void

Initializes the tracker. This needs to be called before any other method is called (with the exception of getVersion() amd setLogger())

Parameters

stage:Stage — The application's stage.
 
dataPath:String — Path were the datafiles (camera ini-file and license file) are located.
 
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.
 
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

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

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

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 libFlareTracker. 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.
Constant Detail
MARKER_BCHConstant
public static const MARKER_BCH:int = 2

The FlareTracker.MARKER_BCH constant defines the value of the markerType property returned by getTrackerResults() when a BCH marker is found.

MARKER_BCH2Constant 
public static const MARKER_BCH2:int = 3

The FlareTracker.MARKER_BCH2 constant defines the value of the markerType property returned by getTrackerResults() when a BCH2 marker is found.

MARKER_DATAMATRIXConstant 
public static const MARKER_DATAMATRIX:int = 6

The FlareTracker.MARKER_DATAMATRIX constant defines the value of the markerType property returned by getTrackerResults() when a data matrix marker is found.

MARKER_FRAMEConstant 
public static const MARKER_FRAME:int = 4

The FlareTracker.MARKER_FRAME constant defines the value of the markerType property returned by getTrackerResults() when a frame marker is found.

MARKER_SIMPLE_IDConstant 
public static const MARKER_SIMPLE_ID:int = 1

The FlareTracker.MARKER_SIMPLE_ID constant defines the value of the markerType property returned by getTrackerResults() when a simple-id marker is found.

MARKER_SPLITConstant 
public static const MARKER_SPLIT:int = 5

The FlareTracker.MARKER_SPLIT constant defines the value of the markerType property returned by getTrackerResults() when a split marker is found.

MARKER_UNDEFINEDConstant 
public static const MARKER_UNDEFINED:int = 0

The FlareTracker.MARKER_UNDEFINED constant defines the value of the markerType property returned by getTrackerResults() when a marker of an unkown type is found.




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

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