Merge pull request #28986 from YangGuanyuhan:ai-aliked-lightglue-pipeline

[GSOC] feat: Add ALIKED feature extractor and LightGlue matcher with DNN integration #28986

## PR Description

### Summary

Integrate ALIKED and LightGlue into OpenCV's `features` module as native`Feature2D` and `DescriptorMatcher` implementations, enabling end-to-end neural feature matching within OpenCV's ecosystem.

---

### What's included

#### New classes

- **`cv::ALIKED`** extends `Feature2D`
  - CNN-based keypoint detection
  - 128-D descriptor extraction via ONNX Runtime

- **`cv::LightGlueMatcher`** extends `DescriptorMatcher`
  - Deep feature matching with spatial context
  - Uses keypoints and image sizes during matching

---

#### API design

- Standard OpenCV patterns:
  - `detectAndCompute()`
  - `match()`
  - `knnMatch()`

- Multiple factory methods:
  - ONNX model path
  - In-memory model buffer
  - Pre-loaded `dnn::Net`

- `Params` structs use `CV_EXPORTS_W_SIMPLE`
  for Python/Java bindings support

- Optional DNN dependency:
  - `HAVE_OPENCV_DNN` guards
  - Stub implementations throw `StsNotImplemented`

---

### Files added

| File | Description |
|------|-------------|
| `src/feature2d_aliked.cpp` | ALIKED implementation |
| `src/matchers_lightglue.cpp` | LightGlueMatcher implementation |
| `src/aliked_context.hpp` | Shared internal context struct |
| `test/test_aliked_lightglue.cpp` | Unit tests (9 test cases) |
| `samples/cpp/example_features_aliked_lightglue.cpp` | Demo application |

---

### Files modified

- `CMakeLists.txt`
  - Add `opencv_dnn` as optional dependency

- `features.hpp`
  - Add ALIKED and LightGlueMatcher declarations

- `precomp.hpp`
  - Add DNN include guard

---

### Usage

