docs(imgproc): correct the documented Sobel kernel size range - #30661
## Problem
`cv::Sobel` and `cv::getDerivKernels` document the kernel size as
> `@param ksize size of the extended Sobel kernel; it must be 1, 3, 5, or 7.`
> `@param ksize Aperture size. It can be FILTER_SCHARR, 1, 3, 5, or 7.`
but `getDerivKernels` (modules/imgproc/src/deriv.cpp) actually enforces a different constraint:
```cpp
if( _ksize % 2 == 0 || _ksize > 31 )
CV_Error( cv::Error::StsOutOfRange, "The kernel size must be odd and not larger than 31" );
```
so every odd size up to 31 is accepted, and `FILTER_SCHARR` (-1) selects the 3x3 Scharr kernels.
Reproduced with opencv-python-headless 5.0.0:
```
getDerivKernels(1, 0, 9) -> OK, 9-tap kernel
getDerivKernels(1, 0, 15) -> OK, 15-tap kernel
getDerivKernels(1, 0, 31) -> OK, 31-tap kernel
getDerivKernels(1, 0, 33) -> error: "The kernel size must be odd and not larger than 31"
getDerivKernels(1, 0, -1) -> OK (Scharr 3x3)
cv2.Sobel(img, cv2.CV_32F, 1, 0, ksize=9/15) -> OK
cv2.Sobel(img, cv2.CV_32F, 1, 0, ksize=101) -> error (out of range)
```
## Change
Documentation-only: the two `@param ksize` entries now state the constraint the
implementation enforces (odd, not larger than 31) while keeping 1, 3, 5, 7 as the typical
choices. No code change.
Signed-off-by: NUAAwqy <162230229@nuaa.edu.cn>
docs(imgproc): medianBlur also accepts ksize = 1 - #30662
## Problem
`cv::medianBlur` documents the aperture as
> `@param ksize aperture linear size; it must be odd and greater than 1, for example: 3, 5, 7 ...`
but the implementation only requires an odd size: the aperture check is
`(ksize % 2 == 1) && (_src0.dims() <= 2)`, and `ksize = 1` is accepted and returns the image
unchanged (a 1x1 median is the pixel itself).
Reproduced with opencv-python-headless 5.0.0:
```
cv2.medianBlur(img, 1) -> OK, output is identical to the input
cv2.medianBlur(img, 2) -> error: "(ksize % 2 == 1) && (_src0.dims() <= 2)" in 'medianBlur'
```
## Change
Documentation-only: mention `ksize = 1` so the docs match the implemented behavior.
No code change.
Signed-off-by: NUAAwqy <162230229@nuaa.edu.cn>
libopencv_imgproc grew noticeably with the HarfBuzz-based text engine. Measured on
macOS/arm64 (clang, Release, stripped) the text-related part of the library was
~830 KB: HarfBuzz 486 KB, the two Rubik fonts 296 KB, the engine ~25 KB, plus ~2 MB
of WenQuanYi when WITH_UNIFONT=ON (the previous default). With GCC and an unstripped
.so on Linux the HarfBuzz part alone is 700+ KB.
This patch brings it down to ~550 KB by default (HarfBuzz 377 KB + Rubik 146 KB +
engine 30 KB) without dropping functionality:
* 3rdparty/harfbuzz: build with -Os -fno-exceptions -fno-rtti -fno-threadsafe-statics
(like HarfBuzz's own build; shaping speed is irrelevant thanks to the glyph cache)
and HB_NO_VAR_COMPOSITES (VARC table, a 2024 format with no real fonts yet).
Variable-font support (wght axis etc.) is untouched. -22% of HarfBuzz code.
* Only the "sans" font (Rubik) is compiled into imgproc by default. Rubik Italic and
WenQuanYi Micro Hei became optional: WITH_ITALICFONT (new) and WITH_UNIFONT are
both OFF now. The build summary lists the built-in fonts.
* New API cv::FontFace::setBuiltinFont(name, path) fills or replaces any of the
three built-in slots ("sans", "italic", "uni") with an external font file. The
registered font takes part in the automatic fallback chain exactly like a
compiled-in one, so users can get CJK text or a true italic without rebuilding
OpenCV. The registry is process-wide; each thread's engine reloads its slots
lazily (generation counter), and the glyph cache is dropped on reload since
hb_font pointers are part of its key.
* "italic" resolves to "sans" when no italic font is built in or registered, so
FONT_ITALIC / FONT_HERSHEY_SCRIPT_* in the legacy putText keep working (upright).
* Fix: a character not covered by any font used to be drawn as '?' taken from the
last built-in slot, which can be empty now; the '?' is looked up like any other
character (user font first).
* Tests: opencv_test_imgproc registers Rubik-Italic.ttf.gz and
WenQuanYiMicroHei.ttf.gz from opencv_extra (testdata/highgui/drawing) as the
"italic"/"uni" slots, so Drawing.ttf_text reproduces the reference picture 1:1
with the default build and the legacy hershey-font tests are unchanged.
Drawing.builtin_font_slots covers the new API. Tests skip if the fonts are absent.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Adds COLOR_BGR2Oklab, COLOR_RGB2Oklab, COLOR_Oklab2BGR, and
COLOR_Oklab2RGB to cvtColor, implementing Bjorn Ottosson's Oklab
perceptual color space (https://bottosson.github.io/posts/oklab/),
requested in #21760.
Scope for this first PR: CV_8U and CV_32F only (matching the existing
Lab/Luv precedent -- neither supports CV_16U either, likely for the
same reason: the cube-root nonlinearity doesn't lend itself to a
fixed-point integer fast path), plain scalar C++ (no SIMD, no OpenCL
kernel -- cvtColor's CV_OCL_RUN/CV_Assert machinery already falls back
to this CPU path cleanly for codes without an OpenCL case), and the
core RGB<->Oklab conversion only (not the Okhsv/Okhsl variants the
issue also mentions, which the issue itself calls secondary to the
"most directly important" Oklab conversion).
Encoding: CV_32F keeps Oklab's native range (L in [0,1], a/b roughly
in [-0.5,0.5] for in-gamut sRGB colors), matching how the reference
formulas and other tools (e.g. CSS Color 4's oklab()) represent it.
CV_8U scales L by 255 and offsets a/b by 128, mirroring CIE Lab's own
8-bit encoding shape.
Testing:
- The forward matrices were verified against an independent NumPy
reimplementation before writing any C++: round-trip identity over
20000 random RGB samples (~1.6e-6 max error), plus cross-checked
pure red/green/blue/white/black/gray against commonly-published
Oklab reference values -- matches to 6+ significant figures.
- New tests in test_color.cpp: reference-value cross-check (same
known values as above, now through the actual cv::cvtColor), a
channel-order check (COLOR_RGB2Oklab vs COLOR_BGR2Oklab on the same
logical pixels), float32 and uint8 round-trips, and alpha-channel
passthrough on the 4-channel inverse. All pass; verified the uint8
round-trip test actually exercises meaningful precision by comparing
its tolerance against CIE Lab's own established uint8 tolerance
(CV_ColorLabTest accepts up to 37 for the analogous case; this uses
32 for a still-meaningful, not looser, bound).
- Confirmed swapBlue() needed COLOR_BGR2Oklab/COLOR_Oklab2BGR added to
its explicit list -- its default (true) is correct for the RGB
variants by accident but wrong for the BGR ones, which would have
silently swapped red and blue. Caught by code review before testing,
then confirmed fixed via the channel-order test.
- Ran the full opencv_test_imgproc suite: no new failures (the same
360 pre-existing "missing opencv_extra test data" failures present
before this change, e.g. StackBlur/HoughCircles/ColorBayer, all in
unrelated files).
- Verified the UMat (OpenCL) path falls back to the CPU implementation
correctly (no OpenCL kernel is added in this PR).
- Added a perf test (cvtColorOklab) covering both directions, CV_8U
and CV_32F, at VGA/720p/1080p.
Natural follow-ups, intentionally left out of this first PR: SIMD/
fixed-point optimization (this is a plain scalar implementation),
Okhsv/Okhsl, and an OpenCL kernel.
Fix calibration tutorial docs, decomposeProjectionMatrix, and convertMaps performance claims #29487Fixes#25655, #26791, #27277.
Three doc fixes:
1. Calibration tutorial: rows/cols swapped, fixed np.mgrid consistency
2. decomposeProjectionMatrix: clarified transVect is camera center in homogeneous coordinates
3. convertMaps: replaced overstated 2x speed claim
### Pull Request Readiness Checklist
- [x] I agree to contribute under Apache 2 License
- [x] Not based on GPL/incompatible license
- [x] PR proposed to proper branch (4.x)
- [x] Reference to original bug report and related work
- [ ] Accuracy test, performance test, test data: N/A (doc-only)
- [x] Feature well documented and sample code buildable
Replace "static inline" by "inline" in headers #29453
This fixes#29436
I also replaced CV_INLINE which can be removed in a later PR.
I can make a similar PR for 4.x if you want.
### 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
Inverted imgproc-geometry dependency and moved more functions to geometry #29230
Fixes: https://github.com/opencv/opencv/issues/20267
Continues: https://github.com/opencv/opencv/pull/29175
OpenCV Contrib: https://github.com/opencv/opencv_contrib/pull/4137
OpenCV Extra: https://github.com/opencv/opencv_extra/pull/1377
Summary:
- LSD returned back to imgproc
- drawing functions moved to imgproc
- undistort image and related perf-pixel functions moved to imgproc
- moments moved to geometry
- estimateXXXtransform moved to geometry
After the patch the geometry module depends on code and Flann and may be used everywhere without potential circular dependencies
### 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
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
imgproc: add findTRUContours - lock-free parallel contour extraction #28773
Integrates the TRUCO algorithm (Threaded Raster Unrestricted Contour Ownership, @cite TRUCO2026) as a transparent fast path inside `cv::findContours`. No API change is required: existing code automatically benefits when `mode=RETR_LIST` and no hierarchy output is requested.
### How it works
When `mode=RETR_LIST` and the caller does not request hierarchy, `findContours` delegates to the TRUCO parallel engine instead of Suzuki-Abe. All ContourApproximationModes are supported; approximation is applied in parallel after extraction. In all other cases the original Suzuki-Abe path is used unchanged.
### Key design ideas
- Row-strip domain decomposition parallelised via `cv::parallel_for_`
- Start-point ownership rule + speculative downward tracing eliminate tile stitching and synchronisation primitives (lock-free)
- 8-bit state space instead of the 32-bit integer labeling required by Suzuki-Abe, giving higher SIMD throughput and lower memory-bandwidth pressure
- Paged contour buffer (`TRUCOPagedContour`) avoids heap reallocation on the hot tracing path
- SIMD-accelerated row scanning via `cv::v_uint8` intrinsics
- Thread count controlled globally via `cv::setNumThreads()`, consistent with OpenCV conventions
### Output correctness
Significant effort has gone into ensuring the output is identical to the original `findContours` in every respect: same contour set, same ordering, and same approximation results for all methods. A dedicated test suite (`test_contours_truco.cpp`) verifies exact match against Suzuki-Abe across all four `ContourApproximationModes` and thread counts from 1 to 39, using noise images, circles, nested rectangles, and mixed scenes.
### Performance vs. Suzuki-Abe (from submitted paper)
- single-thread: ~1.8–1.9× faster (8-bit SIMD advantage)
- 20 threads: ~14–20× faster on i7-13700H (6P+8E, 20T)
- 20 threads: ~10–12× faster on Xeon Silver 4510 (12C/24T)
### 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
- Change 'element' to 'kernel' in LaTeX formulas to match actual parameter name
- Fix erode() and dilate() function documentation (lines 2330, 2338, 2362, 2370)
- Fix MorphTypes enum documentation (MORPH_OPEN, MORPH_CLOSE, MORPH_GRADIENT, MORPH_TOPHAT, MORPH_BLACKHAT)
- Fix backtick formatting in dilate() documentation
Resolves#18095
docs(imgproc): clarify cv::moments behavior for degenerate contours #28227
relates to https://github.com/opencv/opencv/issues/28222
Clarifies that for degenerate contours (single point or collinear points),
cv::moments() returns m00 == 0 and centroid is undefined.
Documents common workarounds such as boundingRect center or point averaging.
Iterative Phase Correlation #28146
### 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
Added BitShift option to CLAHE #28014
Briefly, this PR is the fix of https://github.com/opencv/opencv/issues/28002
### 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
imgproc: add minEnclosingConvexPolygon #27369
### 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
Subdiv2d rect2f clean #27641
Closes https://github.com/opencv/opencv/issues/27623
Changes:
- Added Subdiv2D(Rect2f) constructor overload
- Added initDelaunay(Rect2f) method overload
- No changes to the previous implementation to keep it backward compatible
- Added tests for init and testing with edge case of extremely small coordinates
- [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
See original pull request at : https://github.com/opencv/opencv/pull/27631
Add HoughCirclesWithAccumulator binding #27389
### Pull Request Readiness Checklist
Fix#27377
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
Fix minAreaRect and boxPoints docs (#26799) #27139
As requested from issue #26799 the docs regarding minAreaRect and boxPoints are extended specifying the order of the corners for boxPoints and the way the angle is computed for the rotated rect returned by minAreaRect
Added optional mask to cv::threshold #26842
Proposal for #26777
To avoid code duplication, and keep performance when no mask is used, inner implementation always propagate the const cv::Mat& mask, but they use a template<bool useMask> parameter that let the compiler optimize out unnecessary tests when the mask is not to be used.
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