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[Module], 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. RANSAC needs 4 correspondences, so fewer than 4 matches always count as a failed match, whatever this value is. 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 target’s features are extracted once here and reused for every frame, for three kinds of matcher:

• LoFTR: its extract_features() output is passed as features0, in place of image0.

• LocalFeatureMatcher: the lafs, responses and descriptors of its extract_features() are passed as lafs0, responses0 and descriptors0, next to image0.

• Any other matcher whose extract_features attribute is a torch.nn.Module: every entry of the dict it returns is passed with a 0 suffix (desc as desc0), next to image0.

Other matchers get no cached representation and receive image0 and image1 only. A matcher replaced after this call, or a target reassigned directly, gets the target’s features extracted again on its next use. Setting a target starts a new track: the previous homography maps the old target’s coordinates, so it is cleared. A target reassigned directly starts a new track too, on the next forward() or track_next_frame().

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.