Positional Argument outImg Should Be Keyword Argument in cv2.drawMatches

[zhanwenchen]

System information (version)

• OpenCV => 4.0.1
• Operating System / Platform => MacOS 10.14 Mojave
• Compiler => XCode 10.1

Detailed description

The docstring says

drawMatches(...)
drawMatches(img1, keypoints1, img2, keypoints2, matches1to2, outImg[, matchColor[, singlePointColor[, matchesMask[, flags]]]]) ->

@param outImg Output image. Its content depends on the flags value defining what is drawn in the output image. See possible flags bit values below.

But it doesn't mention that passing None would actually eliminate the need to instantiate a placeholder image to draw on, which would otherwise be quite the task in itself - how would one even calculate the output size of a feature-matched pair of images with lines?

Either way, the actual behavior of the outImg positional argument is exactly what a Python kwarg is meant to do. Please implement this breaking change (breaking changes are necessary in software development).

See this StackOverflow thread for the confusion this has caused.

Steps to reproduce

import cv2
cv2.drawMatchesKnn(img1, kp1, img2, kp2, matches, None)

[alalek]

OpenCV is C++ library. Python bindings are generated from C++ code and these "docstring"s are come from C++ code. Including documentation.

"None" means that there is no pre-allocated output (like slice from larger numpy array).
I believe this function is fully usable.

Feel free to prepare patch with adding of documentation @note for Python users here.