Unifeye Viewer Programming interface

→Return to Overview

Unifeye Viewer for Shockwave Xtra: interface

In order to get information about the Unifeye Viewer Xtra interface inside Director, just click into the message dialog of Director select “Script-Xtras” à ”metaioUnifeyeViewer” à ”put interface”. Please note that the documentation might contain functions that are not yet productive and thus should not be used.

In addition to that this section also contains the functions that are available and the according function documentation.

Creates an instance of the metaioUnifeyeViewer Xtra. If the tracking data is incorrect or wasn't found at all, an error will be thrown to Director. The tracking data has to be correct in order to continue. Please note that in case of the deployment Xtra, only encrypted tracking data files can be loaded (and vice versa for the development Xtra).

@param trackingDataPath tells the Xtra where the tracking data can be found (absolute path or URL).

new object me, string trackingDataPath

---

Loads a tracking data.

Note that a tracking data has already been loaded on new(). Calling loadTrackingData() resets the current tracking data. Please not that in case of the deployment Xtra, only encrypted tracking data files can be loaded (and vice versa).

@param trackingDataPath tells the Xtra where the tracking data can be found (absolute path or URL).

@return 0 in case of success, negative values otherwise:

-1: general failure,

-2: function not implemented,

-3: invalid argument,

-4: null pointer argument,

-5: invalid state,

-6: invalid path argument,

-7: license error.

loadTrackingData object me, string path

---

Enumerates all available cameras of the PC.

@return A list() containing strings of the names of all available cameras. A list entry for a camera starts with the string “Camera://” followed by the name of the camera, e.g.:“Camera://Logitech QuickCam Pro 9000_1”. Every list entry that is not prefixed by “Camera://” can be ignored and is reserved for future features.

enumerateCameras object me

---

Enumerate all supported native formats of the camera that is currently connected to the Xtra.

Every returned format is structured like:

<width>_<height>_<fps>

where width is the horizontal resolution, height the vertical resolution and fps the maximum frames per second of the camera at this resolution. Please note that the frames per second values might be inaccurate due to camera driver issues.

@return An error if no camera is connected

enumerateNativeFormats object me

---

Sets the output format of the currently connected camera.

This determines the format of the images returned by getTrackingDataAndImage(). If the format you set is a non-native format of the camera, the metaio UnifeyeViewer Xtra will try to find the closest format to the one you desired, set it for the camera and use it internally. Nevertheless, the format you will receive later when calling getTrackingDataAndImage() will be the format you set initially which means that the image might be reprocessed additionally (e.g. resized). That is why it is recommended to choose native formats.

@param format The desired image format. The format structure is:

<width>_<height>_<fps>

where width is the horizontal resolution, height the vertical resolution and fps the frames per seconds.

@return 0 in case of success, negative values otherwise:

-1: general failure,

-2: function not implemented,

-3: invalid argument,

-4: null pointer argument,

-5: invalid state,

-6: invalid path argument,

-7: license error.

setOutputFormat object me, string format

---

Gets the current native output video format of the camera. This is not necessarily the format you set on setOutputFormat(). It is the closest native format to the format set by setOutputFormat() supported by the camera.

@return Current native output format of the camera.

getNativeFormat object me

---

Sets the camera parameters of the virtual camera that is used for tracking. If you do not provide parameters, the values will be guessed.

Please refer to Unifeye SDK/Design to get a complete description of those values.

@param fx focal length in x direction (in pixel).

@param fy focal length in y direction (in pixel).

@param px principal point in x direction (in pixel).

@param py principal point in y direction (in pixel).

@param k1 undistortion parameter 1 (if 0, no undistortion is performed)

@param k2 undistortion parameter 2 (if 0, no undistortion is performed)

@param p1 undistortion parameter 3 (if 0, no undistortion is performed)

@param p2 undistortion parameter 4 (if 0, no undistortion is performed)

@return 0 in case of success, negative values otherwise:

-1: general failure,

-2: function not implemented,

-3: invalid argument,

-4: null pointer argument,

-5: invalid state,

-6: invalid path argument,

-7: license error.

setCamera object me, float fx, float fy, float px, float py, float k1, float k2, float p1, float p2

