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.

NOTE: All Anchor Observers should be deactivated before starting the capture to ensure correct behavior of the Mesh Observer with Area Target Capture source. The Anchor Observers can be activated again after the capture is completed.

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.

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”;

// 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 (_).

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, and a valid target name is provided.

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:

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

NORMAL

The capture is running normally.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

RELOCALIZING

The capture is relocalizing and the user should move around or return towards a previously mapped area in order to resume normal capturing.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

EXCESSIVE_MOTION

The user is moving too quickly.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

CAPACITY_WARNING

The capture is removing old data to make room for new data and should be stopped soon.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

INTERRUPTED

The capture is unable to add new data, the user should stop the capture.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

TRACKING_DATA_GENERATION

The capture is processing the captured data.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

AUTHORING_DATA_GENERATION

The capture is generating the authoring artifacts (3dt, glb).

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

DEVICE_DATABASE_GENERATION

The capture is generating the Vuforia device database (dat, xml).

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

PACKAGE_GENERATION

The capture is generating the package(s).

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

GENERATION_SUCCESS

Generation is successful.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

GENERATION_CANCELED

Generation was canceled.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

GENERATION_ERROR_INTERNAL

Generation failed because an internal error occurred.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

GENERATION_ERROR_NO_NETWORK_CONNECTION

Generation failed because the device has no network connection.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

GENERATION_ERROR_SERVICE_NOT_AVAILABLE

Generation failed because the server was not found, is unreachable, or overloaded.

VU_AREA_TARGET_CAPTURE_STATUS_INFO_

GENERATION_ERROR_AUTHORIZATION_FAILED

Generation failed because the credentials are wrong or outdated.

 

Mesh Observer

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