TrackedBody

Inherits from: MonoBehaviour

Serialized Fields

Field	Type	Default	Description
bodyId	string		Unique identifier for this tracked object
meshFilters	List<MeshFilter>	new List()	MeshFilters containing the 3D model(s) to track. Multiple meshes will be combined using their local transforms.
trackedMotion	TrackedMotion	TrackedMotion.None	Which degrees of freedom can be optimized when attached to parent. None = rigid attachment.
initialPoseSource	InitialPoseSource	InitialPoseSource.ScenePosition	How to determine the initial pose for detection
initialViewpoint	Transform		Viewpoint transform to calculate initial pose from. The object's pose will be computed relative to this viewpoint.
isStationary	bool		Object is fixed in the world. Enables AR pose fusion to maintain position when tracking quality drops. A body that has a parent follows its parent and ignores it.
acceptSteadyFits	bool	true	With AR, the body also accepts a fit that keeps the start score for 3 frames in a row and stays close to where AR predicts the object. This helps soft or low-contrast real images keep the lock and show Tracked. With this off, the body accepts only the fits that the strict confidence check passes. Property AcceptSteadyFits.
holdDuringViewDip	bool	true	With AR, the shown pose stays still while the view health is below 0.8 of the usual level for this view, until the view has been healthy again for 5 steps in a row. A dip can only begin after 30 healthy steps in a row. With this off, new fits keep moving the pose while part of the object is hidden. It needs Accept Steady Fits. Property HoldDuringViewDip.
holdDuringFastMotion	bool	true	With AR, no new fit is stored while AR moves the object more than 6 pixels per frame on screen, counted for a camera with a focal length of 450 pixels. The shown pose is carried by AR until the camera slows down. The first fit and the first 30 steps after the start are never held back. With this off, fits taken during fast motion keep moving the pose. It needs Accept Steady Fits. Property HoldDuringFastMotion.
firstAcceptGuard	bool	true	With AR, before the first fit is shown, 3 solves in a row must agree within 8 millimeters and 2 degrees. The guard lets go after 30 steps, so a fit that never settles is still taken in the end. With this off, the first fit that passes the other checks is taken at once. It needs Accept Steady Fits. Property FirstAcceptGuard.
smoothTime	float	DEFAULT_SMOOTH_TIME	Time in seconds to smooth pose corrections. 0 = instant.
rotationStability	float	5000	Rotation stability (Tikhonov regularization). Higher = smoother rotation, slower response to rotation changes.
positionStability	float	30000	Position stability (Tikhonov regularization). Higher = smoother position, slower response to position changes.
silhouetteTracking	SilhouetteTrackingSettings	(default)	Silhouette tracking parameters.
multiScale	MultiScaleSettings	(default)	Multi-scale pyramid settings. Adjust for thin objects at distance or when object appears small in image.
depthTracking	DepthTrackingSettings	(default)	Advanced depth tracking tuning. Adjust when using RealSense depth camera.
useCustomStartThreshold	bool		Use a custom start bar instead of the default one (0.65), for a body that tracks by the edge method.
customQualityToStart	float	0.5	Custom Quality to Start (0-1), the bar a start must clear on 5 frames in a row, for a body that tracks by the edge method. Only used when useCustomStartThreshold is true. The value starts at 0.5.
useCustomConfirmThreshold	bool		Use a custom confirm score. Read only by a body that tracks by the edge method.
customQualityToConfirmStart	float	EDGE_QUALITY_TO_CONFIRM_START	The score the last frame of a start must reach. A start needs the start score on 5 frames in a row and this score on the last one. Only used when useCustomConfirmThreshold is true. The default is 0.65, which equals the start score, so the last frame needs nothing more. Raise it above the start score to make a start surer.
searchBeforeStart	bool	true	Before the first start, search a window around the guide for the shape of the body and refine from the best match when the guide stands out of reach of it. Read only by a body that tracks by the edge method and has no parent. A scene or prefab that saved this field keeps its saved value.
startSearchPeriodSteps	int	2	How many tracking steps pass between two searches. 1 searches on every step. Property StartSearchPeriodSteps.
startSearchMarginBar	float	1.4	The margin the winner of a search must reach before a start is let through. 0 sets no margin bar. Property StartSearchMarginBar.
startSearchScoreFloor	float	0.6	The score the winner of a search must reach before a start is let through. 0 sets no floor. Property StartSearchScoreFloor.
startSearchReachPixels	float	16	How far the guide may stand from the winner, in pixels, and still count as in reach. 0 treats every guide as out of reach. Property StartSearchReachPixels.
startSearchConeHalfAngle	float	5	The half angle, in degrees, of the cone of views around the guide's view. Property StartSearchConeHalfAngle.
startSearchConeSpacing	float	5	The spacing, in degrees, between neighboring views of the cone. Property StartSearchConeSpacing.
startSearchRollRange	float	10	The range, in degrees, of the turns in the image plane. Property StartSearchRollRange.
startSearchFineHalfAngle	float	0	The half angle, in degrees, of an extra fine stage. 0 switches it off. Property StartSearchFineHalfAngle.
startSearchWindowMargin	float	96	How far beyond the box of the guide's outline the search looks, in pixels. 0 searches the whole image. Property StartSearchWindowMargin.
startSearchDistanceCount	int	3	The number of distances the views hold around the guide's own (1, 3 or 5). Property StartSearchDistanceCount.
startSearchScaleDistances	bool	false	Whether the other distances are made by scaling one drawing of each view. Property StartSearchScaleDistances.
useCustomStopThreshold	bool		Use a custom stop bar instead of the default one (0.50 without pose fusion), for a body that tracks by the edge method.
customQualityToStop	float	0.3	Custom Quality to Stop (0-1), the bar the averaged score must stay at or above, for a body that tracks by the edge method. Only used when useCustomStopThreshold is true. The value starts at 0.3.
useCustomSilhouetteStartThreshold	bool		Use a custom start bar instead of the default one, for a body that tracks by the silhouette method.
customSilhouetteQualityToStart	float	0.3	Custom Quality to Start (0-1), the bar a start must clear on 5 frames in a row, for a body that tracks by the silhouette method. Only used when useCustomSilhouetteStartThreshold is true. It is used as set, even below the stop bar.
useCustomSilhouetteStopThreshold	bool		Use a custom stop bar instead of the default one (0.4), for a body that tracks by the silhouette method.
customSilhouetteQualityToStop	float	0.4	Custom Quality to Stop (0-1), the bar the averaged score must stay at or above, for a body that tracks by the silhouette method. Only used when useCustomSilhouetteStopThreshold is true.
assemblyMode	bool		Enable for parts that will be physically installed during operation. The child won't affect parent pose until quality confirms the part is present.
assemblyQualityToConfirm	float	0.4	Quality threshold (0-1) required to confirm the part is installed and start affecting parent pose. Not used when attachManually is true.
attachManually	bool		Only used with assembly mode. The part is scored but never joins the parent's solve until the application calls Attach(), and it leaves the solve when the application calls Detach().
freeCheck	bool		Only used with assembly mode and attachManually, for a part with no tracked motion. While the part is not attached, it settles its own pose a few millimeters and degrees around its seat without moving the parent.
freeCheckDistanceTolerance	float	0.005	How far, in meters, the part may settle from its seat and still be in its seat.
freeCheckAngleTolerance	float	3	How far, in degrees, the part may turn from its seat and still be in its seat.
checkView	Transform		The camera pose the part is checked from. With it, Presence judges the part only while the camera is near this view and still.
checkViewDistance	float	0.1	How far, in meters, the camera may be from the check view and still be near it.
checkViewAngle	float	15	How far, in degrees, the viewing direction may turn from the check view's and still be near it.
stillnessDistance	float	0.015	How far, in meters, the camera may move over the stillness window and still count as still.
stillnessAngle	float	3	How far, in degrees, the viewing direction may turn over the stillness window and still count as still.
stillnessWindow	float	0.5	How long, in seconds, the camera must stay within the stillness bounds to count as still.
presenceHold	float	1	How long, in seconds, the evidence of one judgement is gathered near the check view with the camera still.
enableSilhouetteValidation	bool		Validate tracking points against silhouette boundaries. Uses shared silhouette renderer - significant GPU overhead on mobile.

