Implementation:Kornia Kornia Planar Tracker

Knowledge Sources	Kornia
Domains	Vision, Tracking, Homography
Last Updated	2026-02-09 15:00 GMT

Overview

HomographyTracker performs local-feature-based planar object tracking across video frames by estimating homography transformations using feature matching and RANSAC.

Description

The planar_tracker module in the Kornia tracking package provides the HomographyTracker class, an nn.Module that tracks a planar target object across a sequence of frames. It uses a two-stage matching approach: an initial_matcher (default: LocalFeatureMatcher with GFTTAffNetHardNet and DescriptorMatcher) for the first frame, and a fast_matcher (default: LoFTR("outdoor")) for subsequent frames. Homography estimation is performed by RANSAC. The tracker maintains state via previous_homography and uses perspective warping to pre-align frames for faster matching in subsequent frames. The set_target method initializes the target and pre-extracts features. The forward method dispatches between match_initial and track_next_frame based on whether a previous homography exists. Tracking is reset when the inlier count falls below minimum_inliers_num.

Usage

Import this module when you need to track a planar object (e.g., a document, poster, or planar scene) across video frames using homography estimation. Set the target with set_target(), then call the module on each subsequent frame.

Code Reference

Source Location

• Repository: Kornia
• File: kornia/tracking/planar_tracker.py
• Lines: 1-168

Signature

class HomographyTracker(nn.Module):
    def __init__(
        self,
        initial_matcher: Optional[LocalFeature] = None,
        fast_matcher: Optional[nn.Module] = None,
        ransac: Optional[nn.Module] = None,
        minimum_inliers_num: int = 30,
    ) -> None: ...

    def set_target(self, target: torch.Tensor) -> None: ...
    def reset_tracking(self) -> None: ...
    def match_initial(self, x: torch.Tensor) -> Tuple[torch.Tensor, bool]: ...
    def track_next_frame(self, x: torch.Tensor) -> Tuple[torch.Tensor, bool]: ...
    def forward(self, x: torch.Tensor) -> Tuple[torch.Tensor, bool]: ...

Import

from kornia.tracking.planar_tracker import HomographyTracker

I/O Contract

Constructor Inputs

Name	Type	Required	Description
initial_matcher	LocalFeature or None	No	Feature matcher for initial frame matching (default: LocalFeatureMatcher with GFTTAffNetHardNet(3000)).
fast_matcher	nn.Module or None	No	Fast matcher for subsequent frames (default: LoFTR("outdoor")).
ransac	nn.Module or None	No	RANSAC module for homography estimation (default: RANSAC("homography")).
minimum_inliers_num	int	No	Minimum number of inliers for a successful match (default 30).

forward() Input

Name	Type	Required	Description
x	torch.Tensor	Yes	Current video frame tensor.

Outputs

Name	Type	Description
H	torch.Tensor	Estimated 3x3 homography matrix from target to current frame.
success	bool	Whether the matching and homography estimation was successful (inliers >= minimum_inliers_num).

Tracking Pipeline

1. set_target(target) - Set the reference target image and pre-extract features for both matchers.
2. forward(frame) - On first call (no previous homography): uses match_initial with the initial_matcher. On subsequent calls: uses track_next_frame which pre-warps the frame using the previous homography, matches with the fast_matcher, and transforms keypoints back.
3. If matching fails (inliers below threshold), tracking is reset and must re-initialize.

State Properties

Property	Type	Description
inliers_num	int	Number of inliers from the last RANSAC estimation.
keypoints0_num	int	Number of target keypoints matched.
keypoints1_num	int	Number of frame keypoints matched.
previous_homography	torch.Tensor or None	Last successfully estimated homography.

Usage Examples

import torch
from kornia.tracking.planar_tracker import HomographyTracker

# Create tracker
tracker = HomographyTracker(minimum_inliers_num=30)

# Set the target (reference image)
target = torch.rand(1, 1, 480, 640)  # grayscale
tracker.set_target(target)

# Track across frames
for frame in video_frames:
    H, success = tracker(frame)
    if success:
        print(f"Homography found with {tracker.inliers_num} inliers")
    else:
        print("Tracking lost, will re-initialize on next frame")

Related Pages

• Principle:Kornia_Kornia_Homography_Tracking