FLARManager documentation

 

FLARManager API Documentation

The complete FLARManager ASDoc reference can be found here:
http://transmote.com/flar/reference

 

FLARManager config file

The preferred method for initializing FLARManager is to pass the path to an external XML configuration file into the FLARManager constructor:

var flarManager:FLARManager = new FLARManager("flarConfig.xml", new FlareManager(), this.stage);

In the FLARManager distribution, flarConfig.xml is located in /resources/flar/, so the whole path relative to the bin-debug folder is ../resources/flar/flarConfig.xml, which yields:
new FLARManager("../resources/flar/flarConfig.xml", new FlareManager(), this.stage);

The configuration file can be called whatever you like, as long as you format it according to the following specifications. There are three primary elements; each node accepts a number of attributes and child elements. The top-level elements and their attributes and child elements are listed below. Required elements and attributes are marked as such; if a non-required attribute is omitted, its default value will be used.


Configuration File Index

 


 


Configuration File Details

 

<flarSourceSettings>

This primary element contains configuration settings for the source which the tracker will analyze for objects to track, and configuration settings for displaying the source on-screen.

<flarSourceSettings> attributes

  • displayWidth:Number=640
    Width at which to display video.
     
  • displayHeight:Number=480
    Height at which to display video.
     
  • framerate:Number=30
    Framrerate at which to capture video. This is the value passed to Camera.setMode() in FLARCameraSource.as.
     
  • loaderPath:String=""
    If this value is set, FLARManager will create a FLARLoaderSource instead of the default FLARCameraSource. The file located at this path will be used by the FLARLoaderSource.
     
  • sourceWidth:Number=640
    Width at which to capture video. This is the value passed to Camera.setMode() in FLARCameraSource.as.
     
  • sourceHeight:Number=480
    Height at which to capture video. This is the value passed to Camera.setMode() in FLARCameraSource.as.
     
  • trackerToSourceRatio:Number=0.5
    The source image/video used for tracking is scaled by this value before being sent to the tracker for analysis. Tracking libraries run faster with more downsampling, but also have more difficulty recognizing object patterns/features. A value of 1.0 results in no downsampling; a value of 0.5 (the default) downsamples the source by half.
     
  • useProxy:Boolean=false
    If true, FLARManager will create a FLARProxy instead of the default FLARCameraSource.
     
  • activityThreshold:int=16
    When camera.activityLevel is less than this value, the source will not be sent to FLARToolkit. This freezes the marker in place when there is very little motion, and also stops tracking to boost framerates.

    Defaults to 16; valid values range from 0 (no suppression) to 100 (full suppression). Set higher to further reduce jitter in stationary markers, and set lower to allow more freedom of motion with stationary markers.

    Thanks to Deepanjan Das for this idea

<flarSourceSettings> children
none.

 


<flarManagerSettings>

This primary element contains configuration settings for FLARManager, which determine how FLARManager manages and reports data of tracked objects reported by the tracker.

