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.
The Vuforia Engine Core Unity Samples includes the AreaTargetCapture scene which can be used freely as a starting point for your own application development.
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 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.
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.
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.
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.
Edit the Overlay Canvas and its child objects with your own custom UI and add those objects to the
AreaTargetCaptureBehaviour holds the events and calls to activate the UI. You can edit and add to these
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.
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
OnCaptureStatusInfo to assign events based on the status and success of the capture creation and capturing.
During capture, you may
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.
OnCaptureStopped to provide users with the next steps.
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
OnGenerationError to attach events on the progress of the target generation.
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.
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.