kornia.tracking

class kornia.tracking.HomographyTracker(initial_matcher=None, fast_matcher=None, ransac=None, minimum_inliers_num=30)

Perform local-feature-based tracking of the target planar object in the sequence of the frames.

Parameters:

• initial_matcher (Optional[LocalFeature], optional) – image matching module, e.g. LocalFeatureMatcher or LoFTR. Default: GFTTAffNetHardNet.

• fast_matcher (Optional[Module], optional) – fast image matching module, e.g. LocalFeatureMatcher or LoFTR. Default: DescriptorMatcher.

• ransac (Optional[Module], optional) – homography estimation module. Default: RANSAC.

• minimum_inliers_num (int, optional) – threshold for number inliers for matching to be successful. Default: 30

property device: device

Return the device used by the current target image tensor.

Returns:

The torch.device where self.target is allocated.

property dtype: dtype

Return the data type used by the current target image tensor.

Returns:

The torch.dtype of self.target.

forward(x)

Run one tracking step on frame x.

Parameters:

x (Tensor) – Current frame tensor.

Return type:

Tuple[Tensor, bool]

Returns:

A tuple (H, is_valid) from track_next_frame when previous state exists, otherwise from match_initial.

match_initial(x)

Estimate a homography from the initial target frame to frame x.

Parameters:

x (Tensor) – Current frame tensor to match against the stored target image.

Return type:

Tuple[Tensor, bool]

Returns:

A tuple (H, is_valid) where H is the estimated homography matrix and is_valid indicates whether enough inliers were found.

The method updates keypoint counters, inlier statistics, and stores the estimated homography as previous_homography on success.

no_match()

Return a failed-match response and clear current match statistics.

Return type:

Tuple[Tensor, bool]

Returns:

A tuple (H, is_valid) where H is an empty 3 x 3 tensor on the tracker device and dtype, and is_valid is False.

reset_tracking()

Reset temporal tracking state from previously processed frames.

Return type:

None

Returns:

None.

set_target(target)

Register a new target image and refresh cached matcher features.

Parameters:

target (Tensor) – Reference target image tensor used for subsequent matching.

Return type:

None

Returns:

None.

The method clears previously cached features and precomputes new feature representations when the configured matchers expose an extract_features method.

track_next_frame(x)

Track the target in frame x using the previous homography prior.

Parameters:

x (Tensor) – Current frame tensor to align with the target image.

Return type:

Tuple[Tensor, bool]

Returns:

A tuple (H, is_valid) where H is the updated homography and is_valid indicates whether tracking remained reliable.

The frame is first prewarped by the inverse of the previous homography, then matched with fast_matcher and verified using RANSAC.