AR customization using Mapbox Vision SDK for iOS
Familiarity with Xcode and Swift, and completion of the Mapbox Vision SDK for iOS Install and configure guide.
Mapbox Vision AR for iOS is a high-level framework that sits on top of the Mapbox Vision SDK for iOS. Vision AR manages the navigation route and renders the route on top of the live video stream from the device camera. VisionARViewController is used to display navigation visuals in augmented reality. It can show two types of AR artifacts: a lane and a fence. This tutorial will show you how you can customize the default appearance of these AR artifacts.
Getting started
Before starting this tutorial, go through the Install and configure steps in the Vision SDK for iOS documentation.
Then, update your ViewController to use the code from AR navigation example. This example includes all the logic needed to set up a default AR navigation application, including:
- Creating a
VisionManager. - Creating a
VisionArManager. - Using Mapbox Directions to generate a route.
- Displaying that route using
MapboxVisionAR.
The rest of this tutorial will walk you through how to customize various visual elements in resulting application.
Basics of customizing AR
You can customize AR visuals in two ways:
- Visual appearance (for example, color, size, and quality) is controlled through
VisionARViewControllerviaLaneVisualParamsandFenceVisualParams. - Visibility distance configuration is directly connected with computation load and should be adjusted narrowly to meet application performance requirements. This parameter is configured through
VisionARManagerfor both lane and fence and affects corresponding events received byVisionARManagerDelegate.
You can also change the AR rendering quality, which can be useful for gaining performance on weak devices. Pass any value in from 0 to 1 to adjust AR quality where 0 is the lowest quality and 1 is the highest quality. By default the highest quality is used.
To adjust AR rendering quality use the set(arQuality:) method on VisionARViewController instance:
AR lane customization
Lane length
Adjust the length of the AR lane using the set(laneLength:) method on a VisionARManager instance and specify a length in meters:
Choosing values below 100 meters for lane length provides a good balance between performance and visual effect.
Lane visual parameters
To customize lane appearance use LaneVisualParams. Its default initializer produces an instance with default values for each parameter. Once visual parameters are configured, set them to an instance of VisionARViewController.
Remember that lane visual parameters are not shared across the instances of
VisionARViewControllers, so after the recreation of VisionARViewController
object, you need to set the lane visual parameters again.
Adjust the three available properties detailed below to achieve the desired visual effect.
Lane color
Use a UIColor to define a custom color for the lane. The lane's appearance is tolerant to alpha component of the color. The code below will make the lane red and leave other parameters as defaults:
Lane width
Set the lane width in meters. The code below will make the red lane one meter wide:
Chevron length
The AR navigation lane consists of chevrons lying on the surface of the road. The length of a chevron is expressed in meters and can be adjusted via the arrowLength property. The longer a chevron, the smaller the number of visible chevrons.
The code below will shorten the length of the chevrons used in the red lane:
AR fence customization
You can enable AR fence rendering on a VisionARViewController instance.
Fence visibility distance
You can adjust fence visibility distance to achieve the desired visual effect and set the needed level of performance. The farther away you see the fence, the less stable it will appear on the far end so it's not recommended to set values larger than 250 meters.
The code below uses the setFenceVisibilityDistance method to change the visibility distance from the default, 250 meters, to 100 meters:
Fence visual parameters
To customize fence appearance, you need to use FenceVisualParams. Its initializer produces an instance with default values for each parameter. Once visual parameters are configured, set them to an instance of VisionARViewController.
Remember that fence visual parameters are not shared across the instances of
VisionARViewControllers, so after the recreation of the
VisionARViewController object, you need to set the fence visual parameters
again.
Adjust the five available properties detailed below to achieve the desired visual effect.
Fence color
Use UIColor to define a custom color for the fence. The fence's appearance is tolerant to the alpha component of the color.
The code below will make the fence yellow and leave other parameters as defaults:
Fence height
Set the fence height in meters. The code below will make the yellow fence 2 meters tall:
Fence vertical offset
The fence's vertical offset is the distance (in meters) above the road surface. The code below will raise the fence 1 meter above the road:
Fence horizontal offset
The fence's horizontal offset is the distance (in meters) away from the center lane. The code below will move the fence closer to the center lane by 3 meters:
Number of sections
The AR fence consists of sections represented by glowing arrows. You can adjust the number of sections in the fence.
Restoring defaults
You can alter only the parameters you need on "visual parameters" instances. The rest properties will be configured with default values. To restore all the parameters to default values, create new instances of visual parameters without adjusting their properties.
Final product
You have created an AR experience applying customization options available in the Mapbox Vision AR module.
import MapboxVisionAR
import UIKit
/**
* "AR Customization" tutorial demonstrates how to customize vision AR visuals - AR lane and AR fence.
* The tutorial is based on "ARNavigation" example which shows how to get the route and set up Vision AR session.
*/
class ARCustomizationViewController: ARNavigationViewController {
override func viewDidLoad() {
super.viewDidLoad()
// Adjust AR rendering quality
visionARViewController.set(arQuality: 0.8)
// Make sure lane is visible
visionARViewController.isLaneVisible = true
// Set lane length in meters
visionARManager.set(laneLength: 40)
// Create an instance of `LaneVisualParams`
let laneVisualParams = LaneVisualParams()
// Set lane color
laneVisualParams.color = UIColor.red
// Set lane width in meters
laneVisualParams.width = 1
// Set the length of chevrons in meters
laneVisualParams.arrowLength = 2.5
// Once `laneVisualParams` is configured, set it to the view controller
visionARViewController.set(laneVisualParams: laneVisualParams)
// Enable fence rendering
visionARViewController.isFenceVisible = true
// Set fence length in meters
visionARManager.set(fenceVisibilityDistance: 200)
// Create an instance of `FenceVisualParams`
let fenceVisualParams = FenceVisualParams()
// Set fence color
fenceVisualParams.color = UIColor.yellow
// Set fence height in meters
fenceVisualParams.height = 2
// Set fence vertical offset above the road surface in meters
fenceVisualParams.verticalOffset = 1
// Set fence horizontal offset from the camera in meters
fenceVisualParams.horizontalOffset = 3
// Set the number of arrows in the fence
fenceVisualParams.sectionsCount = 3
// Once `fenceVisualParams` is configured, set it to the view controller
visionARViewController.set(fenceVisualParams: fenceVisualParams)
}
private func restoreDefaultValues() {
// Set the new lane visual params without changes
visionARViewController.set(laneVisualParams: LaneVisualParams())
// Set the new fence visual params without changes
visionARViewController.set(fenceVisualParams: FenceVisualParams())
// Disable fence rendering
visionARViewController.isFenceVisible = false
}
}