AR customization using Mapbox Vision SDK for iOS

beginner
Swift
Prerequisite

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:

  1. Visual appearance (for example, color, size, and overall quality) is controlled through VisionARViewController via LaneVisualParams and FenceVisualParams.
  2. Visibility distance configuration is directly connected with computation load and should be adjusted narrowly to meet application performance requirements. This parameter is configured through VisionARManager for both lane and fence and affects corresponding events received by VisionARManagerDelegate.

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:

show hidden lines
// Adjust AR rendering quality
visionARViewController.set(arQuality: 0.8)
show hidden lines

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:

show hidden lines
// Set lane length in meters
visionARManager.set(laneLength: 40)
show hidden lines
Note

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.

Note

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.

show hidden lines
// Create an instance of `LaneVisualParams`
let laneVisualParams = LaneVisualParams()
show hidden lines
// Once `laneVisualParams` is configured, set it to the view controller
visionARViewController.set(laneVisualParams: laneVisualParams)
show hidden lines

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:

show hidden lines
// Set lane color
laneVisualParams.color = UIColor.red
show hidden lines

Lane width

Set the lane width in meters. The code below will make the red lane one meter wide:

show hidden lines
// Set lane width in meters
laneVisualParams.width = 1
show hidden lines

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:

show hidden lines
// Set the length of chevrons in meters
laneVisualParams.arrowLength = 2.5
show hidden lines

AR fence customization

You can enable AR fence rendering on a VisionARViewController instance.

show hidden lines
// Enable fence rendering
visionARViewController.isFenceVisible = true
show hidden lines

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:

show hidden lines
// Set fence length in meters
visionARManager.set(fenceVisibilityDistance: 200)
show hidden lines

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.

Note

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.

show hidden lines
// Create an instance of `FenceVisualParams`
let fenceVisualParams = FenceVisualParams()
show hidden lines
// Once `fenceVisualParams` is configured, set it to the view controller
visionARViewController.set(fenceVisualParams: fenceVisualParams)
show hidden lines

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:

show hidden lines
// Set fence color
fenceVisualParams.color = UIColor.yellow
show hidden lines

Fence height

Set the fence height in meters. The code below will make the yellow fence 2 meters tall:

show hidden lines
// Set fence height in meters
fenceVisualParams.height = 2
show hidden lines

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:

show hidden lines
// Set fence vertical offset above the road surface in meters
fenceVisualParams.verticalOffset = 1
show hidden lines

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:

show hidden lines
// Set fence horizontal offset from the camera in meters
fenceVisualParams.horizontalOffset = 3
show hidden lines

Number of sections

The AR fence consists of sections represented by glowing arrows. You can adjust the number of sections in the fence.

show hidden lines
// Set the number of arrows in the fence
fenceVisualParams.sectionsCount = 3
show hidden lines

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.

show hidden lines
// 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
show hidden lines

Final product

You have created an AR experience applying customization options available in the Mapbox Vision AR module.

ARCustomizationViewController
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
}
}
Was this page helpful?