Getting started

→Return to Overview

Introduction

The Unifeye Viewer starting from version 3.0 is available for both Adobe’s®f Shockwave® and Adobe’s® Flash® technology thus leveraging the wide distribution and availability for different operating systems and browsers. Please refer to the chapter Introduction for a general introduction into the Unifeye Viewer architecture on both technology platforms.

System requirements

The following operating systems are fed by Unifeye Viewer:

• Windows XP SP3, Vista, Windows 7
• Mac OS X 10.5, Mac OS X 10.6, Mac OS X 10.7. Please note that Unifeye Viewer for Shockwave ONLY supports Mac OS X 10.5 with Intel processors.

Hardware requirements

The following Hardware requirements must be met:

• 32-bit (x86) or 64-bit (x64) Dual Core CPU with more than 2GHz
• 2 GB system memory
• An OpenGL/DirectX capable graphics card with current drivers (minimum 512 MB memory recommended). Shared memory graphics cards are not recommended.
• A DirectShow/WDM (Microsoft) or QT kit compatible (web)cam connected to the PC with up to date drivers (a resolution of 640x480 is recommended. For Flash you should use only 640x480 for displaying but 320x240 for tracking. See Unifeye Viewer Toolkit ARCamera class constructor).

Note on 64 bit systems:

As the Adobe browser plugins are currently only available as 32-bit versions, the Unifeye Viewer will also only run on a 64-bit system if the browser and the Shockwave/Flash plugin are run in 32-bit compatibility mode on the 64-bit system. Please refert to the FAQ for more details.

Software Requirements for Authoring & Development

Unifeye Viewer for Adobe Shockwave

