Merge pull request #29361 from SheliaJimenez:xfeat-feature

Xfeat feature - #29361

## PR Description

### Summary

Integrate XFeat into OpenCV's `features` module as a native `Feature2D` implementation, enabling lightweight neural feature detection and descriptor extraction through OpenCV's standard feature extraction API.

---

### What's included

#### New class

- **`cv::XFeat`** extends `Feature2D`
  - CNN-based keypoint detection
  - 64-D descriptor extraction via ONNX/DNN
  - Score-map based keypoint selection
  - Descriptor sampling from the dense feature map

---

### Files added

| File | Description |
|------|-------------|
| `src/feature2d_xfeat.cpp` | XFeat `Feature2D` implementation |
| `test/test_xfeat.cpp` | XFeat unit and regression tests |

---

### Files modified

- `features.hpp`
  - Add `cv::XFeat` declaration and public factory APIs

---

### Usage

```cpp
#include <opencv2/features.hpp>

using namespace cv;

// Feature extraction
Ptr<XFeat> xfeat =
    XFeat::create("xfeat.onnx", 2000, 0.5f, 640);

std::vector<KeyPoint> keypoints;
Mat descriptors;

xfeat->detectAndCompute(image, noArray(), keypoints, descriptors);
```

---


### Test dependency

Depends on the opencv_extra changes adding the XFeat ONNX model and reference outputs.

Required test data:
https://github.com/opencv/opencv_extra/pull/1383

- `xfeat.onnx`
- `xfeat_lena_640_kpts.npy`
- `xfeat_lena_640_desc.npy`

These files are required for the `Features2d_XFeat` tests in the main OpenCV repository to validate XFeat feature extraction and descriptor generation.


### Pull Request Readiness Checklist

See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request

- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
      Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake

samples/cpp/aliked_lightglue.cpp

@@ -2,8 +2,8 @@
 // It is subject to the license terms in the LICENSE file found in the top-level directory
 // of this distribution and at http://opencv.org/license.html.
 
-// ALIKED + LightGlueMatcher usage example
-// Demonstrates feature detection, extraction, and matching using ALIKED and LightGlue.
+// Learned feature usage examples.
+// Demonstrates ALIKED + LightGlue matching and XFeat feature extraction.
 
 #include <opencv2/features.hpp>
 #include <opencv2/imgcodecs.hpp>
@@ -14,11 +14,47 @@
 using namespace cv;
 using namespace std;
 
+static int runXFeatExample(const String& imgPath, const String& xfeatModel, const String& outputPath)
+{
+    Mat img = imread(imgPath);
+    if (img.empty())
+    {
+        cerr << "Error: cannot load image: " << imgPath << endl;
+        return -1;
+    }
+
+    Ptr<XFeat> xfeat = XFeat::create(xfeatModel, 2000, 0.05f, Size(640, 640));
+    vector<KeyPoint> keypoints;
+    Mat descriptors;
+    xfeat->detectAndCompute(img, Mat(), keypoints, descriptors);
+
+    Mat canvas;
+    drawKeypoints(img, keypoints, canvas, Scalar(0, 255, 0),
+                  DrawMatchesFlags::DRAW_RICH_KEYPOINTS);
+
+    if (!outputPath.empty())
+    {
+        imwrite(outputPath, canvas);
+        cout << "Saved XFeat keypoint visualization to: " << outputPath << endl;
+    }
+
+    imshow("XFeat Keypoints", canvas);
+    cout << "Press any key to exit..." << endl;
+    waitKey(0);
+    return 0;
+}
+
 int main(int argc, char** argv)
 {
     // ---- Parse arguments ----
     String alikedModel, lightglueModel, imgPath1, imgPath2;
 
+    if (argc >= 4 && String(argv[1]) == "--xfeat")
+    {
+        const String outputPath = argc >= 5 ? argv[4] : String();
+        return runXFeatExample(argv[2], argv[3], outputPath);
+    }
+
     if (argc >= 5)
     {
         imgPath1 = argv[1];
@@ -26,12 +62,15 @@ int main(int argc, char** argv)
         alikedModel = argv[3];
         lightglueModel = argv[4];
     }
-else
+    else
     {
-        cout << "Usage: " << argv[0] << " <image1> <image2> <aliked_model> <lightglue_model>" << endl;
+        cout << "Usage:" << endl;
+        cout << "  " << argv[0] << " <image1> <image2> <aliked_model> <lightglue_model>" << endl;
+        cout << "  " << argv[0] << " --xfeat <image> <xfeat_model> [output_image]" << endl;
         cout << endl;
-        cout << "Example:" << endl;
+        cout << "Examples:" << endl;
         cout << "  " << argv[0] << " img1.jpg img2.jpg aliked-n16rot-top1k-640.onnx aliked_lightglue.onnx" << endl;
+        cout << "  " << argv[0] << " --xfeat img.jpg xfeat.onnx xfeat_keypoints.jpg" << endl;
         return 0;
     }
 

samples/cpp/stitching_detailed.cpp

@@ -47,11 +47,12 @@ static void printUsage(char** argv)
         "\nMotion Estimation Flags:\n"
         "  --work_megapix <float>\n"
         "      Resolution for image registration step. The default is 0.6 Mpx.\n"
-        "  --features (surf|orb|sift|akaze|aliked)\n"
+        "  --features (surf|orb|sift|akaze|aliked|xfeat)\n"
         "      Type of features used for images matching.\n"
         "      The default is surf if available, orb otherwise.\n"
         "      When using 'aliked', requires --matcher lightglue and DNN model paths.\n"
-        "  --matcher (homography|affine)\n"
+        "      When using 'xfeat', requires --xfeat_model and uses the standard matcher.\n"
+        "  --matcher (homography|affine|lightglue)\n"
         "      Matcher used for pairwise image matching.\n"
         "  --estimator (homography|affine)\n"
         "      Type of estimator used for transformation estimation.\n"
@@ -107,13 +108,15 @@ static void printUsage(char** argv)
         "      Output warped images separately as frames of a time lapse movie, with 'fixed_' prepended to input file names.\n"
         "  --rangewidth <int>\n"
         "      uses range_width to limit number of images to match with.\n"
-        "\nDNN Feature Options (when --features aliked --matcher lightglue):\n"
+        "\nDNN Feature Options:\n"
         "  --aliked_model <path>\n"
         "      Path to ALIKED ONNX model file.\n"
         "  --lightglue_model <path>\n"
         "      Path to LightGlue ONNX model file (for ALIKED descriptors).\n"
         "  --lg_score_thresh <float>\n"
-        "      LightGlue confidence threshold. The default is 0.0 (accept all).\n";
+        "      LightGlue confidence threshold. The default is 0.0 (accept all).\n"
+        "  --xfeat_model <path>\n"
+        "      Path to XFeat ONNX model file.\n";
 }
 
 
