-- xtra arXtra
-- arXtra v0.1.9 (c) 2009 Valentin Schmidt
-- contact: fluxus@freenet.de


DESCRIPTION
===========

arXtra is an Xtra for Director (tested with v9 - v12) that implements optical marker 
tracking and overlay for augmented reality. 

It allows to detect previously loaded markers in lingo images, which can be frames of 
a live camera stream. If markers are detected, a lingo transform object is returned 
that specifies the position and orientation of the detected marker in the lingo image. 
This information can be then used to copy 3D objects into the image.

arXtra uses some code of the NyARToolKitCPP library, which is derived from ARToolKit 
library v2.72.1:
https://osdn.jp/projects/nyartoolkit/releases/p8664
http://sourceforge.net/projects/artoolkit/files/artoolkit/2.72.1/


API
===

-- create new instance 
-- args: camera settings (external file or lingo list), image width, image height
new object me, any cameraFileOrList, integer w, integer h

-- set treshold (0..1) for marker detection (="sensibility")
setConfidenceTreshold object me, float minConfidence

-- load pattern(s) into xtra
loadPatternFile object me, string patternFile, *patternWidth, patternHeight
loadPatternList object me, list patternList, *patternWidth, patternHeight

-- unload all loaded patterns
unloadAllPatterns object me

-- main function, single marker mode
-- tries to detect loaded pattern in image passed as argument
-- image must be 32-bit, and must have width and height that were passed to new()
-- if successful, a #transform object is returned, otherwise VOID
detectSingleMarker object me, object image

-- main function, multi marker mode
-- tries to detect loaded patterns in image passed as argument
-- image must be 32-bit, and must have width and height that were passed to new()
-- returns lingo list with n elements, if n markers are loaded
-- list elements are either #transform objects, if corresponding marker was detected, or 0.
detectMarkers object me, object image


SOME HINTS ABOUT USAGE
======================

Demo in D10, D11 or D12 format for Windows can be downloaded from:
http://valentin.dasdeck.com/xtras/ar_xtra/win/arxtra_v0.1.9-d10.zip
http://valentin.dasdeck.com/xtras/ar_xtra/win/arxtra_v0.1.9-d11.zip
http://valentin.dasdeck.com/xtras/ar_xtra/win/arxtra_v0.1.9-d12.zip

For Mac there is currently only a D11 demo:
http://valentin.dasdeck.com/xtras/ar_xtra/mac/d11/ar_xtra_mac_v019_d11.zip

Steps to get started with the demo:

- Open "pattHiro.pdf" (in folder "test_patterns") and print it on a white 
paper or karton.

- To run the demo, you also need a video camera that is compatible with
Flash (since the arXtra demo uses the flash camera object to get the
live camera image).

- Start "demo.exe" and press the "settings" button, now you should see a
flash settings panel in the center of the window. Select your camera in
the camera tab, and allow access to the camera (and also activate
checkbox "Save") in the access tab, then close the settings panel.

Notice: unfortunately in Director 12 this settings panel doesn't react 
on mouse clicks, so to use the D12 demo, you first have to run either the 
D10 or D11 demo once, and configure the settings there (important: make 
sure to save camera access permission also for the future!). After this, the 
d12 demo should also run fine.

- Now you should see your camera's image stream in the window. Put your
printed "Hiro" image (see above) somewhere inside the camera's view. If
everything works, arXtra should detect the marker image, and you should
now see a virtual 3D cube put on top of the pattern, with same
orientation as the marker print. Notice: the printed image must not be
bent (that's why karton is better than thin paper), and there must be
enough light/contrast.

Here a screenshot that shows what should happen if everything worked fine:
http://valentin.dasdeck.com/xtras/ar_xtra/arxtra_demo.png


If the demo runs fine for you, and you're still interested in using the
xtra for your own projects, I could search for documentation (it's
somewhere hidden on my hard disc) on how to use your own patterns and
create the required pattern lingo lists (corresponding field member 
"patt.hiro" in demo.dir).