Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Generalizable detector + descriptor combos

Open
  • Is something wrong?
#50 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Quiet
Tech stack
python
Domain
computer-vision

Research direction

The issue proposes a new FeaturePipeline abstraction around detector and descriptor components, using cv2.Feature2D behavior and combined algorithms such as SIFT or ORB. No repository files or tests are identified, so first locate the existing feature extraction entry points and determine how detector/descriptor combinations are currently represented. Done should include a defined API for native combined algorithms and separate detector-descriptor pairs, with coverage for the stated usage patterns.

Written by the indexing model from the issue text.

Description

tech-debt

This has been on the Wishlist for a while. Here's a Gemini idea:

To achieve true polymorphism where any detector $X$ can be cleanly paired with any descriptor $Y$—while also seamlessly supporting combined algorithms (like SIFT or ORB) that handle both natively—you can implement a unified interface layer.

The primary challenge with OpenCV's underlying structure is that everything inherits from cv2.Feature2D in C++, but in Python, the objects are functionally asymmetric: "Detector-only" objects lack .compute(), "Descriptor-only" objects lack .detect(), and combined frameworks implement everything plus .detectAndCompute().

An elegant way to handle this in Python is to treat the Pipeline itself as the polymorphic interface, using a lightweight structural wrapper or duck-typed composition.

Here is a clean, robust architecture that provides a unified API for any combination.

The Polymorphic Pipeline Architecture

By creating a unified container class, you can abstract away whether the underlying execution runs a combined native method or executes two distinct, mismatched components sequentially.

from typing import Protocol, Tuple, Optional, Any
import cv2
import numpy as np

class FeaturePipeline:
    """
    A polymorphic wrapper that pairs any keypoint detector with any 
    feature descriptor, or wraps a single unified extraction algorithm.
    """
    def __init__(self, detector: Any, descriptor: Optional[Any] = None):
        self.detector = detector
        # If no distinct descriptor is provided, assume the detector handles both
        self.descriptor = descriptor if descriptor is not None else detector

    def detect(self, image: np.ndarray, mask: Optional[np.ndarray] = None) -> list:
        """Extract only the keypoints from an image."""
        if hasattr(self.detector, 'detect'):
            return self.detector.detect(image, mask)
        elif hasattr(self.detector, 'detectAndCompute'):
            kp, _ = self.detector.detectAndCompute(image, mask)
            return kp
        else:
            raise AttributeError(f"The configured detector {type(self.detector).__name__} cannot detect keypoints standalone.")

    def compute(self, image: np.ndarray, keypoints: list) -> Tuple[list, np.ndarray]:
        """Compute descriptors for a pre-existing list of keypoints."""
        if hasattr(self.descriptor, 'compute'):
            return self.descriptor.compute(image, keypoints)
        else:
            raise AttributeError(f"The configured descriptor {type(self.descriptor).__name__} cannot compute descriptors.")

    def extract(self, image: np.ndarray, mask: Optional[np.ndarray] = None) -> Tuple[list, np.ndarray]:
        """
        Polymorphically extracts both keypoints and descriptors.
        Optimises for combined algorithms if available.
        """
        # Case 1: Unified native algorithm (e.g., SIFT, ORB)
        if self.detector is self.descriptor and hasattr(self.detector, 'detectAndCompute'):
            return self.detector.detectAndCompute(image, mask)
        
        # Case 2: Mix-and-match sequential execution (e.g., FAST + FREAK)
        keypoints = self.detect(image, mask)
        return self.compute(image, keypoints)
How this Solves Polymorphism

This structure allows your client code to treat every single feature extraction mechanism identically, completely removing conditional checks (if isinstance(...)) from your core tracking loops.

1. Using a Native Combined Pair
# SIFT handles both detection and description internally
sift_pipeline = FeaturePipeline(cv2.SIFT_create())
kp, des = sift_pipeline.extract(img)
2. Using a Mix-and-Match Pair
# FAST handles detection, FREAK handles description
fast_freak_pipeline = FeaturePipeline(
    detector=cv2.FastFeatureDetector_create(),
    descriptor=cv2.xfeatures2d.FREAK_create()
)
kp, des = fast_freak_pipeline.extract(img)
3. Reusing Coordinates for tracking
# Detect features once, then compute them across sequential frames
initial_kp = fast_freak_pipeline.detect(frame_1)
kp_1, des_1 = fast_freak_pipeline.compute(frame_1, initial_kp)
kp_2, des_2 = fast_freak_pipeline.compute(frame_2, initial_kp)
Type Enforcement (Optional Extension)

If you want explicit structural typing flags to catch setup errors before runtime, you can define lightweight Protocol classes to act as interfaces for the sub-components:

from typing import Protocol, runtime_checkable

@runtime_checkable
class DetectorComponent(Protocol):
    def detect(self, image: np.ndarray, mask: Optional[np.ndarray] = None) -> list: ...

@runtime_checkable
class DescriptorComponent(Protocol):
    def compute(self, image: np.ndarray, keypoints: list) -> Tuple[list, np.ndarray]: ...

By initializing with this approach, the runtime environment doesn't care where the underlying binary resides (core vs. contrib), as long as the bound object satisfies the duck-typed interface behavior.

Dominant language
Python
Stars
223
Forks
30
Avg merge
1h 4m
Merged PRs (30d)
9

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from petercorke/machinevision-toolbox-python

All issues in petercorke/machinevision-toolbox-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.