Roadmap

This is a unity package that delivers the authoring application for the UBCO roadmap. It has two components, a VR application and an AR application. Functionally they are the same, they allow to place, manipulate and persist models in the environment.

• AR Application: The AR application is built for mobile AR (Android/iOS). It uses the google's geospacial API, which uses the google streetview to localize and persist model locations between sessions with much better accuracy. See more information in the API: https://developers.google.com/ar/develop/geospatial

• VR Application: This is an Oculus application that allows the users to build out the environments in the VR when they are iterating on the designs. The current version mimcs the environment along the pathway north of the UBCO Campus.

Installaition

Note that the guides are written primarily for android, but they apply to iOS builds as well

Install prerequisites

• To ease things, make sure the project is switched to android platform (in build settings), the color space is switched to linear (in project settings > player).
• Install and configure Oculus Integration for unity.
• Install and configure MRTK for Oculus and Mobile AR
• Install AR Core extensions (See below for image guides)
  • In the pacakge manager, select "Add Package from git URL" from the dropdown on the topleft corner (the + sign).
  • Enter the url https://github.com/google-ar/arcore-unity-extensions.git
• Ensure the ARCore, ARKit and Oculus XR plugins are installed.
  • In the project settings, select and XR plug-in management.
  • Install if it's not already installed.
  • Under the android tab, select ARCore and Oculus
  • Under iOS tab, select ARKit

Install and setup roadmap

• Install package from git:
  • In the pacakge manager, select "Add Package from git URL" from the dropdown on the topleft corner (the + sign).
  • Enter the url https://github.com/hcilab-uofm/Roadmap-core.git
  • The link can be found in on github:
• Configure the defaults of the project by selecting Roadmap > Setup URP default assets
• Setup URP. Optionally, you may use the profiles shipped with this package. In the project windows it can be found in Pacakges > roadmap-core > Assets > Essentials > Settings
  • Update project with default URP settings: Roadmap > Setup URP default assets
  • Update the MRTK shaders: Mixed Reality > Toolkit > Utilities > Upgrade MRTK Standard Shaders for Universal Render Pipeline
• If you get the following error when building:

Shader error in 'Mixed Reality Toolkit/Standard'

- Use `Roadmap` > `Apply MRTK shader patch` to apply patch:

- The above is a fix following instructions in this issue comment. The above menu item applys the patch Media/MRTK_StandardShader_fix.patch

Usage

Main configuration

The main workhorse of this project is the RoadmapApplicationConfig object. A sample is provided with the project:

The models (as prefabs) and relevant data that you will use in the deployed apps on both AR and VR are configured using this. You can create your own config asset in the project window:

Give an appropriate name and setup the configuration. Configuration can be done in the inspector when you select the config asset in the project window.

The inspector would look something similar to this if you don't have any errors/issues and have a few models setup:

If you have any errors/issues you'll see appropriate options and messages to help you resolve them.

To use the configuration in the builds, you can add them to the PlaceablesManager component in the PlatformManager prefab in the scene.

To see how the respective AR (mobile) and VR (oculus quest) scenes would be configured, please see the AR and VR scenes available with the pacakge (see below). The necessary prefabs are also available in the package. Instead of configuring your own scenes, you can duplicate them into the project to add new functionalies.

Synchronization

To synchronize data between devices/group members:

• Make sure to use the same group ID, which can be set by clicking Set Group ID in the config (See above images for reference).
• Make sure the same prefabs and the corresponding config files are used before building the application on either end.

Note that the scene data is synchronize using a unique ID created from the groupID, the identifier of the config and the BuildID. If these three values are the same between the devices/group members, you sync data between them.

You may use the BuildID as a very crude version control system:

• When you have a scene you want to version, make sure the data is pushed to the remote (using sync or overwrite remote options in the built application).
• Build the application with a new BuildID to test a different setup.

Adding models

You can add/remove models through the inspector of a corresponding config (see above images) under Placeables using the + and - buttons. Each entry in Placeables should have a unique name and the corresponding prefab object. If there are duplicate entries (same identifier used or same prefab used), you will get a warning message and the option to remove duplicates along with the option to fix them.

From the inspector you can also builk add prefabs. Clicking on Add prefabs from a folder, will open a new window where you can select a folder. It would recursively search the folder and get all prefabs and list them. To add all the items displayed click on ok, or cancel otherwise.

Building and deploying apps

You can easily switch platforms, build and deploy applications for both AR and VR from the Roadmap Build Setup window. It's available on the menu:

In the window, you will have to drag and drop the respective scenes that should be built and deployed in the AR and VR fields. The location, relative to the project folder, can be set here. Select the platform you would want to build/deploy. If you are the oculus is selected as the target platform and start build is clicked, the OVR Build APK window will be opened for you where you can build deploy for oculus. If arcore is selected, the start build button will directly build the app. The deploy buttons works the same for both platforms, where it will be installed using adb to the device.

Note that, irrespective of which scene is currently open, if configured correctly, the correct scene would get built.

Updating package

This project is actively being develop. To update the package, from the package manager, you can click on update. If you you see unexpected errors, try removing and adding the pacakge back again. If you find any other problems with the package, don't hesitate to create a new issue on github.

To see the changes made, you may look at the CHANGELOG.md file.

Acknowledgement

• The AR version of the projects is built from the amazing PocketGarden implementation: https://github.com/buck-co/PocketGarden