FLARManager v0.4 (for FLARToolkit)

flarmanager_v04

i’m pleased to announce the release of a new-and-improved version of FLARManager! this one has been a while in the works, due in part to general busy-ness, in part to my laptop threatening death, and in part to the fact that there are SO MANY NEW FEATURES.

download here:
http://words.transmote.com/wp/flarmanager/
(NOTE, this is now pointing to version 0.41, which is required for the new tutorials.)

quick description of FLARManager:
FLARManager is a small framework that makes building FLARToolkit applications easier. it also decouples the marker-tracking functionality from Papervision3D, and provides a more robust event-based system for managing marker addition, update, and removal. it supports detection and management of multiple patterns, and multiple markers of a given pattern.

 
here’s a rundown on the most interesting new stuff:
 
[matrix-level smoothing]
FLARManager now applies smoothing to the matrix values reported by FLARToolkit for detected markers; this helps to clear up jitter in rotation, scaling, and position. developers can set the amount of smoothing, and easily implement their own smoothing algorithms.

[external configuration]
devs now have the option to specify many configuration settings via an xml file that does not require app recompilation. among the settable features are capture and display width/height, display mirroring, matrix smoothing, and pattern and camera param file paths.

[easier access to detected marker data]
FLARMarker instances, accessible via FLARMarkerEvents, now expose (x,y,z) location (via a Flash Player 10 Vector3D object), rotation on the x, y, and z axes, and the (x,y) coordinate of the marker’s centerpoint. this opens the door to applications that use FLARToolkit to create new user interfaces and controllers, in addition to its ability to produce traditional augmented reality applications.

[documentation! (just a start...)]
i finally got around to generating ASDocs for FLARManager; this Javadoc-style documentation is similar in format to Adobe’s Flex Language Reference. i still have a ways to go to make these docs more useful, but…it’s a start. you can find the docs in the html_docs folder; just open index.html in a browser. i’ll be putting them online in the near future.

[commercial license]
ARToolworks, the group managing the commercial license for FLARToolkit, will be offering a commercial license for FLARManager very shortly. we are just wrapping up logistics now, and i’ll post more about this shortly; in the meantime, please contact me via the link at the right of the titlebar above for more information.

 


 
below is a full list of the changes since v0.3. it’s pretty substantial; if you’re thinking about upgrading a current project from v0.3 to v0.4, you should carefully review these changes before doing so, to best understand how the upgrade will affect your implementation of FLARManager.

 

FLARCameraSource.as

  • mirroring is now implemented; see FLARManager.as below for more info.
  • full-resolution video: video can be displayed at full capture resolution. however, when the source image is somewhat dark, FLARToolkit slows down substantially. i’m still working on this one; in the meantime, FLARManager still defaults to capture 320×240 video.
  • developers can now explicitly specify capture width/height and display width/height. please note that if you change display width and height and you’re mirroring your display, you should ensure that your application is mirroring along the center of the display width, not just the center of your stage. otherwise, your marker results will likely be offset in the x-axis.
  • downsampleRatio now does just that — specifies how much to downsample the captured video before sending to FLARToolkit. it no longer has any effect on the displayed video.
  • resultsToDisplayRatio provides a value for scaling FLARToolkit results to fit the specified display size. this is mainly used internally within FLARManager; developers should not need to access this (but it is available via a public accessor).

 

FLARLoaderSource.as

the changes here follow the changes in FLARCameraSource.

  • full-resolution display: the loaded source can be displayed at full resolution. this works well, and unlike FLARCameraSource, does not need further iteration.
  • developers can now explicitly specify capture width/height and display width/height.
  • downsampleRatio and resultsToDisplayRatio changes; see FLARCameraSource.as above for more information.

 

IFLARMatrixSmoother.as

matrix smoothing can be set via an external xml config file (see External configuration file below), or via FLARManager.smoothing and FLARManager.smoother. developers can use the default smoother, FLARMatrixSmoother_Average.as, which simply averages matrices over the number of frames specified by FLARManager.smoothing, or write their own implementations of IFLARMatrixSmoother.as.

 

