Area Target Capture API for Native

Implement the Capture API in your project to provide users with the capabilities to scan, generate, track, and overlay digital content in an area.

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

Area Target Capture Configuration

The Area Target Capture controller creates a capture instance based on a configuration setup. The configuration requires a Device Pose Observer, and you may choose to start the capture on creation.

// Retrieve the Area Target Capture controller
VuController* controller = nullptr;
vuEngineGetAreaTargetCaptureController(engine, &controller);

// Create the Area Target Capture configuration
VuAreaTargetCaptureConfig config = vuAreaTargetCaptureConfigDefault();

// Provide a valid Device Pose Observer
config.devicePoseObserver = devicePoseObserver; 

// Auto-start is disabled by default
config.start = VU_FALSE; 

Use the vuAreaTargetCaptureConfigDefault() function to create a configuration with default start (VU_FALSE) value.

When a configuration is created, you can use it to create the Area Target Capture instance. The Area Target Capture instance can be used to capture data and generate Area Targets from the captured data.

// Create the Area Target Capture instance 
VuAreaTargetCapture* capture = nullptr;
VuAreaTargetCaptureCreationError error = VU_AREA_TARGET_CAPTURE_CREATION_ERROR_NONE;
vuAreaTargetCaptureControllerCreateAreaTargetCapture(controller, &config, &capture, &error);

Only one capture can exist at a time, therefore, destroy the existing instance before creating a new one. The capture is created with status VU_AREA_TARGET_CAPTURE_STATUS_INITIALIZED, except if the configuration's start flag is VU_TRUE, then the capture is automatically started on creation with status VU_AREA_TARGET_CAPTURE_STATUS_PREPARING.

The create method returns VU_SUCCESS on successfully creating the capture object. On failure, the create method returns VU_FAILED and the error parameter will hold information about the cause.

Start the Capture

You can start, pause, and resume the capture. While the capture is running, it provides status and status info about its state; this includes if there is sufficient data for an Area Target to be generated, if the capture has reached a state where it cannot continue accumulating data, and if there is an error. Generating an Area Target from the capture data can only be done when the capture is stopped. See Capture States overview for more information.

// Start data acquisition
vuAreaTargetCaptureStart(capture); 

// Optionally pause and resume data acquisition
vuAreaTargetCapturePause(capture); 
vuAreaTargetCaptureResume(capture);

// Stop data acquisition
vuAreaTargetCaptureStop(capture);

After starting the capture, you may pause and resume data acquisition. The resume function returns the instance back into the PREPARING or CAPTURING status; which of the states you return to depends on what status the capture was in when pause was called.

A running capture will be automatically paused if you stop the Vuforia Engine with vuEngineStop(). The capture resumes automatically when you start the Engine again with vuEngineStart(). If the dedicated pause function was called before vuEngineStop(), then you will have to explicitly call the resume function after vuEngineStart().

NOTE: The Device Pose Observer must be active to capture data. Follow the usual recommendations for ensuring that Device Tracking is running normally during the capture process.

Please refer to Capture Status and Status Info for an overview of the Capture States.

Generate from Capture

You can start generating an Area Target from the capture when it is stopped and contains enough data to generate a target from. The stopped capture contains enough data to generate an Area Target if it switched from the PREPARING status to the CAPTURING status while running.

Area Targets generated in the same session, without closing the app or resetting the Device Pose Observer, will be roughly aligned by default. To actively align Area Targets, see Align Area Targets.

Configure the VuAreaTargetCaptureGenerationConfig with the required parameters: The generated target's name, the output folder directory where your artefacts will be placed into, the OAuth2 client credentials, and whether to generate authoring files, dataset files, and a .unitypackage file.

// Create the Area Target Capture  generation configuration
VuAreaTargetCaptureGenerationConfig config = vuAreaTargetCaptureGenerationConfigDefault();

// Provide the OAuth2 client id and client secret
config.userAuth = ”client id”;
config.secretAuth = ”client secret”;

// Set output directory and target name
config.outputDirectory = “/myFolderPath/”;
config.targetName = “myTargetName”;

// Optionally, set a path and targetName to an existing database to align the pose of the generated target with that Area Target
config.alignmentDatabasePath = “/alignWithDatabaseFolderPath/”;
config.alignmentTargetName= “alignWithTargetName”;

// Set requested Area Target artifacts
config.generateAuthoringFiles = VU_TRUE;
config.generateDatabase = VU_TRUE; 
config.generatePackages = VU_FALSE;

Use your OAuth2 client credentials as authentication in the configuration. Provide a valid path to an existing directory that is writable. The path can be absolute or relative. All generated files will be placed into the output directory, and therefore, it must exist for the entirety of the generation lifetime.

The names of the generated files will be based on the given targetName. The targetName must be an ASCII string that is between 1-64 characters long and only consists of the following characters: numerals (0-9), literals (a-z, A-Z), dash (-), and underscore (_).

Align Area Targets

