Merge pull request #30661 from NUAAwqy:docs/deriv-kernel-size-range

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>
This commit is contained in:
bob
2026-11-09 20:15:14 +08:00
committed by GitHub
parent 2e0c9a44e6
commit 71babee383

View File

@@ -1215,7 +1215,7 @@ kernels are generated (see #Sobel). The filters are normally passed to #sepFilte
@param ky Output matrix of column filter coefficients. It has the type ktype .
@param dx Derivative order in respect of x.
@param dy Derivative order in respect of y.
@param ksize Aperture size. It can be FILTER_SCHARR, 1, 3, 5, or 7.
@param ksize Aperture size. It can be FILTER_SCHARR, or an odd number not larger than 31 (1, 3, 5, and 7 are the typical choices).
@param normalize Flag indicating whether to normalize (scale down) the filter coefficients or not.
Theoretically, the coefficients should have the denominator \f$=2^{ksize*2-dx-dy-2}\f$. If you are
going to filter floating-point images, you are likely to use the normalized kernels. But if you
@@ -1544,7 +1544,7 @@ The second case corresponds to a kernel of:
8-bit input images it will result in truncated derivatives.
@param dx order of the derivative x.
@param dy order of the derivative y.
@param ksize size of the extended Sobel kernel; it must be 1, 3, 5, or 7.
@param ksize size of the extended Sobel kernel; it must be odd and not larger than 31 (1, 3, 5, and 7 are the typical choices).
@param scale optional scale factor for the computed derivative values; by default, no scaling is
applied (see #getDerivKernels for details).
@param delta optional delta value that is added to the results prior to storing them in dst.