Skip to main content

AR customization using Mapbox Vision SDK for iOS

Join the Mapbox Developers Discord Communityarrow-right
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 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
github View on GitHub
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
    }
}
Join the Mapbox Developers Discord Communityarrow-right
Was this page helpful?