---

Connects a camera to the Xtra for tracking. Always call connect() BEFORE start(). IMPORTANT NOTE: If an error occured during connect(), you need to call disconnect() before connect() works again!

@param source The name of the camera you want to connect to the system. Call enumerateCameras() to get a list of names of all available cameras.

@return 0 in case of success, negative values otherwise:

-1: general failure,

-2: function not implemented,

-3: invalid argument,

-4: null pointer argument,

-5: invalid state,

-6: invalid path argument,

-7: license error.

connect object me, string source

---

Disconnects the currently connected camera from the system.

Call stop() BEFORE disconnecting when the camera is running.

@return 0 in case of success, negative values otherwise:

-1: general failure,

-2: function not implemented,

-3: invalid argument,

-4: null pointer argument,

-5: invalid state,

-6: invalid path argument,

-7: license error.

disconnect object me

---

Starts the camera and the tracking. In order to work, connect() has to be called BEFORE.

@return 0 in case of success, negative values otherwise:

-1: general failure,

-2: function not implemented,

-3: invalid argument,

-4: null pointer argument,

-5: invalid state,

-6: invalid path argument,

-7: license error.

start object me

---

Stops the tracking and has to be called BEFORE calling disconnect().

@return 0 in case of success, negative values otherwise:

-1: general failure,

-2: function not implemented,

-3: invalid argument,

-4: null pointer argument,

-5: invalid state,

-6: invalid path argument,

-7: license error.

stop object me

---

Returns the current image plus the according tracking values within a list.

@return The returned value is a list which holds the data as follows:

[1]: index 1 is always the camera image. If no image is available, [1] will be VOID.

[2-n]: each index [2-n] will contain tracking information. The index [2-n] is equal to the number of the coordinate system (COS) (as defined in the tracking data file) minus 1.

[2-n][1] tracking quality: this value indicates the quality of the tracking:

0 means the COS with the COS ID [2-n]-1 is currently not being tracked.

1 means the COS is being tracked.

[2-n][2] transform: the tracking transformation matrix. This matrix will be used to position your 3d model in 3d space.

Example:

[1]: "..." --> the image.

[2][1]: 1.0 --> coordinate system 1 (the first in the tracking data file) is currently being tracked.

[2][2]: "..." --> the tracking values.

[3][1]: 0.0 --> coordinate system 2 (the second in the tracking data file) is currently not being tracked.

[3][2]: "..." --> empty tracking values (identity transformation).

getTrackingDataAndImage object me

---

Shows the pin properties dialog of the current camera.

This dialog can be shown to the user to setup the camera in terms of resolution, framerate, etc. if this is supported by the camera driver. Please note that this does currently only work on Windows based systems.

showPinProperties object me

---

Shows the property page. This dialog can be shown to change several camera parameters (like gain, brightness, shutter) if this is supported by the camera driver. Please note that this does currently only work on Windows based systems.

showPropertyPage object me

---

Activates the next best microphone in the PC.

@return 1 if successful, else 0 (e.g. there is no microphone available or it has already been activated).

startMicrophone object me

---

Deactivates the active microphone.

@return 1 if successful, else 0 (e.g. microphone hasn't been started yet or wasn't activated).

stopMicrophone object me

---

Returns the current volume level of the active microphone.

@return the level of the microphone. Ranges from 0 (no noise) to 4 (very loud).

getMicrophoneLevel object me

---

Saves an image to disk.

The target format of the image can be .bmp, .png, .jpg or .tiff. If the parameter path is empty, a file dialog will open and the user can choose a location where to save the image. Opening the file dialog does currently not work when using this Xtra inside a web page. You might consider using the function getPathToDesktop() and a file name in such cases. If the parameter path is incorrect, no image will be saved. If you are running on Windows Vista or later, Internet Explorer 7 or higher and in protected mode, calling this function will additionally open a dialog box asking the user for a file location. This is needed due to IE security restrictions