@@ -154,6 +157,7 @@ bool timelapse = false;
 int range_width = -1;
 String aliked_model_path;
 String lightglue_model_path;
+String xfeat_model_path;
 float lg_score_thresh = 0.0f;
 
 
@@ -399,6 +403,11 @@ static int parseCmdArgs(int argc, char** argv)
             lightglue_model_path = argv[i + 1];
             i++;
         }
+        else if (string(argv[i]) == "--xfeat_model")
+        {
+            xfeat_model_path = argv[i + 1];
+            i++;
+        }
         else if (string(argv[i]) == "--lg_score_thresh")
         {
             lg_score_thresh = static_cast<float>(atof(argv[i + 1]));
@@ -423,6 +432,16 @@ static int parseCmdArgs(int argc, char** argv)
         cout << "Error: --features aliked requires --aliked_model and --lightglue_model\n";
         return -1;
     }
+    if (features_type == "xfeat" && xfeat_model_path.empty())
+    {
+        cout << "Error: --features xfeat requires --xfeat_model\n";
+        return -1;
+    }
+    if (features_type == "xfeat" && matcher_type == "lightglue")
+    {
+        cout << "Error: --features xfeat does not support --matcher lightglue; use homography or affine\n";
+        return -1;
+    }
 
     return 0;
 }
@@ -444,7 +463,8 @@ int main(int argc, char* argv[])
 
     // Disable OpenCL for DNN-based features to avoid backend sync issues
     bool use_aliked = (features_type == "aliked");
-    if (use_aliked)
+    bool use_xfeat = (features_type == "xfeat");
+    if (use_aliked || use_xfeat)
         cv::ocl::setUseOpenCL(false);
 
     // Check if have enough images
@@ -464,9 +484,9 @@ int main(int argc, char* argv[])
 #endif
 
     Ptr<Feature2D> finder;
-    if (use_aliked)
+    if (features_type == "aliked")
     {
-        // ALIKED will be created per-image in the loop below
+        finder = ALIKED::create(aliked_model_path);
     }
     else if (features_type == "orb")
     {
@@ -494,6 +514,15 @@ int main(int argc, char* argv[])
     {
         finder = SIFT::create();
     }
+    else if (features_type == "xfeat")
+    {
+#ifdef HAVE_OPENCV_DNN
+        finder = XFeat::create(xfeat_model_path, 4096, 0.05f, Size(640, 640));
+#else
+        cout << "OpenCV is built without opencv_dnn module. XFeat algorithm is not available!" << std::endl;
+        return -1;
+#endif
+    }
     else
     {
         cout << "Unknown 2D features type: '" << features_type << "'.\n";
@@ -538,15 +567,7 @@ int main(int argc, char* argv[])
             is_seam_scale_set = true;
         }
 
-        if (use_aliked)
-        {
-            Ptr<ALIKED> aliked = ALIKED::create(aliked_model_path);
-            computeImageFeatures(aliked, img, features[i]);
-        }
-        else
-        {
-            computeImageFeatures(finder, img, features[i]);
-        }
+        computeImageFeatures(finder, img, features[i]);
         features[i].img_idx = i;
         LOGLN("Features in image #" << i+1 << ": " << features[i].keypoints.size());