Installation Guide

→Return to Getting Started

Information

If you are using the Unifeye Viewer package prior version 3.0 (which only contains the Unifeye Viewer for Adobe Shockwave), please refer to Unifeye Viewer package and Installation and development guide for information regarding the package content and installation/development process.

If you are using the Unifeye Viewer package starting from version 3.0 which has both the Unifeye Viewer for Adobe Flash and Unifeye Viewer for Adobe Shockwave then please continue reading.

Package Content

General information

The Unifeye Viewer package 3.0 contains libraries/extensions both for Adobe Shockwave and Adobe Flash for creating Augmented Reality applications. If you are not sure which technology you should be using, please refer to Unifeye Viewer Introduction.

In case of Adobe Shockwave the Unifeye Viewer is implemented as an Xtra which is Shockwave’s native plugin interface. By using the Xtra mechanism the Unifeye Viewer for Shockwave can take full advantage of modern computer architectures as it is written in native C++ code, compiled for the two available platforms: Microsoft Windows and Apple Mac OS.

In case of Adobe Flash the Unifeye Viewer is implemented as a so called SWC file (a library file for Flash, written in ActionScript3) which can be easily integrated into existing or new Flash projects. In contrast to the Shockwave version camera is access is provided by Flash itself and not the SWC file of Unifeye Viewer.

The main configuration for both types of the Unifeye Viewer is a so called tracking configuration file. It configures the tracking approach to be used (currently only planar markerless tracking also known as feature based tracking) and the targets/patterns to be tracked. In contrast to earlier versions of the Unifeye Viewer package only encrypted tracking configuration files can be used now. This introduces a major simplification especially for Shockwave developers as there is now only one version of the Unifeye Viewer Xtra (which used to be called the deployment Xtra) and no WIBU key license dongle shipped and used any more. It also generally implies that if you are planning to use your own tracking patterns/tracking targets for commercial deployment you will have to contact metaio and request an according encryption of your tracking pattern. This service is available after you purchased the deployment license for commercial deployment. More details regarding the development and deployment process can be found in the Development and Deployment process below.

Package content overview

The Unifeye Viewer package is shipped as a zip archive. It provides the following files and folders.

Folder Shockwave

Examples

This folder contains example models within the model subdirectory. The models are provided in w3d format (the Adobe Shockwave model format) as well as the original 3D Studio Max files. The file UnifeyeViewerLogo.w3d is not animated. The UnifeyeViewer.w3d file contains a simple animation.

The subdirectory tracking contains encrypted tracking configuration files (and according PDF files for print out) that you can use in your applications.

The subdirectory ShockwaveARFrame contains a more complex Shockwave application which is described in more detail here. There are two main files: PreMovie.dir is only responsible for downloading the Unifeye Viewer Xtra (if not already installed) and then forwards to the main application ShockwaveARFrame.dir/.dcr. The ShockwaveARFrame application parses a configuration file (ApplicationConfiguration.scef) which can setup a basic AR scene. The folder online contains all the needed files to be placed on a web server in order to run the example. It also contains an index.html page which uses a browser detection/Shockwave detection script which tells the user to download the Shockwave player if it is not already installed. If you want to use it you will have to adjust the URLs within the ApplicationConfiguration.scef according to your needs. This sample application can even be used without programming by just adjusting the ApplicationConfiguration.scef file and uploading the contents of the online folder accordingly. For more details regarding the configuration of the application please refer to the application configuration documentation.

The subdirectory ShockwaveSimpleAR contains the most basic example showing how to integrate the Unifeye Viewer Xtra into a Shockwave application. For more details, please refer to the quick start example.

Folder UnifeyeViewer _Xtra

This folder contains the Unifeye Viewer Xtra and all according dependencies of the Unifeye Viewer Xtra. Usually the Xtra will be pulled from metaio’s web server once you deploy your application and set up the Shockwave project settings within Director accordingly (see Development and Deployment process).

The subdirectory Mac contains the Mac version of the Xtra, the folder Windows contains the Windows version. If you want to copy the Xtra manually do not forget to copy all files in the according directory.

Folder Flash

Examples

The examples directory contains some example material, like example models, example Flash Builder Projects, example tracking configuration files. In the following we will explain the content of the subfolders in detail:

The models subdirectory contains different example models, as well as other example material, like FLV movies and a movie plane model (which can be used to put FLV files on it).

The subdirectory tracking contains encrypted tracking configuration files (and according PDF files for print out) that you can use in your applications.

The subdirectory UnifeyeViewerToolkit contains a Flash Builder Project which contains the source code of the UnifeyeViewerToolkit. It can be used in order to modify and customize the toolkit class collection for your projects. The UnifeyeViewerToolkit is a collection of classes which can be used for 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. You can find more information about how to use this toolkit in the FlashARFrame project and in the UnifeyeViewerToolkit API documentation.

