mapbox/mapbox-arkit-ios

Utilities for combining Mapbox maps and location services with ARKit in your applications.

Warning: The MapboxARKit API is experimental and will change. It is published to be able to get feedback from the community. Please use with caution and open issues for any problems you see or missing features that should be added.

Usage

Import MapboxARKit

import MapboxARKit

Declare an an annotation manager instance in your view controller

...
@IBOutlet weak var sceneView: ARSCNView!
var annotationManager: AnnotationManager!
...

Create the annotation manager instance with ARSCNView instance and become the delegate

The easist way to use MapboxARKit is to pass the ARSCNView and interact with the scene via the AnnotationManagerDelegate protocol. However, you can also initialize and AnnotationManager instance with only the ARKit session and handle all ARSCNView delegation yourself.

override func viewDidLoad() {
    super.viewDidLoad()
                
    // Create the annotation manager instance and give it an ARSCNView
    annotationManager = AnnotationManager(sceneView: sceneView)
        
    // Become the delegate of the annotation manager
    annotationManager.delegate = self
        
}

Monitor ARKit camera state readiness

AnnotationManager monitors the ARSession and acts as a proxy for related notifications. This is useful for knowing when it makes sense to interact with the ARSession and ARSCNView and do thing like adding an Annotation instance

extension ViewController: AnnotationManagerDelegate {

    func session(_ session: ARSession, cameraDidChangeTrackingState camera: ARCamera) {
        switch camera.trackingState {
        case .normal:
            // Tracking is sufficient to begin experience 
            allowARInteractions()
        default:
            break
        }
    }
}

Annotation management of annotations that represent a real world location with a SceneKit node

In view controller logic that is exercised after an ARSession is ready (see above), you can tell your AnnotationManager where it is in the world and ask it to place annotations (that are actually ARAnchor instances) representing other geographic locations in the world.

...

// Set the origin location of the annotation manager. The originLocation is a CLLocation that is as close as possible to the actual location (latitude, longitude) of the ARKit session origin point in the real world

annotationManager.originLocation = originLocation

// Create and add an annotation, MapboxARKit will supply a default red sphere as a SceneKit node to visualize the annotation if a node is not provided in an implementation of `AnnotationManagerDelegate.node(for:)`

let annotation = Annotation(location: location, calloutImage: nil)
annotationManager.addAnnotation(annotation: annotation)

// Create and add an annotation with an image that will be shown above the annotation as a callout view. `calloutImage` is a UIImage

let annotationWithCallout = Annotation(location: location, calloutImage: calloutImage)
annotationManager.addAnnotation(annotation: annotationWithCallout)

// Remove an annotation. The annotation manager will remove the annotation instance and its associated SceneKit node

annotationManager.removeAnnotation(annotation: annotation)

...

Provide your own SceneKit nodes for annotations

Although MapboxARKit provides default red spheres to visualize added annotations, applications may want different nodes. This can be useful when adding 3d models. the node(for:) delegate method in AnnotationManagerDelegate allows an application to pass associate arbitrary nodes with annotations for a location.

extension ViewController: AnnotationManagerDelegate {
    func node(for annotation: Annotation) -> SCNNode? {
        return createSpecialNode(for: annotation)
    }
}

Installation

Requirements:

• Xcode 9 or greater
• An iDevice with an A9 (or greater) processor running iOS 11 or greater
• Carthage (for development and running the sample app)
• CocoaPods (for installing the library in your own app)

Adding MapboxARKit to your iOS app

Although there has not yet been a beta release of this library yet, you can still experiment with it in your application by using CocoaPods to install it. Edit your Podfile to include:

# The MapboxARKit pod
pod 'MapboxARKit', :git => 'https://github.com/mapbox/mapbox-arkit-ios.git'

Running the sample project

• Run scripts/setup.sh. This script will check that you have Carthage installed and, if so, install the development dependencies
• Open MapboxARKit.xcodeproj in Xcode 9
• Select the MapboxARKitDemoApp scheme and target
• Set your team identity for code signing
• Create a file called mapbox_access_token in the root of the MapboxARKit project directory and write your Mapbox Access Token in that file
• Install and run the app on a device (ARKit cannot run in the simulator)