(see also http://msdn.microsoft.com/en-us/library/bb250462(VS.85).aspx).

@param img The image to save to disk.

@param path The path to the target file. If empty a file save dialog will be shown. Please note, that in this case the user will have to set the file extension as well.

saveImage object me, image img, string path

---

Returns path to the user desktop.

@return path to the user desktop.

getPathToDesktop object me

Unifeye Viewer for Flash SWC library: interface

With UnifeyeViewer for Flash metaio provides a Flash library (SWC file) called metaioUnifeyeViewer.swc which implements the planar markerless tracking (also known as feature based tracking) functionality. Below we will give you an overview how this Flash library can be used in custom applications. Please also refer to the Flash example section for more details. There is also a collection of classes available (called the UnifeyeViewerToolkit, see below) which provides you with a top level access to the actual Unifeye Viewer for Flash library and a lot of convenience functionality. You can use it freely inside your own applications. The FlashARFrame example uses this internally as well.

How to use/import the Unifeye Viewer for Flash SWC library (metaioUnifeyeViewer.swc)

The metaioUnifeyeViewer.swc Flash library can be imported into application using the following ActionScript3.0 line:

import cmodule.metaioUnifeyeViewer.CLibInit;

Next create the metaio Tracking object:

 
var loaderMetaioTracking:cmodule.metaioUnifeyeViewer.CLibInit = new cmodule.metaioUnifeyeViewer.CLibInit(); 
m_libMetaioTracking = loaderMetaioTracking.init(); 

Now all functions described later in this section are available using the following pattern:

 
var res:int = m_libMetaioTracking.functionName(...); 

metaioUnifeyeViewer.swc library: Programming interface

In the following we give an overview of the interface provided by the metaioUnifeyeViewer.swc Flash library:

• getTrackingValues(cosI:uint):Array : Retrieves tracking values for a particular coordinate system/tracking pattern
  • param: cosID:int The ID of the according coordinate system/tracking pattern. The first pattern defined in your tracking configuration file has ID "1", the second ID "2", etc.

• trackImage(frameWidth:uint, frameHeight:uint, frameBufferLength:uint, frameBuffer:ByteArray, imageFormat:uint, imageOrigin:uint) : Tracks a given frame (of the camera)
  • param: frameWidth:uint The width of the frame
  • param: frameHeight:uint The height of the frame
  • param: frameBufferLength:uint The length of the buffer which contains the frame data
  • param: frameBuffer:ByteArray The buffer which contains the frame data
  • param: imageFormat:uint The format of the image (1=ARGB, 2=RGB, 3=GRAY)
  • param: imageOrigin:uint Describes the location of the image origin (1 = lower left corner, 2 = upper left corner)

• getNumberOfDefinedCoses():uint : Retrieves the number of defined coordinate systems (usually the number of tracking patterns used in your tracking configuration file)
  • return: The number of defined coordinate systems

• initTrackingSystemEncrypted(camWidth:uint, camHeight:uint, dataSize:uint, trackingData:ByteArray):uint : Initialises the tracking system
  • param: camWidth:uint The horizontal resolution of the camera
  • param: camHeight:uint The vertical resolution of the camera
  • param: dataSize:uint The size of the ByteArray containing the contents of your tracking configuration file
  • param: trackingData:ByteArray The ByteArray containing the contents of the encrypted tracking configuration file
  • return: True if the initialisation was successful, otherwise false.

• releaseTrackingSystem():void : Destroys the tracking system

Unifeye Viewer Toolkit

The UnifeyeViewerToolkit is a collection of classes which can be used for the development of custom AR applications. It directly contains the Unifeye Viewer Flash library plus a lot of convenience classes for building up AR applications with the Unifeye Viewer, like a loading screen, a camera access class, mathematical tools, tracking interface classes (that hide the interface to the actual Unifeye Viewer Flash library) and XML parsing classes. Please note that the access to the metaioUnifeyeViewer.swc Flash library is fully encapsulated into the Tracking class of the UnifeyeViewerToolkit. For an example please refer to the FlashARFrame example application which makes heavy use of this toolkit.

Please refer to the documents listed below for more details regarding the classes and functions provided by the toolkit:

• UnifeyeViewerToolkit API documentation (Unifeye Viewer 3.0)
• UnifeyeViewerToolkit API documentation (Unifeye Viewer 3.1)

---

→Return to Overview

-- SupportMetaio - 2010-07-15