This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.
While developing AR experiences with Model Targets, it may be that the real-life object differs in size from the digital model, or that the Model Target is being tested with a differently scaled replica of the object. This guide provides guidelines on how to manage scaling and to identify scaling problems throughout the development process.
It is important that the system knows the actual dimensions of the object that is being tracked (captured in the Model Target’s dataset), whether it is a replica for testing, or the real-world object.
If the Model Target and the real-life object do not have the same dimensions, the tracking can perform poorly or even fail in some instances. Vuforia Engine can handle some degree of discrepancy between model and object. However, receiving WRONG_SCALE as the StatusInfo of the ModelTargetResult at runtime or from the log in the Unity Editor is an indication that the size of your Model Target is set incorrectly and the target is either too small or too large compared to the physical object.
In this guide, you will learn how to correctly maintain the scale of the Model Target throughout the development process in the Model Target Generator (MTG), Unity Editor, or in Native.
There are two ways of scaling Model Targets:
- Scale the model in a CAD modeling software before importing it into the MTG.
- Set the scale (physical size) of the Model Target in the Unity editor or at runtime.
We recommend maintaining an exact 1:1 scale between the object and the 3D model at all times. Therefore, the best practice on scaling 3D models is to size it in the CAD modeling software before importing the 3D model into the MTG. Additionally, the unit information should also be set accordingly to the file format that is used in the CAD modeling software.
The MTG can import a large variety of 3D model file formats; we recommend using the formats that will contain the unit information. Some of these include FBX, Collada, glTF, and PVZ. See the Model Target Generator User Guide for more information on supported formats.
Overseeing the Scale in the Model Target Generator
In the MTG’s Model Units tab, select the right units to define how the input data’s dimensions should be interpreted. Typically, these values are unit-less so they could be inches, centimeters or meters. Therefore, choosing the dimensions of the Model Target so that the measurements matches with the real-life object is an important step during the process of generating the Model Target. The scaling of the 3D model to its correct dimensions should be done before importing it into the MTG.
File Units in the MTG are only there to correct missing/wrong unit information - it is not meant for scaling.
- Choose the Model Units tab and select the correct dimensions the model should be represented in. The general practice for this is:
- Checking if the dimensions match between the real-life object and the Model Target. If they do not match, then the File Units should be set to the correct dimensions.
- The available units are: hm (hectometer), am (decameter), m (meter), dm (decimeter), cm (centimeter), mm (millimeter), ft (feet), and in (inches).
- If the File Units options are unavailable, it is an indication that the model might be corrupt, and it should be reimported.
However, there may be use cases where the Model Target’s dimensions would explicitly not be set to match the real-life object:
- When testing your Model Target with a scaled replica of the real-life object (I.e. a testing with a to-scale miniature of a car, in form of a toy or a 3D printed).
- When the 3D model’s dimensions are pre-set and are different from the real-life object, or the unit information of the model is unknown.
In the above cases, the correct physical size of the target can be configured in the Unity Editor or at runtime.
Managing Model Target Scaling in Unity
In most scenarios, the Model Target at this point would not require any editing. However, in the few situations where re-scaling is necessary, this can be achieved by editing the ModelTarget GameObject in the Unity Editor. Make sure to configure to the correct size of the physical object in meters.
- Select the ModelTarget GameObject and enter the scaling values (length, width, and height) to match the physical dimensions of the object. You will notice that changing one of its dimensions automatically scales the others accordingly.
NOTE: Particles and physics might be affected and cause issues when scaled together with the ModelTarget GameObject.
Testing with a Scaled Replica of the Model Target
If you are developing a Model Target experience for a full-size car model but using a toy model of that car for testing, then you should also adjust the Virtual Scene Scale Factor that is found in Vuforia Configuration.
Consider the following example
The physical car you are developing an AR experience for is 4m in length. All your virtual scene content matches that scale, but you want to test the application on a toy car that is in 1:20 scale with regards to the real car:
- In the Model Target Behaviour component, change the Physical Length to 20cm (4m divided by 20).
- In the Vuforia Configuration, set the Virtual Scene Scale Factor to 20.
- Vuforia Engine will now know the accurate size of the physical object but will report tracking poses in the reconfigured scale for your scene content.
Please refer to the Virtual Scene Scale Factor in Unity article to transform your target into the proper scale.
Managing Model Target Scaling at Runtime
Setting your Model Target to a different size during runtime is only supported when it is uniformly scaled- this applies for all API languages. It is recommended that you store the original values using getSize(), and then apply a new size with setSize().
Remember, the DataSet of the Model Target must be deactivated before changing its size. It can be reactivated once the change has been made.
For a guide on how to load Model Targets into your native Android environment, please see the article Model Targets Native Workflow.
The following code snippet in C# presents a way to rescale the Model Target at runtime.
public void SetScaleFactor(float scale)
{
if (!mModelTargetBehaviour)
{
Debug.LogError("Cannot set scale, missing model target!");
return;
}
// First, stop the Tracker
var objTracker = TrackerManager.Instance.GetTracker<objecttracker>();
objTracker.Stop();
// Get the list of active datasets
var ads = objTracker.GetActiveDataSets().ToList();
// Deactivate active datasets
foreach (var ds in ads)
{
objTracker.DeactivateDataSet(ds);
}
// Query current Model Target size
Vector3 currentSize = mModelTargetBehaviour.ModelTarget.GetSize();
Debug.Log("Current MT size: " + currentSize.ToString("0.000"));
// Set the new Model Target size by using a scale factor
newSize = scale * currentSize;
mModelTargetBehaviour.ModelTarget.SetSize(newSize);
Debug.Log("Changed MT size to: " + mModelTargetBehaviour.ModelTarget.GetSize().ToString("0.000"));
// Re-activate datasets
foreach (var ds in ads)
{
objTracker.ActivateDataSet(ds);
}
// Re-start tracker
objTracker.Start();
// Scale the augmentation accordingly
foreach (Transform child in mModelTargetBehaviour.transform)
{
child.transform.localScale *= scale;
}
}