Skip to content

CVKit Tracking (f8.cvkit.tracking)

No description.

  • Service class: f8.cvkit.tracking
  • Version: 0.0.1
  • Source directory: f8/cvkit/tracking
  • Tags: cv, tracking

When to Use

  • Use f8.cvkit.tracking after a target has already been initialized and you want to keep following it over time.
  • It is a good fit for moving people, objects, or screen regions that remain visually coherent across frames.
  • It is usually more suitable than repeated matching once the target has been acquired.

Common Wiring Patterns

  • A common flow is templatematch / manual ROI -> tracking.
  • During development, keep f8.viz.track attached so loss-of-lock is immediately visible.
  • The tracking output is often forwarded into f8.pyengine for position-based rules, region triggers, or follow logic.

Pitfalls / Gotchas

  • Occlusion, rapid acceleration, and large scale change can all cause loss of lock.
  • Track drift can build up gradually; periodic re-initialization from a detector or matcher is often needed.
  • If the initial box is unreliable, long-term tracking usually will be too.

Service Reference

How to Run

../win/f8cvkit_tracking_service.exe
  • Workdir: ./
  • Environment overrides: none

Typical Inputs / Outputs

  • Data inputs: initBox
  • Data outputs: tracking, monitor
  • Commands: stopTracking

Service State Fields

Name Access Required On Node Schema Description
shmName rw true true string Optional SHM name override (e.g. shm.xxx.video).
initSelect rw true true string / enum[first_box, closest_center, largest_area, highest_score] / default=closest_center Init bbox selection strategy: first_box | closest_center | largest_area | highest_score.
trackerKind rw true true string / enum[csrt, kcf, mil, boosting, median_flow, ...] / default=csrt OpenCV tracker backend: csrt | kcf | mil | boosting | median_flow | mosse | tld | nano | vit.
modelDir rw true true string / default=models Directory containing downloaded tracker model files for nano | vit.
autoDownloadModels rw true true boolean / default=True Auto-download missing tracker model files when a model-based tracker is selected.
stopTrackingCooldownMs rw true true integer / default=1000 After stopTracking, ignore initBox for this many ms. Set to 0 to disable.
stopTrackingCooldownUntilTsMs ro true true integer When > 0, initBox is ignored until this timestamp (ms).
isTracking ro true true boolean True when tracker is running.
isNotTracking ro true true boolean Negation of isTracking.
lastError ro true true string Last error message.
active rw true false boolean / default=True Service lifecycle state (activate/deactivate).
svcId ro true false string Readonly: current service instance id (svcId).

Key Fields That Matter

  • shmName (Video SHM, rw): Optional SHM name override (e.g. shm.xxx.video). Schema: string.
  • initSelect (Init Select, rw): Init bbox selection strategy: first_box | closest_center | largest_area | highest_score. Schema: string / enum[first_box, closest_center, largest_area, highest_score] / default=closest_center.
  • trackerKind (Tracker Kind, rw): OpenCV tracker backend: csrt | kcf | mil | boosting | median_flow | mosse | tld | nano | vit. Schema: string / enum[csrt, kcf, mil, boosting, median_flow, ...] / default=csrt.
  • modelDir (Model Dir, rw): Directory containing downloaded tracker model files for nano | vit. Schema: string / default=models.
  • autoDownloadModels (Auto Download Models, rw): Auto-download missing tracker model files when a model-based tracker is selected. Schema: boolean / default=True.
  • stopTrackingCooldownMs (Stop Cooldown (ms), rw): After stopTracking, ignore initBox for this many ms. Set to 0 to disable. Schema: integer / default=1000.
  • stopTrackingCooldownUntilTsMs (Stop Cooldown Until (tsMs), ro): When > 0, initBox is ignored until this timestamp (ms). Schema: integer.
  • isTracking (Is Tracking, ro): True when tracker is running. Schema: boolean.

Service Commands

stopTracking

Stop current tracking and return to waiting for initBox.

  • Show on node: true
  • Params: none

Service Data Input Ports

Name Required On Node Schema Description
initBox true true object{bbox, bottom, conf, confidence, ...} Init payload (single bbox or nested detection tree). Recursively extracts bbox candidates and uses the one selected by initSelect.

Service Data Output Ports

Name Required On Node Schema Description
tracking true true object{bbox, frameId, height, status, ...} Tracking output stream.
monitor true false object{active, alive, cpu, error, ...} Unified runtime monitor snapshots (health/resource/perf/error).

Operators

None