All docsHelpTutorialsAR customization using Mapbox Vision SDK for iOS

AR customization using Mapbox Vision SDK for iOS

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:

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

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:

// Set lane length in meters
visionARManager.set(laneLength: 40)
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.

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

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:

// Set lane color
laneVisualParams.color = UIColor.red

Lane width

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

// Set lane width in meters
laneVisualParams.width = 1

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:

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

AR fence customization

You can enable AR fence rendering on a VisionARViewController instance.

// Enable fence rendering
visionARViewController.isFenceVisible = true

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:

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

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.

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

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:

// Set fence color
fenceVisualParams.color = UIColor.yellow

Fence height

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

// Set fence height in meters
fenceVisualParams.height = 2

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:

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

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:

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

Number of sections

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

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

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.

// 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

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
}
}