Install and configure
Before starting, go through the Guides and Vision SDK Basics pages.
To set up the Vision SDK you will need to download the SDK, install the frameworks relevant to your project, and complete a few configuration steps.
SDK integration
You can integrate the Mapbox Vision SDK for iOS using a dependency manager such as Carthage or CocoaPods, or you can install the SDK manually.
To download the SDKs, you will need a Mapbox account. Sign up for a free account.
After logging in to mapbox.com with valid credentials, you will be able to access download and installation instructions at vision.mapbox.com/install.
SDK configuration
After downloading or importing the SDK into your project, you have to configure it:
Set your Mapbox access token
Mapbox Vision SDK requires a Mapbox account and access token.
- As soon as you signed up at Mapbox, you can get an access token.
- Get an access token from the Mapbox account page.
- In Xcode, select the application's target, then go to the
Info
tab. - Under the "Custom iOS Target Properties" section, set
MGLMapboxAccessToken
to your access token.
Configure permissions
- The Vision SDK needs to track the user's location in the foreground. To allow this, you have to edit the
Info.plist
file and set a proper description of location usage for theNSLocationWhenInUseUsageDescription
key. - The Vision SDK uses the device's camera in the foreground. You have to edit the
Info.plist
file and set a proper description of camera usage for theNSCameraUsageDescription
key.
Set up the initial code
Import relevant modules
MapboxVision
is required.
MapboxVisionAR
and MapboxVisionSafety
are optionals, you have to import them to use AR and Safety features respectively.
show hidden linesimport MapboxVisionimport MapboxVisionARimport MapboxVisionSafetyshow hidden lines
Prepare VisionManager
Initialize a video source and create an instance of VisionManager
with the CameraVideoSource
you have created.
show hidden linesprivate var videoSource: CameraVideoSource! private var visionManager: VisionManager!show hidden lines// create a video source obtaining buffers from camera modulevideoSource = CameraVideoSource() // create VisionManager with video sourcevisionManager = VisionManager.create(videoSource: videoSource)show hidden lines
Set up VisionManager
's delegate
You might want to subscribe to Vision events.
If you want to subscribe to Vision events, set up the delegate and implement required methods of the delegate.
show hidden lines// set up the `VisionManagerDelegate`visionManager.delegate = selfshow hidden linesextension GettingStartedViewController: VisionManagerDelegate {// implement required methods of the delegate}show hidden lines
See VisionManagerDelegate API reference
for a full list of methods.
Set up VisionARManager
's and VisionSafetyManager
's delegates
Similarly, you can subscribe to AR and Safety events with VisionARManager
and VisionSafetyManager
respectively.
show hidden linesprivate var visionARManager: VisionARManager!show hidden lines// create VisionARManager to use AR featuresvisionARManager = VisionARManager.create(visionManager: visionManager)// set up the `VisionARManagerDelegate`visionARManager.delegate = selfshow hidden linesextension GettingStartedViewController: VisionARManagerDelegate {// implement required methods of the delegate}show hidden lines
show hidden linesprivate var visionSafetyManager: VisionSafetyManager!show hidden lines// create VisionSafetyManager to use Safety featuresvisionSafetyManager = VisionSafetyManager.create(visionManager: visionManager)// set up the `VisionSafetyManagerDelegate`visionSafetyManager.delegate = selfshow hidden linesextension GettingStartedViewController: VisionSafetyManagerDelegate {// implement required methods of the delegate}show hidden lines
See VisionARManagerDelegate
and VisionSafetyManagerDelegate
API references for a full list of methods.
Configure VisionPresentationViewController
to display sample buffers from the video source
You may use VisionPresentationViewController
to present events emitted from VisionManager
.
Configure VisionPresentationViewController
with an instance of VisionManager
and add it to the current UI hierarchy:
show hidden linesprivate let visionViewController = VisionPresentationViewController()show hidden lines// configure view to display sample buffers from video sourcevisionViewController.set(visionManager: visionManager)addChild(visionViewController)view.addSubview(visionViewController.view)visionViewController.didMove(toParent: self)show hidden lines
Start delivering events
To start delivering events from VisionManager
, start running CameraVideoSource
and then start VisionManager
.
The viewWillAppear(_:)
method from UIKit
can be a good place for this:
show hidden linesoverride func viewWillAppear(_ animated: Bool) {super.viewWillAppear(animated) // start delivering eventsvideoSource.start()visionManager.start()}show hidden lines
Stop delivering events
To stop delivering events from VisionManager
, stop running CameraVideoSource
and then stop VisionManager
.
You can do this in UIKit
's viewDidDisappear(_:)
method:
show hidden linesoverride func viewDidDisappear(_ animated: Bool) {super.viewDidDisappear(animated) // stop delivering eventsvideoSource.stop()visionManager.stop()}show hidden lines
Clean up the resources
It's important to clean up the resources when you don’t need them anymore:
show hidden linesdeinit {// AR and Safety managers should be destroyed before the Vision managervisionARManager.destroy()visionSafetyManager.destroy() // finally destroy the instance of `VisionManager`visionManager.destroy()}show hidden lines
Test your first app with Vision SDK
Local testing setup
Read more about setting up your development environment for testing the capabilities of the Vision SDK in the Testing and development guide.
Vehicle setup
After installing the framework, you will need to set up the device in the vehicle. Some things to consider when choosing and setting up a mount:
- Generally, shorter length mounts will vibrate less. Mounting to your windshield or to the dashboard are both options.
- Place the phone near or behind your rearview mirror. Note that your local jurisdiction may have limits on where mounts may be placed.
- Make sure the phone’s camera view is unobstructed (you will be able to tell with any of the video screens open).