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

Increase stability — raise Rotation Stability and Position Stability on the TrackedBody
Enable stationary mode — if the object is fixed in the real world, enable Is 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

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

Free tier limit — the Free license allows 60 seconds of tracking per session. Contact support@xrproj.com for a 15-day trial
Restart the app or Unity Editor to reset the timer

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

Pro license bound to different machine — Pro 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