Quality Metrics¶

XRTracker exposes several quality metrics that indicate how well tracking is performing. Use these metrics to detect tracking failures, trigger re-detection, and provide user feedback.

Overview¶

All quality values are on the 0.0 - 1.0 scale, where higher is better. Metrics are smoothed over time for stability, preventing single-frame noise from causing false alarms.

Metric	Available With	What It Measures
Tracking Quality	All modalities	How well the model fits the image, as the one score that decides start and stop
Shape Quality	Silhouette	How tightly the contour matches the expected shape
Depth Quality	Depth	How closely the depth data aligns with the model surface

Tracking Quality¶

The main metric to monitor. TrackingQuality is the averaged score that the stop decision reads, and InstantQuality is the same score for the current step. The start decision reads the start score on five frames in a row. That is InstantQuality for most bodies and StartScore for an edge body under AR pose fusion (see below). How the score is evaluated depends on the active tracking method:

Silhouette — The score is the histogram score. It reads how well the object visually stands out from the background. Higher = clearer separation between object and surroundings.
Edge, without AR pose fusion — The score is the share of sites that find a matching edge, divided by 0.70 and clipped to 1. A score of 1 means that 70 percent of the sites agree.
Edge, under AR pose fusion — TrackingQuality is the registration margin, mapped to 0 to 1 by a straight line through zero that sends the margin's reference value (0.988) to 0.65, and clipped to 1. The number reads like the one without pose fusion. It keeps or gives up the lock after the start, and the inspector calls it the Hold Confidence. The start does not read it. The start reads the coverage score, which the inspector calls the Start Score.

The bars travel with the number and are on the same scale as it. Compare the number with the bars of the body (QualityToStartTracking, QualityToConfirmStart and QualityToStopTracking) and never with a fixed value, because the scale depends on the method.

A body that tracks by the edge method starts, holds and stops on its edge score even when depth tracking is on, because depth only helps the fit. A silhouette body with depth tracking on reads the larger of its silhouette score and its depth score, so a body that has a depth model and no usable silhouette can still be tracked.

Start Score and Hold Confidence¶

An edge body under AR pose fusion reads two scores, because the start and the hold judge different things. The Runtime Status of the Tracked Body inspector shows each one with its bar.

Readout	Property	Bar	Decides
Start Score	`StartScore`	`QualityToStartTracking`	Whether the body starts. It reads the share of sites that find a matching edge, divided by 0.70 and clipped to 1.
Hold Confidence	`TrackingQuality`	`QualityToStopTracking`	Whether the body keeps or gives up its lock. It reads the registration margin, mapped to 0 to 1.

Every other body reads one score, so StartScore returns the same value as InstantQuality, and the inspector shows a single Tracking Quality row.

Shape Quality¶

Available with silhouette tracking. Measures how consistently the tracked contour matches the expected shape — a tighter, more uniform fit gives higher shape quality. A body that tracks by the edge method reads zero.

Info

Shape quality complements tracking quality. An object may have good visual separation from the background (high tracking quality) but a slightly off pose (lower shape quality).

Depth Quality¶

Available when depth tracking is enabled. Measures how closely the measured depth aligns with the model surface. Higher = better alignment. Near-perfect alignment typically gives quality values above 0.9.

Tracking Confidence¶

Each TrackedBody reports one state, Confidence, with a ConfidenceReason and the event OnConfidenceChanged. It reads the same score and the same start, confirm and stop bars that decide IsTracking.

Confidence	Description
Tracked	The solve of the current step was accepted
Degraded	The pose is still worth displaying, but the current step did not verify it
Lost	The tracker cannot vouch for the pose. It has not found the body yet, or the evidence has been missing for long enough that the displayed pose is no longer supported

Lost is a report and the tracker does not reset itself, so what to do about a lost body is the decision of your application. IsTracking is the switch of the tracking pipeline. It is true while the solver runs, including while a pose is held under AR pose fusion, and it is not a verdict on quality.

A start needs the start score to reach QualityToStartTracking on five frames in a row. By default the confirm score, QualityToConfirmStart, equals the start score, so the last of those frames needs no more than the start score. No other gate stands in the way of a start. Tracking stops when the averaged score drops below QualityToStopTracking. While recovery tries a candidate, the body is drawn where it stood, and it moves only when tracking starts again. See Starting & Recovery for the whole start.

Default Thresholds¶

The defaults are on the scale of the number, so they differ between the methods.

Threshold	Silhouette	Edge	Edge under AR pose fusion
Quality to Start	0.3	0.65	0.65
Quality to Confirm	0.3	0.65	0.65
Quality to Stop	0.4	0.50	0.558

A silhouette body has a start bar of 0.3 and a stop bar of 0.4, both used as set, as in 1.0.3. QualityToStartTracking reads 0.3. When the averaged score stays under 0.4, tracking stops and the tracker returns to the guide.

You can override the start and stop bars per body with the Custom Start Threshold and Custom Stop Threshold options on the TrackedBody inspector, which set Quality to Start and Quality to Stop. A body keeps one pair of values for the edge method and another for the silhouette method, and the inspector shows the pair of the method the body tracks by. A silhouette body that you saved with a custom start or stop value in 1.0.3 keeps that value, because it copies the value to its own pair when it loads. The confirm score of an edge body has its own option, Custom Confirm Score. You can set it above the start score to make a start surer. A confirm score at or below the start score asks for nothing more than the start score does, so an object that reads low even when it is aligned needs a lower Custom Start Threshold instead.

Using Quality Metrics in Code¶

var body = GetComponent<TrackedBody>();

// Read quality values
float trackingQuality = body.TrackingQuality;  // 0.0 - 1.0, the averaged score
float instantQuality = body.InstantQuality;    // 0.0 - 1.0, the score of the current step
float startScore = body.StartScore;            // 0.0 - 1.0, the score the start reads
float shapeQuality = body.ShapeQuality;        // 0.0 - 1.0
float depthQuality = body.DepthTrackingQuality; // 0.0 - 1.0

// Read the bars of the body, on the same scale as the score
float startBar = body.QualityToStartTracking;  // compare with StartScore
float confirmBar = body.QualityToConfirmStart;
float stopBar = body.QualityToStopTracking;

// React to the state of the body
body.OnConfidenceChanged += (confidence, reason) =>
{
    if (confidence == TrackingConfidence.Lost)
    {
        // Show "tracking lost" UI. The tracker does not reset itself,
        // so call ResetTracking() if your application decides to start over.
    }
};

// Compare the score with the bars and never with a fixed number
if (body.Confidence == TrackingConfidence.Tracked && trackingQuality >= confirmBar)
{
    // High confidence — safe to use the pose for precise operations
}

Tips¶

Tune thresholds for your use case — the defaults work for general scenarios, but specific objects or environments may need adjustment. Use the custom threshold options on TrackedBody.
Compare the score with the bars — the scale of the number depends on the method, so a fixed value that suits one body can be wrong for another.
Shape quality is independent from tracking quality — check both when validating tracking. An object can track well but at a slightly wrong pose.
For edge tracking, if quality drops significantly, the object is likely occluded or has drifted — consider re-detection
Display quality metrics during development using the debug UI to monitor tracking health in real time