Skip to content

Track Class Lock

Class: TrackClassLockBlockV1

Source: inference.core.workflows.core_steps.transformations.track_class_lock.v1.TrackClassLockBlockV1

Lock the class label of each tracked object by majority voting, eliminating class flicker in video workflows where a model alternates between similar classes for the same physical object.

How This Block Works

This block maintains per-track voting state, keyed by the video_identifier embedded in the image's video metadata:

  1. Pre-lock, every qualifying frame (confidence >= vote_confidence) counts as a vote for the predicted class. A class becomes locked once it collects min_votes votes AND leads the runner-up class by at least lead_margin votes.
  2. Post-lock, the locked class is written into every subsequent detection of that track. Reported confidence is the running mean of counted votes (clamped to 1.0).
  3. A locked class can only change after switch_after CONSECUTIVE qualifying frames of the same challenger class. Challenger evidence is streak-scoped: both the streak counter and its confidence sum reset whenever the streak breaks, and on a successful switch the new class's tallies are seeded from the streak values only, so reported confidence never exceeds 1.0.
  4. When a NEW tracker id appears where a locked track recently disappeared (within reattach_window frames, bounding box IoU >= reattach_iou), the new track inherits the lost track's lock and voting state. This makes locks survive tracker id switches caused by short detection gaps or occlusions. Only locked tracks are inherited, and a track still present in the current frame is never inherited. Set reattach_window to 0 to disable re-attachment.
  5. State for tracks unseen for state_ttl frames is purged.

Each detection is annotated with a boolean class_locked flag in detections.data.

Requirements

Detections must carry tracker_id (wire this block after a tracking block such as Byte Tracker). The image's video_metadata is used to maintain separate state per video stream.

Type identifier

Use the following identifier in step "type" field: roboflow_core/track_class_lock@v1to add the block as as step in your workflow.

Properties

Name Type Description Refs
name str Enter a unique identifier for this step.. ❌
min_votes int Cumulative qualifying votes a class needs before the initial lock is acquired. Higher values delay locking but make the initial decision more reliable.. ✅
vote_confidence float Minimum prediction confidence for a frame to count, both for pre-lock votes and post-lock challenger streaks. Frames below this threshold are ignored.. ✅
lead_margin int Number of votes by which the top class must lead the runner-up before locking. Prevents premature locks when two classes are contested.. ✅
switch_after int Number of CONSECUTIVE qualifying frames of the same challenger class required to change an existing lock. Any interruption resets the streak. Minimum 1 (a value of 1 switches on a single contrary frame; use >= 2 to enforce a multi-frame streak).. ✅
state_ttl int Number of frames after which state of unseen tracks is purged.. ✅
reattach_window int When a NEW tracker id appears where a locked track disappeared within this many frames, the new track inherits the lost track's lock and votes. Bridges tracker id switches caused by short detection gaps. Set to 0 to disable re-attachment.. ✅
reattach_iou float Minimum IoU between a new detection's bounding box and a recently lost locked track's last known bounding box for the lock to be inherited. Higher values require the object to reappear closer to where it vanished.. ✅

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Runtime compatibility

soft — runtime hosted_serverless, dedicated_deployment; execution remote; input video
Block keeps per-video state in process memory (keyed by video_metadata.video_identifier). With remote step execution on stateless or multi-replica HTTP runtimes, successive requests may be served by different worker processes, so the state resets between calls and the output is meaningless for tracking / counting / aggregation. Use local step execution in an InferencePipeline for stable cross-frame results.
soft — input image
Block depends on temporal context from video or repeated-frame workflows. With a still image/photo, there is no meaningful history to track, compare, aggregate, or visualize, so the block provides little or no benefit.

Available Connections

Compatible Blocks

Check what blocks you can connect to Track Class Lock in version v1.

Input and Output Bindings

The available connections depend on its binding kinds. Check what binding kinds Track Class Lock in version v1 has.

Bindings

  • input

    • image (image): Image with embedded video metadata. The video_metadata contains video_identifier used to maintain separate voting state for different videos..
    • detections (Union[rle_instance_segmentation_prediction, object_detection_prediction, keypoint_detection_prediction, instance_segmentation_prediction]): Tracked predictions (object detection, instance segmentation, keypoint detection or RLE instance segmentation). Must include tracker_id information from a tracking block..
    • min_votes (integer): Cumulative qualifying votes a class needs before the initial lock is acquired. Higher values delay locking but make the initial decision more reliable..
    • vote_confidence (float_zero_to_one): Minimum prediction confidence for a frame to count, both for pre-lock votes and post-lock challenger streaks. Frames below this threshold are ignored..
    • lead_margin (integer): Number of votes by which the top class must lead the runner-up before locking. Prevents premature locks when two classes are contested..
    • switch_after (integer): Number of CONSECUTIVE qualifying frames of the same challenger class required to change an existing lock. Any interruption resets the streak. Minimum 1 (a value of 1 switches on a single contrary frame; use >= 2 to enforce a multi-frame streak)..
    • state_ttl (integer): Number of frames after which state of unseen tracks is purged..
    • reattach_window (integer): When a NEW tracker id appears where a locked track disappeared within this many frames, the new track inherits the lost track's lock and votes. Bridges tracker id switches caused by short detection gaps. Set to 0 to disable re-attachment..
    • reattach_iou (float_zero_to_one): Minimum IoU between a new detection's bounding box and a recently lost locked track's last known bounding box for the lock to be inherited. Higher values require the object to reappear closer to where it vanished..

  • output

    • tracked_detections (Union[object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction, rle_instance_segmentation_prediction]): Prediction with detected bounding boxes in form of sv.Detections(...) object if object_detection_prediction or Prediction with detected bounding boxes and segmentation masks in form of sv.Detections(...) object if instance_segmentation_prediction or Prediction with detected bounding boxes and detected keypoints in form of sv.Detections(...) object if keypoint_detection_prediction or Prediction with detected bounding boxes and RLE-encoded segmentation masks in form of sv.Detections(...) object if rle_instance_segmentation_prediction.
Example JSON definition of step Track Class Lock in version v1 
{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/track_class_lock@v1",
    "image": "<block_does_not_provide_example>",
    "detections": "$steps.byte_tracker.tracked_detections",
    "min_votes": 10,
    "vote_confidence": 0.8,
    "lead_margin": 3,
    "switch_after": 15,
    "state_ttl": 300,
    "reattach_window": 30,
    "reattach_iou": 0.3
}