World-scale AR manual alignment
The world-scale AR manual alignment example allows for overlaying 3D maps and location data onto the AR camera feed using Unity’s AR interface and location services. This article outlines the setup and purpose of each major part of this example. Depending on your device and GPS signal, features in the AR scene may not be aligned properly with the features in the real world. This example scene is a good starting point for aligning your AR scene when the GPS signal is not strong enough.
Concepts
- AR Session: In AR apps, the scene’s main camera is positioned automatically to match the real-world device’s position, but only from the moment the app is initialized.
- Map Alignment: To make an AR session location aware, the WorldAlignmentKitManual prefab aligns a 3D map around the AR camera.
- Customization: Once the Map is aligned, you have access to all Mapbox’s data and customization to build world-scale experiences.
Getting started
To open the example, navigate to MapboxAR > Examples > Scenes > WorldScaleAR-ManualAlignment and double-click to open. You’ll see a split screen in the Game view. The bottom half of the screen is for aligning the position with the real world.
Some layers that aren’t included by default in a Unity project are needed to run this scene. Select WorldAlignmentKitManual in the Hierarchy view. To add new layers, click Layer and select Add Layer.
Next, add:
- ARGameObject
- Map
- Path
- Both
The WorldAlignmentKitManual contains:
- ARRoot: The UnityInterface Prefab for building cross-platform AR apps.
- MapCamera: A top-down view of the map, used to view GPS traces, AR position, and the current map alignment.
- ArAlignedMap: The map, aligned to AR Root using your devices location services. Renders blue debug color buildings by default.
- DebugCanvas: This contains a detailed debug log of location services and AR activity. To view it, press the LOG icon in play mode and on devices. This is included as a Unity UI element to make debugging easier on-location. It also contains a pointer button to relocalize the map.
- LocationProvider: Provides GPS data to the map, and spoofs data for testing in the editor.
Running in the editor
Once you set up your project layers, play the scene. In the Editor, the map is positioned based on EditorLocationProvider settings, a component attached to WorldAlignmentKitManual > LocationProvider > Editor in the hierarchy. In the Scene view, you'll see the map and the blue debug buildings. In the Game view, you'll see both the blue debug buildings, and a top down view of the map which shows the position indicated by a red pointer.
Editing the Scene
Make the scene more interesting by styling the buildings. With the following settings, you can transform the buildings from the debug blue color to one of the styles included with the Maps SDK for Unity.
- On the AbstractMap script, select the buildings Vector Layer Visualizer in the FEATURES section.
- Set the Texturing Style to Custom.
- Set the Texturing Type to Atlas With Color Palette.
- Select MapboxStylesRoofsPerRenderer for the Top Material.
- Select MapboxStylesFacadesPerRenderer for the Side Material.
- Select DefaultAtlasInfo for Atlas Info.
- Select Warm for the Color Palette.
Before building to your device, see the screenshot below to confirm the settings and run the scene in the Editor. For detailed information on how styling works read the styling documentation.
Running on a device
First, check that your device supports ARKit or ARCore. Build settings differ for iOS and Android. Check your Player Settings before you build:
- iOS: ARKit supports the METAL graphics API only. Select Metal or Auto Graphics API.
- iOS: Be sure to include a Camera Usage Description and Location Usage Description
- Android: Use OPENGL ES or Auto Graphics API.
Once the AR plane is detected, the map will be visualized with the styles that you set in the previous step. Then, you can manually align your map to your actual location. Use the lower part of the screen to specify your exact position. Use the upper part of screen to align the AR buildings with real buildings. To reset your location, press the pointer button on the right. Press the LOG icon on the left for debugging information.