vectorized and parallel DFT/DCT + matchTemplate - #30061
(Made with a help from Claude Code Fable 5.1)
## Summary
This PR replaces the scalar 1D DFT/DCT kernels in `modules/core/src/dxt.cpp` with a new engine
built on universal intrinsics and compiled per ISA through `ocv_add_dispatched_file`, and makes
the 2D transforms, the `DFT_ROWS`/`DCT_ROWS` batches and `matchTemplate` (`crossCorr`) multi-threaded.
The public API, the output formats (CCS packing of real spectra, `DFT_COMPLEX_OUTPUT` layout,
DCT ordering and normalization) and the IPP/OpenCL paths are unchanged. Only floating-point
rounding may differ (the new twiddle tables are more accurate than the old recurrence-generated
ones, so the error goes down, not up).
Measured on Apple M4 Max (16 cores, NEON), macOS 26.5.x, Xcode 26.6, Release build
(`-O3`, no IPP). All numbers are the minimum over repeated runs, `5.x` vs this PR.
## Changes
### New 1D engine (`dxt.hpp`, `dxt.simd.hpp`, `dxt.cpp`)
- **Split re/im layout.** The input pass gathers the data into separate `re[]`/`im[]` workspace
arrays; all middle stages operate on the split arrays, so a complex multiplication is four
independent vector FMAs with no lane shuffling. The output pass interleaves back (or packs the
CCS / DCT layout) with the scaling fused in.
- **Mixed-radix decimation-in-time with a fused first stage.** The plan chooses the first stage
(radix 1/2/4/8, twiddle-free, fused with the gather and the digit-reversal permutation) from
the power of two in the length, then radix-4 stages, then radix-3, radix-5 and a generic odd
radix. There are no radix-2 middle stages.
- **Vectorized butterflies with universal intrinsics** (`v_float32`/`v_float64`, VLA-safe): one
flat loop per stage with a single clamped counter for both the data and the twiddle offsets
(the back-off clamp handles spans that are not multiples of the vector width; such stages run
out of place, ping-ponging between two workspace pairs, the others run in place).
- **Vectorized first stage.** The radix-2/4/8 first stage reads the input columns contiguously
(`v_load_deinterleave`), runs the small DFT in registers and scatters the outputs of every
lane with one 4-channel interleaved store. Only odd lengths use a scalar table-driven gather.
- **Vectorized edge passes**: interleave/deinterleave, the real-FFT untangling in both directions
(with `v_reverse` for the mirrored half), DCT-II post-twiddle and DCT-III pre-twiddle, the
Makhoul permutations.
- **Inverse = conjugation trick**: the middle stages are direction-free and use forward twiddles
only; the inverse conjugates on the gather and negates the imaginary scale on the output.
- **Immutable plan + per-executor workspace, zero allocations per transform.** The plan
(radix sequence, permutation table, per-stage split twiddle tables) is built once in `init()`
and shared by all rows of a batch; every executor owns a workspace. Twiddles are generated in
double precision from a two-level exact table (a few ulps, much cheaper to build than the old
N-point recurrence, which matters because `cv::dft()` builds a plan on every call).
- **Per-ISA dispatch**: `ocv_add_dispatched_file(dxt SSE2 AVX2 AVX512_ICL RVV)`; the kernels are
reached through a function-pointer table resolved once per depth, following the pattern of
`arithm.simd.hpp` / `warp_kernels.simd.hpp`. The plan is built with the vector width of the
dispatched kernels (never with the baseline `VTraits`).
- The legacy scalar engine, `DFTInit`, the SSE3 `DFT_VecR*` butterflies and the `noPermute`/
`factors[0] >>= 1` machinery are removed (−1400 lines). The legacy `cv_hal_dft` hook (which
took the old tables) is no longer called from the 1D path; the in-tree RISC-V HAL
implementation of it will be updated in a separate PR.
### Parallelism
- `crossCorr` (`matchTemplate`): the correlation tiles are independent and are now distributed
with `parallel_for_`; every worker creates its DFT buffers and `DFT2D` contexts once per range.
(The tile loop had been sequential since the C++ rewrite in 2010, which dropped the OpenMP
pragma of `icvCrossCorr`.)
- 2D DFT/DCT and `DFT_ROWS`/`DCT_ROWS` batches: the row pass, the column pass and the DCT line
loop distribute their lines over threads; the 1D plan is shared, each worker allocates its
workspace once per range. The number of stripes is derived from the N log N cost, so a 256x256
transform stays on the calling thread and 1024x1024 gets ~20 stripes. Nested calls (the 2D DFTs
inside the parallel `crossCorr` tiles) are serialized by `parallel_for_` itself.
- The column pass copies columns in batches (`CopyFromColumns`/`CopyToColumns`, 4..16 adjacent
columns copied row by row into contiguous buffers sized to stay within 128 KB) instead of two
at a time: with power-of-two row steps the old strided copies aliased in the cache and took
60-70% of the 2D time.
### Tests
- `Core_DFT.sweep_1d`, `Core_DCT.sweep_1d`: every 5-smooth length up to 2048 plus odd, prime and
"awkward" lengths, both depths, C2C forward/inverse, R2C (CCS and complex output), C2R (CCS and
complex input), DCT/IDCT, in-place, column vectors, round trips; compared against the naive
O(N^2) references of `test_dxt.cpp` with a tolerance of `32*eps*(log2(N) + 2 + maxfactor/16)`.
- `Core_DFT.sweep_rows`: `DFT_ROWS` batches sharing one plan.
- `Core_DFT.nonzero_rows`: 2D transforms with `nonzero_rows` (previously uncovered).
- `Core_DFT.parallel_large`: large 2D / rows / DCT transforms, multi-threaded result vs the
single-threaded one.
- The naive DCT reference reduces the angle exactly before `cos()` (its accuracy was limiting
the comparison for n > 100 in double precision).
- Perf: `perf_dft.cpp` gains 1D row/column cases for `dft` and `dct`.
- Existing `opencv_test_core` (incl. `Core_DFT*`, `Core_DCT*`, `Core_MulSpectrums`,
`Core_DivSpectrums`) and `opencv_test_imgproc` (phaseCorrelate, matchTemplate, filter2D) pass;
the x86-64 build (SSE3 baseline + SSE4.1/AVX2/AVX512_ICL dispatch) passes the DFT/DCT tests
under Rosetta 2 (AVX2/AVX-512 paths compile-checked only on this machine).
## Performance
### 1D transforms (single row, one thread), microseconds
`C2C` = complex-to-complex, `R2C` = real-to-CCS, `C2R` = CCS-to-real (inverse, scaled),
`32`/`64` = float/double.
| n | C2C32 | C2C64 | R2C32 | C2R32 | R2C64 | DCT32 | IDCT32 | DCT64 |
|---|---|---|---|---|---|---|---|---|
| 256 | 0.82 → 0.55 | 0.86 → 0.74 | 0.67 → 0.53 | 0.63 → 0.52 | 0.64 → 0.56 | 0.88 → 0.56 | 0.88 → 0.56 | 0.90 → 0.66 |
| 1000 | 3.84 → 1.70 | 4.08 → 2.58 | 2.86 → 1.36 | 2.88 → 1.38 | 2.77 → 1.74 | 3.95 → 1.69 | 4.02 → 1.72 | 3.97 → 2.15 |
| 1024 | 3.25 → 1.65 | 3.44 → 2.40 | 2.46 → 1.23 | 2.35 → 1.27 | 2.42 → 1.59 | 3.57 → 1.57 | 3.51 → 1.59 | 3.45 → 2.02 |
| 4096 | 14.9 → 6.4 | 16.4 → 11.5 | 10.7 → 4.3 | 10.2 → 4.5 | 11.0 → 6.9 | 15.4 → 6.0 | 15.3 → 6.0 | 17.0 → 9.5 |
| 4725 (3³·5²·7) | 27.5 → 17.2 | 29.4 → 24.1 | 28.2 → 16.4 | 29.8 → 18.3 | 30.3 → 24.7 | – | – | – |
| 65536 | 350 → 273 | 411 → 494 | 223 → 136 | 274 → 139 | 251 → 249 | 318 → 167 | 299 → 159 | 372 → 320 |
Each `cv::dft()` call builds its plan anew; at n = 4096 the plan takes ~1.9 µs of the 6.4 µs
(the old code spent ~4 µs of 14.9 on its tables). For n = 65536 both versions are bound by the
memory traffic of the out-of-cache data, and C2C64 gets slightly slower (the split layout needs
one more pass over 1 MB of data; a plan cache or larger radices could recover this later).
### 2D transforms, single thread, microseconds
| size | C2C32 | R2C32 | C2R32 | R2C64 | DCT32 | IDCT32 | R2C32 rows |
|---|---|---|---|---|---|---|---|
| 256×256 | 297 → 140 | 162 → 75 | 165 → 77 | 178 → 126 | 259 → 166 | 290 → 174 | 72 → 29 |
| 512×512 | 1660 → 569 | 765 → 306 | 723 → 317 | 896 → 551 | 1381 → 946 | 1377 → 957 | 303 → 125 |
| 480×640 | 1555 → 715 | 895 → 377 | 918 → 392 | 978 → 677 | 1248 → 707 | 1262 → 695 | 389 → 147 |
| 1024×1024 | 7508 → 2625 | 3781 → 1387 | 3883 → 1398 | 4964 → 3201 | 6438 → 4556 | 6805 → 4583 | 1341 → 516 |
| 1080×1920 | 13141 → 5543 | 7143 → 2880 | 7269 → 2970 | 7770 → 5348 | 9735 → 5190 | 9477 → 5381 | 3116 → 1192 |
| 2048×2048 | 38151 → 16822 | 18381 → 6973 | 18784 → 7294 | 25146 → 17476 | 30291 → 21631 | 30540 → 22003 | 5809 → 2242 |
### 2D transforms, default thread count (16), microseconds
| size | C2C32 | R2C32 | C2R32 | R2C64 | DCT32 | IDCT32 | R2C32 rows |
|---|---|---|---|---|---|---|---|
| 256×256 | 309 → 138 | 157 → 75 | 161 → 77 | 174 → 126 | 265 → 167 | 293 → 170 | 71 → 29 |
| 512×512 | 1660 → 162 | 785 → 155 | 788 → 160 | 866 → 256 | 1410 → 235 | 1366 → 228 | 303 → 41 |
| 480×640 | 1531 → 178 | 895 → 142 | 916 → 141 | 957 → 222 | 1241 → 172 | 1248 → 173 | 393 → 46 |
| 1024×1024 | 7495 → 381 | 3755 → 274 | 3767 → 269 | 4875 → 478 | 6323 → 650 | 6583 → 630 | 1343 → 94 |
| 1080×1920 | 12905 → 681 | 7131 → 403 | 7240 → 382 | 7760 → 657 | 9673 → 605 | 9513 → 607 | 3124 → 143 |
| 2048×2048 | 38155 → 1481 | 18324 → 826 | 18559 → 857 | 24861 → 1776 | 30120 → 2592 | 30741 → 2734 | 5890 → 274 |
(5.x is single-threaded for all of these; 256×256 stays single-threaded in the new code by design.)
### matchTemplate (`opencv_perf_imgproc`, `*matchTemplate*`), milliseconds
Whole suite (156 cases): 921 → 284 ms. Selected cases (8-bit image, 16×16 template unless noted):
| image, template | SQDIFF | SQDIFF_NORMED | CCORR | CCORR_NORMED | CCOEFF | CCOEFF_NORMED |
|---|---|---|---|---|---|---|
| 128×128 | 0.15 → 0.12 | 0.14 → 0.12 | 0.09 → 0.05 | 0.13 → 0.09 | 0.11 → 0.08 | 0.13 → 0.10 |
| 320×240 | 0.99 → 0.52 | 1.09 → 0.58 | 0.79 → 0.23 | 0.96 → 0.42 | 0.93 → 0.38 | 1.02 → 0.53 |
| 640×480 | 3.19 → 1.17 | 3.35 → 1.22 | 2.27 → 0.29 | 3.12 → 1.04 | 2.94 → 0.90 | 3.43 → 1.38 |
| 800×600 | 5.86 → 1.64 | 5.61 → 1.77 | 4.11 → 0.34 | 5.48 → 1.53 | 5.19 → 1.28 | 5.82 → 2.04 |
| 1024×768 | 9.73 → 2.72 | 9.59 → 2.90 | 6.88 → 0.48 | 9.11 → 2.45 | 8.44 → 2.05 | 9.84 → 3.44 |
| 1280×1024 | 14.92 → 4.33 | 15.01 → 4.58 | 10.70 → 0.64 | 14.31 → 3.97 | 13.40 → 3.33 | 15.37 → 5.58 |
| 1280×1024, 1260×1000 | 13.06 → 7.90 | 13.08 → 7.74 | 10.75 → 3.58 | 12.23 → 5.03 | 11.11 → 3.94 | 12.03 → 5.05 |
`TM_CCORR` is now dominated by the (still single-threaded) `integral()` and normalization passes
in the other methods; those are candidates for a follow-up.
## Notes for reviewers
- `modules/core/src/dxt.hpp` documents the engine layout; the plan builder (`DftPlan::build`)
and the driver (`runDft`) are in `dxt.cpp`, the kernels in `dxt.simd.hpp`.
- Stages whose span is smaller than the vector width run scalar (on NEON this only affects
lengths of the form 2·odd; on AVX2/AVX-512 also the first radix-4 stage of 4^k lengths);
handling them with narrower fixed-width vectors is a possible follow-up.
- A radix-8 middle stage was implemented and measured slower on NEON than two radix-4 stages
(register pressure), so it is not included.
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
objdetect: default CCheckerDetector chart type to MCC24 - #30412Fixes#30410.
`CCheckerDetectorImpl::m_chartType` had no initializer and the constructor is empty, so a detector from `CCheckerDetector::create()` read an indeterminate chart type unless `setColorChartType()` was called first. It now defaults to `MCC24`, the first `ColorChart` value. With `operator new` filling memory with 0xFF, 5.x reports chart type -1 and `process()` fails on `mcc/MCC24.png`; with the fix it reports `MCC24` and finds the chart. Added `CV_mccRunCCheckerDetectorBasic.default_chart_type`, which checks the default and runs detection without setting the type.
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake
Fix code according to fuzzer findings - #30286
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
calib document fix - #30208
Documentation changes - three doxygen blocks in `modules/objdetect`.
- **`findChessboardCorners`** (PR#22083): whether the returned order pins down a unique
physical corner depends on the **parity** of the two `patternSize` dimensions, not on
whether they differ. Quads are built from the dark squares only (`calibinit.cpp:755`
`THRESH_BINARY`, `:796` white frame, `:1919` holes-only), so a rotation is admissible
only if it maps dark squares onto dark squares. For `patternSize` of w x h interior
corners the squares form a (w+1) x (h+1) grid, so 180° preserves the colouring exactly
when w and h share parity:
| `patternSize` | distinct origins | ambiguity |
|--------------------------------|------------------|---------------|
| different parity (9x6, 8x5) | 1 | none |
| same parity, w != h (8x6, 7x5) | 2 | 180° |
| w == h (7x7, 8x8) | 4 | 90° |
The square case is not colour: the transpose at `calibinit.cpp:1745` is a no-op when
`width == pattern_size.width`, so the detector cannot tell rows from columns. Verified
over 24 in-plane rotations and 60 perspective views per board, zero detection failures;
inverting the square colouring moves the origin but not the count.
Practical consequence is the reverse of what was documented: the common 9x6 board is
unambiguous, while this docstring's own sample `Size patternsize(8,6)` is not. The note
now recommends a board whose dimensions differ in parity first, then
#findChessboardCornersSB + `CALIB_CB_MARKER`, then ChArUco. Still harmless for
intrinsics (each view absorbs the rotation into its own pose); still breaks hand-eye.
- **`findCirclesGrid`** (PR#7312): the returned points are the keypoint locations reported
by `blobDetector` as-is, without refinement - the parameter is a `FeatureDetector` and
`SimpleBlobDetector` is only the default, so the points are not necessarily moment
centroids. Under perspective the apparent centre of a projected circle can be displaced
from the projection of the physical centre; the displacement vanishes when the board is
parallel to the image plane and is not removed by fitting an ellipse. Points at the
`blobDetector = NULL` path for supplying corrected centres. Describes the bias
qualitatively rather than quoting a fixed estimate.
- **`setLegacyPattern` / `detectBoard`** (PR#23152, PR#29636): the flag is a no-op on
odd-row boards, and a wrong setting fails silently - markers detected, zero corners,
only a `CV_LOG_DEBUG` line; notes that calib.io boards use the legacy layout and aligns
the 4.6.0 version wording across both headers.
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
objdetect: handle unsupported QR modes gracefully - #30123
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
### Description
Resolves#30110.
This PR addresses two related defects in `QRCodeDetector` and Python string conversion bindings:
1. **`objdetect`**: In `QRCodeDecoderImpl::decodeSymbols` (`qrcode_encoder.cpp`), encountering unsupported or unhandled QR mode indicators (such as Hanzi mode 13 or FNC1) previously called `CV_Error(Error::StsNotImplemented, format("mode %d", currMode))`, throwing an unhandled `cv2.error` exception out of high-level detector calls like `detectAndDecodeMulti()`. Replaced `CV_Error` with `return false;` to report symbol decode failure gracefully.
2. **`python`**: In `pyopencv_from(const String& value)` (`cv2_convert.cpp`), converting C++ string payloads to Python `str` previously called `PyString_FromString` (`PyUnicode_FromString`), which raises a `UnicodeDecodeError` when decoding non-UTF-8 payload bytes (e.g. GB2312 or Shift-JIS lead bytes). Updated string conversion to use `PyUnicode_DecodeUTF8(..., "surrogateescape")` with fallback to `PyBytes_FromStringAndSize`.
### Testing
- Added `TEST(Objdetect_QRCode, unsupported_mode_graceful)` in `modules/objdetect/test/test_qrcode.cpp`.
Remove deprecated CommaInitializer API - #29948
This goes hand in hand with https://github.com/opencv/opencv_contrib/pull/4217
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake
Objdetect test cleanup - #29741
co-authored by: @Prasadayus
### Given real assertions
| change | reason |
|---|---|
| new `Objdetect_CheckChessboard.accuracy` (`test_checkchessboard.cpp`) | `cv::checkChessboard`'s only validation lived inside a test named `timing`, which aborted at the first of 19 images. The new test iterates all 19 from `chessboard_timing_list.dat` with `SCOPED_TRACE` and `EXPECT_EQ`, so every image is reported instead of stopping at the first mismatch |
| deleted `test_chesscorners_timing.cpp` | what remained after extracting the assertions was a stopwatch — it measured `findChessboardCorners` and asserted nothing about the result |
### Re-enabled - the reason for disabling no longer holds
| test | reason |
|---|---|
| `Charuco.testSeveralBoardsWithCustomIds` (`test_charucodetection.cpp:922`) | disabled by #24338 because 5.x returns charuco corners as `32FC2` rather than `2×32FC1` (#23473). The test never compares shapes: it asserts `expected_corners.total() == c_corners.total() * c_corners.channels()` and then compares `expected_corners.reshape(1, 1)` against `c_corners.reshape(1, 1)` — both flattened to one row, so the channel layout cannot affect the result. The comparison was already made shape-agnostic; only the `DISABLED_` prefix was never removed |
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
It was warning:
Implicit conversion turns floating-point number into integer: 'float' to 'unsigned int'
when assigning to `worst_score`.
Looks to me like `worst_score` is actually being given the wrong type, and that it should have the same type as `hamming_distance`, which is `DistanceType`.
It order to test, fixed a few adjacent -Wfloat-conversion warnings in translation units that use lsh_index.h.
Use validBitIdThreshold for Aruco refineDetectedMarkers #29252
The goal of this PR is to solve the issue raised by @vrabaud in https://github.com/opencv/opencv/pull/28289 (comment: https://github.com/opencv/opencv/pull/28289#discussion_r3355812646).
**Issue:**
`refineDetectedMarkers()` converted the extracted cell ratios with `convertTo(CV_8UC1)` (an implicit 0.5 threshold) before computing the code distance, ignoring `detectorParams.validBitIdThreshold`.
**Solution:**
Make the refine path consistent with the main detection path `Dictionary::identify`.
**Changes:**
- Add a `Dictionary::getDistanceToId()` overload that takes the float cell pixel ratio matrix and `validBitIdThreshold` (similar to how it's done for the `identify()` overload.
- Move the per cell distance computation into a private `getDistanceToIdImpl` helper used by both `identify()` and the new overload of `getDistanceToId()` to avoid repetitions.
- `refineDetectedMarkers()` now calls the new overload.
**Tests:**
- `CV_ArucoRefine.validBitIdThreshold`: a marker with one degraded cell is recovered at threshold 0.7 but not at 0.49.
- `CV_ArucoDictionary.getDistanceToIdCellPixelRatio`: unit-tests both `getDistanceToId` overloads.
All passed
bound alphanumeric values in qr decodeAlpha before map lookup #29378
decodeAlpha in the no-quirc QR backend reads alphanumeric symbols from the post-ECC bitstream and indexes a fixed 45-entry map[] with the raw values. The 11-bit pair from next(11) goes up to 2047, so tuple/45 lands on 45 once the pair passes 2024, and the 6-bit trailing char from next(6) goes up to 63, so map[value] runs out to map[63]. A QR whose data codewords carry an alphanumeric segment with one of those out-of-range values reads past the static array, and the stray byte lands in the string returned by detectAndDecode. WITH_QUIRC defaults off, so this is the decoder a stock build runs.
Before, the only guard was on the encode side, which never emits those values, so the decoder trusted the stream and indexed map[] directly. New version checks value range and return empty string for malformed qr codes.
### Pull Request Readiness Checklist
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
- [ ] The feature is well documented and sample code can be built with the project CMake
Optimization ArUco: get border errors in one pass for both normal and inverted markers #29329
This PR is a follow up to optimization in https://github.com/opencv/opencv/pull/29267.
## Context:
When detecting inverted markers, we call `_getBorderErrors` twice:
- `int borderErrors = _getBorderErrors(cellPixelRatio, ...);`
- `Mat invCellPixelRatio = 1.f - cellPixelRatio;`
- `int invBError = _getBorderErrors(invCellPixelRatio, ...);`
meaning:
1. Scan border cells once.
2. Allocate a new Mat.
3. Invert the entire `cellPixelRatio` matrix, not just the border.
4. Scan border cells again on the inverted matrix.
5. If inverted marker is better, copy the full inverted matrix back
## Solution
only call `_getBorderErrors` once and compute both
- borderErrors: `cellPixelRatio > validBitIdThreshold`
- invBorderErrors: `1 - cellPixelRatio > validBitIdThreshold`
This saves:
1. full invert into temporary Mat: (`Mat invCellPixelRatio = 1.f - cellPixelRatio;`)
2. scan temporary border: the second `_getBorderErrors`
3. copy temporary Mat back into `cellPixelRatio`: `invCellPixelRatio.copyTo(cellPixelRatio);`
Note that the solution does not implement:
```
if(params.detectInvertedMarker) {
_getBorderErrorsBoth(...);
} else {
borderErrors = _getBorderErrors(...);
}
```
because the extra cost to computing invBorderErrors: `if(1.f - ratio > validBitIdThreshold) invBorderErrors++;` is negligible. this also avoids having to maintain two functions: `_getBorderErrorsBoth` and `_getBorderErrors`
## Tests:
No visible results when testing the full marker detection pipeline because this step is not expensive. There is a roughly 8% noise when re-running the marker detections making it hard to spot small speed diffs.
When testing only this specific step with a float matrix of size: `(markerSize + 2*border)^2` on a AMD Ryzen 7 (8 cores / 16 threads):
- The new code is 30-45× faster at this stage depending on the marker size and whether the candidate was actually an inverted one, saving ~530-580 ns per candidate, mainly because we removed `Mat invCellPixelRatio = 1.f - cellPixelRatio`
- The new code is equivalent when detecting non-inverted markers +/- 3 ns
---
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [ ] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake
doc: remove duplicated bib #29298
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake
Fix speed regression in Aruco identify #29267
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake
Update BarcodeDetector super-resolution API to use single-file ONNX #29227
### Pull Request Readiness Checklist
This PR updates the `BarcodeDetector` super-resolution API to support and utilize a single-file ONNX model format.
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
[OpenCV 5] Fix apriltag corners order and update the doc #28823
I have updated documentation for the AprilTag dictionaries.
Corresponding issues:
- https://github.com/opencv/opencv-python/issues/1195
- https://stackoverflow.com/questions/79044142/why-is-the-order-of-the-incoming-corners-different-between-apriltag-and-aruco-ma
This is a breaking change and is targeted only for OpenCV 5.
---
I have updated the ArUco doc with more information about fiducial markers detection.
I have tried to add some recommendations, best practices:
- `DICT_ARUCO_MIP_36h12` should be the recommended family, [see](https://stackoverflow.com/a/51511558)
- link to download pregenerated markers for `MIP_36h12` is [here](https://sourceforge.net/projects/aruco/files/. I have not found some other official links for the other ArUco family, but since `MIP_36h12` should be used, I guess it is fined.
- recommendation to have a white border when printing the marker
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
Caffe importer cleanup #28678
Merge with: https://github.com/opencv/opencv_extra/pull/1324
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
- [x] The feature is well documented and sample code can be built with the project CMake
Fixed the new chessboard detector by not using OpenCL #29211
This should hopefully fix test failures on macOS x64 builder in the latest 5.x branch.
The code of Chessboard detector (namely, the FastX part) runs tons of different-size box filters on the same image. Optimally, those filters need to be computed all together using once-computed integral image, but instead those multiple box filters, especially given how the current opencl path in box filter is organized, seem to 'overload' our OpenCL cache system and it breaks, at least on macOS. Given that boxfilter is relatively cheap operation, it will unlikely loose much by running on CPU vs GPU. So this is the current solution - switch to CPU path there. Local tests show that even on Apple M4 Max with very fast GPU we get better execution speed on CPU than on GPU.
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [ ] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake
Homogeneize some calib/3d behavior #29077
- use CV_Check to validate input sizes (thus throwing for invalid inputs)
- return bool to validate a function result
This fixes#22746
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
Moved geometry transformations from imgproc to 3d, future geometry module #29101
The first step of 2d geometry operations migration to the future geometry module.
I created 2d.hpp to isolate the moved functions for now. I propose to create geometry.hpp when the module is renamed and include all things there.
OpenCV contrib: https://github.com/opencv/opencv_contrib/pull/4126
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [ ] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake
Migrated chessboard and circles grid detectors to objdetect #28804
OpenCV Contrib: https://github.com/opencv/opencv_contrib/pull/4125
OpenCV Extra: https://github.com/opencv/opencv_extra/pull/1375
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [ ] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake
Update ArUco doc #28824
See https://github.com/opencv/opencv/pull/28823
Update of the ArUco doc but targeted for OpenCV 4.
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
objdetect(aruco): fix maxCorrectionBits in predefined dictionaries #29034
This PR fixes the bugs in the creation of some dictionaries and standarizes its construction.
## Bugs
1. **DICT_ARUCO_MIP_36h12_DATA** was incorrectly assigned `maxCorrectionBits=12`, which is the intermarker distance. This was causing a high rate of false positives during detection, which is a significant problem.
2. **APRILTAG** dictionaries were incorrectly created with `maxCorrectionBits=0`, making it impossible to do error correction.
## Solution
Given a intermarker distance X, the correct `maxCorrectionBits = X/2 - 1`. Thus, standardize the construction of Dictionaries as such.
objdetect: clear stale outputs in CharucoDetector::detectDiamonds #28818
## Summary
- clear `diamondCorners`/`diamondIds` outputs at the beginning of `CharucoDetector::detectDiamonds`
- prevent stale detections from previous calls when the current call has fewer than 4 markers or finds no diamonds
- add a regression test that pre-fills outputs, calls `detectDiamonds` with 3 markers, and verifies outputs are empty
Fixes#28783.
## Testing
- built `opencv_test_objdetect` locally
- ran `opencv_test_objdetect --gtest_filter=Charuco.detectDiamondsClearsOutputsWithLessThanFourMarkers`
- result: PASS
Block layout-based convolution in DNN #28585
merge together with https://github.com/opencv/opencv_extra/pull/1321
Some core parts of the new engine in DNN module have been revised substantially:
1. all tests seem to pass, except for `Test_Graph_Simplifier.ResizeSubgraph`, which has been disabled because it does not take the newly added `TransformLayoutLayer` into account. The test should be reworked perhaps.
1. convolution and related operations (maxpool/avgpool) now use so-called block layout (`DATA_LAYOUT_BLOCK`), where `NxCxHxW` tensors are represented as `NxC1xHxWxC0`, where `C1=(C + C0-1)/C0` and `C0` is a power-of-two (usually 4, 8, 16 or 32).
1. graph is now pre-processed and `TransformLayoutLayer` is inserted to convert data from NCHW or NHWC layout to the block layout or vice versa. The transformations are done in a lazy way only when they are really needed. For example, in the whole Resnet only 2 transformations are performed.
1. transformer-based models and other models that do not use convolutions will run as usual, without going to block layout.
1. there is yet another graph preprocessing stage added that embeds constant weights/scale and bias into convolution and batch norm layers.
1. 'batchnorm', 'activation' and 'adding a residual' are now fused with convolution, just like in the old engine. That brings some noticeable acceleration.
1. optimized convolution kernels have been added.
* depthwise convolution, as well as maxpool and avgpool support C0=4, 8, 16 etc. _as long as_ C0 is divisible by the number of fp32 lanes in a SIMD register of the target platform (e.g. on ARM with NEON there must be `C0 % 4 == 0`, on x64 with AVX2 `C0 % 8 == 0`).
* non-depthwise convolution only supports C0=8 for now. C0=8 seems to be a sweetspot for ARM with NEON, x64 with AVX2 or RISC-V with RVV (with 128- or 256-bit registers). For some platforms with dedicated matrix accelerators C0=16 or even C0=32 might be more efficient, but we could add the respective kernels later.
* only fp32 kernels have been added. fp16/bf16 kernels might be added a little later.
### Pull Request Readiness Checklist
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
- [x] Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake
Identify ArUco markers based on threshold to reduce false positives #28289
**Goal:** parametrize the current marker identification process (pixel-based majority count) to reduce the number of false positives while maintaining high recall. Useful in high risk scenarios in which false positives are not acceptable.
**Context:** This PR builds on top of https://github.com/opencv/opencv/pull/23190 in which we've introduced a pixel-based confidence in the marker detection.
**Solution:** Include a new parameter: `validBitIdThreshold` used to identify markers based on the pixel count of each cell. Set the parameter default either to 50% which is equivalent to the current majority count implementation or to 49% which already singnificantly reduces the number of false positives (see details below).
**Test coverage:**
- Unit tests: `CV_ArucoDetectionThreshold`, `CV_InvertedArucoDetectionThreshold`
- The impact of `validBitIdThreshold` on false positives was also tested using the benchmark dataset: `MIRFLICKR-25k` https://www.kaggle.com/datasets/skfrost19/mirflickr25k which contains random images without any markers. Every marker detection is a false positive.
Example of images in the dataset:


**Results:** A threshold of 49% already allows to significantly reduce the number of false positives for the dict `DICT_4X4_1000`:
- `5942` false positives for `validBitIdThreshold = 0.5`
- `629` false positives for `validBitIdThreshold = 0.49` and `0.46`
- number of false positives divided by `9.5` when compared to `validBitIdThreshold = 0.5`
- `139` false positives for `validBitIdThreshold = 0.43` and `0.4`
- number of false positives divided by `42` when compared to `validBitIdThreshold = 0.5`
Dicts with a higher number of cells are not as impacted since it's much harder to obtain false positives. However, the less cells in a marker the further away it can be reliably detected, so the dict `DICT_4X4_1000` is commonly used.
<img width="1280" height="800" alt="false_positive_image_rate" src="https://github.com/user-attachments/assets/1a0ee16a-221d-443e-835b-022ed6dea6b0" />
In the image attached, the values of `validBitIdThreshold` tested are: `0.10f, 0.20f, 0.30f, 0.40f, 0.43f, 0.46f, 0.49f, 0.50f, 0.53f, 0.56f, 0.60f, 0.70f, 0.80f, 0.90f`
Summary of the results: [summary.csv](https://github.com/user-attachments/files/24315662/summary.csv)
Note that we can also analyse the number of false positives per marker `id`. For example, here's the histogram for the dict `DICT_4X4_1000`. (The CSV attached contains all the results)
<img width="1440" height="640" alt="false_positive_ids_DICT_4X4_1000_thr0 50" src="https://github.com/user-attachments/assets/af4f3ff8-9b8f-4682-9d51-a090c2610d8c" />
For example, the marker id 17 is detected 252 times with `validBitIdThreshold = 0.5` and only 34 times with `validBitIdThreshold = 0.49`. Looking at marker 17 (see below), we understand that this simple pattern randomly occurs in images.
<img width="447" height="441" alt="Marker17" src="https://github.com/user-attachments/assets/f5d09227-b39b-4598-94f9-b529f8300703" />
Results for every dict and every `validBitIdThreshold` [per_id.csv](https://github.com/user-attachments/files/24315667/per_id.csv)
**Missing coverage:** there is no labeled dataset with images containing markers to analyse the impact of on the recall (i.e. look at the true positive rate). For my specific use case (drones) any threshold above `0.4` allows to maintain a high recall in all conditions.
### Pull Request Readiness Checklist
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [ ] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake
Fix ~0.5px systematic offset in CharucoDetector subpixel refinement #28380Resolves#25539
### Problem
`CharucoDetector::detectBoard` produces Charuco corner coordinates that are consistently offset by approximately **+0.5 pixels** compared to `findChessboardCorners + cornerSubPix`.
This offset is systematic (mean ≈ −0.5 px when comparing legacy − Charuco) and reproducible across images. Visual inspection also shows that the legacy chessboard detector aligns better with the actual corner locations.
### Root cause
In `charuco_detector.cpp`, the points passed to `cornerSubPix` are manually shifted by `-Point2f(0.5f, 0.5f)` before refinement and then shifted back by `+Point2f(0.5f, 0.5f)` after refinement.
However, `cornerSubPix` refines corners in **absolute image coordinates** and converges to the true saddle point based on image gradients. Shifting the initial guess does not affect the converged result as long as the true corner lies within the refinement window.
The additional `+0.5` shift applied after refinement therefore introduces a constant bias, resulting in:
```
P_out = P_true + 0.5
```
### Solution
Remove the manual `±0.5` coordinate shifts around the `cornerSubPix` call and let the refined result be returned directly.
### Test updates
Updated expected corner values in the following tests:
- `testBoardSubpixelCoords`
- `testSeveralBoardsWithCustomIds`
The previous expected values (e.g. `200`, `250`, `300`) were only correct due to the +0.5px bias introduced by the bug.
`generateImage` creates checkerboard squares of exactly **50 pixels**, which places true corner locations on **pixel boundaries** rather than pixel centers. As a result, the correct subpixel coordinates are:
```
199.5, 249.5, 299.5
```
instead of the previously expected integer values.
After updating the expected values, all **30 Charuco-related tests pass** with the fix applied.
### Verification
I verified the fix using a Python reproducer that compares `CharucoDetector` output against `findChessboardCorners + cornerSubPix`:
- **Before fix:** mean error ≈ −0.501 px


- **After fix:** mean error ≈ −0.001 px


After the change, the Charuco detector output aligns with the legacy chessboard detector both numerically and visually.
### Notes
This change only affects the post-refinement coordinate handling and does not alter detection logic, refinement parameters, or performance.
See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake
docs: fix spelling errors in documentation and code #28301
- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
- [ ] The feature is well documented and sample code can be built with the project CMake
### Description
Fixed multiple spelling errors across documentation, comments, and code:
- 'colummn' → 'column' (cublas.hpp, 3 occurrences)
- 'points_per_colum' → 'points_per_column' (calib3d.hpp, 3 occurrences)
- 'Asignee' → 'Assignee' (sift files, 2 occurrences)
- 'compability' → 'compatibility' (face.hpp, 2 occurrences)
- 'orignal' → 'original' (aruco_detector.cpp)
- 'refrence' → 'reference' (chessboard.cpp)
- 'indeces' → 'indices' (stitching.hpp)
- 'OutputPrecison' → 'OutputPrecision' (test)
- 'tranform' → 'transform' (slice_layer.cpp, 3 occurrences)
Total: 24 fixes across 14 files. Documentation and comment changes only, no functional impact.
Precompute X values in Forney algorithm to eliminate redundant gfPow calls.
Previously, gfPow(2, ...) was computed multiple times for the same error
location across different loop iterations, resulting in O(L²) redundant
Galois field arithmetic operations.
This change:
- Precomputes all X values once before the main loop
- Reduces complexity from O(L²) to O(L) for X value computations
- Removes the TODO comment at line 1642
- No functional changes, only performance improvement
The optimization is most beneficial when there are many error locations
in QR codes (larger L values).