The Multimap Sample

This scene shows the basic setup needed to build an AR app with our localization features.

This sample requires you to first map a location with the Mapping App‚Äč

Open the MultimapSample scene found in the Assets/ImmersalSDK/Samples/Scenes folder.

Downloading Your Maps

Log in to the Developer Portal and download your map files of a premapped location.

Overview of the scene

The scene is very similar to the Content Placement sample. The difference is the addition of another AR Map and the lack of content placement functionality.

AR Session, AR Session Origin and AR Camera

Game objects provided by AR Foundation and you can find more about their functionalities from Unity's documentation. They provide the basic functionalities for the AR session.

ImmersalARCloudSDK

Basic settings for our SDK and the ARLocalizer.cs script.

  • Developer Token is where you would insert your token found in our Developer Portal. Since this sample uses an embedded map file, there is no need for a token (used for server connection).

  • Target Frame Rate for the app. iOS can manage 60fps, but most Android devices are locked to 30fps.

  • Android Resolution specifies the image size used by our SDK computer vision. Some older Android devices have performance issues with bigger image sizes so you can change this if needed.

  • iOS Resolution is the same setting, but for iOS devices. You can leave this at default, which for most devices is the maximum resolution.

AR Localizer is the script that uses our SDK to find the device pose within the map.

  • Localization Interval sets the interval between attempted localizations. At the app start, the script has an automatic burst mode to find the first ten or so poses as fast as possible.

  • Downsample reduces the image size for improved performance.

  • Debug Text is an optional reference to a TextMeshProUGUI object to display localization attempt information.

EventSystem and Canvas

These are components of Unity's UI system. The debug text displays the successful and total localization attempts.

The Pose Indicator is a prefab that gives an estimate of the current localization status. The prefab displays a red icon when no poses have been found or it has been a long time since the previous found pose. It also resets when AR Foundation loses tracking. When the SDK finds multiple poses, the indicator turns green.

The Pose Indicator also has events for OnPoseFound and OnPoseLost that can be used to trigger actions in an AR app.

AR Space and AR Maps

These game objects are used by our SDK to transform the AR content to match the real-world.

When a pose is found by ARLocalizer.cs, the AR Space is transformed in a way that the AR content visually matches the real-world. The AR Camera in the scene is not transformed, but the AR Space is brought to the camera.

All AR content should be placed under the AR Space game object.

Technically the content can be placed under the AR Maps themselves if that makes organizing the scene easier.

Map files in AR Maps are used to move the parent AR Space object. Every AR Map needs to have a parent AR Space object. If one does not exist, it will be created at runtime.

Since this sample uses an embedded map file, you should place the previously downloaded map to the Map File slot.

  • Map File is where you place your .bytes map data files available from the Developer Portal.

  • Color changes the color of the preview point cloud.

  • Render Mode sets the visibility of the preview point cloud. You can disable or render it in Editor and/or at runtime.

Using the sample

When you open the scene, you will see 2 AR Maps and their point cloud previews in the scene.

You can have as many AR Maps in the scene as you need, but having just one like in the Content Placement sample is fine too.

You can move and rotate the AR Space and AR Map game objects. Localization will take any edits you make into account. This is a key feature of our multimap support.

When the AR Map transform is reset, the pivot of the map is where the Anchor Image was taken.

Placing AR Content

The point cloud preview can be used to accurately place AR Content directly in the Unity Editor, which is very handy.

The Quick Tip video below shows how you can move and rotate the maps to fix any orientation problems and how to place content using the preview point cloud as a reference.

Building and testing

  1. Place your downloaded map files into the AR Map game object's map file slots in the inspector and align the maps.

  2. Open Build Settings (Ctrl + Shift + B) and make sure only the MultimapSample is included in the Scenes in Build.

  3. Change your Player Settings if necessary. It's a good idea to change the Product Name and Package Name so the app will not overwrite a previously installed app on your device.

  4. Build the app and install it to your device.

When you start the app and look around at the location you mapped, the device should localize and find its pose in just seconds.

If you set the AR Map Render Mode options to Editor and Runtime, you should see the point cloud previews of the maps align to the real world as poses are found.