Matching
Nearest-neighbour matching
nn_match and match compare two descriptor matrices, one descriptor per row, and return a Vector{NNMatch} sorted best first. Both run the same KernelAbstractions kernels: match on the CPU, nn_match on any device (device = CUDABackend(), for instance), and a GPU returns what the CPU returns. match is public but not exported, because it would shadow Base.match; call it as VisualGeometryToolkitFeatures.match.
The strategy is a positional argument:
MutualNN(the default) keeps pairs that are each other's nearest neighbour;NNkeeps every row's nearest neighbour;KnnMatch(k)keeps every row'sknearest neighbours, for a downstream geometric check to disambiguate.
The metric is a keyword: CosineSimilarity (the default, for unit descriptors) or L2. ratio_threshold applies Lowe's ratio test, and min_similarity or max_distance bound the score.
julia> using VisualGeometryToolkitFeatures
julia> D1 = Float32[1 0; 0 1; 0.6 0.8];
julia> D2 = Float32[0 1; 1 0];
julia> [(m.first, m.second) for m in nn_match(D1, D2)]
2-element Vector{Tuple{Int64, Int64}}:
(1, 2)
(2, 1)
julia> length(nn_match(D1, D2, NN())) # row 3 matches too, one way
3Matches as correspondences
An NNMatch holds indices. VisualGeometryToolkitCore's correspondences(features1, features2, matches) turns them into VisualGeometryToolkitCore correspondences between the matched features, with each match's score and ratio as attribute columns, ready for a robust estimator.
DescribedFeature pairs a detection with its descriptor. described_features builds a StructArray of them from detections and a descriptor matrix, and descriptor_matrix returns the descriptors as a matrix without copying; match and correspondences accept the StructArray directly.
Many galleries at once
nn_match_stacked matches one set of features against many galleries (a dictionary of descriptor matrices) in one matrix product, with the same result per gallery as matching that gallery alone. A StackedDescriptorIndex keeps the stacked galleries on the device between calls.
LoMa
LoMaDescriptor and LoMaMatcher run the learned DeDoDe descriptors and LoMa matchers of Nordström et al. (ECCV 2026) from the authors' ONNX exports, through ONNX Runtime on the CPU or CUDA. The models are downloaded on first use and cached in the package's scratch space. A descriptor describes about max_detections of the strongest detections, spread over the image (spread_strongest), of a 3 × H × W RGB channelview of any size (it resamples the image to the network's LOMA_IMAGE_SIZE² input itself, and the detections stay in the image's pixels); a matcher matches two described sets and returns Vector{NNMatch}, like match:
describe = LoMaDescriptor(:b)
matcher = LoMaMatcher(:b128)
fa = describe(img_a, asift_detect(img_a))
fb = describe(img_b, asift_detect(img_b))
matches = matcher(fa, fb, size(img_a), size(img_b))Both run on ONNX Runtime's CUDA provider when it is available and on the CPU otherwise (execution_provider = :auto, the default; the fallback warns and names why; :cpu and :cuda are explicit, and an explicit :cuda that cannot run is an error naming why). The CUDA provider needs a CUDA device and an environment that holds CUDA_Runtime_jll and CUDNN_jll: their CUDA 12 builds are downloaded on first use and loaded for ONNX Runtime alone, whatever CUDA runtime CUDA.jl uses (onnx_cuda_status says what was found). ONNX Runtime itself is, on the CUDA path, conda-forge's build of release 1.31.1 (Microsoft's GPU builds carry no code for sm100, the B200), with device code for sm70 to sm120; the package installs it on the first CUDA probe from four conda-forge files pinned by sha256 into the artifact store (VisualGeometryToolkitCore's `artifactstore, never a cluster's depot: 0.34 GB, once per store). The CUDA 12 runtime and cuDNN are the two JLLs' own artifacts, which Pkg places in the depot. ONNX Runtime's thread pool isthreads = Threads.nthreads(), the process's allotment (in a Slurm job, start Julia with–threadsset to the job'sSLURMCPUSPERTASK), never the machine's cores. [lomaprovenance`](@ref) records the provider used, the threads and the library versions.
Another package's ONNX network runs on the same runtime through onnx_session(path; execution_provider, threads, gpu_mem_limit): the provider resolved as above, the thread pool the caller's, and on CUDA the session's device arena capped at gpu_mem_limit bytes (8 GiB by default), which the ASIFT detector's device plans leave free. Run it through onnx_run(session, inputs) (or onnx_run(f, session) for any call that runs it, a device-tensor run among them): the arena's growth is then measured and the detector's budget counts it.
The package's examples/loma.jl runs this on a pair of downloaded images and draws the matches. Cite the LoMa and DeDoDe papers when you use these networks (their entries are on the home page).