Augmented reality : a tutorial for graphic designers

This tutorial is intended to graphic designer who want to integrate a map in their application without many notions of actionscript.

What you will need to follow this tutorial :

• A Mappy API account. Please contact commercial@mappy.com for more information about mappy APIs.
• A web server able to run php scripts.
• Flash CS 4. A trail version of Flash can be found on Adobe's website.
• Adobe Extension Manager CS4 to install Mappy's extension.

Now let's move on :

1. First, download and install Mappy's extension for flash. The extension will be run by Adobe Extension Manager CS4 and will install a Map component in your componants library. You cant press ctrl + F7 to display the Componant Library if it doesn't appear on your screen.
   
2. Now create a new Flash File (AS3) and set the scene size to 906x780. Save it as AugmentedReality.fla
3. Import on the scene a photo, for example this one :
   
4. Drag the map component on the stage, and name it "map".

   
   Now edit the component's properties with the Component Inspector
   

   You can allow or disallow the mouse wheel zoom, double clic zoom, etc...
   Set Latitude to 48.85, Longitude to 2.35 and zoom level to 7 so that it displays a map of Paris.

5. Our map displays what we want, we'll place it where it should be in the photo. Press F8 to transform the map component it into a Symbol and name your symbol OrientedMap.

   
   And name this new occurence on the scene orientedMap

6. We'll be able to use one of Flash CS4 new functionality : the Rotate 3D tool.

   

   You can play with it to match the map with the real map on the photo (it can be very tricky, though...).

   

7. Now, we have to handle the boring part : a little bit of actionscript to authenticate with our mappy account. Set the Document Root property of you animation to AugmentedReality and create the file AugmentedReality.as :
   

   package  {
   	import flash.display.MovieClip;
   	import com.mappy.accessor.Service;
   	import flash.system.Capabilities;
    
   	public class AugmentedReality extends MovieClip {
    
   		public function AugmentedReality():void {
   			if ( (Capabilities.playerType != "PlugIn") && (Capabilities.playerType != "ActiveX") ) {
   				// The application isn't running in a web page, so we can't retreive the token from the flashvars
   				Service.getInstance().requestLocalToken("YOUR_LOGIN", "YOUR_PASSWORD");
   			} else {
   				Service.token = loaderInfo.parameters.token;				
   			}
   		}
    
   	}
   }

   
   Don't forget to replace YOUR_LOGIN by your actual login, and YOUR_PASSWORD by the password mappy provided to you.
   Now, what you need to know about that is that a security token is generated in the php page hosting your application (the code is provided with the sources of the tutorial). Then it is transmited to flash through flashvars, and you need to set the Service.token property at the very begining of the application. What happens if you want to test your application directly in the flash IDE without a php page ? That's the purpose of these lines :

   if ( (Capabilities.playerType != "PlugIn") && (Capabilities.playerType != "ActiveX") ) {
   	// The application isn't running in a web page, so we can't 
   retreive the token from the flashvars
   	Service.getInstance().requestLocalToken("YOUR_LOGIN", "YOUR_PASSWORD");
   }

   
   Note that you NEED to remove these lines before publishing your application or anyone can steal your password.

   You can find deeper documentation about authentication in the first tutorial.

8. Do you want to go further ? With a little ActionScript 3 code, we can add the location of your home
   Create a new Symbol by pressing ctrl + F8. Name it HomeIcon, and select Export to ActionScript

   

   Draw a flag or anything you want. Be sure to place the bottom of the flag's handler at (0, 0). This point will be the one referencing exactly your home location.

   

   Type this code in the file AugmentedRealty.as :
   

   package  {
   	import com.mappy.geo.GeoCoordinates;
   	import com.mappy.MappyMap;
   	import com.mappy.poi.Poi;
   	import com.mappy.poi.poiLayer.PoiLayer;
   	import flash.display.MovieClip;
   	import flash.display.Sprite;
   	import flash.events.Event;
   	import com.mappy.accessor.Service;
   	import com.mappy.MapEvent;
   	import flash.geom.Point;
   	import flash.system.Capabilities;
    
   	public class AugmentedReality extends MovieClip {
    
   		// Convention : the names of our private variable begin by _
   		private var _map : MappyMap; 
    
   		public function AugmentedReality():void {
   			if ( (Capabilities.playerType != "PlugIn") && (Capabilities.playerType != "ActiveX") ) {
   				// The application isn't running in a web page, so we can't retreive the token from the flashvars
   				Service.getInstance().requestLocalToken("YOUR_LOGIN", "YOUR_PASSWORD");
   			} else {
   				Service.token = loaderInfo.parameters.token;				
   			}
   			_map = orientedMap.map; // we target the map in the dislpay list
   			_map.addEventListener(MapEvent.BASICMAP_READY, handler_mapReady);
   		}
    
   		// This function is called when the map is ready
   		private function handler_mapReady(e:Event):void {
   			var myHome : Poi = new Poi(new GeoCoordinates(2.35, 48.85));
   			myHome.icon = new HomeIcon; // A symbol that we created
   			myHome.anchor = new Point(0, 0);
   			_map.poiLayer.addPoi(myHome);		
   		}
    
   	}
   }

   A POI is a Point Of Interest. you can add pois to the application with this code :
   

   			var myHome : Poi = new Poi(new GeoCoordinates(2.35, 48.85));
   			_map.poiLayer.addPoi(myHome);		

   
   With the GeoCoordiantes object, you can specify the latitude and the longitude where the icon should be displayed. If you wonder what are the coordinates of your home, you can browse the map here.

   The last two lines allow to display you own picture on the map :
   

   			myHome.icon = new HomeIcon; // A symbol that we created
   			myHome.anchor = new Point(0, 0);

   
   The first instruction creates the picture, and assigns it to the POI. The second instruction specifies that the point in the picture that will be at the exact geographic place is (0,0). Remember, that's why our flag is down there.

That's a good start ! If you want to add some more functionalities to your application (offer to draw the route from the user's location to your home, display your favorites restaurants all over the world, and so on), you will need to write some more ActionScript. The best place to begin is the tutorials home