ShockwaveARFrame: A complex AR application

→Return to Examples

Architecture and Director based configurations

The Unifeye Viewer Shockwave Xtra ships with two different example applications. The most basic application is the ShockwaveSimpleAR application described in section UnifeyeViewerSimpleAR "How to create your first Shockwave Application". The second example is a more complex application and called ShockwaveARFrame. It is an advanced application that reads in a configuration file (see section "configuration without programming"), contains multiple 3D model loading, animation playback of 3D models, sound playback, error checks, on the fly webcam change, dynamic stage size and GUI components. You can use this application as a template for your own application development. Doing so might speed up your development process. The ShockwaveARFrame application can be configured via an application configuration file (see ApplicationConfiguration.scef) for greater flexibility. This is a human readable XML file that defines the 3D models you want to use, the sound you want to play, etc. For the full documentation of the configuration file please refer to the ApplicationConfiguration.scef file of the ShockwaveARFrame example application and the section "Configuration without programming".

This section covers the internals of the ShockwaveARFrame application.

The application performs several logical steps until the AR experience is finally started. Figure 1 gives an overview of the application logic and its components. The names of the different steps correspond to the member names in the cast. Dotted arrows with small tips point to scripts that are used by other scripts. Thick arrows indicate the application flow. The flow starts at “BlendInOutImage” and ends at “ARLogic”.

Figure 1 Application logic of the ShockwaveARFrame application

The main application logic has dependencies to other packages and media content (3D models, sounds). This is shown in Figure 2. Dotted arrows with triangle tips represent behaviour scripts that are attached to sprites.

The scripts “PrepareAndLoad” and “ARLogic” have connections to the content. “PrepareAndLoad” downloads the content and “ARLogic” works with it. The content-sprites have additional setup-behaviours attached. These scripts resize the accordant sprites according the size of the stage.

“ChooseCamera” makes use of GUI elements. The Gui-System itself controls the menu-bar that again has a connection to “CameraSetup”. This connection allows the user to change the webcam properties on the fly during execution using according GUI elements.

Figure 2 External dependencies of the ShockwaveARFrame application

You can configure the application internally in different ways by changing several properties and variable values:

• Changing the color of the menu bar:
  1. Open the script “GUIControl” below “GUI”. You will find the variables “pBORDER_COLOR”, “pMENUBAR_COLOR”, “pTEXT_COLOR”. The three variables each define a color of a part of the menu bar. Change the values according to your needs.
• Changing distances and the border width of the menu bar
  1. Open the script “GUIControl” below “GUI”. You will find the variables “pPIXEL_PER_FRAME” and “pBUTTONSPACE”. The variable “pPIXEL_PER_FRAME” defines the width of the border of the sub-menu of the menu bar and “pBUTTONSPACE” defines the spacing between the horizontal arranged buttons of the menu bar.
• Changing the menu bar entries
  1. Open the script “GUIControl” below “GUI”. The whole menu is defined by the variable “pMenuButtons”. Change “pMenuButtons” and its content to adapt the menu bar to your needs. An in-depth explanation of “pMenuButtons” can be found in the script documentation itself. If you click on one of the buttons of the menu, the method “clickCB” will be called. The name of the button is passed as a parameter. Use this method to define click behaviour of a button.
• Disable/Enable the GUI
  1. Open the script “GUIControl” below “GUI”. Set “pUSE_GUI” to “true”, if you want to use the menu bar and its sub elements. Set it to “false” otherwise. This variable is defined as a configurable parameter. Click on the sprite “MenuBar” in the score and navigate to its behaviour. You should see the behaviour “GUIControl” attached. Click it and a “GUI available” checkbox will appear just below.

Figure 3 Disabling/Enabling the GUI

• Changing the Blend-in image
  1. In the subfolder media of the ShockwaveARFrame application, an image called BlendInImage.png can be found. Just replace the image with your Blend-in .png image.
  2. HINT: if you publish your movie and the image does not seem to “blend-in” but appears immediately (or contains strange colors), include the image completely into the Director movie.
• Changing the colors of the “Choose Camera” frame
  1. The “Choose Camera” text can be adjusted directly on the stage by entering frame 11 in the score. If you want to adjust the colors of the listed cameras, open the script “ChooseCamera” below “GUI”. In the method “beginSprite” you can find the two variables “BACKGROUND_COLOR” and “FOREGROUND_COLOR”. The variables define the background and foreground color of the text and can be changed according to your needs.