For creating Shockwave applications with the Unifeye Viewer Shockwave Xtra, Adobe Director 11.5 is needed (see http://www.adobe.com/products/director/).

Unifeye Viewer for Adobe Flash

For creating Flash applications with the Unifeye Viewer for Flash a Flash/Flex authoring/programming tool supporting ActionScript 3.0 (AS3) and SWC file needs to be used. Unifeye Viewer for Flash is distributed as SWC file. We recommend using Adobe Flash Builder (http://www.adobe.com/products/flashbuilder/) as the examples provided with Unifeye Viewer were also build using Flash Builder.

There is also a free and open source development tool available for Flash/Flex called FlashDevelop (http://www.flashdevelop.org/) which can also be used.You may also use Adobe Flash Professional CS5 (http://www.adobe.com/products/flash/).

Software Requirements for Deployment

Unifeye Viewer for Adobe Shockwave

If you deploy your created Shockwave application/movie to the web, end users may view it in any browser which is supported by Adobe with an according
Shockwave plugin (Adobe Shockwave player) in version 11.5 or above. A full list of compatible browser can be retrieved from the Adobe website. Examples of supported browsers are:

• Microsoft Internet Explorer 7.0, 8.0, 9.0 (Windows)
• Firefox 3.0 and higher
• Google Chrome7 and higher
• Safari 5 and higher (Mac OS)
• Opera 10 and higher

The Adobe Shockwave player can be downloaded here: http://get.adobe.com/shockwave

When you publish your project to the web Adobe Director can create a template HTML frame which forwards the user to the Adobe page in case the browser plugin is not installed. In addition to that, the examples provided within the Unifeye Viewer package also contain HTML/JavaScript code that checks for the availability of the Shockwave plugin. In order to install the Adobe Shockwave Player, users may need Administration rights.

Unifeye Viewer for Adobe Flash

If you deploy your created Flash application to the web, end users may view it in any browser which is supported by Adobe with an according
Flash plugin (Adobe Flash player) in version 10.0 or above. A full list of compatible browser can be retrieved from the Adobe website. Examples of supported browsers are:

• Microsoft Internet Explorer 6.0, 7.0, 8.0
• Firefox 2.0, 3.0, 3.5
• Google Chrome
• Safari
• Opera

When you publish your Flash project, e.g. Adobe Flash Builder can create a template HTML frame which forwards the user to the Adobe page in case the Flash browser plugin is not installed. In addition to that, the examples provided within the Unifeye Viewer package also contain HTML/JavaScript code that checks for the availability of the Flash plugin. In order to install the Adobe Flash Player, users may need Administration rights.

Installation

If the Unifeye Viewer is not yet installed on your PC please consult the installation guide.

Consult the feature overview for an extensive list of features provided with the Unifeye Viewer.

Quickstart

Before starting with the quickstart section make sure that you installed the Unifeye Viewer package properly. This is covered in the installation guide (see also the previous section).

Five steps to start with Augmented Reality using Unifeye Viewer for Adobe Flash

Please note that this quickstart tutorial assumes that you are using Flash Builder (http://www.adobe.com/products/flashbuilder/) as your Flash authoring/programming environment.

1. step: Create a print-out of the tracking pattern:
   Open the PDF file package/Flash/examples/tracking/car/TrackingPattern_car.pdf with your favorite PDF viewer and print it.
2. step: Start Adobe Flash Builder and make sure that a camera is connected to your computer and not active within any other application.
3. step: Import the "FlashSimpleAR"-Project into your Adobe Flash Builder workspace by following these steps:
   • Open the "Import -> Flash Builder Project" - dialog box as shown in the figure below.
     
     
   • Select the "Project folder" option, and browse to the folder where the "FlashSimpleAR" project directory is located (see figure below). Usually this is: package/Flash/examples/FlashSimpleAR.
     
     
   • By clicking "Finish" the project will be imported to your Flash Builder workspace, and the application can be compiled.
4. step: Compile and start the Flash application
   As soon as the project is imported you can compile and start the FlashSimpleAR application by clicking the sign on the toolbar. After compilation the application will be started automatically.
5. step: Confirm the privacy/security dialog asking for permission to use the webcam and enjoy the AR experience.
   • By default the application will start in your default browser.
     
     
   • After confirming the privacy dialog, the camera's live stream gets visible.
   • Now hold the tracking pattern in front of camera until tracking is initialized and a cube is augmented upon the tracking pattern.
     
     

There is also a more elaborate quick start tutorial in the examples section for Flash for the FlashSimpleAR application.

Unifeye Viewer Flash performance considerations

You can improve the performance of your applications when you consider the following notes:

• Keep the framerate of the application high. We recommend to set the applications framerate to 30 fps. Please refer to theApplication frame rate article on Adobes guide for optimization of Flash applications in order to get more information on that topic.
• Keep the resolution for tracking as low as possible. In UnifeyeViewer 3.1 the camera capture resolution has been decoupled from the tracking resolution (resolution of the buffer which will be passed to the tracking system by the trackImage() call of the Tracking class in the UnifeyeViewerToolkit). So it is possible to use a high camera resolution in order to display the camera video stream, but use a lower resolution for tracking. Note the slightly changed interface of the ARCamera class. The constructor receives four resolution values: the first two ( trackWidth, trackHeight) are the width and height of the framebuffer (which can be obtained using getCurrentFrame()) which will be passed to tracking system, the next two ( videoWidth, videoHeight) define the capture resolution of the camera video stream. We recommend to use VGA (640x480) resolution for the camera capture and QVGA (320x240) for the tracking.
• Keep the count of visible polygons as low as possible. Flash does not use graphics hardware in order to perform 3D rendering (at least at the moment until Molehill will be released). The UnifeyeViewerToolkit uses Papervision3D as rendering engine for 3D content, which implements 3D rendering completely in ActionScript. This limits the number of visible polygons to a few thousand. It's is very difficult to name a maximum count of polygons since it depends on many factors (number of tracking patterns to be tracked, tracking resolution, PC hardware, etc.), but we recommend to use not more than 2000 visible polygons.

A quickstart for Augmented Reality using Unifeye Viewer for Adobe Shockwave

Before starting to use Unifeye Viewer for Adobe Shockwave please make sure that the Unifeye Viewer Shockwave Xtra was installed properly, as noted in the installation guide for Shockwave.

After performing the installation sucessfully please refer to the Shockwave SimpleAR tutorial.

General development and deployment process

Overview of the configuration and deployment process

This section provides an overview of the configuration and deployment process for Unifeye Viewer applications including an overview of the process for AR development based on the standard application (without programming) and AR development based on Unifeye Viewer Shockwave for Shockwave and Flash. The section From development to deployment below contains important informations for the development and deployment process.

Development based on the standard application

The Unifeye Viewer is shipped with a standard application which allows easy configuration of online AR applications. They are called !ShockwaveARFrame and !FlashARFrame. The application can be configured and tested in a local environment (e.g. on a private web server). After successful testing, the application can be deployed to a public server using an encrypted tracking configuration file for your application. Please note that metaio will provide you with according encrypted tracking configuration files once you purchase the deployment license. Refer to the section Sending your tracking configuration for encryption for more details.

The development and deployment process is shown below.

Development based on the Unifeye Viewer Shockwave Xtra or Unifeye Viewer Flash SWC library

If you need your own program logic the application programming can be done directly inside Adobe Director (for Shockwave) or Adobe's Flash development environments (we recommend using Adobe Flash Builder). For deployment you publish the compiled Shockwave/Flash application/movie to a public server and use an encrypted tracking data file. Before deployment you need to purchase the deployment license and metaio will provide you with encrypted tracking configuration files for your tracking patterns. Refer to the section Sending your tracking configuration for encryption for more details.

From development to deployment

For Unifeye Viewer and Shockwave

1. Plan and develop your AR Shockwave application with the Unifeye Viewer Shockwave Xtra. This includes the creation of a tracking configuration file, writing the application logic, preparing the content and testing it within Director and potentially on an internal web server. You can only use encrypted tracking configuration files. Note, that for deployment you will need the deployment license and metaio will provide you with the according encrypted tracking configuration files for your tracking patterns (see also Sending your tracking configuration file).
   The Unifeye Viewer ships with two example applications you can use as reference and templates (for more information about the sample applications, see the examples section).
2. If your application development is done, send the final tracking configuration file to metaio (if not already done in step 1). Please make sure to have a deployment license of Unifeye Viewer. For more details, please contact sales@metaio.com. You will receive an encrypted tracking configuration file in return to be used. In order to install the Xtra on your system for usage in a browser, you have to publish to the web (see below) and run your movie once in the web browser. If everything is set up correctly the Shockwave plugin will ask you to download the Unifeye Viewer Xtra automatically to a specific location. This is achieved by choosing: "Modify -> Film -> Xtras" from the menu and then clicking on the "Add" button and selecting the metaioUnifeyeViewer Xtra. It is important to select the Xtra and uncheck and check the checkbox "Download if needed".
   If you already did this the download process might not be triggered.
3. Publish your application for the web. Do not forget to adjust your Lingo code to use the correct and final encrypted tracking configuration file.
   In the menu bar at "File -> Publication settings" make sure that "HTML" and" Shockwave-File (DCR)" is checked. Finally click on "File -> Publish". This will generate the Shockwave movie (the compiled Shockwave application) for you.
   If you have adapted the xtrainfo.txt file of Director before (see the Installation guide), everything should be fine and the published movie should reference the Xtra automatically. Double click the generated HTML file. If the Unifeye Viewer Xtra wasn’t installed on your system before or the installed Xtra is an older version, the newest version of the deployment Xtra should be downloaded and installed on your system automatically (see also the previous point). Just agree the dialog when you are asked if you want to install the Unifeye Viewer Xtra on your system.
   IMPORTANT NOTE:
   Published (.dcr) Shockwave movies cannot reference/load local files of your hard disk (due to security restrictions). Therefore your published application might not work correctly. In order to get your application to work, simply upload the HTML page and its referenced content on a web server and call it again from there. You may also consult the Adobe Director help file for more details on that.
4. Create your own HTML page and embed the previously generated Shockwave movie file (.dcr). Have a look at the HTML page that was published along with the Shockwave .dcr file to see how it is done.
5. Create a so called "pre-movie" with Director. The "pre-movie" will act as entrance page for the actual Shockwave application you created. It only references the Xtra (pretending to need it without using it) in order to trigger the download process. This is necessary due to a general issue with Xtras in Shockwave and recommended by Adobe. The ShockwaveARFrame contains an example of such a "pre-movie".
6. Put the "pre-movie", the HTML page with the embedded Shockwave application along with all necessary content online and see if it works.

The illustration below gives some more information about the general deployment process when a user loads you website that contains the Unifeye Viewer Shockwave Xtra. Please note that the Xtra will alwayse being pulled from the metaio web server (see also above 3.).

Notes:

• The "pre-movie" is a standalone Shockwave movie/application that forwards the user to the real Shockwave AR application. It downloads all required Xtras in advance if necessary. A "pre-movie" is recommended because, according to Adobe’s documentation, a Shockwave movie can have problems using an Xtra directly after downloading it. According to Adobe, using a "pre-movie" is the official way for using Xtras in online scenarios. The ShockwaveARFrame example application uses a "pre-movie". Open PreMovie.dir for more details.
• Before you launch your application, we recommend testing it on different browsers.
• If you are developing online applications you should try to keep the file size of your content and assets small (as they have to be downloaded). Especially 3D models should not contain more than 30000 triangles as on weak computers the rendering performance and thus the overall system performance may drop.

For Unifeye Viewer and Flash

1. Plan and develop your AR Flash application with the Unifeye Viewer SWC library. This includes the creation of a tracking configuration file, writing the application logic, preparing the content and testing it within your authoring environment (we recommend using Adobe Flash Builder) and potentially on an internal web server. You can only use encrypted tracking configuration files. Please note that for deployment you need to purchase the deployment license and metaio will provide you with the according encrypted tracking configuration files for your tracking patterns (see also Sending your tracking configuration file).
   The Unifeye Viewer ships with two example applications you can use as reference and templates (for more information about the sample applications, see the examples section).
2. If your application development is done, send the final tracking configuration file to metaio (if not already done in step 1). Please make sure to have a deployment license of Unifeye Viewer. For more details, please contact sales@metaio.com. You will receive an encrypted tracking configuration file in return to be used.
3. Publish your application for the web. Do not forget to adjust your ActionScript code to use the correct and final encrypted tracking configuration file. Also embed the Unifeye Viewer SWC library directly into your final application (SWF file).
   IMPORTANT NOTE:
   Published Flash applications can usually only load files (e.g. the tracking configuration file) from specific locations (due to security restrictions). Therefore your published application might not work correctly. In order to get your application to work and test, you should simply upload the HTML page and its referenced content on a web server and call it from there. You may also consult your development environments help file for more details on the security restrictions.
4. Create your own HTML page and embed the previously generated Flash file (.swf). Have a look at the HTML page that was published along with the Flash .swf file to see how it is done.
5. We also recommend using a preloader for your actual Flash application that is very small, loads very fast and loads the actual (potentially bigger) Flash application showing a loading/progress bar. This enhances usability. The FlashARFrame also provides according source code.
6. Put the preloader, the HTML page with the embedded Flash application along with all necessary content online and see if it works.

Sending your tracking configuration for encryption

Unifeye Viewer can only load encrypted tracking configuration files which you can't create by yourself. The package contains several example tracking configurations which you can use during development. However if you purchase the deployment license, metaio will encrypt your tracking configurations/tracking patters for you. Please contact sales@metaio.com (for purchasing questions) or contact support(for support if you have purchased the commercial developer license) if you have any questions.

If you are creating a tracking pattern please also consult the Tracking configuration section. The planar markerless (also known as feature based) tracking is based on unique features identified in the given reference image which implies that you need a sufficiently well textured image to achieve a good tracking quality/stability and robustness.

For evaluating the tracking quality metaio will soon provide an according online tool. In the meantime you can either contact support or use the planar markerless configuration tool provided with the free download/demo version of Unifeye Design: http://www.metaio.com/products/design/.

When sending the pattern to metaio please provide the following data/information:

• the pattern itself (as high resolution image or pdf file)
• the final print dimensions (in millimeters) along the width and height of the pattern
• information if you want to use it for Flash or Shockwave (or both)
• information if you want to track several patterns at the same time (only recommended for Shockwave) or not (that is one tracking configuration file per pattern will be created)

Version history

Please refer to this section for a version history of the Unifeye Viewer package.

→Return to Overview

-- SupportMetaio - 2010-07-12