It’s possible to align the capture that you are generating with another Area Target’s pose. This feature is especially useful when you need to re-scan an area due to changes in the surroundings, or if multiple Area Targets are part of an AR experience and a common origin is needed. Then, aligning the poses enables you to easily do so while keeping tracking stable and the AR content correctly rendered in the space. See Scanning Practices for Handheld Scanners on how to scan smaller spaces.

Align the capture instance generation by supplying the alignmentDatabasePath to the existing Area Target database and the Area Target’s alignmentTargetName as a string in the configuration.

NOTE: Alignment works best when you align to smaller Area Target Databases. Alignment to large Area Targets can take significantly longer. Aligning to an Area Target where more than one of its areas look similar to the captured space may cause alignment errors.

Generation files

Generate the files that are necessary for your use case.

Set the generateAuthoringFiles to VU_TRUE to generate the authoring 3DT Space file and the navigation mesh. Have only this this flag set to VU_TRUE to capture and save your work without Internet connection and without requiring the OAuth2 client credentials. After capture, transfer and load the 3DT Space files into the Area Target Generator for generating Area Targets. The Capture API cannot generate Area Targets solely from the 3DT Space file.

Set generateDatabase to VU_TRUE to generate the Area Target dataset file pair (.dat and .xml) with the Capture API. Dataset generation requires an Internet connection and valid OAuth2 client credentials.

Set generatePackages, generateAuthoringFiles, and generateDatabase to VU_TRUE to generate a .unitypackage for importing and editing the captured space later in Unity.

Generate an Area Target

To generate an Area Target from the capture call vuAreaTargetCaptureGenerate() with the capture instance, the generation config, and the optional generation error. Note that the parameters in the configuration must be valid and the capture must be stopped beforehand and hold enough capture data.

vuAreaTargetCaptureGenerationError error = VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_NONE;
vuAreaTargetCaptureGenerate(capture, &config, &error);

Target generation can be started when the required parameters are fulfilled; Vuforia Engine is running, capturing was stopped, enough capture data was gathered, valid credentials, a valid output directory, flag for generating the database, a valid target name is provided, and if alignment is set, a valid path to an Area Target database, and a valid Area Target name.

NOTE: If the Vuforia Engine is stopped while generation is running, the target generation is automatically canceled.

If all the requirements are met, vuAreaTargetCaptureGenerate() starts Area Target generation in the background, switches the capture to status VU_AREA_TARGET_CAPTURE_STATUS_GENERATING, and returns VU_SUCCESS. After generation, the capture status returns to VU_AREA_TARGET_CAPTURE_STATUS_STOPPED.

If any of the requirements weren’t met, vuAreaTargetCaptureGenerate() returns VU_FAILED, and the error parameter will hold the respective error information. If you are receiving the VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INVALID_STATUS, this indicates that the capture was not stopped beforehand.

If the capture hasn’t accumulated enough data, the VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_INSUFFICIENT_DATA is reported. You should then destroy the existing capture and start a new capture.

If the generation of an Area Target fails with VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_DATABASE_GENERATION_REQUIRED, the generateDatabaseflag was not enabled in the configuration of the capture. Similarly, receiving VU_AREA_TARGET_CAPTURE_GENERATION_ERROR_AUTHORING_FILES_GENERATION_REQUIRED means that the generateAuthoringFiles was not enabled. Both are required for generating the .unitypackage in the Capture API.

Cancel a running generation

You may cancel a running target generation by using the vuAreaTargetCaptureCancelGeneration() function. This function blocks until the generation is successfully aborted. Upon successful cancellation, status info will hold VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_CANCELED.

vuAreaTargetCaptureCancelGeneration(capture);

Monitor generation progress

While the capture is running Area Target generation, you can query for the associated progress and remaining time estimate.

float progress = 0.0f;
uint32_t remainingTimeSeconds = 0;
vuAreaTargetCaptureGetGenerationProgress(capture, &progress);
vuAreaTargetCaptureGetGenerationTimeEstimate(capture, &remainingTimeSeconds);

NOTE: vuAreaTargetCaptureGetGenerationProgress() may not provide an estimate at all times during generation; it returns VU_FALSE on such occasions.

When the status info returns VU_AREA_TARGET_CAPTURE_STATUS_INFO_GENERATION_SUCCESS, all requested artefacts specified in the configuration can be found in the specified outputDirectory. Destroy thereafter the instance to free up memory

vuAreaTargetCaptureDestroy(capture);

NOTE: Calling destroy while the capture is gathering data will automatically stop it from doing so. If the capture is running target generation, it will be automatically canceled.

Capture Status Info

Help your users during the capturing activity with the status info and on-screen messages.

VuAreaTargetCaptureStatusInfo statusInfo;
vuAreaTargetCaptureGetStatusInfo(capture, &statusInfo);

The following status info values are available:

Mesh Observer

The Mesh Observer section has been moved to Mesh Observer. Use the Mesh Observer to render runtime meshes based on your capture.  

Learn More

Area Target Capture API

Area Target Capture API for Unity