<flarManagerSettings> attributes

  • adaptiveSmoothingCenter:Number=10
    The amount of smoothing applied to marker motion varies depending on the amount of motion. Slow-moving markers are smoothed more, helping to ease jitter on near-stationary markers, while faster-moving markers are smoothed less, in order to maintain responsiveness at higher speeds.

    Smoothing at a marker speed of FLARManager.adaptiveSmoothingCenter is equal to FLARManager.smoothing. Set FLARManager.adaptiveSmoothingCenter to 0 to turn adaptive smoothing off.
     

  • inverted:Boolean=true
    If true, FLARManager will invert the source image/video and detect markers with white borders instead of black borders.
     
  • markerExtrapolation:Boolean=true
    If true, marker extrapolation is enabled. With marker extrapolation, fast-moving markers that are lost by the tracker due to blur can continue their motion along the same speed and direction without being reported as removed. Marker extrapolation continues until the marker is picked back up by the tracker, or FLARManager.markerRemovalDelay frames have expired.
     
  • markerMode:int=FLARManager.TRACKING_MODE_SINGLE
    FLARManager uses markerMode and patternMode to determine how to handle detected markers. Acceptable values for xml are "SINGLE" and "MULTI".

    FLARManager defaults to "SINGLE" for markerMode and "MULTI" for patternMode. For more information on the various combinations, view the online docs.
     

  • markerRemovalDelay:int=1
    Number of frames after removal that a marker will persist before dispatching a MARKER_REMOVED event.
     
  • markerUpdateThreshold:Number=80
    If a detected marker is within this distance (pixels) from an active marker, FLARManager considers the detected marker to be an update of the active marker. Else, the detected marker is a new marker. Increase this value to accommodate faster-moving markers; decrease it to accommodate more markers on-screen at once.
     
  • mirrorDisplay:Boolean=true
    If true, video and detected marker data are flipped horizontally.
     
  • sampleBlurring:int=1
    The amount of blur applied to the source image before sending to the tracker for marker detection. Higher values increase framerate, but reduce detection accuracy.
     
  • patternMode:int=FLARManager.TRACKING_MODE_MULTI
    FLARManager uses markerMode and patternMode to determine how to handle detected markers. See markerMode for more info.
     
  • smoothing:int=3
    Apply a smoothing algorithm to transformation matrices generated by the tracker. Smoothing is equal to the number of frames over which FLARManager will average transformation matrices; the larger the number, the smoother the animation, and the slower the response time between marker position/orientation changes. A value of 0 turns smoothing off.
     

<flarManagerSettings> children

 
<flarManagerSettings><smoother>
IFLARMatrixSmoother to use to apply smoothing to transformation matrices generated by the tracker. This defaults to FLARMatrixSmoother_Average, but developers can implement their own smoothing algorithms. See Inside FLARManager: Customization for more information.

<smoother> attributes

  • className:String='FLARMatrixSmoother_Average'
    The name of the smoother class to use. If the class resides somewhere other than com.transmote.flar.utils.smoother, a fully-qualified class name must be used.
     
  • ...rest:Object=null
    All other attributes are passed into the initFromXML() method of the specified smoother.
     

<smoother> children
none.

 
<flarManagerSettings><thresholdAdapter>
Adaptive thresholding 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.

The default threshold adapter is DrunkHistogramThresholdAdapter, but developers can implement their own adaptive thresholding algorithms. See Inside FLARManager: Customization for more information.

<thresholdAdapter> attributes

  • className:String='DrunkHistogramThresholdAdapter'
    The name of the threshold adapter class to use. If the class resides somewhere other than com.transmote.flar.utils.threshold, a fully-qualified class name must be used.
     
  • ...rest:Object=null
    All other attributes are passed into the initFromXML() method of the specified threshold adapter.
     

<thresholdAdapter> children
none.

 


<trackerSettings>

This primary element contains configuration settings for the selected tracking library.

<trackerSettings> attributes
none.

 
<trackerSettings> children

 
<trackerSettings><flareSettings>
This element contains configuration settings for the flare*tracker and flare*NFT tracking libraries. Developers only need to include this element when using flare*tracker or flare*NFT.

<flareSettings> attributes

  • cameraParamsFile
    –REQUIRED (for flare*tracker / flare*NFT)–
    The camera parameters file, within the resources path (see below). flare*tracker and flare*NFT need this information to initialize and run.
     
  • resourcesPath
    The path (relative to the application .swf) to the folder that contains flare*tracker-related resources, including the license (.lic) and camera parameters (cam.ini) files. For flare*NFT applications, this folder will also contain the data for the targets to track (featureSet.ini and *.spil files).
     

<flareSettings> children

 
<trackerSettings><flareSettings><nftSettings>
This element contains flare*NFT-specific configuration settings.

