Samples included in the toolkit
The Geo AR Toolkit contains two samples that show how to build an app from scratch:
- SimpleAR – Simply adds labels around you in random locations. Look for "add locations" and "clear locations" in the application menu.
- BingAR – Uses Bing to display information about restaurants nearby. Displays the restaurant name, the type of food they serve and their average user rating.
Creating an app with the toolkit
The basic steps anyone would follow to build an app with the toolkit are:
- Start a new project
- Add a reference to GART.dll
- Add an ARDisplay control to your page
- Add the views (or layers) you want as children of the ARDisplay
- In Page.OnNavigatedTo (Windows Phone) or Window.Current.CoreWindow.VisibilityChanged (Windows 8) call ARDisplay.StartServices()
- In Page.OnNavigatedFrom (Windows Phone) or Window.Current.CoreWindow.VisibilityChanged (Windows 8) call ARDisplay.StopServices()
- (Optional) In Page.OnOrientationChanged call ARDisplay.HandleOrientationChange(e)
- Create a collection of ARItem objects (or your own custom type that inherits from ARItem)
- Set the GeoLocation property of each ARItem to a location in the real world
- Set ARDisplay.Items equal to your new collection
- (Optional) Style visual elements to give them a custom appearance or show custom data
Tutorials and articles:
Augmented reality with GART - what's changed on Windows Phone 8 by Igor
Implementing Augmented Reality using GART by Igor (targeted at Windows Phone but applies to Win8)
Augmented Reality with Bing Maps in a Windows Store App on Bing Blogs by Ricky Brundritt
How the toolkit works:
ARDisplay is the workhorse of the solution. When StartServices is called, ARDisplay takes care of creating AR services, initializing them and subscribing to their events. When StopServices is called, ARDisplay takes care of unsubscribing from the services
and freeing their resources. When we say ‘AR Services’ we're talking about the PhotoCamera (for the background video feed), Location for Lat / Long positioning and Motion for Heading / Attitude. Each of these services can also be individually Enabled
or Disabled for applications that don’t need or want them. For example, you may want to set LocationEnabled to false and set the Location property to a known location while you’re developing at home.
The next part of the solution are the individual views (or layers) that can be added as children to ARDisplay. Currently there are four:
- HeadingIndicator – Draws a circle with a cone that rotates to show the users heading. Good for layering on top of a map.
- OverheadMap – Displays a Bing map that remains centered on the users location. Normally the map is fixed to ‘North Up’ but it can also rotate to the users heading.
- VideoPreview – Essentially a rectangle that displays video from the camera. Normally it’s placed as the first (or lowest) layer and it’s set to fill the screen, but you can have multiple instances of this layer at different
sizes and locations. So, for example, you could have an OverheadMap fill the screen with a small video preview in the corner.
- WorldView – Displays a virtual world in 3D space and applies matrix math to keep the virtual world aligned with what’s seen through the camera.
As mentioned above, it’s easy for you to create your own views as well. The minimum requirement for a view is to implement the IARView interface. This interface has three properties:
- Attitude (Matrix) – The current matrix in 3D space for the rotation of the device.
- AttitudeHeading (double) – The current heading that the user is
facing in degrees.
- Location (GeoCoordinate) – The lat / long / altitude of the user as well as the heading they are traveling in.
- TravelHeading (double) – The current heading that the user is
traveling in degrees.
Note the difference between facing and traveling. A person can be driving north on the freeway but looking west out the window.
The IARView interface is all you need to implement if you want to indicate where the user is or where they’re looking. If you want to create a view that also shows the items around the user, you’ll need to implement the IARItemsView interface. IARItemsView
adds one additional property:
- ARItems (ObservableCollection<ARItem>) – The collection of items that should be rendered in relation to the current Location, Heading and Attitude of the user.
Any control can implement the interfaces listed above and get notified when their values change. However, it’s probably easiest to inherit from one of the base controls we provide:
- ARView – Implements the IARView interface as a set of dependency properties and bubbles any changes up as OnPropertyChanged overrides.
- ARRotateView – Inherits from ARView and adds the property RotationSource which can be set to North, TravelHeading or AttitudeHeading. It then provides a bindable Rotation property to be used in Xaml markup. HeadingIndicator and OverheadMap
both inherit from this class.
- ARItemsView – Inherits from ListBox and implements IARView and IARItemsView. This base class can be used for building views that render the individual items to be displayed. WorldView inherits from this class.