Use the Model Target Generator's command-line interface (CLI) 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 the uploading of CAD data.
See also Model Target Web API for alternative interactions with the Model Target Generator.
Prerequisites
Choose one of two 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; the CAD model is not uploaded.
If you are interested in the CLI version or require an on-premise setup with a restricted internet connection contact Vuforia Support at vuforia-feedback@ptc.com. In the email, please include your customer account details and a description of your use case.
Limitations
The Model Target CLI is available for Windows, MacOS, and Linux operating systems. See Supported Versions for the supported minimum versions. The CLI is distributed as a command line tool in the Tools section of the Vuforia Developer Downloads page.
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 the 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 to your application.
Model Target Database Generation
The Model Target CLI expects a JSON file to be the input that describes the dataset and configuration of the Model Target.
See the Best Practices article for a complete list of supported 3D file formats and preparing your 3D model. For each Model Target, one or more views
need to be configured to define the positions from which the tracking can be initialized. See the Guide Views section below for more details.
- Both
models
andviews
are arrays that 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.optimizeTrackingFor
can 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.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].uniformScale
is 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.
1234567891011121314151617181920212223Copy## 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 ]
}
}
]
}
]
}
Uncertain Parts
Each model
in a JSON file can be equipped with an optional partProperties
array to specify parts that should be ignored during object detection and tracking. This can improve the detection and initial tracking of objects containing parts whose position or appearance in the 3D model might differ from the physical object or parts that might or might not be present.
Uncertain parts could include:
- Articulated parts such as the wheels on a vehicle or flexible pipes and cables.
The part properties are applied to the referenced node and its successors until the successor redefines the same property with a different value. This means that when a node has uncertain
set to true, all successor nodes (Children of the node, including the children’s children, etc.) will have that same value until a node has uncertain
set to false.
Set the partProperties
, its index
, name
, partIDPath
, or occurenceId
, depending on the 3d model’s nodes convention, and set uncertain
to true.
NOTE: Currently, uncertain parts are only supported with glTF, PVZ, and .dae (Collada) files.
index – valid for glTF input only
Identify the node via its node index number.
1234567Copy"partProperties": [
{
"index": 11,
"uncertain": true
},
...
]
partName – valid for all supported input formats
Identify the node via its name. Since the name is not unique, each node with the given name is marked as uncertain.
1234567Copy"partProperties": [
{
"partName": "Composite part 10",
"uncertain": true
},
...
]
partIdPath – valid for PVZ input only
Identify the node via the PVZ part id path.
1234567Copy"partProperties": [
{
"partIdPath": "/0/1/2/3",
"uncertain": true
},
...
]
occurrenceID – valid for glTF input only
Identify the node via its PTC occurrence ID stored in node.extensions.PTC_NODE_ASSEMBLY_NAME.occurrence. It is only available in models extracted from the Vuforia Procedure Editor.
1234567Copy"partProperties": [
{
"occurrenceId": "3XVs96VDtUK9fBPxA",
"uncertain": true
},
...
]
Example of a glTF node definition with the occurrence id property:
12345678910Copy{
"name": "SomePart",
"mesh": 45,
"matrix": [ 1, 0, 0, 0, 0, 0, -1, 0, 0, 1, 0, 0, -3.0, 1.0, -1.0, 1 ],
"extensions": {
"PTC_NODE_ASSEMBLY_NAME": {
"occurrence": "88f9dc1dde854887a28380bbf5c71d5f"
}
}
}
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 virtual camera's position 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.
Set up Guide Views in the Model Target Generator for prototyping and debugging and copy their values 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 rotation
objects into your 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 to allow the import of the dataset files into the Unity Editor. Model Targets created with the Model Target CLI include preview models in the Unity scene, but the Inspector will not show a preview image.