Implementation:PeterL1n BackgroundMattingV2 HomographicAlignment

Knowledge Sources	BackgroundMattingV2 OpenCV Feature Matching
Domains	Computer_Vision, Image_Registration
Last Updated	2026-02-09 00:00 GMT

Overview

Concrete tool for aligning background images to source frames using ORB feature matching and RANSAC homography provided by inference_utils.py.

Description

HomographicAlignment is a callable class that corrects camera drift between source and background images. It uses OpenCV's ORB detector to find keypoints, brute-force matching to pair descriptors, filters to the top 15% by distance, estimates a 3x3 homography matrix via RANSAC, and warps the background to match the source viewpoint. Out-of-bounds areas are filled with source pixels.

Usage

Use as an optional preprocessing step in image and video inference pipelines. Pass as a transform in the dataset pipeline when --preprocess-alignment is enabled.

Code Reference

Source Location

• Repository: BackgroundMattingV2
• File: inference_utils.py
• Lines: 6-46

Signature

class HomographicAlignment:
    """Apply homographic alignment on background to match with the source image."""

    def __init__(self):
        """Initializes ORB detector and brute-force matcher."""
        self.detector = cv2.ORB_create()
        self.matcher = cv2.DescriptorMatcher_create(cv2.DESCRIPTOR_MATCHER_BRUTEFORCE)

    def __call__(
        self,
        src: PIL.Image,  # Source image
        bgr: PIL.Image   # Background image
    ) -> Tuple[PIL.Image, PIL.Image]:
        """
        Returns:
            src: Unchanged source image (as PIL.Image)
            bgr: Aligned background image (as PIL.Image)
        """

Import

from inference_utils import HomographicAlignment

I/O Contract

Inputs

Name	Type	Required	Description
src	PIL.Image	Yes	Source image (subject + background)
bgr	PIL.Image	Yes	Reference background image to align

Outputs

Name	Type	Description
src	PIL.Image	Unchanged source image
bgr	PIL.Image	Background warped to match source viewpoint

Usage Examples

In Dataset Pipeline

from inference_utils import HomographicAlignment
from dataset import ImagesDataset, ZipDataset
from dataset.augmentation import PairCompose, PairApply
from torchvision import transforms as T

src_dataset = ImagesDataset('images/src')
bgr_dataset = ImagesDataset('images/bgr')

dataset = ZipDataset([src_dataset, bgr_dataset], transforms=PairCompose([
    HomographicAlignment(),     # Align background to source
    PairApply(T.ToTensor()),    # Convert both to tensors
]))

src_tensor, bgr_tensor = dataset[0]

Related Pages

Implements Principle

• Principle:PeterL1n_BackgroundMattingV2_Homographic_alignment