The subdirectory FlashSimpleAR contains a Flash Builder project for a simple quickstart application which just shows the basic functionality of metaio's UnifeyeViewer for Flash library. It shows how tracking can be done, and which steps are needed for creating a simple AR application. Please see also the Flash quickstart section and the simple tutorial.

The subdirectory FlashARFrame contains a Flash Builder Project for a more complex application. The FlashARFrame application demonstrates all functionality of the UnifeyeViewerToolkit (which internally uses the Unifeye Viewer Flash SWC library). The application uses a customizable preloader, resource loading and management, application configuration files (which allows an easy creation of AR scenes by editing XML files), abstracts access to the rendering engine etc. A detailed explanation for this application can be found in the FlashARFrame documentation.

UnifeyeViewer

This folder contains the actual UnifeyeViewer Flash SWC library: metaioUnifeyeViewer.swc. It can be added to your own project in order to start an AR application from scratch. Please refer to the API documentation for more details regarding the API. Please also note that the UnifeyeViewerToolkit classes (see above) provided with the Unifeye Viewer package use this library internally and provide a lot of convenience functionality to give you a quick start creating your AR applications.

Installation Process

The Unifeye Viewer shipped as a zip file (see above). This section describes the setup process of your development environment for working with the Unifeye Viewer. Please note that you can also use the provided ShockwaveARFrame or FlashARFrame application if you want to start without programming. These applications are configurable in terms of models, sounds, animations, tracking information and so on and can be deployed directly to your web server. For more details please refer the ShockwaveARFrame and FlashARFrame application.

Adobe Shockwave

Prerequisites

If you want to have full control over the application logic we recommend the development of a customized application. The authoring/development environment for Shockwave is Adobe Director 11.5. Please go to http://www.adobe.com/de/products/director/ for details and purchasing information. The introduction also contains some further URLs where you can find an introduction to Director and Shockwave.

You can also start without programming by using the already compiled/published Shockwave movie from the sample application ShockwaveARFrame which is delivered within the Unifeye Viewer package. For simple applications this might be sufficient. The application uses an XML based configuration file called ApplicationConfiguration.xml. With this configuration file you can exchange or add 3d models, trigger the play back of animations of 3d models or play back sounds while a 3d model is shown to the user. You will not need a license of Adobe Director 11.5 when using the published ShockwaveARFrame movie. A simple text editor to edit the configuration file is enough.

In order to create 3D data, you will need an adequate 3D modelling tool like 3D Studio MAX or Maya which can export 3D scenes to the Shockwave 3D file format (.w3d). For more details on the content preparation process please refer to the content preparation section.

Installation of the Xtra for development purpose

For using the metaio Unifeye Viewer Shockwave Xtra within Director, copy the appropriate subfolder Windows or Mac from the UnifeyeViewer _Xtra folder of the package to the Adobe Director Xtra folder located at <DirectorInstallationFolder>/Configuration/Xtras/.

If you want to develop cross platform Shockwave projects consider the following:

1. Developing on Windows (for Windows and Mac OS):
   Please copy the Mac version of the Xtra file ( UnifeyeViewer_Xtra\Mac\metaioUnifeyeViewer.xtra\Contents\MacOS\metaioUnifeyeViewer) to the directory: <DirectorInstallationFolder>\Configuration\Cross Platform Resources\Macintosh\Xtras\ and rename the file extension to ".cpio". After that you should have a file named:
   <DirectorInstallationFolder>\Configuration\Cross Platform Resources\Macintosh\Xtras\metaioUnifeyeViewer.cpio
2. Developing on Mac OS (for Mac OS and Windows):
   Please copy the Windows version of the Xtra file ( UnifeyeViewer_Xtra/Windows/metaioUnifeyeViewer.x32) to the directory:
   <DirectorInstallationFolder>/Configuration/Cross Platform Resources/Windows/Xtras/
   After that you should have a file named: <DirectorInstallationFolder>/Configuration/Cross Platform Resources/Windows/Xtras/metaioUnifeyeViewer.x32

This ensures that the Director Shockwave application you create will download the metaio Unifeye Viewer Xtra correctly on Mac when you develop on Windows and vice versa.

As next step adjust the Xtra configuration file: <DirectorInstallationFolder>/Configuration/xtrainfo.txt and add the line:

