Knowledge Base

After loading a model, you can add information to the workflow. To define where the model will be later displayed in the Spatial Workplace app, a spatial reference must be added to the workflow.

There are three types of references:

• Markers
• Object trackers
• Model placement

Markers

A marker is used to position information that is to be displayed within a workflow at the desired spot over the real-life component. For this, at least one virtual marker needs to be added in the editor where the real-life marker will be in relation to the real-life component. Different devices use different types of markers. The virtual model is then loaded in Spatial Workplace according to the scanned position of the marker.

The following types of markers exist:

• ArUco marker: This type of marker is meant to be used with mobile devices (iOS and Android). The size of the marker can be adjusted by the user and can be between 1 and 99 cm. As a rule of thumb, markers with a size of 10 cm (12 cm with borders) or 15 cm (18 cm with borders) should be used, but the user has the option to select the size that works best with the respective component.
• QR code marker: This type of marker is meant to be used with a HoloLens 2. Again, the size can be adjusted by the user. The proposed default is 15 cm (17 cm with borders).

To add a marker to your model:

1. Click on Add on the top.
2. Choose either ArUco or QR code marker depending on your requirements.
3. Click on the surface of the model where you want to place it. The other options/buttons of the editor are disabled until you place the marker.
4. To change the position of the marker on the model's surface, select it and click on Object > Snap in the top menu or press S on the keyboard.
5. Change the position and rotation of markers independent of the model's surface by using the transformation gizmos or the Transform menu on the right.

Here's a list of all available tracking parameters:

• Dynamic Initial Pose: When enabled, the user can dynamically set the initial tracking viewpoint during runtime.
• Continuous Tracking (Mobile Only): If enabled (default) the object tracker would have continuous object tracking for mobile devices. It is more suitable for objects that can be moved or rotated during the task but keep their form. Non-continuous tracking only tracks the object at the start of the task and then continues the tracking using SLAM. Non-continuous tracking is more suitable for objects that are not moved or rotated during the task and that change their form (e.g. parts are added or removed).
• Extendible Tracking: If enabled (default), the model-based tracking will be extended with SLAM-based tracking. This allows tracking to be continued even if the model isn't visible in the camera image anymore. The user needs to perform a SLAM dance, which means translating and rotating the camera so that there is enough baseline for the feature reconstruction.
• Min. Inlier Ratio Init: Threshold for validating tracking during initialization. The value range reaches from 0.5 to 0.9, with 0.6 being the default value. Higher values are recommended if the line model matches the real-life object perfectly with no occlusion. However, usually they will not match perfectly, which is why a lower value works better.
• Laplace Threshold: Threshold for creating the line model (mm). The value range reaches from 0.0001 to 100000, with 5 being the default value. This specifies the minimum depth between two neighbouring pixels to be recognized as an edge.
• Normal Threshold: Threshold for generating the line model. The value range reaches from 0.0001 to 1000, with 1000 being the default value. This specifies the minimum normal difference between two neighbouring pixels necessary to be recognized as an edge. Usually, it is set to a high value because normal-based lines can't be recognized very reliably. Though, for certain models, it might make sense to use a lower value.
• Line Gradient Threshold: Threshold for edge candidates in the image. The value range reaches from 0 to 256, with 40 being the default value. High values will only consider pixels with high contrast as candidates while low values will also consider other pixels. This is a trade-off. If there are too many candidates, the algorithm might choose the wrong pixels. If there are not enough candidates, the line model might not stick to the object in the image. 
• Keyframe Distance: Minimum distance between keyframes (mm). The value range reaches from 0.001 to 100000, with 100 being the default value. The line model is only generated for certain keyframes. Higher values improve performance but come with lower precision (and vice versa). 
• Line Search Length Init Relative: Length of the orthogonal search lines (in per cent) relative to the minimum resolution during initialization and tracking. The value range reaches from 0.00625 to 1, with 0.03125 being the default value. The model-based tracker projects the 3D line model into the camera image and searches for edge pixels orthogonal to the projected lines. 
• Use Color: This is disabled by default. If enabled, colored edges are distinguished better while tracking. It is only useful for objects with colored edges. It can increase the tracking quality but requires more processing power.
• Field of View (HoloLens 2 Only): A larger field of view makes the object appear smaller during image capturing. It is recommended to use 'wide' for large objects and 'narrow' for small ones. 

2. The green arrow symbolizes the view direction of the user. The user can choose which models are positioned according to this reference in the menu on the right. When starting the workflow in Spatial Workplace, the selected models and connected pins will be positioned in relation to the viewing direction of the user when they start the Spatial Workplace app.

Model visibility: Different from the pins connected to a spatial reference, models will not be visible by default. To make them visible while playing the workflow, you need to either:

• add a hologram of the model in one or many pins
• add a scene state node that makes the model visible

Real-life setting recommendations

Taking care of all tracking variables is important for positioning the pins at their exact spot and minimizing offset. This includes the physical characteristics of the marker, the environment, and the device used for running the Spatial Workplace application. To achieve the best possible results, follow the below-listed recommendations to increase tracking efficiency.

Marker conditions:

• Use a marker with the correct size and ID number as defined in the editor.
• All four corners should be clearly visible for the scanner camera, including the white space around it.
• The marker should always be flattened and placed in the exact position on the real-life object without curls, rips, or wrinkles.
• Reflective surfaces covering the marker can compromise the tracking (e.g., glass or lamination).
• Markers should always be scanned from an angle of 90 degrees in relation to the surface on which they are placed (i.e., the camera should be looking directly at the object/marker). Scanning from different perspectives can influence the positioning of pins.

Environmental conditions:

• The number of features in the environment and your component influence tracking. After the marker is scanned and the original position is set, the device tracking system takes control of keeping the content in its place. The number of features in your setting increases the efficiency of device tracking. Good features include corners and contrast visible on the component itself and between the component and its environment.
• The room should have good lighting. The devices' cameras usually have lower capacities for receiving light in relation to our eyes. Make sure that there is enough light in the room to ensure the best possible tracking results. However, also avoid environments that are too bright.
• Reflective surfaces should be avoided, especially for placing markers, pins, and other content.
• Brusque movements during a task run can cause drifts in the position of the content. Keep a stable position of the device during task performance.
• In large settings, the further away a pin is from the position of the scanned marker, the bigger the chance of undesired drifts in content positioning. This is caused by the intensification of small inaccuracies in marker tracking and by the amount of necessary movement between the marker and the content location. To minimize this problem, check the "Adding extra markers to improve tracking" section below.

Device conditions:

• HoloLens devices
  • HoloLens devices require a clean visor and sensors that are free of obstructing objects.
  • Looking around the room or walking around the area increases the device's ability to track the room's setting. Having many people that are constantly in motion in the room can compromise tracking.
  • Users have different interpupillary distance (IPD). Uncalibrated IPD values on the device can compromise the AR experience. This Microsoft article explains how to use a calibration app to customize the IPD of your device. 
• iOS and Android devices
  • Clear camera lenses are necessary for correct tracking.
  • Auto-focus can compromise the positioning of pins.