<nftSettings> attributes

  • featureSetFile
    –REQUIRED (for flare*NFT)–
    The feature set file. flare*NFT needs the feature set data to track NFT targets.
     
  • framerate:Number=30
    The framerate at which flare*NFT will attempt to track targets.
     
  • multiTargets:Boolean=false
    If true, flare*NFT will run in multiple-target mode, which allows the tracker to respond to more than one discrete target at once. This mode requires more processing power and therefore runs somewhat slower than single-target mode (the default).
     

 
<nftSettings> children
none.

 
<trackerSettings><flarToolkitSettings>
This element contains configuration settings for the FLARToolkit tracking library. Developers only need to include this element when using FLARToolkit.

<flarToolkitSettings> attributes

  • cameraParamsFile:String=""
    –REQUIRED (for FLARToolkit)–
    The path (relative to the application .swf) to the FLARToolkit camera parameters file (e.g. FLARCameraParams.dat or camera_para.dat). FLARToolkit requires this file to initialize and run.
     
  • labelAreaMin
    Minimum size (width*height) a dark area of the source image must be in order to become a candidate for marker outline detection.
    Higher values result in faster performance, but poorer marker detection at smaller on-screen sizes.
     
  • labelAreaMax
  • Maximum size (width*height) a dark area of the source image can be in order to become a candidate for marker outline detection.
    Lower values result in faster performance, but poorer marker detection at larger on-screen sizes.
     

  • thresholdSourceDisplay:Boolean=true
    If true, FLARManager will display the source as thresholded just before marker detection. Useful for debugging.
     

 
<flarToolkitSettings> children

 
<trackerSettings><flarToolkitSettings><patterns>
–REQUIRED (for FLARToolkit)–
This element describes all of the ARToolkit-style marker patterns that FLARToolkit will attempt to detect. FLARToolkit will detect only the patterns listed within this element. If this element is omitted, FLARToolkit will not attempt to track any patterns.

<patterns> attributes

  • resolution:int=0
    –REQUIRED (for FLARToolkit)–
    Resolution (width/height) of marker pattern files. All patterns in a single application must share the same resolution; this is mandated by FLARToolkit. For more information about pattern resolution, see here.
     
  • patternToBorderRatioX:Number=50
    Out of the entire width of a marker, the amount that the pattern occupies relative to the amount the border occupies. Value is expressed as a percentage (0-100). For example, a value of 50 indicates that the width of the pattern area is equal to the total width (on either side of the pattern) of the border.
    Note that the border must still be a square (equal width and height).
     
  • patternToBorderRatioY:Number=50
    Out of the entire height of a marker, the amount that the pattern occupies relative to the amount the border occupies. Value is expressed as a percentage (0-100). For example, a value of 50 indicates that the height of the pattern area is equal to the total height (on either side of the pattern) of the border.
    Note that the border must still be a square (equal width and height).
     
  • minConfidence:Number=0.5
    ‘Confidence’ is a value (from 0.0 to 1.0) assigned by FLARToolkit to each detected marker, that describes the algorithm’s perceived accuracy of the pattern match. This value sets the minimum confidence required to signal a recognized marker. Lower values will be more likely to detect both real markers and false positives; higher values will be less likely to detect both real markers and false positives.
     

 
<patterns> children

 
<trackerSettings><flareSettings><patterns><pattern>
Each <pattern> node represents a pattern that FLARToolkit will attempt to detect. FLARToolkit can look for an unlimited number of patterns, but as it attempts to match each detected marker against all possible patterns, more patterns mean slower pattern matching (and ultimately, slower overall performance). Developers should keep this list as short as possible for each application.

<pattern> attributes

  • path:String
    –REQUIRED (for FLARToolkit)–

    The path to the associated pattern file (relative to the published SWF). The path to the pattern file must be specified for FLARToolkit to track the pattern.
     
  • size:Number=80
    The width of a marker (in pixels) on-screen at which the scale of its transformation matrix is 1.0. This can be used to adjust the size that a mode will appear on-screen. If a model is appearing too large, decrease this number, and vice-versa.
     

 
<pattern> attributes
none.