[#namePPC:"metaioUnifeyeViewer", #nameW32:"metaioUnifeyeViewer.x32", #package:"http://www.ar-live.de/download/metaioUnifeyeViewer/Xtra/metaioUnifeyeViewer", #info:"http://www.metaio.com"]

Your development configuration is now finished.

Start a new Director project. From the menu choose: "Modify -> Film -> Xtras". Click on the "Add" button and select the metaioUnifeyeViewer Xtra. If you want to download the Xtra to the client’s computer in the deployment phase (recommended), select the Xtra and uncheck and check again the checkbox "Download if needed".

Please note that when you run your Director project within Director, the Xtra from within the <DirectorInstallationFolder>/Configuration/Xtras/ folder will be used. If you publish your Director project to the web browser, the Xtra will be downloaded (if you selected so, see above) and put into the location:

1. Windows:
   %APPDATA%\Adobe\Shockwave Player 11\xtras\download\metaio GmbH\UnifeyeViewer\
   where %APPDATA% maps on Windows XP to:
   to C:\Documents and Settings\<USERNAME>\Application Data\,
   and on Vista to:
   C:\Users\<USERNAME>\AppData\LocalLow
2. Mac:
   ~/Library/Application Support/Adobe/Shockwave Player 11/Xtras/download/metaio GmbH/UnifeyeViewer/

and then used from that location by the web browser.

System configuration

The tracking system of the Unifeye Viewer Shockwave Xtra is initialized by a tracking configuration file which is also called "TrackingData" file. It defines the markerless patterns to be tracked by the systems. It is a mandatory file needed by the Xtra. If the Xtra doesn’t initialize properly this is usually due to a missing or malformed tracking configuration file. Also note that the Xtra only handles encrypted tracking configuration files. This implies that for deployment you will need to purchase the deployment license which enables you to send your tracking patterns/images to metaio and metaio will encrypt your tracking patterns for you (see also the development and deployment process).

Another configuration aspect is setting the camera parameters respectively the camera calibration (also known as the intrinsic parameters of a camera). This includes parameters like focal length or distortion values. If you want to have highly accurate augmentations, you should provide such parameters for each camera you want to use. Using the camera calibration is an optional step. You do not have to provide a camera calibration in order to get the tracking to work. Default values will be used internally if you omit this step. However if you use it, augmentation will be better and usually more stable. Refer to the section camera calibration in Unifeye Viewer for more information.

Please note that the Unifeye Viewer package contains no tools for generating a tracking configuration or camera calibration file for you. You can use the tools provided by Unifeye SDK/Unifeye Design for generating camera calibrations. Tracking configuration files will be created/encrypted upon request (see above). Please also refer to the tracking configuration section for details about good tracking patterns.

Adobe Flash

Prerequisites

Unifeye Viewer package offers a template application FlashARFrame which implements a basic application logic which might cover many simple use cases. If you want implement your own application you can start with one of the example applications or using UnifeyeViewerToolkit when application should be developed from scratch. Both examples and UnifeyeViewerToolkit are contained in Unifeye Viewer package. The development environment for Flash is Adobe Flash Builder 4. Please go to http://www.adobe.com/products/flashbuilder/ for details and purchasing information.

As already mentioned for simple use cases it might be sufficient to use the FlashARFrame example application. In this case no software development is required. The application can be configured for using custom tracking patterns and content. By providing a XML based configuration file called ApplicationConfiguration.xml you can define 3d content, audio content, and movie content and which pattern should trigger the appropriate content.

Currently supported 3d fileformats are COLLADA and MD2, therefore for creation of 3D content you will need a 3D modelling software which supports the export of 3D scenes to one of these two formats (e.g. 3D Studio MAX). For more details on the content preparation process please refer to the content preparation section.

Installation of the UnifeyeViewerToolkit for development purpose

In order to develop custom application from scratch you have to copy the metaio tracking library located in UnifeyeViewerInstallationDirectory\package\Flash\UnifeyeViewer\metaioUnifeyeViewer.swc to the libs directory of your Flash Builder project (see FlashSimpleAR tutorial to see how to use the library) .

In case you want to start development using UnifeyeViewerToolkit you have to copy only the UnifeyeViewerInstallationDirectory\package\Flash\examples\UnifeyeViewerToolkit\bin\UnifeyeViewerToolkit.swc library into the libs directory of your Flash Builder Project.

The directory UnifeyeViewerInstallationDirectory\package\Flash\examples\ contains example projects ( FlashARFrame, FlashSimpleAR) which can be easily imported to your current Adobe Flash Builder Workspace (see Quickstart guide for Flash).

You can customise the UnifeyeViewerToolkit by importing the UnifeyeViewerToolkit project which is also located in UnifeyeViewerInstallationDirectory\package\Flash\examples\ directory.

System configuration

As well as for Unifeye Viewer Shockwave Xtra, the tracking system of the Unifeye Viewer Flash is initialized by a tracking configuration file which is mandatory for initialization of the tracking system. This, so called "TrackingData" file defines the markerless patterns to be tracked by the system. The Unifeye Viewer Flash supports only encrypted tracking configuration files. You will need to purchase the deployment license in order to define own tracking patterns. For more information please refer to the development and deployment process for Unifeye Viewer package.

Unlike the Unifeye Viewer Shockwave Xtra, the Unifeye Viewer Flash does not support camera calibration, the tracking system uses default values which should be sufficient for most applications.

Development and Deployment process

For details about the general development and deployment process of your application please refer to the general deployment process section.

→Return to Getting Started

-- SupportMetaio - 2010-07-12