documentation
We show the general method for defining and altering the behavior of what VisionLib is trying to track. This tutorial assumes that you have already defined a tracker and that you are familiar with the general structure of a tracking configuration (.vl) file (otherwise, see › Configuration File Reference first).
You can use the modelURI parameter to define a 3D model as a reference model. To define multiple models, you can use the models parameter instead. This allows you to specify an array of models. You can later alternate through this array. If models and a modelURI are declared, VisionLib will add both.
Here is an example usage of models:
In this example, 4 different obj files are loaded. All four are initially enabled. VisionLib will add them up and treat them as a single reference object. Disabling any model at a later point causes it to be removed from this combined model.
Some of a model's properties can be changed during runtime, using the setModelProperties command. This command expects a model definition as its parameter. This definition may be complete or partial. Only the fields present in the partial definition are updated by the command:
Instead of changing a single model, you can also update the properties of all models at once using the setModelPropertiesForAll command:
The command above sets the same values for all models. If you would like to set different values in the individual models, use the setMultipleModelProperties command instead. It receives an array of (partial) model definitions. Again, only the fields present in the partial definitions are updated by the command:
The following parameters can be used in model definitions for addModel, setModelProperties, setModelPropertiesForAll and setMultipleModelProperties:
| Parameter | Type | Default value | Runtime mutable | Example in model definition |
|---|---|---|---|---|
| name | string | optional (null) | NO | "name": "MyModel1" |
|
A unique model identifier Can be an arbitrary string, which is used to reference the model later on. If it is not provided, the name will be set to "Model_[n]", with incrementing numbers [n]. | ||||
| uri | string | optional ("") | YES | "uri": "http://mysuperserver/mymodel.ply" |
|
URI to the cad file of the model to be tracked. The following file formats are generally supported: 3D, 3DS, AC, ASE, B3D, BLEND, BVH, COB, CSM, DAE, DXF, FBX, GLB, GLTF, HMP, IFC, IRR, IRRMESH, LWO, LWS, LXO, MD2, MD3, MD5, MDC, MDL, MDL, MS3D, NDO, NFF, NFF, OBJ, OFF, OGEX, PK3, PLY, Q3D, Q3S, RAW, SCN, SMD, STL, TER, VTA, X, XGL, XML and ZGL. Using FBX files can lead to problems if the file uses an internal scaling factor. Depending on the model loader you are using, the resulting 3D model may be scaled by such a factor. Especially, the scaling factor has a different interpretation in VisionLib than in Unity. Usage of OBJ and PLY files is recommended, because these formats are well tested and they can be easily produced using MeshLab (http://meshlab.sourceforge.net/) and the data is stored binary (with PLY). The usage of HTTP URIs is currently not possible on UWP, which includes HoloLens. If you require this feature, please contact us. | ||||
| enabled | boolean | optional (true) | YES | "enabled": false |
|
Use this model for tracking Sets whether the model is used for tracking. | ||||
| occluder | boolean | optional (false) | YES | "occluder": true |
|
Use this model to occlude models whose corresponding real objects can not be tracked Sets whether the model occludes other components (models) of the combined reference model (for more information on this, see Model Tracking Occluders). An occluder is not itself used for tracking. | ||||
| transform.t | array of 3 floats | optional ([0,0,0]) | YES | "transform": {"t":[3,0,0]} |
|
Translation of the object. The translation of the model in model coordinates at runtime. | ||||
| transform.s | array of 3 floats | optional ([1,1,1]) | YES | "transform": {"s":[0.44,0.44,0.44]} |
|
Scale of the object. The scale of the model in model coordinates at runtime. | ||||
| transform.q | array of 4 floats | optional ([0,0,0,1]) | YES | "transform": {"r":[0,1,0,0]} |
|
Rotation of the object as quaternion. The rotation of the model in model coordinates at runtime. | ||||
Send an addModel command to add a model at runtime. This command expects a model definition as its parameter:
The command will return {"addedModel": "Piece000"} where in this example Piece000 is the name of the added model. Note: This is especially useful if the model name was not provided in the model definition passed with the addModel command.
If the name of the model is already taken, the following message will be returned in the error parameter of the command callback:
Sending a removeModel command removes a model at runtime. This command expects a model name as its parameter:
This command will return nothing if it succeeds.
You can also remove all modes by sending a removeAllModels command. This command has no parameters.