Table of Contents

Class PTZAutoTrackingSettings

Namespace
VisioForge.Core.Types.X.AI
Assembly
VisioForge.Core.dll

Settings for the PTZ auto-tracking controller, which converts object-detection positions into continuous PTZ velocity commands so an ONVIF PTZ camera follows a tracked object.

public class PTZAutoTrackingSettings

Inheritance

Inherited Members

Remarks

The controller implements a simple proportional (P) control law with a dead zone and command rate limiting. The error is the target box center relative to the frame center, normalized to the range [-1, 1] on each axis. Inside the dead zone the axis is held; outside it the axis speed is clamp(Gain * error, -MaxSpeed, MaxSpeed).

Properties

ClassLabelFilter

Gets or sets the class label to follow when VisioForge.Core.Types.X.AI.PTZAutoTrackingSettings.TargetSelection is VisioForge.Core.Types.X.AI.PTZTargetSelection.ByClassLabel (case-insensitive, e.g. "person"). Ignored otherwise.

public string ClassLabelFilter { get; set; }

Property Value

string

CommandInterval

Gets or sets the minimum interval between successive move commands sent to the camera, to avoid flooding it. Stop commands are edge-triggered and are not rate limited. Timing is measured against the frame timestamps supplied to the controller. Defaults to 200 ms.

public TimeSpan CommandInterval { get; set; }

Property Value

TimeSpan

DeadZone

Gets or sets the half-width of the centered dead zone, as a fraction of the frame half-size on each axis (0..1). While the normalized error on an axis is within this value the axis is not driven. Defaults to 0.1.

public float DeadZone { get; set; }

Property Value

float

Gain

Gets or sets the proportional gain applied to the normalized error. Higher values move the camera faster for the same off-center distance. Defaults to 1.2.

public float Gain { get; set; }

Property Value

float

HomePresetToken

Gets or sets the optional ONVIF preset token to return to when the target is lost. When null or empty no home move is issued. Defaults to null.

public string HomePresetToken { get; set; }

Property Value

string

LostTargetTimeout

Gets or sets how long the current target may be absent before it is declared lost. When the target disappears the camera is stopped immediately; after this timeout elapses the controller raises the target-lost event, optionally returns to VisioForge.Core.Types.X.AI.PTZAutoTrackingSettings.HomePresetToken, and reacquires. Timing is measured against the frame timestamps supplied to the controller. Defaults to 2 seconds.

public TimeSpan LostTargetTimeout { get; set; }

Property Value

TimeSpan

ManualTrackerId

Gets or sets the tracker identifier to follow when VisioForge.Core.Types.X.AI.PTZAutoTrackingSettings.TargetSelection is VisioForge.Core.Types.X.AI.PTZTargetSelection.ByTrackerId. Ignored otherwise.

public int ManualTrackerId { get; set; }

Property Value

int

MaxSpeed

Gets or sets the maximum absolute speed sent on any axis (0..1). Defaults to 0.5.

public float MaxSpeed { get; set; }

Property Value

float

PatrolDwellTime

Gets or sets how long the camera dwells at each patrol preset before advancing to the next. Timing is measured against the frame timestamps supplied to the controller. Defaults to 10 seconds.

public TimeSpan PatrolDwellTime { get; set; }

Property Value

TimeSpan

PatrolEnabled

Gets a value indicating whether idle patrol is enabled, i.e. VisioForge.Core.Types.X.AI.PTZAutoTrackingSettings.PatrolPresetTokens contains at least one token.

public bool PatrolEnabled { get; }

Property Value

bool

PatrolPresetTokens

Gets or sets the ordered ONVIF preset tokens the camera cycles through as an idle patrol when no target has reappeared. Patrol is enabled only when this array is non-empty (see VisioForge.Core.Types.X.AI.PTZAutoTrackingSettings.PatrolEnabled). When null or empty no patrol is performed. Defaults to null.

public string[] PatrolPresetTokens { get; set; }

Property Value

string[]

PatrolStartDelay

Gets or sets how long the controller waits after a target is declared lost, with no new target reappearing, before it starts the idle patrol. Any target acquisition during patrol immediately aborts it and resumes tracking. Timing is measured against the frame timestamps supplied to the controller. Defaults to 30 seconds.

public TimeSpan PatrolStartDelay { get; set; }

Property Value

TimeSpan

StopJoinTimeout

Gets or sets how long StopAsync/DisposeAsync waits for the background worker and the final camera stop to complete before giving up, so an unresponsive camera cannot hang teardown. Raise it on high-latency links; lower it for a snappier shutdown. Defaults to 5 seconds.

public TimeSpan StopJoinTimeout { get; set; }

Property Value

TimeSpan

TargetBoxHeightRatio

Gets or sets the desired target box height as a fraction of the frame height (0..1). When VisioForge.Core.Types.X.AI.PTZAutoTrackingSettings.ZoomEnabled is true the controller zooms in when the target appears smaller than this and out when it appears larger. Defaults to 0.5.

public float TargetBoxHeightRatio { get; set; }

Property Value

float

TargetSelection

Gets or sets the strategy used to pick which detected object to follow when no target is currently locked. Defaults to VisioForge.Core.Types.X.AI.PTZTargetSelection.Largest.

public PTZTargetSelection TargetSelection { get; set; }

Property Value

PTZTargetSelection

ZoomDeadZone

Gets or sets the zoom dead zone, as an absolute difference between the desired and actual box height ratio (0..1). While the difference is within this value the zoom axis is held. Defaults to 0.05.

public float ZoomDeadZone { get; set; }

Property Value

float

ZoomEnabled

Gets or sets a value indicating whether zoom is driven to keep the target box height near VisioForge.Core.Types.X.AI.PTZAutoTrackingSettings.TargetBoxHeightRatio. Defaults to false.

public bool ZoomEnabled { get; set; }

Property Value

bool

Methods

Validate()

Validates the settings and throws ArgumentException if any value is invalid.

public void Validate()