• Changing the colors of the “CameraError” frame
  1. Enter frame 10 through the score and adjust the color of the text on the stage.
• Changing the color of the status text
  1. Click on the sprite “StatusText” in the score. Now you can adjust the colors of the text via its settings.
• Changing position and scale of the AR movie.
  1. The AR movie is formed by all sprites placed on the stage. If you want to adjust their size and scale within the stage, open the script “GlobalFunctions” below “Internal” and change the values of the returned rectangle of the method “GF_getStageRect()”. An in-depth explanation of the values is given in the documentation inside the script itself.
• Changing the blend-in duration of the blend-in image
  1. Click on the first frame script in the score. The property inspector to the right will show several configurable parameters. Change the parameter “Blend duration in MS” to adjust the blend-in duration of the image.

Figure 4 Changing the blend-in duration

Configuration without programming

The ShockwaveARFrame example application ships as Director source code project and as published version. The published version is provided as a Shockwave movie for the web (ShockwaveARFrame.dcr). You can customize the published version to create your own Shockwave applications without programming. Customizations can be done by exchanging or modifying the tracking configuration file and/or the ApplicationConfiguration.scef file. You can edit both XML files by using a text editor. Please note that the sample ApplicationConfiguration.scef file links to an encrypted tracking configuration file and thus only works with the deployment version of the Unifeye Viewer Xtra. You can however adjust it to fit your needs (see below).

Section ApplicationConfiguration will explain how to configure the application and how to exchange and modify media content. Section "Content preparation" will explain how to prepare such content. More details about content generation in general can be found in section UnifeyeViewerContentPreparation.

Content preparation

This section only gives a rough introduction to content generation especially for the scenario of the ShockwaveARFrame example application. For more details on the general content preparation process please refer to section UnifeyeViewerContentPreparation.

1. 3D models
   1. If you want to use your own geometry and 3D content, you will need a software package that can export Shockwave 3D files (.w3d). This can be done with 3D Studio MAX or MAYA 8.0. See section UnifeyeViewerContentPreparation for more information. To use your 3D content, reference it by using the “geometry” tags in the ApplicationConfiguration.scef file.
2. Sounds
   1. Create sound files with your favourite sound tool and save them in the mp3 format. Reference the sound files through “audio” tags in the ApplicationConfiguration.scef file.
3. Movie Textures
   1. Flash video files are the base for movie textures. Use a video tool to create them. Make sure that the video resolution isn’t too high. A resolution of 320x240 should usually be enough.
   2. You can use “flash video files” (.flv) directly or “shockwave movie files” (.swf) for movie textures. The “swf” format has the advantage that sound and video can run synchronously whereas using “flv” it can’t. Therefore it is recommended using “.swf” files.
      You can create your own “swf” movie files using the Adobe Flash Authoring Tool. A template for “swf” movie creation is placed in the subfolder media of the ShockwaveARFrame example application. The file is called VideoTextureFrame.fla. You will recognize that it is a special Flash movie that simply embeds an “flv” movie. Click on the “FLVPlayer” instance on the stage and change its “contentPath” in the “parameter” section to reference your own “flv” movie. Finally you have to publish the movie as “.swf” file by pressing e.g. “Ctrl” + “Return”. The published “.swf” file can be referenced in the ApplicationConfiguration.scef file to use the video as movie texture.
   3. If you want to place a movie texture on a 3D model, you have to specify the movie texture parts of the 3D model accordingly. This is done by assigning a special material to the movie texture parts. Inside your 3D modelling tool, create a standard material and include the substring “metaioMovieTexture” in the name of the material. Assign this material to all 3D model parts that should contain the same movie texture. Afterwards connect a movie (.swf or .flv) to your geometry (.w3d) using the configuration options inside the ApplicationConfiguration.scef file.
   4. If using “swf” movie textures, the movie textures might be invisible when running a projector. To solve this problem, just move all .flv movies from the media folder into the root folder. This is the folder where the projector (.exe or .app) is being placed.
4. Billboards
   1. Billboards are 3D objects which always face the virtual camera. If you want to use billboards, you have to define the billboard parts of your 3D model. Inside your 3D modelling tool, create a standard material and include the substring “metaioBillboard” in the name of the material. Assign this material to all 3D model parts that should be billboards. Please make sure that no animation is assigned to any billboard part.

→Return to Examples

-- SupportMetaio - 2010-07-15