Offline Model Target Generator

For customers with a Premium plan, 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 limits the communication to the Vuforia servers down to a complete air-gapped environment depending on the method you choose to sign generated model targets with.

Use the offline MTG with:

  • A secret key pair to work in complete air-gapped environments. No data communication is sent.
  • OAuth2 Client Credentials with the scope "datasetsignature.create” to sign the Model Target dataset.
  • Your Vuforia Developer Credentials to sign the Model Target dataset creation.

    NOTE: When using Client Credentials or your Vuforia Developer Credentials, the Offline Model Target Generator communicates with the cloud for authentication, sharing analytics and dataset signing, but without uploading the CAD model.

If you are interested in the offline version, 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 MTG and signed with the private key for air-gapped environments can only be loaded by applications initialized with a particular Vuforia Engine license key. This key will be provided by Vuforia Support.

If you sign with your Vuforia Developer Credentials or OAuth2 Client Credentials, any license key from your Premium plan can be used in your application.

In addition, Model Target dataset files created with the offline MTG can only be loaded with Vuforia Engine SDK version 10.0 or later.

Secret Key Pair

To use the offline MTG in air-gapped environments, create a private and public RSA key pair. The public key is used by us to generate a unique license key for you to add in your application. Use the private key to sign the Offline Model Target dataset generations.

  1. Contact us to get access to the offline MTG.
  2. After approval, use the snippet below to generate a cryptographic signing key pair in RSA Base64 encoded format and share the public key with your Vuforia-feedback contact.

    The following Java code snippet can be used to create a secret key pair:

    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 with this key. Using other license keys with datasets signed with a private key and generated from the offline MTG is not possible.

  3. With the private key, generate a Model Target dataset file pair in the offline MTG. Use the provided Vuforia license key to sign your AR application that uses the dataset files.
  4. Use the provided Vuforia license key to sign your AR application that uses the dataset files.

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

For dataset signing, choose one:

  • -p: private key for signing the dataset.
  • -vu: your Vuforia developer portal username and -vp: your Vuforia developer portal password.
  • -ci: client credential client_id and -cs: client credential client_secret.

Output files

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 including preview models in the Unity scene, but the inspector will not show a preview image.