Properties

Property	Type	Access	Description
SilhouetteTracking	SilhouetteTrackingSettings	get	Advanced edge tracking tuning settings. Adjust for difficult objects like thin tubes. Changes can be applied at runtime via UpdateEdgeTrackingParameters().
MultiScale	MultiScaleSettings	get	Multi-scale pyramid settings. Adjust for thin objects at distance or when object appears small in image. Must be set before registration - runtime changes not currently supported.
DepthTracking	DepthTrackingSettings	get	Advanced depth tracking tuning settings. Adjust when using RealSense depth camera. The distance tolerance and the standard deviations of the depth correspondences (0.05, 0.03 and 0.02 meters by default, one for each correspondence iteration) reach the tracker at its next step while the scene plays. Every other depth setting is read when the body registers.
OcclusionSettings	OcclusionSettings	get	Occlusion detection parameters for this body. Adjust threshold for tight assemblies where parts are close together.
EnableSilhouetteTracking	bool	get	Whether silhouette tracking is active (derived from TrackingMethod).
EnableEdgeTracking	bool	get	Whether edge tracking is active (derived from TrackingMethod).
EdgeTracking	EdgeTrackingSettings	get	Edge tracking settings for tuning crease angle, search length, and so on.
IsRegistered	bool	get
ParentBody	TrackedBody	get	Parent body this object is attached to (null if independent).
HasParent	bool	get	Whether this body has a parent assigned (for inspector visibility).
IsActiveMode	bool	get	Whether this body has active tracking (at least one DOF enabled or no parent). True if no parent (always active) or if any TrackedMotion flags are set.
OnStartTracking	UnityEvent	get	Event fired when tracking starts.
OnStopTracking	UnityEvent	get	Event fired when tracking stops.
IsTracking	bool	get	Whether the tracking pipeline of this body is running. It is true while the solver runs, including while a pose is held under pose fusion, and it is not a verdict on quality. Read Confidence for the state of the pose.
TrackingQuality	float	get	The averaged score the stop decision reads, from 0 to 1. Higher is better. Compare it with QualityToStopTracking and never with a fixed number, because the scale depends on the method. A body that tracks by the edge method without pose fusion reads the share of sites that find a matching edge divided by 0.70 and clipped to 1. Under pose fusion it reads the registration margin mapped to 0 to 1 so that a margin at its start bar reads 0.65. A silhouette body reads the histogram score.
InstantQuality	float	get	The same score for the current step, from 0 to 1.
StartScore	float	get	The score the start decision reads for the current step, on the same 0 to 1 scale. The start compares it with QualityToStartTracking on 5 frames in a row. For an edge body under AR pose fusion it is the coverage score, while TrackingQuality is the registration margin that keeps or gives up the lock. The inspector shows them as Start Score and Hold Confidence. For every other body it returns InstantQuality.
ShapeQuality	float	get	Shape quality (0-1), averaged over 30 frames, for a body that tracks by the silhouette method. Higher is better.
DepthTrackingQuality	float	get	Depth quality (0-1), averaged over 30 frames, for a body with depth tracking. Higher is better.
Confidence	TrackingConfidence	get	The one state of the body, Tracked, Degraded or Lost. It reads the same score and the same start, confirm and stop bars that decide IsTracking. Lost is a report and the tracker does not reset itself, so what to do about a lost body is the decision of the application.
ConfidenceReason	TrackingConfidenceReason	get	Why the body is in the state that Confidence reports.
SilhouetteVisibility	float	get	The share of valid silhouette lines (0-1). It reads zero for a body that tracks by the edge method.
DepthVisibility	float	get	Depth visibility ratio (0-1). Ratio of valid depth points.
IsSilhouetteValidationEnabled	bool	get	Whether silhouette validation is currently enabled.
IsTextureTrackingEnabled	bool	get	Whether texture tracking (feature-based tracking) is currently enabled.
IsOcclusionEnabled	bool	get	Whether occlusion handling is currently enabled.
IsDepthTrackingEnabled	bool	get	Whether depth tracking is currently enabled.
QualityToStartTracking	float	get	The bar a start must clear on 5 frames in a row, on the same scale as TrackingQuality. It reports the bar that is actually enforced. An edge body configured with a start bar below its stop bar is raised to the stop bar and reads the stop bar. The default is 0.65 for an edge body, with or without pose fusion, and 0.3 for a silhouette body.
QualityToStopTracking	float	get	The bar the averaged score must stay at or above, on the same scale as TrackingQuality. The default is 0.50 for an edge body without pose fusion, 0.558 for an edge body under pose fusion and 0.4 for a silhouette body.
QualityToConfirmStart	float	get	The score the last frame of a start must reach, on the same scale as TrackingQuality. It is the custom confirm score when a body that tracks by the edge method sets one, and the start score otherwise, so it asks for nothing more than the start does. It reads 0.65 for an edge body, with or without pose fusion, and 0.3 for a silhouette body.
UseCustomConfirmThreshold	bool	get, set	Whether to use a custom confirm score instead of the default, for a body that tracks by the edge method.
CustomQualityToConfirmStart	float	get, set	Custom confirm score (0-1), the score the last frame of a start must reach. Only used when UseCustomConfirmThreshold is true.
SearchBeforeStart	bool	get, set	Whether the body searches a window around the guide for its own shape before the first start.
StartSearchRoute	StartSearchPath	get	Which start the body takes while the search holds it. Unknown until a winner has been measured against the guide, InReach when the guide stands within reach of the winner, and Far when the body is seeded from the winner.
StartSearchGuidePixels	float	get	The median on-screen displacement, in pixels, between the guide and the latest winner measured. It is not a number when none was measured.
AttachManually	bool	get, set	Whether a part in assembly mode joins the parent's solve only when the application calls Attach().
IsAttached	bool	get	Whether the application has attached the part with Attach() and not detached it since. A reset of the body does not change it.
Presence	PartPresence	get	Unknown, Present or Absent. It is judged only with a check view, only while the camera is near the check view and still, and from the evidence of a whole presence hold.
IsInSeat	bool	get	Whether the part is in its seat. A part that is not settling is held at its seat and is in it.
SettledDistance	float	get	How far, in meters, the part has settled from its seat. It is zero when the part is not settling.
SettledAngle	float	get	How far, in degrees, the part has turned from its seat while settling. It is zero when the part is not settling.
ContributesToOptimization	bool	get	Whether this body currently contributes to optimization. When false, the body still tracks and computes quality metrics, but its observations don't affect the parent body's pose optimization.

