Getting started Guide (v3.0)

NOTE: This wiki is for v3.0 of the framework and above!

This is a guide to help developers get up to speed with PRAugmentedReality. It is geared primarily towards anyone who is new to iOS development, or has not worked extensively with 3rd-party libraries before.

These step-by-step instructions are written with Xcode 4.6.2 using the iOS 6 SDK.

Setting it up

Using Cocoapods

Put this line in your podfile: pod 'PRAugmentedReality'

If you don't already use Cocoapods, go check it out! http://cocoapods.org/
It'll make your life so much easier.

Manually

Several Libraries are required for PRAugmentedReality to work in your app:

• AVFoundation
• CoreGraphics
• CoreLocation
• CoreMotion
• MapKit
• MobileCoreServices
• SystemConfiguration
• QuartzCore

Then grab the Classes folder and drag it into your project.

Using it

What's in there?

There are 4 parts toPRAugmentedReality:

• PRARManager - The singleton interface between your code and PRAugmentedReality
• AR - AR Controller & AR Object
• Location - Manages gyroscope/accelerometer/heading motion
• ARSettings.h for all global constants (preprocessor directives actually). There, you can modify:
  • The refresh rate
  • Delays/Timeouts for updates and timers
  • Positioning of the overlays
  • Math

Included for your convenience are also some basic graphics.

What do I feed it?

To create AR Objects to display, you will need an NSArray of NSDictionaries. Each dictionary contains the data for one AR Object, and will be passed on to create objects of type ARObject.
The data required is:

id      - key: "nid"
title   - key: "title"
lat     - key: "lat"
lon     - key: "lon"

Types don't matter too much as they will just be passed as NSObjects anyway (check out the buildAROverlays:(NSArray*)arData ... function for details, line 102 of ARController.m).
Nevertheless, it is recommended to use:

id      - [NSNumber numberWithInt:_id_];
title   - [NSString stringWithString:@"_the_address_"];
lat     - [NSNumber numberWithDouble:_lat_];
lon     - [NSNumber numberWithDouble:_lon_];

Starting AR

To use PRAugmentedReality in your app you only have to interact with the PRARManager class.
The included example is there in part to help you visualize the following sections if need be.

This assumes you handle user location & data for the places you wish to display. Then you need to:

1. Start the general process
2. Launch the AR data setup
3. Display the AR data upon reception

Most of these processes are asynchronous so you'll have to make sure to wait for things to finish.

1. Start the general process

Make sure the class you wish to start this whole business with knows about PRARManager: #import "PRARManager.h"

Start it:

[PRARManager sharedManagerWithRadarAndSize:self.view.frame.size andDelegate:self];  

The screen size is needed to let the manager know of the size of the calling view (will differ not only for every device but also with toolbars or navbars).

2. Launch the AR data setup

[[PRARManager sharedManager] startARWithData:arData forLocation:myLocation];

And pass it the arData described above: NSArray of NSDictionaries, where each dictionary contains the data for an AR Object.

3. Display the AR data

Implement the methods of the PRARManagerDelegate protocol. FYI, the following code (you can pretty much copy & paste this into your class and it will work) assumes that you used the above init method which enabled the "radar" view:

- (void)prarDidSetupAR:(UIView *)arView 
       withCameraLayer:(AVCaptureVideoPreviewLayer*)cameraLayer
          andRadarView:(UIView *)radar
{
    [self.view.layer addSublayer:cameraLayer];
    [self.view addSubview:arView];
    [self.view addSubview:radar];
}
- (void)arControllerUpdateFrame:(CGRect)arViewFrame
{
    [[self.view viewWithTag:AR_VIEW_TAG] setFrame:arViewFrame];
}
- (void)gotProblemIn:(NSString*)problemOrigin withDetails:(NSString*)details
{
    NSLog(@"Error in %@: %@", problemOrigin, details);
}  

Ready to move on?

Check out the https://github.com/promet/PRAugmentedReality/wiki/Expanding-on-it-(v3.0) guide to create you're own stuff based on this framework.