dedode / README.md
Flor's picture
card: update from fastforks 1cbf1671
efe5701 verified
|
Raw History Blame Contribute Delete
8.12 kB
---
library_name: "fastforks"
pipeline_tag: "image-to-image"
license: "mit"
tags:
- "matching"
- "dense-matching"
- "image-matching"
- "feature-matching"
- "cuda"
- "pytorch"
- "fastforks"
- "fastforks-card"
---
# DeDoDe v2 (fastforks)
DeDoDe v2 (Edstedt et al., 3DV 2024; detector v2: CVPR Workshops 2024): detect, don't describe, describe, don't detect. A VGG19 network with convolutional refiners finds 10000 keypoints per image (the detector, retrained in v2), a separate descriptor network (VGG19, or VGG19 + a frozen DINOv2 ViT-L/14 for -G) describes them, and the descriptions are matched as mutual maxima of a dual softmax. Returns both keypoint sets, the index pairs of the matches and their probability.
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/Parskatt/DeDoDe> at `6d156183f4dc`.
Task: matching. Tier: experimental. Outputs: `keypoints1`, `keypoints2`, `pairs`, `scores`. Backends: `portable`, `kernels`.
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).
## Variants
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/dedode/card.toml).
| variant | weights (author link) | SHA-256 | weights licence | commercial use |
|---|---|---|---|---|
| `dedode-v2-b@1` | [dedode_detector_L_v2.pth](https://github.com/Parskatt/DeDoDe/releases/download/v2/dedode_detector_L_v2.pth)<br>[dedode_descriptor_B.pth](https://github.com/Parskatt/DeDoDe/releases/download/dedode_pretrained_models/dedode_descriptor_B.pth) | `4113809dd9e0`<br>`8eccfc270ec9` | MIT | yes |
| `dedode-v2-g@1` | [dedode_detector_L_v2.pth](https://github.com/Parskatt/DeDoDe/releases/download/v2/dedode_detector_L_v2.pth)<br>[dedode_descriptor_G.pth](https://github.com/Parskatt/DeDoDe/releases/download/dedode_pretrained_models/dedode_descriptor_G.pth)<br>[dinov2_vitl14_pretrain.pth](https://dl.fbaipublicfiles.com/dinov2/dinov2_vitl14/dinov2_vitl14_pretrain.pth) | `4113809dd9e0`<br>`ef6e3f2911bb`<br>`d5383ea8f487` | MIT | yes |
## Licence
Original-code strings, recorded as they are (research-use package; check them before any other use). Code: MIT. Licence files: `LICENSE`, `LICENSE-DINOv2`.
Training data: MegaDepth (Internet photo collections with SfM / MVS depth) (Detector v2 and descriptors: MegaDepth (README training section, papers); DINOv2 (-G, frozen): LVD-142M (Meta).).
Licence evidence: https://github.com/Parskatt/DeDoDe/blob/6d156183f4dc84cd704ae779eebc8350995c5b06/README.md#license ; https://github.com/Parskatt/DeDoDe/blob/6d156183f4dc84cd704ae779eebc8350995c5b06/LICENSE
## Input size
any H x W >= 32, padded to a multiple of 32
Tested up to (portable, fp16, RTX 5060 Ti 16 GB): `dedode-v2-b` 3000x4000 (1.9 GiB peak allocated, 3.8 reserved); `dedode-v2-g` 3000x4000 (2.5 GiB peak allocated, 4.5 reserved)
## Speed and memory
### Matching, synthetic, 768x1024
| model | time (ms): original fp32 | original | portable | kernels | kernels speed-up: vs original | vs portable | peak memory (MiB, allocated / reserved): original | portable | kernels |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `dedode-v2-b` | – | 318 | 246 | – | – | – | 1734 / 1992 | 1535 / 1654 | – |
| `dedode-v2-g` | – | 666 | 592 | – | – | – | 2335 / 2472 | 2142 / 2334 | – |
### Startup and first call
| model | load (s): original | portable | kernels | first call (s): original | portable | kernels |
| --- | --- | --- | --- | --- | --- | --- |
| `dedode-v2-b` | 3.73 | 0.67 | – | 1.10 | 0.75 | – |
| `dedode-v2-g` | 6.36 | 1.12 | – | 1.51 | 1.04 | – |
### torch.compile and TensorRT
| 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) |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `dedode-v2-b` | 768x1024 | 246 ms | 164 ms | planned for 0.2.1 | – | 50.5 s | – | 1535 / 1654 | 1893 / 2434 | – | – |
| `dedode-v2-g` | 768x1024 | 592 ms | 330 ms | planned for 0.2.1 | – | 86.4 s | – | 2142 / 2334 | 2881 / 3316 | – | – |
Fixed-size cells: time (ms) / peak allocated / peak reserved memory (MiB).
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.
## Accuracy
### On public datasets
Dense matchers: 5000 matches per pair sampled from the warp by certainty (upstream's balanced KDE sampling); sparse matchers: all their matches of one call (LightGlue, XFeat: LightGlue's MegaDepth-1500 setting; LoFTR, DeDoDe: their card defaults). OpenCV essential-matrix RANSAC (0.5 px threshold, normalised by the mean focal length); AUC of the larger of the rotation and translation-direction errors. Original = the original code named under Details, same checkpoint and protocol.
| variant | dataset | original fp16 | portable | note |
|---|---|---|---|---|
| `dedode-v2-b` | MegaDepth-1500, every 10th pair, relative pose AUC@5 / @10 / @20 degrees | 57.3 / 71.5 / 82.5 | 54.6 / 71.8 / 83.1 | |
Measured on NVIDIA GeForce RTX 5060 Ti, torch 2.14.1+cu130, fastforks aee4b565, 2026-11-13.
### Parity with the original code
Every variant is checked against reference outputs of the original code at its pinned commit. CPU, float32: max |diff| <= 0.011 vs the original. GPU, float16 (the default), portable and kernels: mean |diff| <= 0.002 and p99 <= 0.001 (absolute error of the output `keypoints1`).
## Limitations
- Sparse output: no dense warp. `result.matches()` gives the matched points for `estimate_pose`; `pairs` are the index pairs pycolmap / COLMAP databases take.
- One image pair per call internally (batches run pair by pair); the match counts differ per pair.
- No exportable module: the match counts are data-dependent (`torch.compile` runs with graph breaks; ONNX / TensorRT export fails).
- Images are resized to a `size` x `size` square (default 784, as upstream) whatever their aspect ratio; the dual softmax holds a `max_keypoints`^2 matrix (10000 keypoints: 400 MB per float32 copy).
- Upright only: the released descriptors are not trained for in-plane rotations.
## Usage
```python
from fastforks import matching
model = matching.load("dedode-v2-b") # mode="auto": the preferred backend from recorded measurements
result = model("view1.jpg", "view2.jpg")
result.keypoints1 # [2, H1, W1] float32: x, y in view2 pixels
result.backend # what ran, e.g. Backend(mode='portable', device='cuda:0', dtype='float16')
```
Install with `pip install fastforks` (see <https://github.com/kleinicke/fastforks>). Other variants: `dedode-v2-b`, `dedode-v2-g`.
## Kernels backend
`matching.load("dedode-v2-b", mode="kernels")` runs our CUDA kernels (`igev`, `cutlass_conv`, `cudnn_hacc`). It needs a prebuilt kernel for your GPU architecture (downloaded from <https://huggingface.co/fastforks/kernels> on first use) and a recent NVIDIA driver; if there is none it raises `BackendUnavailableError` with the reason and never falls back silently. `mode="auto"` picks `kernels` when it can run and logs the choice.
<!-- staged from fastforks 1cbf1671 (2026-11-15) -->