Troubleshooting¶

Common issues and how to resolve them.

Tracking Issues¶

Initial pose too far off — move the TrackedBody GameObject closer to where the real object appears relative to the camera
Wrong scale — verify the mesh dimensions match the real object in meters
No tracking model (silhouette mode) — silhouette tracking requires a generated model. Click Generate Silhouette Model in the TrackedBody inspector. Edge tracking doesn't need this.
Camera not providing frames — check that the Image Source is set correctly on XRTrackerManager and the camera is active
Guide too far from the object — the start search covers an object that stands within about 90 pixels of the guide, so a guide that is farther away needs a larger Window Margin and Cone Half Angle, or a closer guide. See Starting & Recovery

Start search proposes a pose that is a few degrees off — the tracker does not always correct that, so the body can start with a wrong tilt or depth. Switch Search Before Start off on the body

Increase stability — raise Rotation Stability and Position Stability on the TrackedBody
Enable stationary mode — if the object is fixed in the real world, enable Stationary on the TrackedBody
Low contrast — silhouette tracking needs foreground/background separation. Try edge tracking if contrast is low
Insufficient correspondence iterations — increase Correspondence Iterations on XRTrackerManager (default 5)

Background too similar — silhouette tracking struggles when the background matches the object color. Switch to edge tracking or add depth
Object too featureless — spheres, smooth cylinders, and plain boxes have few distinguishing features. Add depth tracking if a sensor is available
Fast motion — edge tracking is more sensitive to rapid movement. Switch to silhouette if the camera or object moves quickly
Partial occlusion — if more than ~60% of the object is hidden, tracking may fail. Enable occlusion handling if another tracked body is blocking it

Accept Steady Fits is off — with it on (the default, in the Edge Tracking section of the Tracked Body inspector), XRTracker also accepts a fit that the coverage score verifies. See AR Foundation
Start Score and Hold Confidence differ — under AR pose fusion, the Runtime Status shows both. A body can read a high Start Score and a low Hold Confidence while the registration check cannot reach its bar on a soft picture

Camera too close — texture tracking works only when the camera is farther from the object than about 1.5 times the object's radius, which is half its largest dimension. See Limits of Texture Tracking

Custom thresholds — the default Quality to Start may be too high for your object. Enable custom thresholds and lower them
Adjust modality — some objects track better with edge than silhouette. Experiment with the Tracking Method setting

High-poly mesh — decimate meshes above 50k triangles. Internal geometry that isn't visible externally can be removed
Too many subdivisions — reduce the subdivisions setting in Model Settings

Viewpoint coverage — check the Viewpoint Coverage setting. Use Full Sphere for objects viewed from any angle, or restrict to Upper Hemisphere / Side Ring for objects with known orientation

Camera Usage Description not set — add a description in Player Settings > Other Settings > Camera Usage Description
ARSession missing — ensure an ARSession component exists in the scene
AR Foundation not installed — install AR Foundation and ARKit XR Plugin via Package Manager

ARCore not supported — check that the device supports ARCore (see Google's device list)
ARCore not installed — the app may need Google Play Services for AR installed on the device
Image Source wrong — must be set to Injected for AR Foundation

Camera in use — another application may have exclusive access to the camera
Camera name mismatch — if using Auto Select Camera Name, verify the exact camera name matches
Calibration file missing — if using a calibration file, ensure it's in StreamingAssets

No license found — register for a free Developer license: Tools > XRTracker > License Registration
If you already have a .lic file, import it from the registration window or drag it into the License File field on XRTrackerManager

Check expiry date — select the .lic file in Unity to view its details in the Inspector
Request a new license — contact support@formulaxr.com

Commercial license bound to different machine — Commercial licenses are node-locked. The Machine ID is shown in the XRTrackerManager inspector during Play Mode. Provide this ID when requesting a license

Lower camera resolution — reduce the capture resolution on the Image Source settings
Reduce correspondence iterations — lower Correspondence Iterations on XRTrackerManager (minimum 1, but tracking quality decreases)
Simplify meshes — fewer triangles = faster rendering per tracking frame

Multiple tracked bodies — each body adds rendering overhead. Disable occlusion if not needed