Is it a bug of design of OpenCV's function "pyrDown"

Question

I see the declaration of pyrDown:

CV_EXPORTS_W void pyrDown( InputArray src, OutputArray dst,
                           const Size& dstsize=Size(), int borderType=BORDER_DEFAULT );

so I assume the 3rd parameter dstsize could be something like: Size(src.cols/4, src.rows/4. But as the docs says:

in any case, the following conditions should be satisfied:

so only the default size Size((src.cols+1)/2, (src.rows+1)/2) is legal. Then why the parameter dstsize being needed? It seems so useless...

Here I find a similar question post:

http://answers.opencv.org/question/25281/pyrup-only-for-doubling-size/

and @berak commented there:

pyramids only work in powers of 2

while I think pyramids only work in power ONE of 2, is that true?

Answer 1

In English: When the width/height of the src is odd such as 2*x+1 , then when use pyrDown the half will be (x+0.5), the default method to deal with such a situation is ceil it, this is Size((src.cols+1)/2, (src.rows+1)/2), but we can also floor it by set dstsize.

In Chinese: (当图片边长是奇数时，折半后有 0.5 的小数，默认是向上取整，可以设置dstsize来向下取整）。

Here is an image with shape of (183, 275, 3).

Then let's test pyrDown in Python, there are four possible dstsizes:

>>> img = cv2.imread(fname)
>>> img.shape
(183, 275, 3)
>>> img1 = cv2.pyrDown(img)
>>> img1.shape  # the default size is `Size((src.cols+1)/2, (src.rows+1)/2)`
(92, 138, 3)
>>> img2 = cv2.pyrDown(img, dstsize=(137, 91))
>>> img2.shape
(91, 137, 3)
>>> img3 = cv2.pyrDown(img, dstsize=(137, 92))
>>> img3.shape
(92, 137, 3)
>>> img4 = cv2.pyrDown(img, dstsize=(138, 91))
>>> img4.shape
(91, 138, 3)

Note:

shape: (h,w,c)
Size:  (w,h)