Area Target Capture API for Native

Implement the Capture API in your project to provide users 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.

VuController* controller = nullptr;
vuEngineGetAreaTargetCaptureController(engine, &controller);

VuAreaTargetCaptureConfig config = vuAreaTargetCaptureConfigDefault();
config.devicePoseObserver = devicePoseObserver; // Provide a valid Device Pose Observer
config.start = VU_FALSE; // Default configuration value

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

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

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 in order to ensure correct behavior of the Area Target Capture preview mesh on all platforms. They 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 a 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.

vuAreaTargetCaptureStart(capture); // Start data acquisition

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

vuAreaTargetCaptureStop(capture); // Stop data acquisition

// Generate Area Target
...

After starting the capture, you may pause and resume data acquisition. The resume function returns the instance back into the PREPARING or CAPTURING state; which of the states you return to depends on what state it 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. 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 and a .unitypackage file.

VuAreaTargetCaptureGenerationConfig config = vuAreaTargetCaptureGenerationConfigDefault();
config.userAuth = ””; // Client ID
config.secretAuth = ””; // Client Secret
config.outputDirectory = “/myFolderPath/”;
config.targetName = “myTargetName”;

config.generateAuthoringFiles = VU_TRUE; // Default configuration values
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 (_).

Set generateAuthoringFiles to VU_TRUE to generate additional artefacts, namely, the authoring .3dt file, the occlusion mesh, and the navigation mesh.
Set generatePackages to VU_TRUE to generate a .unitypackage. The generateAuthoringFiles must also be VU_TRUE in this case, otherwise the generation of the .unitypackage file fails.

Generate an Area Target

Call vuAreaTargetCaptureGenerate() with the generation config, generation error, and the capture instance. Note that the parameters in the configuration must be valid/passed 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 has been stopped, enough capture data was gathered, valid credentials, a valid output directory, and a valid target name is provided.

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

vuAreaTargetCaptureGenerate() will then start running target generation in the background and the status will switch to VU_AREA_TARGET_CAPTURE_STATUS_GENERATING, and immediately returnsVU_SUCCESS. After generation, the 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.

Cancel a running generation

You may cancel a running target generation by using the vuAreaTargetCaptureCancelGeneration() function. This function blocks other calls 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 retrieves mesh updates during capturing from an Area Target Capture instance. Use the Observer to render a preview mesh of a capture giving users appropriate UX feedback on the covered area. Create and configure the Observer and then use its mesh observations to render meshes at runtime. The Mesh Observer configuration requires an Area Target Capture instance and the parameter activate that can be set to VU_FALSE or VU_TRUE.

VuMeshAreaTargetCaptureConfig config = vuMeshAreaTargetCaptureConfigDefault();

// Default configuration values
config.capture = capture; // Must be a valid VuAreaTargetCapture instance
config.activate = VU_TRUE; // Auto-activates on creation

The Area Target Capture instance is the exclusive source of the Mesh Observations reported by the Mesh Observer.

The Mesh Observer is dependent on the existence of the Area Target Capture instance from which it is drawing the Mesh observations from. Therefore, destroy the Mesh Observer before you destroy the Area Target Capture instance.

VuObserver* meshObserver = nullptr;
VuMeshAreaTargetCaptureCreationError error = VU_MESH_AREA_TARGET_CAPTURE_CREATION_ERROR_NONE;
vuEngineCreateMeshObserverFromAreaTargetCaptureConfig(engine, meshObserver, &config, &error);

Destroy the Mesh Observer.

vuObserverDestroy(meshObserver);

Status and status info

Retrieve the Mesh observations from the Engine State. First, create an observation list to hold the Mesh observations.

// Create observation list
VuObservationList* obsList = nullptr;
vuObservationListCreate(&obsList);

// Get the Mesh observation list
vuStateGetObservationsByObserver(state, meshObserver, obsList);
int numObservations = 0;
vuObservationListGetSize(obsList, &numObservations)
for (int i = 0; i < numObservations; i++)
{
   VuObservation* obs = nullptr;
   vuObservationListGetElement(obsList, i, &obs));
   // process observation
}

Each Mesh Observation holds an object of type that contains a list of Mesh Blocks. The VuMeshObservationInfo always hold a complete list of the meshes from the Area Target Capture instance, including meshes that were unchanged, recently updated, or added to the list. Meshes removed from the list will not have their ID reported in the latest retrieved observation.

// Get observation info from a Mesh observation
VuMeshObservationInfo info;
vuMeshObservationGetInfo(obs, &info);

Mesh observation block

Each mesh block holds metadata and the actual mesh data. The metadata consists of a unique ID, a timestamp, and a version number. These fields enable the unique identification of each mesh block and the tracking of potential updates to the mesh block.  Both the ID and the version are positive numbers.

The IDs are unique within a Vuforia session, they are generated at runtime and are not persistent across Vuforia sessions. Moreover, the IDs are not reused, meaning that a newly added mesh block can never have the same ID as an already removed mesh block. Whenever a mesh block has been updated, its timestamp is adjusted to reflect the time of the change, and its version is increased. The actual data of a mesh block consists of an axis aligned bounding box of the mesh, and a pointer to a VuMesh structure that holds the mesh. The meshes are reported in world space coordinates.

int numBlocks = 0;
vuMeshObservationBlockListGetSize(info.meshes, &numBlocks);
for (int b = 0; b < numBlocks; b++)
{
    VuMeshObservationBlock block;
    vuMeshObservationBlockListGetElement(info.meshes, b, &block);
    // Render VuMesh of Mesh Block
    render(block.mesh);
}