```cpp
// Feature extraction
Ptr<ALIKED> aliked =
    ALIKED::create("aliked-n16rot-top1k-640.onnx");

vector<KeyPoint> kpts;
Mat descs;

aliked->detectAndCompute(image, Mat(), kpts, descs);

// Feature matching
Ptr<LightGlueMatcher> lg =
    LightGlueMatcher::create("aliked_lightglue.onnx");

lg->setPairInfo(
    kpts1Mat,
    kpts2Mat,
    img1.size(),
    img2.size()
);

vector<DMatch> matches;
lg->match(descs1, descs2, matches);
````
please refer to samples/cpp/example_features_aliked_lightglue.cpp

---

### Test plan

* Build with `BUILD_LIST=features,dnn`
* Build without DNN:

  * Verify stubs compile
  * Verify `StsNotImplemented` is thrown
* Run:

  * `ctest -R Features2d_ALIKED`
  * `ctest -R Features2d_LightGlueMatcher`
* Run sample application with:

  * Real images
  * Real ONNX models
* Verify Python/Java bindings compile and work

---

### Related

Phase 1 of the
"End-to-End AI Feature Extraction and LightGlue Matching Pipeline"
GSoC project.

Designed to be extensible to:

* XFeat
* SuperPoint
* Other neural feature extractors

### test dependency

Depends on the opencv_extra PR adding ALIKED and LightGlue test models:

- [opencv_extra PR](https://github.com/opencv/opencv_extra/pull/1366)

This PR adds the following ONNX models to `download_models.py`:

- `aliked-n16rot-top1k-640.onnx`
- `aliked_lightglue.onnx`

These models are required for the `features2d` tests in the main OpenCV repository to validate the ALIKED and LightGlue feature extraction and matching pipeline.

### 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/stitching_detailed.cpp

@@ -16,6 +16,8 @@
 #include "opencv2/stitching/detail/seam_finders.hpp"
 #include "opencv2/stitching/detail/warpers.hpp"
 #include "opencv2/stitching/warpers.hpp"
+#include "opencv2/features.hpp"
+#include "opencv2/core/ocl.hpp"
 
 #ifdef HAVE_OPENCV_XFEATURES2D
 #include "opencv2/xfeatures2d.hpp"
@@ -45,9 +47,10 @@ 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)\n"
+        "  --features (surf|orb|sift|akaze|aliked)\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"
         "      Matcher used for pairwise image matching.\n"
         "  --estimator (homography|affine)\n"
@@ -103,7 +106,14 @@ static void printUsage(char** argv)
         "  --timelapse (as_is|crop) \n"
         "      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";
+        "      uses range_width to limit number of images to match with.\n"
+        "\nDNN Feature Options (when --features aliked --matcher lightglue):\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";
 }
 
 
@@ -142,6 +152,9 @@ float blend_strength = 5;
 string result_name = "result.jpg";
 bool timelapse = false;
 int range_width = -1;
+String aliked_model_path;
+String lightglue_model_path;
+float lg_score_thresh = 0.0f;
 
 
 static int parseCmdArgs(int argc, char** argv)
@@ -204,7 +217,7 @@ static int parseCmdArgs(int argc, char** argv)
         }
         else if (string(argv[i]) == "--matcher")
         {
-            if (string(argv[i + 1]) == "homography" || string(argv[i + 1]) == "affine")
+            if (string(argv[i + 1]) == "homography" || string(argv[i + 1]) == "affine" || string(argv[i + 1]) == "lightglue")
                 matcher_type = argv[i + 1];
             else
             {
@@ -376,6 +389,21 @@ static int parseCmdArgs(int argc, char** argv)
             result_name = argv[i + 1];
             i++;
         }
+        else if (string(argv[i]) == "--aliked_model")
+        {
+            aliked_model_path = argv[i + 1];
+            i++;
+        }
+        else if (string(argv[i]) == "--lightglue_model")
+        {
+            lightglue_model_path = argv[i + 1];
+            i++;
+        }
+        else if (string(argv[i]) == "--lg_score_thresh")
+        {
+            lg_score_thresh = static_cast<float>(atof(argv[i + 1]));
+            i++;
+        }
         else
             img_names.push_back(argv[i]);
     }
@@ -383,6 +411,19 @@ static int parseCmdArgs(int argc, char** argv)
     {
         compose_megapix = 0.6;
     }
+
+    // Validate DNN options
+    if (features_type == "aliked" && matcher_type != "lightglue")
+    {
+        cout << "Error: --features aliked requires --matcher lightglue\n";
+        return -1;
+    }
+    if (features_type == "aliked" && (aliked_model_path.empty() || lightglue_model_path.empty()))
+    {
+        cout << "Error: --features aliked requires --aliked_model and --lightglue_model\n";
+        return -1;
+    }
+
     return 0;
 }
 
@@ -401,6 +442,11 @@ int main(int argc, char* argv[])
     if (retval)
         return retval;
 
+    // Disable OpenCL for DNN-based features to avoid backend sync issues
+    bool use_aliked = (features_type == "aliked");
+    if (use_aliked)
+        cv::ocl::setUseOpenCL(false);
+
     // Check if have enough images
     int num_images = static_cast<int>(img_names.size());
     if (num_images < 2)
@@ -418,7 +464,11 @@ int main(int argc, char* argv[])
 #endif
 
     Ptr<Feature2D> finder;
-    if (features_type == "orb")
+    if (use_aliked)
+    {
+        // ALIKED will be created per-image in the loop below
+    }
+    else if (features_type == "orb")
     {
         finder = ORB::create();
     }
@@ -488,7 +538,15 @@ int main(int argc, char* argv[])
             is_seam_scale_set = true;
         }
 
-        computeImageFeatures(finder, img, features[i]);
+        if (use_aliked)
+        {
+            Ptr<ALIKED> aliked = ALIKED::create(aliked_model_path);
+            computeImageFeatures(aliked, img, features[i]);
+        }
+        else
+        {
+            computeImageFeatures(finder, img, features[i]);
+        }
         features[i].img_idx = i;
         LOGLN("Features in image #" << i+1 << ": " << features[i].keypoints.size());
 
@@ -507,7 +565,14 @@ int main(int argc, char* argv[])
 #endif
     vector<MatchesInfo> pairwise_matches;
     Ptr<FeaturesMatcher> matcher;
-    if (matcher_type == "affine")
+    if (use_aliked && matcher_type == "lightglue")
+    {
+        Ptr<LightGlueMatcher> lg = LightGlueMatcher::create(lightglue_model_path);
+        Ptr<LightGlueFeaturesMatcher> lgMatcher = makePtr<LightGlueFeaturesMatcher>(lg);
+        lgMatcher->setScoreThreshold(lg_score_thresh);
+        matcher = lgMatcher;
+    }
+    else if (matcher_type == "affine")
         matcher = makePtr<AffineBestOf2NearestMatcher>(false, try_cuda, match_conf);
     else if (range_width==-1)
         matcher = makePtr<BestOf2NearestMatcher>(try_cuda, match_conf);