Cloud Area Targets

Cloud Area Targets extend the accessibility of Vuforia’s Area Target technology by hosting the target dataset in a safe cloud-hosting environment provided by PTC. This reduces the initial app download size, and guarantees at runtime that only the necessary portions of the target and the occlusion representation are streamed to the device, keeping transport and storage to the bare minimum. Follow this guide to get started.

Introduction

The Cloud Area Targets feature uses cloud-hosted artifacts in PTC’s Area Target Web Service to provide tracking and occlusion through the AreaTargetObserver and MeshObserver respectively. The feature supports streaming, where the data is downloaded on an as-needed basis which reduces the amount of data that needs to be downloaded.

Data Communication

Area Targets are generated and managed via the Cloud Area Target Web API. It is an HTTPs REST API authenticated using your Vuforia Engine Developer Portal account, with authorization controls to create/modify/delete and stream targets. See Authentication for details.

During runtime, you can pass read-only credentials to the Vuforia Engine SDK to securely retrieve your target assets from the high-performance Cloud Area Target delivery environment. The above diagram explains the relationship of the components and how users only download parts of the Area Target as needed.

Important considerations to keep in mind about streaming Cloud Area Targets:

• Tracking data can be streamed in parts only if the developer provides the external position (external prior), otherwise the user needs to download the whole dataset for initial localization. (as one can assume the user might be anywhere in the target).
• Occlusion meshes are streamed in parts based on the initial estimated pose.
• There is a persistent on-device cache for already downloaded data. Unless this cache is explicitly deleted (via the SDK function, app uninstall or some other cache cleanup functionality - like clearing cache in an app menu on Android) - the data will not be downloaded again.

Further considerations:

• The use of external position or lack thereof will affect the amount of downloaded data and latency of the initial localization.
• The downloaded data is measured in m².

Network bandwidth will affect performance.

• 4G, 5G and typical wi-fi connections all might have quite different bandwidth and latency characteristics, depending on coverage and other factors.
• Loss of network connection might affect tracking and occlusion quality.

Prerequisites

Cloud Area Targets requires the purchase of a Cloud Area Targets Add-on, which can only be added to a Premium or Enterprise plan. Contact us to learn more.

The Python areatarget-webapi-client.py client library is provided along with the credential entitlements.

For trial access, please contact Vuforia Engine via the support form for access to Cloud Area Targets, as well as to get access to the Python script.

Device Support

Primary supported device platforms are iOS (with ARKit) and Android (with ARCore).

Manage Cloud Area Targets

Manage your hosted Cloud Area Targets with the Python client library to create, list, download, and delete Cloud Area Targets using simple commands. The Python library is named areatarget-webapi-client.py and is only provided during a customer's Cloud Area Target setup process.

Prerequisites

The Python client requires Python 3.8 and the following Python dependencies installed via pip or apt-get install:

• requests
• tqdm

Cloud Area Targets can be created using the Authoring Space file (3DT), as generated by the Area Target Generator, the Vuforia Creator App, or the Area Target Capture API. See How to Create Area Targets on creating Space files.

Additionally, we support the generation of Cloud Area Targets directly from E57 source input data from the supported range of scanners. See Area Targets for a list of supported scanners.

Credentials

Use the Credentials tab in the Engine Developer Portal to create and configure client credentials that are required for Cloud Area Targets. These should be made after your account has been set up with the correct entitlements. We recommend creating two sets of Oauth2 credentials;

• one for creation and management of Cloud Area Targets, and
• one for runtime delivery in the app with just the areatargets.delivery scope enabled.

This will prevent you from mistakenly build and publish an application with the credentials of all the areatargets scopes. If you do only use one set of credentials, consider making them read-only.

See Web API Authentication and Scopes for details.

Create

Create a Cloud Area Target with the Python client by executing the following command:

area-target-webapi-client.py \
    --client_id CLIENT_ID --client_secret CLIENT_SECRET \
    create FILE.3DT|FILE.E57

This will upload the specified Space file (3DT or E57) and generate the Cloud Area Target in the Vuforia Servers that are located in the USA.

The create command can take from a few seconds to a few hours to complete depending on the size of the space file and the quality of the network connection.

When the create command completes, the output will contain the Area Target id and other info as follows:

{
    'generation_progress': 0,
    'id': '7d6572223125f39402d79ed6996ecc18',
    'name': 'Example',
    'status': 'awaiting_generation'
}

While generation is in progress, you can query its status with:

area-target-webapi-client.py \
    --client_id CLIENT_ID --client_secret CLIENT_SECRET \
    status TARGET_ID

That will output, e.g., awaiting generation:

{
    'generation_progress': 0,
    'id': '7d6572223125f39402d79ed6996ecc18',
    'name': 'Example',
    'status': 'awaiting_generation'
}

Or, generation in progress:

{
    'generation_progress': 19,
    'id': '7d6572223125f39402d79ed6996ecc18',
    'name': 'Example',
    'status': 'generation_in_progress'
}

And when completed, the output will state ready:

{
    'id': '7d6572223125f39402d79ed6996ecc18',
    'name': 'Example',
    'status': 'ready'
}

When the reported status is ready, then the generation process is completed and the Cloud Area Target is ready for use.

An Observer can now be created in Unity with the TargetID. Follow the instructions in the Working with in Unity guide to set up your Cloud Area Target.

Download

To author content against the Area Targets in Unity, download the Unity package from the cloud as follows:

area-target-webapi-client.py \
    --client_id CLIENT_ID --client_secret CLIENT_SECRET \
    download TARGET_ID DST_FOLDER --download_authoring unitypackage

List

List your Cloud Area Targets using the list command: Each generated Cloud Area Target associated with the client credentials is listed with name, id, and other details.

area-target-webapi-client.py \
    --client_id CLIENT_ID --client_secret CLIENT_SECRET \
    list

Delete

Delete a Cloud Area Target using its TargetID.

area-target-webapi-client.py \
    --client_id CLIENT_ID --client_secret CLIENT_SECRET \
    delete TARGET_ID

Troubleshooting issues

In case the Python client fails for any reason, you can re-execute the failing command with the extra option -vv for more details.

Learn More

Vuforia Web Services API

Authentication

Area Targets

Area Targets in Unity

Area Targets API Overview