Area Target Capture API for Unity

The Area Target Capture GameObject in Unity includes a simple user interface and components to easily customize and build your application with capturing and Area Target generation capabilities.

For a general introduction, please see Area Target Capture API.

Quickstart Guide

The Vuforia Engine Core Unity Samples includes the AreaTargetCapture scene which can be used freely as a starting point for your own application development.

  1. In a new Unity Project, add the latest Vuforia Engine SDK and Vuforia Samples.
  2. Open the AreaTargetCapture Scene.
  3. Configure the Build Settings to iOS and build to a device with LiDAR.

Area Target Capture GameObject

In Unity, an Area Target Capture GameObject implements the Area Target Capture Behaviour. Add the Area Target capture to your build to enable capturing spaces. Authenticate target generating by creating a credentials pair and insert them in the Client ID and Client Secret. See Vuforia Web API Authentication for details.

  1. The GameObject is available in Vuforia Engine -> Area Target -> Area Target Capture.
  2. Add the AR Camera to your scene and set up Vuforia Configuration with an application license key and the Share Recordings in iTunes setting enabled.

The Area Target Capture Prefab contains a default UI to control the capturing and generation process. You may replace this with your own UI from the component Inspector window of the Area Target Behaviour.

 

Area Target Behaviour component

The Area Target Capture Behaviour requires an Client ID and a Client Secret as input which are the Client Credentials obtained as described in Vuforia Web API Authentication with Client Credentials.

You must also provide the capture with a Target Name of 1-64 characters without spaces and use only ASCII characters (numerals, literals, dash, and underscore).

NOTE: HitTest and Anchor creation are automatically disabled during capturing when an Area Target Capture Behaviour is active. After the capture is completed, HitTest and Anchors are again available.

Use a Material to display a preview mesh during the capture process for user feedback if you have a dedicated capture phase in your application. When enabled, the Preview Mesh Material will be rendered on the captured surfaces. See Preview Mesh for details.

Additional Assets

Choose which artifacts you wish to generate from the capture. When enabled, the Authoring Structure will generate authoring mesh, occlusion mesh, and Navigation Mesh files. A *.unitypackage can also be generated from the capture; this package will contain the files needed for authoring Area Targets in Unity. See Area Targets in Unity for details.

The Storage Directory is the persistent data folder in Unity, and when Share recording in iTunes is enabled, files are easily transferable, See the Recording and Playback feature for details on transferring from a device. Each capture receives the Target Name and a timestamp if multiple captures are created during a session. The Storage Directory is a read only and cannot be changed.

Preview Mesh

An essential part of the Area Target Capture is the PreviewMesh GameObject. The Mesh Visualization Behaviour is used for visualizing the capturing process by rendering a layer on the captured surfaces at runtime. Changing the Display Material will also affect the Preview Mesh Material in the Area Target Behaviour component.

Capturing and Generation Workflow

There are a couple of things to have in mind besides the general Scanning an Environment practices, namely, the movement during capturing and reaching the size limit of the scan.

  • To initiate the capture after start, some motion of the device is required before the capture instance switches from PREPARING to CAPTURING
  • Users need to find a balance between too little and too much motion during capturing: You can notify the user when either of the following two are reported from the status info.
    • The status info CAPACITY_WARNING reports when the maximum size of the captured data is reached and that the capture will start discarding earlier captured data to make space for the new one. It is recommended to stop capturing at this point.
    • The status info INTERRUPTED is a warning message that the capture cannot add more data and the users should stop the capturing immediately.
  • NOTE: When resuming from a paused capture session, users are required to relocalize in the space by pointing the device’s camera towards an already captured area.

Capture Status and Status Info

The AreaTargetCaptureStatus and AreaTargetCaptureStatusInfo provides information on the status of the capture. Use the reported information to track the progress of the capture and on the target generation.

Capture States Overview

In the capture create process, the instance will switch from INITIALIZED into a PREPARING status; and starts accumulating data until there is enough information to generate a functional Area Target that is reported with the CAPTURING status. Data acquisition continues to accumulate, but you can at this point stop the capture and trigger the target generation.

Configuration Options

Edit the Overlay Canvas and its child objects with your own custom UI and add those objects to the AreaTargetCaptureOverlayCanvas.

The AreaTargetCaptureBehaviour holds the events and calls to activate the UI. You can edit and add to these OnCapture() and OnGeneration() functions.

Capture API

The Area Target Capture API can be divided into two main parts: capturing and generating. To generate a target, the AreaTargetCaptureBehaviour must be present with the fields Client ID, Client Secret, and Target Name filled out.

Capturing

When StartCapture() is called, the AreaTargetCaptureBehaviour creates a capture instance (with status INITIALIZED) where data is stored as the user scans the room. During data acquisition, the capture status is PREPARING or CAPTURING where the former informs that there is not yet enough data, but the latter status does.

Use the subscriber objects OnCaptureCreationError, OnCaptureStarted, and OnCaptureStatusInfo to assign events based on the status and success of the capture creation and capturing.

During capture, you may PauseCapture() and ResumeCapture(). The capture status then switches to PAUSED. PauseCapture() can only succeed if the status was in PREPARING or CAPTURING. ResumeCapture() will fail if the status was not PAUSED.

When a capture from the user is done, they should be able to StopCapture(). The capture status will switch to STOPPED. Calling StopCapture() will only succeed if the status was PREPARING, CAPTURING, or PAUSED. A capture must be stopped before you can generate a target from it.

Use OnCaptureStopped to provide users with the next steps.

Generating

Call GenerateTarget(string TargetName) to asynchronously generate the Area Target from the captured data. The capture status will switch to GENERATING and to STOPPED when generation is completed. GenerateTarget() can only be called if the capture accumulated enough data to switch from PREPARING to CAPTURING status. If the generation is successful, the capture instance and data will automatically be destroyed. If the generation fails, the status info will hold details on the cause.

Subscribe to the OnGenerationStarted, OnGenerationCompleted, and OnGenerationError to attach events on the progress of the target generation.

Use also GetGenerationTimeEstimate(out int generationTimeEstimate) to get the remaining generation time in seconds. The capture status must be in GENERATING for it to succeed. It may take few seconds after the Area Target generation started for the time estimate to become available.

Subscribe to OnGenerationProgressUpdated and OnGenerationRemainingTimeUpdated to update any UI dependencies.

A running generation can be canceled with CancelTargetGeneration(). Upon canceling, the capture will switch to CANCELED status. A new GenerateTarget() call can then be made.

Should the user decide not to generate a target from the capture, calling DestroyCapture() will destroy the capture.