Methods

Method	Returns	Description
FindParentInHierarchy()	TrackedBody	Find the nearest TrackedBody ancestor in Unity hierarchy (excluding self). Used internally and by editor for display.
ResetTracking(bool forgetLearned = false)	void	Return the body to the pose it was placed at, stop its tracking and start its lifecycle over. With forgetLearned false the body keeps what it learned while it tracked. With true it forgets it.
ExecuteDetection()	void
ForceStartTracking()	void	Force-start tracking, bypassing quality-based auto-start. Useful for testing modalities that can't self-assess object presence (for example edge-only). It has no effect on a child, because a child is tracked while its parent is.
Attach()	void	Says that a part in assembly mode with attachManually is mounted. From the next tracked frame on, the part joins the parent's solve.
Detach()	void	Says that the part is no longer mounted. From the next tracked frame on, the part is scored again and no longer joins the parent's solve.
TryGetStartSearchReading(out StartSearchReading reading, out StartSearchVerdict verdict)	bool	Reads what the latest search found and what the start gate decided on it. It returns false when the body holds no search, when the plugin could not be read, and on any step on which the gate was not asked.
UpdateStabilityParameters()	void	Update stability (Tikhonov regularization) parameters at runtime. Call this after changing RotationStability or PositionStability while playing.
UpdateEdgeTrackingParameters()	void	Update edge tracking tuning parameters at runtime. Call this after changing EdgeTracking settings while playing.
UpdateOcclusionParameters()	void	Update occlusion detection parameters at runtime. Call this after changing OcclusionSettings while playing.
SetInitialPose(Transform viewpoint)	void	Set the initial pose from a viewpoint transform. The object's current world position is computed relative to the viewpoint. viewpoint: The viewpoint transform (for example, camera position). If null, uses main camera.
SetInitialPose(Vector3 position, Quaternion rotation)	void	Set the initial pose from raw position and rotation values (camera-relative). position: Position relative to camera rotation: Rotation relative to camera
SetAttachmentPose(Vector3 childWorldPosition, Quaternion childWorldRotation)	bool	Set custom attachment pose using world-space position and rotation. Internally computes the relative pose to parent. If already attached, updates the pose immediately on native side. If not attached yet, the pose will be used when registering/attaching. childWorldPosition: Child's world-space position childWorldRotation: Child's world-space rotation Returns: True if successful (or stored for later use)
ClearCustomAttachmentPose()	void	Clear custom attachment pose override. If already attached, recomputes pose from current Unity hierarchy. If not attached yet, pose will be computed from hierarchy at registration time.
UpdateGeometry(IList<MeshFilter> newMeshFilters, TrackingModelAsset newTrackingModel = null)	bool	Update body geometry (mesh and silhouette model) at runtime while preserving tracking state. Use this to swap the visual representation without losing the current pose estimate. newMeshFilters: New mesh filters defining the geometry newTrackingModel: Pre-baked tracking model asset (silhouette + optional depth). Null for edge-only mode. Returns: True if geometry was successfully updated
SetTrackedMotion(TrackedMotion trackedMotion)	bool	Updates which degrees of freedom are tracked for this attached body. trackedMotion: New motion configuration (None = rigid) Returns: True if successfully updated
AddOccluder(TrackedBody occluder)	bool	Add another body as an occluder for this body. This body's tracking will ignore regions occluded by the occluder. Requires occlusion to be enabled on this body. occluder: The body that occludes this one Returns: True if successfully added
RemoveOccluder(TrackedBody occluder)	bool	Remove an occluder relationship. occluder: The body to remove as occluder Returns: True if successfully removed
EnableMutualOcclusion(TrackedBody other)	bool	Enable mutual occlusion between this body and another. Both bodies will occlude each other. other: The other body Returns: True if successfully enabled
DisableMutualOcclusion(TrackedBody other)	bool	Disable mutual occlusion between this body and another. other: The other body Returns: True if successfully disabled
SetContributesToOptimization(bool contributes)	bool	Set whether this body contributes to the optimization solution. When disabled, the body still gets its pose updated (follows parent if attached), but its gradient/hessian don't influence the parent's tracking. Use this for child bodies with low tracking quality. Only sends to native when state actually changes (efficient for per-frame calls). contributes: True to contribute, false to exclude from optimization Returns: True if successfully set
ComputeLocalBounds()	Bounds	Computes the combined local-space bounds of all mesh filters. Bounds are relative to this TrackedBody's transform.
GetEffectiveSphereRadius()	float	Gets the effective sphere radius for silhouette model generation. Returns the configured value if positive, otherwise computes auto value (0.8 x diameter).
GetViewpointCount()	int	Gets the number of viewpoints based on nDivides setting. Geodesic sphere vertex count: 10 * 4^n + 2
GetPointsPerView()	int	Gets the effective points per view.

Events

Event	Type	Description
OnPoseUpdated	Action<Vector3, Quaternion>	Event fired when pose is updated. Subscribe to receive pose updates without modifying TrackedBody.
OnConfidenceChanged	Action<TrackingConfidence, TrackingConfidenceReason>	Event fired when Confidence changes, with the new state and the reason for it.