How to Create Datasets for Playback

With Lightship's Recording feature, you can record the real-world location of your AR application for playback and testing in the Unity editor. You can create a playback dataset by using the Recording sample project or by recording through the API.

Prerequisites

To scan using the Recording sample project, you will need to download it and build it to your device. For more information, see Sample Projects.

To create your own recording app, you will need a Unity project with Lightship AR enabled. For more information, see Installing ARDK 3.0.

Using the Scanning Sample to Record

To record a playback dataset using the sample:

1. Open the recording sample on your device. When you are ready to record the dataset, tap Start.
2. Record the environment using your device's camera. Keep in mind the following:

• Keep your device in Portrait Mode.
• Hold your device as steadily as possible to reduce errors in the dataset.
• The sample has a one-minute time limit for recording your dataset.

1. Tap Stop to finish recording.
2. When you are ready, tap Export to convert your most recent recording to a playback dataset.
3. After the export is complete, the sample will display a path to the archived dataset. Remember this path to locate the dataset later for use in the editor.

Using the API to Record Datasets

If the Recording sample is too limited for your project, you can create your own scanner instead.

To create a location scanner in Unity:

1. Enable Scanning in Lightship Settings:
   1. In the Lightship top menu, select Settings.
   2. In the Inspector window, check the box labeled Scanning.
2. In your AR Scene, add an AR Scanning Manager to the scene, then disable it:
   1. Select the ARSession GameObject.
   2. In the Inspector window, click Add Component, then add an AR Scanning Manager to it.
   3. Un-check the box next to AR Scanning Manager (Script) to disable it.
3. Create two buttons in your scene; one to start the recording, the other to stop it.
   1. Right-click in the Hierarchy, then, in the UI menu, select Button. Rename the Button "Record".
   2. Repeat the previous step, naming the new button "Stop".
   3. For each button, expand its GameObject and select the Text sub-object, then change the Text field to "Record" or "Stop", as appropriate.
   4. Move the buttons in the scene view to where you would like them.
4. Create scripts to drive the recording, then connect them to the buttons:
   1. In the Assets window, right-click, then select C# Script from the Create menu. Name the new script StartScript. Repeat this two more times, naming the scripts RecordButton and StopButton.
   2. In the Hierarchy, right-click, then select Create Empty. Name the new GameObject "Startup". 1. With Startup selected, in the Inspector window, click Add Component and add StartScript to Startup.
   3. Select each button in the Hierarchy, then add its appropriate script to the OnClick field in the Inspector.
5. Add the code found at the end of this page to the appropriate scripts, then build to your device and test it out!

Exporting Recorded Data

Follow the instructions for your device's operating system:

Exporting from iOS

1. Connect your device to Xcode, then enable developer mode.
2. Under Device and Simulators, find the sample app.
3. Using the dot menu, tap Download Container.
4. Once the container downloads to your machine, right-click on the package, then click Show Package Contents.
5. Navigate to the path from the recording output (for example: AppData/Documents/scankit/(ID of your scan)/chunk_0.tgz).
6. Copy the archive to your machine, then unzip it into the Assets/StreamingAssets directory in your Unity project.

Exporting from Android

1. Connect your device to your development machine.
2. Get the files from your device:
   1. iOS: Open Android File Transfer, then navigate to the path from the recording output.
   2. Windows: When the dialog pops up asking what you want to do, select File Transfer, then navigate to the path from the recording.
3. Copy the archive to your machine, then unzip it into the Assets/StreamingAssets directory in your Unity project.

Using the Playback Data in Unity

To add a playback dataset to Unity:

1. Open Project Settings from the Edit menu, then scroll down to XR Plugin Management and select Niantic Lightship SDK.
2. Enable Editor Playback, then input the absolute path to your dataset in the Dataset Path field.

StartScript.cs

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class StartScript : MonoBehaviour
{
   public void Start() {
      // get permission to use location data if on Android
      // then enable location and compass services
       #if UNITY_ANDROID
        if (!Permission.HasUserAuthorizedPermission(Permission.FineLocation))
        {
            var androidPermissionCallbacks = new PermissionCallbacks();
            androidPermissionCallbacks.PermissionGranted += permissionName =>
            {
                if (permissionName == "android.permission.ACCESS_FINE_LOCATION")
                {
                    Start();
                }
            };

            Permission.RequestUserPermission(Permission.FineLocation, androidPermissionCallbacks);
            return;
        }
        #endif
       Input.compass.enabled = true;
       Input.location.Start();
  }
}

RecordButton.cs

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class RecordButton : MonoBehaviour
{
  // enable the scanning manager to start recording
  public void StartRecording() {
    ARScanningManager.enabled = true;
  }

}

StopButton.cs

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class StopButton : MonoBehaviour
{
  public async void StopRecordingAndExport() {

    // save the recording with SaveScan()
    // use ScanStore() to get a reference to it, then ScanArchiveBuilder() to export it
    // output the path to the playback recording as a debug message
    string scanId = ARScanningManager.GetCurrentScanId();
    await ARScanningManager.SaveScan();
    var savedScan = ARScanningManager.GetScanStore().GetSavedScans().Find(scan => scan.ScanId == scanId);
    ScanArchiveBuilder builder = new ScanArchiveBuilder(savedScan, new UploadUserInfo());
    while (builder.HasMoreChunks())
    {
        var task = builder.CreateTaskToGetNextChunk();
        task.Start();
        await task;
        Debug.Log(task.Result);   // <- this is the path to the playback recording.
    }
    ARScanningManager.enabled = false;
  }

}