Flor commited on
Commit
37eb99e
Β·
verified Β·
1 Parent(s): 4c6c3fe

card: update from fastforks 1cbf1671

Browse files
Files changed (1) hide show
  1. README.md +105 -0
README.md ADDED
@@ -0,0 +1,105 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ library_name: "fastforks"
3
+ pipeline_tag: "image-to-image"
4
+ license: "other"
5
+ license_name: "see-model-card"
6
+ license_link: "https://github.com/cvg/FlexGlue/blob/99920296d082c9405ebfd612d674efe288e74881/README.md#license"
7
+ tags:
8
+ - "matching"
9
+ - "dense-matching"
10
+ - "image-matching"
11
+ - "feature-matching"
12
+ - "cuda"
13
+ - "pytorch"
14
+ - "fastforks"
15
+ - "fastforks-card"
16
+ ---
17
+ # FlexGlue (fastforks)
18
+
19
+ FlexGlue (Lindenberger, Sarlin, Miksik and Pollefeys 2026): sparse feature matching from dense features. ALIKED finds up to 2048 keypoints per image at a 1024-pixel long side, a DINOv3 ConvNeXt-B describes each image at 512 x 512, nine transformer layers (rotary self-attention, cross-attention) relate both feature maps, and a head predicts where each keypoint lands in the other image; mutual nearest neighbours of keypoints and predictions are the matches. Returns both keypoint sets, the index pairs of the matches and their confidence.
20
+
21
+ This repo is the model card only: it holds no weights. fastforks downloads the authors' weights from the links below and checks them against the SHA-256 in the model card. Code: <https://github.com/kleinicke/fastforks>. Kernels for the `kernels` backend: <https://huggingface.co/fastforks/kernels>. Original code: <https://github.com/cvg/FlexGlue> at `99920296d082`.
22
+
23
+ Task: matching. Tier: experimental. Outputs: `keypoints1`, `keypoints2`, `pairs`, `scores`. Backends: `portable`.
24
+
25
+ Input: two RGB images of one scene. Output: for every pixel of the first image its position in the second (x, y in pixels) and a certainty that the pixel is visible in both. Sparse matchers (LightGlue) return the keypoints of both images and the index pairs of the matched ones instead. To reconstruct camera poses from an image folder with these matchers, see [structure from motion](../sfm.md).
26
+
27
+ ## Variants
28
+
29
+ Weights are the authors' files (not hosted here). SHA-256 shortened to 12 hex digits; the full hashes are in [`card.toml`](https://github.com/kleinicke/fastforks/blob/main/src/fastforks/matching/models/flexglue/card.toml).
30
+
31
+ | variant | weights (author link) | SHA-256 | weights licence | commercial use |
32
+ |---|---|---|---|---|
33
+ | `aliked-flexglue@1` | [flexglue.pth](https://github.com/cvg/FlexGlue/releases/download/v0.1/flexglue.pth)<br>[aliked-n16.pth](https://raw.githubusercontent.com/Shiaoming/ALIKED/683d7c65197395c0b3f01ebe76e1084a27e73a65/models/aliked-n16.pth) | `d7371f743b8c`<br>`5be8704840ed` | MIT AND LicenseRef-DINOv3-License AND BSD-3-Clause | yes |
34
+
35
+ ## Licence
36
+
37
+ Original-code strings, recorded as they are (research-use package; check them before any other use). Code: MIT AND BSD-3-Clause. Licence files: `LICENSE`, `LICENSE-ALIKED`, `LICENSE-DINOv3`.
38
+
39
+ Training data: FlexGlue: the README states no training data and the training code is not released (see the paper). The DINOv3 ConvNeXt-B backbone was pretrained on LVD-1689M (Meta, not released); ALIKED was trained on MegaDepth..
40
+
41
+ - Licence note: The checkpoint includes the DINOv3 ConvNeXt-B backbone weights (`extractor.backbone.*`): the DINOv3 License (Meta: attribution and conditions apply) covers them; read it before commercial use.
42
+
43
+ Licence evidence: https://github.com/cvg/FlexGlue/blob/99920296d082c9405ebfd612d674efe288e74881/README.md#license ; https://github.com/Shiaoming/ALIKED/blob/683d7c65197395c0b3f01ebe76e1084a27e73a65/LICENSE
44
+
45
+ ## Input size
46
+
47
+ any H x W >= 32, padded to a multiple of 32
48
+ Tested up to (portable, fp16, RTX 5060 Ti 16 GB): `aliked-flexglue` 3000x4000 (2.0 GiB peak allocated, 2.5 reserved)
49
+
50
+ ## Speed and memory
51
+
52
+ ### Matching, synthetic, 768x1024
53
+
54
+ | model | time (ms): original fp32 | original | portable | kernels | kernels speed-up: vs original | vs portable | peak memory (MiB, allocated / reserved): original | portable | kernels |
55
+ | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
56
+ | `aliked-flexglue` | – | – | 129 | – | – | – | – | 1775 / 1886 | – |
57
+
58
+ ### Startup and first call
59
+
60
+ | model | load (s): original | portable | kernels | first call (s): original | portable | kernels |
61
+ | --- | --- | --- | --- | --- | --- | --- |
62
+ | `aliked-flexglue` | – | 0.92 | – | – | 1.20 | – |
63
+
64
+ ### torch.compile and TensorRT
65
+
66
+ | model | input | time: portable | compile | TensorRT fp16 | kernels | preparation: compile (cold first call) | ONNX + engine build | peak MiB (alloc / reserved): portable | compile | kernels | TensorRT (engine + torch) |
67
+ | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
68
+ | `aliked-flexglue` | 768x1024 | 129 ms | deferred (build >5 min) | deferred (build >5 min) | – | – | – | 1775 / 1886 | – | – | – |
69
+
70
+ Fixed-size cells: time (ms) / peak allocated / peak reserved memory (MiB).
71
+
72
+ Hardware, protocol and caveats: [benchmarks](https://github.com/kleinicke/fastforks/blob/main/docs/benchmarks.md) (RTX 5060 Ti 16 GB, sm_120). Original = the original code named above at the precision of portable (fp16, or `(fp32)` where fp16 is unsupported or not finite); original fp32 = its default fp32 run. Peak memory is the torch allocator's.
73
+
74
+ ## Accuracy
75
+
76
+ ### Parity with the original code
77
+
78
+ Every variant is checked against reference outputs of the original code at its pinned commit. CPU, float32: max |diff| <= 0.0001 vs the original. GPU, float16 (the default), portable and kernels: mean |diff| <= 0.0052 and p99 <= 0.012 (absolute error of the output `keypoints1`).
79
+
80
+ ## Limitations
81
+
82
+ - Sparse output: no dense warp. `result.matches()` gives the matched points for `estimate_pose`; `pairs` are the index pairs pycolmap / COLMAP databases take.
83
+ - One image pair per call internally (batches run pair by pair); the keypoint counts differ per image.
84
+ - No exportable module: the keypoint and match counts are data-dependent (`torch.compile` runs with graph breaks; ONNX / TensorRT export fails).
85
+ - Upstream's sparse mode only: no RoMa v2 refiner, no dense or sampled matches and no covisibility score.
86
+ - Two resizes per image as upstream: ALIKED sees a long side of `long_side` (aspect kept), the descriptor a `size` x `size` square whatever the aspect ratio.
87
+
88
+ ## Usage
89
+
90
+ ```python
91
+ from fastforks import matching
92
+
93
+ model = matching.load("aliked-flexglue") # mode="auto": the preferred backend from recorded measurements
94
+ result = model("view1.jpg", "view2.jpg")
95
+ result.keypoints1 # [2, H1, W1] float32: x, y in view2 pixels
96
+ result.backend # what ran, e.g. Backend(mode='portable', device='cuda:0', dtype='float16')
97
+ ```
98
+
99
+ Install with `pip install fastforks` (see <https://github.com/kleinicke/fastforks>). Other variants: `aliked-flexglue`.
100
+
101
+ ## Kernels backend
102
+
103
+ No kernels backend: not implemented: data-dependent keypoint and match counts. Portable at 768x1024, 2048 keypoints, MegaDepth pair: 129.6 ms against 152.9 ms for the original with its float16 option (1.18x), peak allocated 1799 vs 1801 MB (reserved 1962 vs 1950), 760 vs 759 matches.
104
+
105
+ <!-- staged from fastforks 1cbf1671 (2026-11-15) -->