Use the command line interface (CLI) of the Model Target Generator to integrate the software into automated workflows and toolchains.
The Model Target CLI allows for Model Target generation in scenarios where the entire process needs to be either automated or done with stricter usage guidelines and data protection, i.e., preventing uploading any CAD data..
See also Model Target Web API for alternative interactions with the Model Target Generator.
Prerequisites
There are different ways to use and authenticate Model Target generations with the Model Target CLI.
Use the CLI with:
- OAuth2 Client Credentials with the scope “datasetsignature.create” to sign the Model Target database.
- Your Vuforia Developer Credentials to sign the Model Target database generation. Developers with Basic plans are limited to 20 Model Target generations.
NOTE: When using Client Credentials or your Vuforia Developer Credentials, you only communicate with the cloud for authentication, sharing analytics, and database signing; there is no uploading of the CAD model.
If you are interested in the CLI version and have additional concerns on data protection, 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 Model Target CLI 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 Model Target CLI does not support generation of Advanced Model Targets nor the Simplification feature as these require uploading CAD data to the PTC and Vuforia servers.
Remember to add a license key from your Premium plan in your application.
Model Target Database Generation
The Model Target CLI expects a JSON file as input that describes the dataset and configuration of the Model Target.
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 the tracking will initialize. See the Guide Views section below for more details.
- Both
modelsandviewsare arrays and support loading multiple models and Guide Views to populate your dataset. cadDataUrlis the location of the 3D model you wish to use. This can be an absolute path or relative to the current working directory.optimizeTrackingForcan be set to ‘”default”, “low_feature_object”, or “ar_controller”. If the field is left empty, it will be assigned to “default”. See Optimizing Tracking for Model Targets for details.automaticColoringcan be set to "auto”, “never”, or “always”. If left empty, it defaults to “never”.upVectorshould define the up vector in model space. For common formats (including glTF) it will be Y-up [0.0, 1.0, 0.0].uniformScaleis the scale factor for preprocessing the 3D model. Its parameter is by default set to 1. Use it when the 3D model needs to be scaled up or down to match the real-life size of the object it represents.
## CREATE DATASET
{
"name": "dataset-name",
"models": [
{
"name": "3D-model",
"cadDataUrl": "C:/Development/My Models/3D-model.obj",
"optimizeTrackingFor": "default",
"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.
For prototyping and debugging, Guide Views can be set up in the Model Target Generator and copied into the input JSON file. Open the JSON project file in the MTG’s project folder, identify the relevant Guide View, and copy the translation and »translation objects into your own JSON description.
Using the Model Target CLI
Launch the executable from a command-line tool (PowerShell in Windows, Terminal in Linux), authenticate with your chosen authentication method, and load the JSON.
Command Line Interface.
The Model Target CLI has the following mandatory parameters:
-i: path to the JSON definition of the dataset (Alternative: an inline string that contains the json definition).-o: output file directory.
For dataset signing, choose one:
-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 Unity Asset Package is also generated that allows importing the dataset files into the Unity Editor. Model Targets created with the Model Target CLI includes preview models in the Unity scene, but the Inspector will not show a preview image.
