--- library_name: "fastforks" pipeline_tag: "image-to-image" license: "other" license_name: "see-model-card" license_link: "https://github.com/Parskatt/romav2/blob/95c9968145c8906b7b59383258e9f73b02853d89/README.md#license" tags: - "matching" - "dense-matching" - "image-matching" - "feature-matching" - "cuda" - "pytorch" - "fastforks" - "fastforks-card" --- # RoMa v2 (fastforks) RoMa v2 (Edstedt, Nordström, Wadenbäck, Felsberg et al. 2025): dense feature matching between two images of any viewpoint. A frozen DINOv3 ViT-L/16 describes both images at a coarse square size, a multi-view ViT with alternating attention and a DPT head turn the global cosine matches into a coarse warp and an overlap logit, and convolutional refiners on VGG19-BN features (local correlation at strides 4, 2, 1) sharpen it, at the coarse size and again at a fine size. Returns, for every pixel of the first image, its position in the second (pixels) and the probability that it is visible there. 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: . Kernels for the `kernels` backend: . Original code: at `95c9968145c8`. Task: matching. Tier: experimental. Outputs: `warp`, `certainty`. 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/romav2/card.toml). | variant | weights (author link) | SHA-256 | weights licence | commercial use | |---|---|---|---|---| | `romav2@1` | [romav2.0.1.pt](https://github.com/Parskatt/RoMaV2/releases/download/v2.0.1/romav2.0.1.pt) | `1557dec0d21b` | MIT AND LicenseRef-DINOv3-License | yes | ## Licence Original-code strings, recorded as they are (research-use package; check them before any other use). Code: MIT AND LicenseRef-DINOv3-License. Licence files: `LICENSE`, `LICENSE.md`. Training data: Upstream README: a mix of wide-baseline matching datasets following UFM and MapAnything (MegaDepth and others; see the paper); none has a dataset entry here yet. The frozen DINOv3 descriptor was pretrained on LVD-1689M (not released).. - Licence note: The checkpoint includes the DINOv3 ViT-L/16 weights, and net/dinov3.py and net/vit/ come from DINOv3: the DINOv3 License (Meta: attribution and conditions apply) covers those parts; read it before commercial use. Licence evidence: ## Input size any H x W >= 32, padded to a multiple of 32 Tested up to (portable, fp16, RTX 5060 Ti 16 GB): `romav2` 3000x4000 (2.9 GiB peak allocated, 4.7 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 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `romav2` | 1412 | 741 | 546 | 354 | 2.1x | 1.5x | 9881 / 10124 | 1989 / 2596 | 1909 / 2300 | ### Startup and first call | model | load (s): original | portable | kernels | first call (s): original | portable | kernels | | --- | --- | --- | --- | --- | --- | --- | | `romav2` | 5.45 | 0.85 | 0.96 | 2.09 | 0.91 | 0.62 | ### 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) | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `romav2` | 768x1024 | 546 ms | 576 ms | 353 ms | 354 ms | 254 s | 185 s | 1989 / 2596 | 3150 / 3386 | 1909 / 2300 | 6694 / 6740 | 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. The same 300 pairs for all modes, so float32 and bfloat16 compare pair for pair. Original = the original code named under Details, same checkpoint and protocol. | variant | dataset | original fp32 | original fp16 | portable | kernels | note | |---|---|---|---|---|---|---| | `romav2` | MegaDepth-1500, relative pose AUC@5 / @10 / @20 degrees | | 63.2 / 77.1 / 86.7 | 63.0 / 76.9 / 86.5 | 62.9 / 76.9 / 86.4 | | | `romav2` | MegaDepth-1500, every 5th pair, relative pose AUC@5 / @10 / @20 degrees | 64.6 / 78.0 / 87.1 | 64.7 / 78.2 / 87.3 | 64.7 / 78.3 / 87.3 | 64.4 / 77.9 / 86.9 | | Measured on portable: NVIDIA GeForce RTX 5060 Ti, torch 2.14.1+cu130, fastforks 011e320c, 2026-11-11 to 2026-11-12; kernels: NVIDIA GeForce RTX 5060 Ti, torch 2.14.1+cu130, fastforks 011e320c, 2026-11-12. ### Parity with the original code Every variant is checked against reference outputs of the original code at its pinned commit. CPU, float32: max |diff| <= 1.6e-05 vs the original. GPU, bfloat16 (the default), portable and kernels: mean |diff| <= 0.0086 and p99 <= 0.032 (absolute error of the output `warp`). ## Limitations - The precision matrices of the warp (upstream `precision_AB`) and upstream's sampling / keypoint helpers are not returned; tools/eval_matching.py has the MegaDepth-1500 sampling. - Both images are resized to squares (upstream's behaviour), whatever their aspect ratio. ## Usage ```python from fastforks import matching model = matching.load("romav2") # mode="auto": the preferred backend from recorded measurements result = model("view1.jpg", "view2.jpg") result.warp # [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 ). Other variants: `romav2`. ## Kernels backend `matching.load("romav2", mode="kernels")` runs our CUDA kernels (`romav2`). It needs a prebuilt kernel for your GPU architecture (downloaded from 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.