External configuration file

developers can now pass a number of configuration settings to FLARManager via FLARManager.initFromFile(). these settings include:

  • source width/height
  • display width/height
  • capture framerate
  • capture downsampleRatio
  • loader file path, for using FLARLoaderSource.as
  • display mirroring
  • FLARManager.updateMarkerThreshold
  • smoothing value
  • camera parameters file path
  • list of pattern files
  • pattern resolution
  • patternToBorderRatio
  • pattern minimum required confidence

initializing FLARManager via an external xml config file is now the preferred method. initialization via an IFLARSource, path to camera params file, and Vector of FLARPattern instances is now deprecated, and will be removed from the FLARManager.as constructor in the next release.

 

FLARMarker.as

  • FLARMarkerOutline functionality has been rolled into FLARMarker, and FLARMarkerOutline.as is now deprecated. there is no longer any need to access FLARMarkerEvent.marker.outline.someValue; just access FLARMarkerEvent.marker.someValue.
  • vector3D offers (x, y, z) coordinates of a detected marker.
  • rotationX, rotationY, and rotationZ provide rotation of a detected marker along each of the three axes.
  • sessionId provides a unique id for each detected marker in a session.
  • FLARMarker instances were not being properly garbage collected in the previous version of FLARManager; they are now.

 

FLARManager.as

  • initFromFile() allows developers to initialize FLARManager via an external xml config file. see External configuration file above.
  • mirrorDisplay allows developers to turn horizontal display mirroring on and off easily. this can also be achieved via an external config file.
  • markerUpdateThreshold is now exposed; this value specifies the maximum amount of motion (in the xy plane) a marker can move before it is read as a new marker. it defaults to 20px; increasing this value can help to keep fast-moving markers from flickering.
  • smoothing sets the number of frames over which FLARMatrixSmoother_Average averages marker matrix results. lower values result in crisper motion with more jitter; higher values result in slower, smoother updates. set to 0 to turn off smoothing completely.
  • smoother can accept custom smoothing algorithms, as implementations of IFLARMatrixSmoother.

 

