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.
- In a new Unity Project, add the latest Vuforia Engine SDK and Vuforia Samples.
- Open the AreaTargetCapture Scene.
- 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.
- The GameObject is available in Vuforia Engine -> Area Target -> Area Target Capture.
- 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 Capture Behaviour component
The Area Target Capture Behaviour requires a 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).
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.
Alignment Database
Under the Advanced Settings, you can align your capture with an Alignment Database. Use this setting to align the origin of your capture with an existing Area Target’s pose. Aligning Area Targets can be done e.g., when you are replacing an Area Target and need to maintain the position and orientation, or if multiple Area Targets are part of an AR experience and a common origin is needed. See also Multiple Area Targets for adding multiple Area Targets in a Unity scene.
NOTE: Alignment works best when you align to smaller Area Target Databases. Alignment to large Area Targets can take up to a few minutes to complete. Aligning to an Area Target where more than one of its areas look similar to the captured space may cause alignment errors. See Scanning Practices for Handheld Scanners on how to scan smaller spaces with alignment in mind.
NOTE: Area Targets generated in the same session, without closing the app or resetting the Device Pose Behaviour, will be roughly aligned by default. Use the alignment option to actively choose the Area Target you want to use for alignment.
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.