Skip to main content

AR customization using Mapbox Vision SDK for Android

Additional Developer Resources
Prerequisite
Familiarity with Java or Kotlin.

Mapbox Vision AR for Android is a high-level framework that sits on top of the Mapbox Vision SDK for Android. Vision AR manages the navigation route, translates it to the core library, and renders an AR navigation route on top of the live video stream from the device’s camera. VisionArView is used to show navigation 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 Android documentation.

Then, update your Activity to use the code from AR navigation example. This example includes all the logic needed to set up a default vision navigation project, including:

  • Creating the VisionManager.
  • Creating the 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 in VisionArView via LaneVisualParams and FenceVisualParams. Default constructors of those classes init all the values of visual parameters with the defaults which used by VisionArView, so to reset visual parameters to default values you need to use default constructors.
  2. Visibility distance configuration is directly connected with computation load and should be adjusted narrowly to meet application performance requirements. For both lane and fence, this parameter is configured in the Activity using VisionARManager.

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 setArQuality() method on visionArView:

visionArView.setArQuality(0.8f);

AR lane customization​

Lane length​

Adjust the length of the AR lane using the setLaneLength method on a VisionARManager instance and specify a length in meters:

VisionArManager.setLaneLength(40f);
Note
It's not recommended to set value bigger than 100 meters.

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 VisionArView.

Note

Remember that lane visual parameters are not shared across instances of VisionArView recreation parameters should be set again.

Adjust the three available properties detailed below to achieve the desired visual effect.

Lane color​

Use Color 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:

final LaneVisualParams laneVisualParams = new LaneVisualParams(
        new Color(1.0f, 0.0f, 0.0f, 1.0f),
        LaneVisualParams.LANE_DEFAULT_WIDTH,
        LaneVisualParams.LANE_ARROW_DEFAULT_LENGTH
);

Lane width​

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

final LaneVisualParams laneVisualParams = new LaneVisualParams(
        new Color(1.0f, 0.0f, 0.0f, 1.0f),
        1.0f,
        LaneVisualParams.LANE_ARROW_DEFAULT_LENGTH
);

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:

final LaneVisualParams laneVisualParams = new LaneVisualParams(
        new Color(1.0f, 0.0f, 0.0f, 1.0f),
        1.0f,
        2.5f
);

AR fence customization​

You can enable AR fence rendering on a visionArView instance.

visionArView.setFenceVisible(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:

VisionArManager.setFenceVisibilityDistance(100.0f);

Fence visual parameters​

To customize fence appearance you need to use FenceVisualParams. It has empty default constructor which inits all the fields with default values which are used by VisionArView.

Note

Fence visual parameters are not shared across instances of VisionArViews, so after recreation of VisionArView objects 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 Color to define a custom color for the fence. The fence's appearance is tolerant to alpha component of the color.

The code below will make the fence yellow and leave other parameters as defaults:

final FenceVisualParams fenceVisualParams = new FenceVisualParams(
        new Color(1.0f, 1.0f, 0.0f, 1.0f),
        FenceVisualParams.FENCE_DEFAULT_HEIGHT,
        FenceVisualParams.FENCE_DEFAULT_VERTICAL_OFFSET,
        FenceVisualParams.FENCE_DEFAULT_HORIZONTAL_OFFSET,
        FenceVisualParams.FENCE_DEFAULT_SECTIONS_COUNT
);

Fence height​

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

final FenceVisualParams fenceVisualParams = new FenceVisualParams(
        new Color(1.0f, 1.0f, 0.0f, 1.0f),
        2.0f,
        FenceVisualParams.FENCE_DEFAULT_VERTICAL_OFFSET,
        FenceVisualParams.FENCE_DEFAULT_HORIZONTAL_OFFSET,
        FenceVisualParams.FENCE_DEFAULT_SECTIONS_COUNT
);

Fence vertical offset​

The fence's vertical offset is the distance above the road surface in meters. The code below will raise the fence 1 meter above the road:

final FenceVisualParams fenceVisualParams = new FenceVisualParams(
        new Color(1.0f, 1.0f, 0.0f, 1.0f),
        2.0f,
        1.0f,
        FenceVisualParams.FENCE_DEFAULT_HORIZONTAL_OFFSET,
        FenceVisualParams.FENCE_DEFAULT_SECTIONS_COUNT
);

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:

final FenceVisualParams fenceVisualParams = new FenceVisualParams(
        new Color(1.0f, 1.0f, 0.0f, 1.0f),
        2.0f,
        1.0f,
        3.0f,
        FenceVisualParams.FENCE_DEFAULT_SECTIONS_COUNT
);

Number of sections​

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

final FenceVisualParams fenceVisualParams = new FenceVisualParams(
        new Color(1.0f, 1.0f, 0.0f, 1.0f),
        2.0f,
        1.0f,
        3.0f,
        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.

visionArView.setFenceVisualParams(new FenceVisualParams());
visionArView.setLaneVisualParams(new LaneVisualParams());
// disable fences rendering
visionArView.setFenceVisible(false);

Final product​

You created a fully customized AR experience provided by Mapbox Vision AR for Android.

ArCustomizationActivity.java
github View on GitHub
package com.mapbox.vision.examples;

import androidx.annotation.NonNull;

import com.mapbox.vision.ar.FenceVisualParams;
import com.mapbox.vision.ar.LaneVisualParams;
import com.mapbox.vision.ar.VisionArManager;
import com.mapbox.vision.ar.core.models.Color;
import com.mapbox.vision.ar.view.gl.VisionArView;

public class ArCustomizationActivity extends ArActivity {

    @Override
    protected void setArRenderOptions(@NonNull final VisionArView visionArView) {
        // Make sure lane is visible
        visionArView.setLaneVisible(true);
        // Set the desired lane length in meters.
        VisionArManager.setLaneLength(40f);

        final LaneVisualParams laneVisualParams = new LaneVisualParams(
                // Set red lane color
                new Color(1.0f, 0.0f, 0.0f, 1.0f),
                // Set lane width in meters
                1f,
                // Set the length of the chevrons in meters
                2.5f
        );
        // After `laneVisualParams` is configured you need to set it to `VisionArView`
        visionArView.setLaneVisualParams(laneVisualParams);

        // Enable fence rendering
        visionArView.setFenceVisible(true);

        final FenceVisualParams fenceVisualParams = new FenceVisualParams(
                // Set yellow fence color
                new Color(1.0f, 1.0f, 0.0f, 1.0f),
                // Set the height of the fence in meters
                2f,
                // Set the vertical offset of the fence above the road surface in meters
                1f,
                // Set the horizontal offset of the fence from the center of the road in meters
                3f,
                // Set the number of arrows in the fence
                3
        );
        // After `fenceVisualParams` is configured you need to set it to to `VisionArView`
        visionArView.setFenceVisualParams(fenceVisualParams);
        // Setting AR render overall quality a bit lower to gain performance
        visionArView.setArQuality(0.8f);
    }
}
Additional Developer Resources
Was this page helpful?