This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.
For selected customers with a Pro license, an offline version of the Model Target Generator (MTG) is available as a command line tool. Integrate the tool into automated workflows and toolchains to use it in situations where an internet connection is not available.
The Offline MTG allows for Model Target generation in scenarios where the entire process needs to be either automated or done in an isolated (air-gapped) environment without internet connection.
Prerequisites
The offline MTG is only available to selected customers with a Pro license. A secret key pair is required to use the tool. If you are interested in the offline version of the MTG, please reach out to Vuforia Support on vuforia-feedback@ptc.com. In the email, please include your customer account details and a description of your use case.
The Offline MTG is only available for Windows and Linux operating systems and is distributed as a command line tool available in the Tools section of the Vuforia Developer Downloads page.
Limitations
We recommend file formats that encode units. These include, glTF, fbx, dae, pvz etc. 3D file formats that do not carry unit information may fail to correctly display Guide Views at runtime.
The offline MTG does not support generation of Advanced Model Targets nor the Simplification feature as these require uploading data to the PTC and Vuforia servers.
Model Target Datasets created with the Offline Model Target Generator can only be loaded by applications initialized with a particular Vuforia Engine license key. This key will be provided by Vuforia Support.
In addition, Model Target datasets created with the offline MTG can only be loaded with Vuforia Engine SDK version 9.8 or later. They are not backwards compatible.
Secret Key Pair
In order to use the offline MTG, a private and public RSA key pair must be created and used to sign the generated Model Target database.
- Contact us to get access to the offline MTG.
- After approval, use the snippet below to generate an RSA (cryptosystem) key pair (Base64 encoded) and share the public key with your Vuforia-feedback contact.
We then generate a Vuforia license key with the public key and return it to you. This Vuforia license key can be used for initializing your AR applications and is mandatory in applications that use the Model Target datasets generated from the Offline MTG. Using other license keys with datasets signed with a private key and generated from the offline MTG is not possible.
- With the private key, generate a Model Target dataset in the offline MTG.
- Use the provided Vuforia license key to sign your AR application that uses the dataset.
The following Java code snippet can be used to create a secret key pair:
import java.security.SecureRandom;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.util.Base64;
public class PublicPrivateKeyGenerator
{
public static void main(String[] args)
{
try{
KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSA");
keyGen.initialize(2048, new SecureRandom());
KeyPair keys = keyGen.genKeyPair();
byte[] publicKey = keys.getPublic().getEncoded();
byte[] privateKey = keys.getPrivate().getEncoded();
System.out.println("//privateKey = " + Base64.getEncoder().encodeToString(privateKey));
System.out.println("//publicKey = " + Base64.getEncoder().encodeToString(publicKey));
}
catch(Exception e)
{
}
}
}
Model Target Dataset Creation
The offline MTG expects a JSON file as input that describes the dataset to create. This defines the CAD model(s) to use as well as various parameters that will be used to create the dataset.
For a full list of supported 3D file formats and preparing your 3D model, please see the Best Practices article. For each Model Target, one or more views needs to be configured that will define at what positions tracking of the object can be initialized. See the Guide Views section below for more details.
- Both models and views are arrays and support loading multiple models and Guide Views to populate your dataset.
- cadDataUrl is the location of the 3D model you wish to use. This can be an absolute path or relative to the current working directory.
- trackingMode can be set to “default”, “car”, or “scan”. If the field is left empty, it will be assigned to “default”.
- motionHint is a hint to indicate if the object is likely to be moved or remain static. Set it to either “adaptive” or “static”. If left empty, it will default to “static”.
- automaticColoring can be set to "auto”, “never”, or “always”. If left empty, it defaults to “never”.
- upVector should define the up vector in model space. For common formats (including glTF) it will be Y-up [0.0, 1.0, 0.0].
## CREATE DATASET
{
“name”: “dataset-name”,
“models”: [
{
“name”: “3D-model”,
“cadDataUrl”: “C:/Development/My Models/3D-model.obj”,
“trackingMode”: “default”,
“motionHint”: “static”,
“automaticColoring”: “auto”,
“upVector”: [ 0.0, 1.0, 0.0 ],
“views”: [
{
“name”: “viewpoint-name”,
“guideViewPosition”: {
“translation”: [ 0, 0, 5 ],
“rotation”: [ 0, 0, 0, 1 ]
}
}
]
}
]
}
Guide Views
A Model Target can support multiple Guide Views that you can switch between manually. Each Guide View is specified with a translation and rotation that represents the position of the virtual camera with respect to the object. This virtual camera follows the glTF Y-up convention with the lens looking towards the negative Z-axis.
- The rotation field defines a 3D rotation quaternion [qx, qy, qz, qw].
- The translation field defines a 3D translational offset in scene units [tx, ty, tz].
Please refer to the Model Target Guide Views article for details on Guide Views.
Using the Offline MTG
Launch the offline MTG command-line tool (PowerShell in Windows, Terminal in Linux) and load the private key and 3D model as a JSON.
Command Line Interface.
The offline MTG requires the following parameters:
-i: path to the JSON definition of the dataset (Alternative: an inline string that contains the json definition)-o: output file location-p: private key for signing the dataset
Output files
Generating a Model Target Dataset with the Offline Model Target Generator does not require any connectivity. The dataset will be signed with the provided private key, no outside connection will be established.
The output dataset consists of an .xml and .dat file pair. A .unitypackage is also generated that allows importing the dataset into the Unity Editor. Model Targets created with the Offline MTG will be represented with preview models in the Unity scene, but the inspector will not show a preview image.
When loading the created Model Target Dataset in your Vuforia Engine application, make sure to use the Vuforia Engine license key provided by Vuforia Support. The license key needs to match the private key provided to the Offline MTG during dataset generation.
Using another Engine license key to initialize the application will fail to load the dataset.