miscellaneous changes

  • Flash 3D marker tracking is greatly improved. turns out that FLARToolkit and Flash 3D have a different z origin; FLARGeomUtils.convertFLARMatrixToFlashMatrix now adds an offset when translating matrices from FLARToolkit to Flash 3D. non-4:3 aspect ratios in Flash 3D are currently broken, however :(
  • 12 new sample patterns are included in the resources/flar/patterns folder. these are 4×4 patterns, and FLARToolkit is able to distinguish them as separate patterns quite successfully.
  • ASDocs can be found in the html_docs folder; just open index.html in a browser. i’ll be putting them online in the near future.

 

bugs

there are a LOT of new features here, so there are likely bugs! please help me squash them. there are a few minor bugs lurking here and there, but nothing major that i’ve seen (with the exception of non-4:3 aspect ratios being broken in Flash 3D). please let me know if you find anything!

3 Other Comments

25 Comments

  1. Aloysio Chagas says:

    Nice Eric. I’ll test it! :) )

  2. Harley says:

    this is perfect. version v04 seems to work much better than v03.
    All the cubes render nicely. also, i like how you are using the xml file to configure the app.

    Well done!

  3. It is just absurd having around 6000 files and same amount of folders in your SVN repository. There are too many copies of pv3d and flartoolkit. If you want to distribute them use SWC or move the source files into the root of the repository.

    This is totally not the way to use SVN

  4. ericsoco says:

    thanks for the cranky note, peter. i know this, and started in on making a SWC, but it’s not o easy with FLARToolkit, there are a lot of idiosyncrasies in the codebase that make compiling a SWC tricky, and i haven’t yet had the time to focus on that.

    if it bothers you so much, why don’t you make a SWC for FLARToolkit and for PV3D and send them my way? and i’ll replace the files in the repo with those SWCs.

  5. Jesse Freeman says:

    Great to hear that you have updated this code. I played around with an earlier version and I can’t wait to test this out. Shoot me an email or chat me up on twitter @theflashbum and I can help you make a swc. Been doing some ANT house keeping for people lately and helping you out is the least I can do for your excellent contribution back to the whole FLAR loving community.

    - Jesse

  6. mr awesome says:

    Hey Eric – thanks for taking the time away from either video games / HULU / smoking pot / having sex with girls ( or however you spend your free time ) to do all this work and then give it away for free. You fuckin rock!!!!

    Hey Peter – shut the fuck up while the adults are talking and learn to say thanks, you prick

  7. Harley says:

    Eric: I wish I could figure this out, but I am afraid I will break it if I add in a BasicRenderEngine to the SimpleCube.as

    If I want to replace the blocks with dae blocks for example, what would you suggest?

    I was looking at the starter kit and then some of the other pv3d examples and I’m not seeing a basic work flow to begin to modify your app.

  8. There is some bug at the latest pv3d (could not find source for class org.papervision3d.core.animation.AnimationKeyFrame3D) as soon as this is fixed I will send you SWCs. Building such is not hard at all, just create library project in flex.

  9. ericsoco says:

    @harley — in SimpleCubes.addMarker, you can simply replace the Cube with a loaded DAE. the tricky thing with DAEs is that using them is asynchronous: you have to wait for them to load.

    you can either preload your DAEs and then attach them as needed (when the corresponding marker is detected), or load on-demand, but only if not already loaded. i prefer the latter. it’s trickier, but requires less up-front loading time.

    there was a thread on this (that i responded to) recently on the FLARToolkit forum that you should check out. basically, you’ll have to maintain an array/vector of load status for DAEs, with pattern id as index. when a new marker appears, check if the corresponding DAE has been loaded yet. if so, add it to the display list. if not, begin loading it and add it once loaded. if it’s currently loading, just let it continue (and add it once loaded).

    on removal, if it’s already visible, remove it from the display list. if not, flag it to *not* be added once loaded.

    it’s a bit tricky, but should work well once you have it up and running.
    make sense?

  10. Harley says:

    Thanks eric.

    just a point on Peter’s offer:

    first, nice to offer support, after being a little rude. also there are couple of pv3d developers that are making starter kits and include the pv3d swc file as well as the flar swc files, and some other libraries.

    second, the version should be part of the file name. keep in mind the original port of the Flar tool kit used v2, great white. additionally, modification of the pv3d’s 3dcamera was needed. so.. if it is a modified version.. i would prefer the source code for sure, just in case.

    last, I prefer Eric’s decision to post his source along with the sources of other libraries. Cleaning up the svn would be a substantial amount of work, although neccessary. It might be a month before he could get out version 4.

    Keep in mind you can always browse the svn repository and download the parts you want and not all of it.

  11. Harley says:

    Eric: so loading the dae file was easy as you said. here is the modified code:

    public function addMarker (marker:FLARMarker) :void {
    // store marker
    var markerList:Vector. = this.markersByPatternId[marker.patternId];
    markerList.push(marker);

    // create a new Cube, and place it inside a container (DisplayObject3D) for manipulation
    var container:DisplayObject3D = new DisplayObject3D();
    var materialsList:MaterialsList = new MaterialsList({all: this.getMaterialByPatternId(marker.patternId)});
    //var cube:Cube = new Cube(materialsList, CUBE_SIZE, CUBE_SIZE, CUBE_SIZE);
    //cube.z = 20;
    var COLLADA_3D_MODEL : StrString = './assets/models/cube/cube10.DAE';
    //String = './assets/models/teapot/teapot.DAE';

    var cube:DAE;
    cube = new DAE ();
    cube.load(COLLADA_3D_MODEL, materialsList);
    cube.scaleX = cube.scaleY = cube.scaleZ = 4;
    //the rest of

    although performance takes a big hit. I will work on the algorithm you previously described.

  12. ericsoco says:

    thanks for posting, harley. i would post my code that handles this stuff with arrays, but i wrote it for a client… :/

    performance shouldn’t take a hit, except perhaps right when the DAE is loaded. or, if the DAE has too many polygons. you should try loading your model into mr. doob’s previewer, as a control (remove FLAR from the equation just for testing):

    http://code.google.com/p/mrdoob/wiki/pv3dpreviewer

    or maybe one of the other two collada previewers mr. doob suggests:
    http://blog.anthony-scavarelli.com/archives/77
    http://www.juxtinteractive.com/work/vizualpv3d/

  13. Tim says:

    Eric! Great work man, good to see all the new features.

    Nice move that you are licesing the FLARmanager.

    Can you say something about the performance? Compared to for example 0.3.. or a Flash Player 9 version?

  14. ericsoco says:

    performance should be about the same as previous versions. FLARManager is pretty lightweight; it’s FLARToolkit that will be the performance bottleneck, and FLARToolkit hasn’t really changed since saqoosha released it back in november. the FP9 version would in theory be *slightly* slower than the FP10 version, as it uses Arrays instead of Vectors, but i can’t imagine there would be any noticeable difference as the Arrays and Vectors in question are both very small.

    one change that makes performance feel better is a little bit of matrix smoothing. it really does clean things up a bit. however, that’s really just a stopgap measure until FLARToolkit gets some improvements (using PixelBender / Alchemy) that allow it to do subpixel outline detection: http://groups.google.com/group/flartoolkit-userz/msg/e3da8c2257daf970

  15. Ric says:

    Bug / missing files with DAE and build v041?

    First off, thanks a ton for FLARManager, it’s great.

    Not sure if this is a bug, or I’m doing something wrong. I’m a N00B with much of this, but I was having fits trying out FLARManager with loading a DAE.

    I was trying to build the DAE example above (thanks Harley) by modifying the FLARManagerExample_PV3D example file from the 0.41 build, but couldn’t compile as I was getting tons of errors from DAE.as.

    I finally realized the 0.41 zip package is missing the ascollada folder in the org directory. Once I added that (copied over from my FLARToolKit project folder) and it works a treat.

    Now to figure out why my model’s textures aren’t showing up when they do in FLARToolKit… :P

    Anyway, thanks again!

  16. ericsoco says:

    @ric: nope, the ascollada package are not missing from the FLARManager distro, i chose to leave them out. it’s a big enough download as-is (see grumpy comment from peter above), and one of the main points of FLARManager is that it’s decoupled from PV3D. including the ascollada package would take it further in the other direction.

  17. [...] sur le terrain avec quelques usages et applications cette semaine. Côté outil, c’est la nouvelle version de Flarmanager, framework permettant de faire du multipoint avec flash et la librairie flartoolkit. Si vous avez [...]

  18. thomas says:

    Une petite réalité augmenté pour Harry Potter 6 vidéos + effets : http://vimeo.com/5091261

    http://www.harrypotter-letrain.com/

    This comment was originally posted on Hebi Flash Blog

  19. Franck says:

    L’exemple 3DVIA n’est pas franchement de la réalité augmentée, au mieux un petit collage d’une visu 3D dans une photo. Je ne vois pas bien l’intérêt ou l’usage.

    La démo Zugara est pas mal en terme d’usage. c’est rigolo, en vrai 3D ce serait encore mieux mais certainement plus complexe à réaliser.

    This comment was originally posted on Hebi Flash Blog

  20. Galdric says:

    C’est vrai ;) En réalité, au vu de leurs ambitions, je l’ai placé quand même car je pense que Dassault là dessus nous réserve quelques suprises dans ce domaine.. je parie dessus en tout cas

    This comment was originally posted on Hebi Flash Blog

  21. Yogesh says:

    Eric..thanks for this excellent class. Just wanted to check if this is still free to use for the non-commercial purposes?

  22. ericsoco says:

    @yogesh — are you asking about v0.5? all versions of FLARManager are free for non-commercial use, and v0.4 and v0.5 are available for commercial use for a fee. please see the section on licensing on this page for more info.

Leave a Reply

Additional comments powered by BackType