loftr / README.md
Flor's picture
card: update from fastforks 1cbf1671
b28007d verified
|
Raw History Blame Contribute Delete
7.94 kB
metadata
library_name: fastforks
pipeline_tag: image-to-image
license: apache-2.0
tags:
  - matching
  - dense-matching
  - image-matching
  - feature-matching
  - cuda
  - pytorch
  - fastforks
  - fastforks-card

LoFTR (fastforks)

LoFTR (Sun et al., CVPR 2021): detector-free dense matching. A ResNet-FPN gives 1/8 and 1/2 resolution features; a linear-attention transformer matches the 1/8 cells of both images (dual-softmax, mutual nearest neighbours above a confidence threshold) and a second transformer refines each match to sub-pixel precision in a 5 x 5 window at 1/2 resolution. Returns the matched points of both images, their (identity) index pairs and the coarse confidence.

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/zju3dv/LoFTR at df7ca80f9173.

Author weight repos: https://huggingface.co/kornia/loftr.

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.

Variants

Weights are the authors' files (not hosted here). SHA-256 shortened to 12 hex digits; the full hashes are in card.toml.

variant weights (author link) SHA-256 weights licence commercial use
loftr-indoor@1 loftr_indoor_ds_new.ckpt be9ff88b323e Apache-2.0 yes
loftr-outdoor@1 loftr_outdoor.ckpt 21f5bec59681 Apache-2.0 yes

Licence

Original-code strings, recorded as they are (research-use package; check them before any other use). Code: Apache-2.0. Licence files: LICENSE.

Training data: MegaDepth (Internet photo collections with SfM / MVS depth) (loftr-outdoor: MegaDepth. loftr-indoor: ScanNet (ScanNet terms of use: non-commercial research), README training section.).

Licence evidence: https://github.com/zju3dv/LoFTR/blob/df7ca80f917334b94cfbe32cc2901e09a80e70a8/LICENSE ; https://huggingface.co/kornia/loftr/tree/0fb3b456cf176746709c38fa9cf80695a1c82dac

Input size

any H x W >= 32, padded to a multiple of 32 Tested up to (portable, fp16, RTX 5060 Ti 16 GB): loftr-indoor 3000x4000 (2.0 GiB peak allocated, 2.8 reserved); loftr-outdoor 3000x4000 (1.9 GiB peak allocated, 2.8 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
loftr-indoor – 242 111 – – – 1751 / 1910 796 / 904 –
loftr-outdoor – 241 110 – – – 1739 / 1870 796 / 904 –

Startup and first call

model load (s): original portable kernels first call (s): original portable kernels
loftr-indoor 1.49 0.32 – 0.69 0.53 –
loftr-outdoor 0.35 0.24 – 0.24 0.58 –

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)
loftr-indoor 768x1024 111 ms 71.0 ms planned for 0.2.1 – 30.2 s – 796 / 904 634 / 684 – –
loftr-outdoor 768x1024 110 ms 176 ms planned for 0.2.1 – 33.3 s – 796 / 904 1149 / 1232 – –

Fixed-size cells: time (ms) / peak allocated / peak reserved memory (MiB).

Hardware, protocol and caveats: benchmarks (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 fp32 portable note
loftr-outdoor MegaDepth-1500, relative pose AUC@5 / @10 / @20 degrees 50.1 / 67.5 / 80.3 50.6 / 67.6 / 80.3
loftr-outdoor MegaDepth-1500, every 10th pair, relative pose AUC@5 / @10 / @20 degrees 53.8 / 71.8 / 83.7 52.1 / 71.0 / 83.3

Measured on NVIDIA GeForce RTX 5060 Ti, torch 2.14.1+cu130, fastforks 3a7e4880 / aee4b565, 2026-11-13 to 2026-11-15.

Parity with the original code

Every variant is checked against reference outputs of the original code at its pinned commit. CPU, float32: max |diff| <= 3e-05 vs the original. GPU, float16 (the default), portable and kernels: mean |diff| <= 0.0025 and p99 <= 0.02 (absolute error of the output keypoints1).

Limitations

  • Sparse output: no dense warp. result.matches() gives the matched points for estimate_pose; every match is its own keypoint pair (pairs is [[0, 0], [1, 1], ...]).
  • 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 converted to grayscale and matched at long_side (default 840, upstream's MegaDepth test size); the coarse matching holds an (H W / 64)^2 score matrix, so memory grows with the 4th power of the side. The indoor weights were evaluated by upstream at 640 x 480 (ScanNet).

Usage

from fastforks import matching

model = matching.load("loftr-indoor")  # 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: loftr-indoor, loftr-outdoor.

Kernels backend

matching.load("loftr-indoor", 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.