Opencv-python: Where is documentation?

[wvxvw]

After much searching, I found this: https://opencv-python-tutroals.readthedocs.io/en/latest/ It says it's abandoned. The C++ documentation doesn't seem to include anything meaningful about this package (it only tells you how to build Python bindings).

PyPI page dedicated to this package only has the title "Documentation for opencv-python", but there's nothing there. Does the documentation even exist?

[sergregory]

Actually, the C++ documentation at docs.opencv.org includes the Python function name with all the parameters for each of the C++ functions that are exported to python module (absolute majority of OpenCV functionality is exported to Python bindings). For example, look here: https://docs.opencv.org/4.5.3/d7/dfc/group__highgui.html#ga0f11fad74a6432b8055fb21621a0f893

Another handy option that I personally use a lot is offline docs browsing the Zeal/Dash - https://zealdocs.org/. They have both C++ and Python docsets for OpenCV (generated just the same way as official docs @ docs.opencv.org do it)

[wvxvw]

It's not really useful... Let me put it in the context: I'm writing documentation for a Python function that should take a cv2.Image and return a cv2.Image. So, I vaguely know that cv2.Image is a wrapper for Mat C++ class, but, it's not really what's returned or taken. Most opencv-python users would have no idea what I'm talking about if I tell them I want Mat as an input.

And, obviously, I'm not interested in offline solutions... I want to be able to cross-reference the documentation from the one I generate for my code. Since I understand Sphinx is no longer used by OpenCV, then intersphinx is out of the question, but there's still an option for extlinks, where I could set up the documentation to direct the reader to the OpenCV documentation. Unfortunately, there's none for Python bindings. The fact that some entities are accidentally mentioned within C++ documentation is absolutely of no use, as the users of such documentation wouldn't know how to import those, what are actually the types of arguments and return values the functions need / produce etc.

[abhiTronix]

Since I understand Sphinx is no longer used by OpenCV, then intersphinx is out of the question, but there's still an option for extlinks, where I could set up the documentation to direct the reader to the OpenCV documentation. Unfortunately, there's none for Python bindings.

@wvxvw Nope, Actually OpenCV-Python documents available from OpenCV devs on there website itself: https://docs.opencv.org/master/d6/d00/tutorial_py_root.html. Please check docs before creating issue anywhere.

[sergregory]

Well, now I'm confused.. AFAIK there is no such thing as cv2.Image. All the C++ functionality is written around cv::Mat, but when we switch to the Python world, all Python bindings expect numpy arrays where C++ functions expect cv::Mat. And this is what all opencv-python users expect (again, to the best of my knowledge) - provide numpy array as input and get output from opencv-python as numpy array (where it is suitable).

There is an initiative on adding typing to Python bindings that is part of this year's google summer of code. You cna track the progress here: https://github.com/opencv/opencv/pull/20370

[wvxvw]

@abhiTronix That is not documentation. That is examples with some free-form prose. When I write "documentation" I mean "list of classes, methods, their arguments, variables" and so on, whatever's applicable. Read the comment you replied above before making assumptions.

@sergregory cv2.Image is a made-up thing. The problem is nobody knows what it returns in Python. By trial and error, I can tell that it's sometimes numpy.ndarray, sometimes None, but, maybe in some other circumstances it's something else, and there's no way to tell. You don't have any documentation that tells what it should return.

Anyways, it's a pointless discussion. You don't have and don't publish documentation. End of story. Why are you trying to tell me otherwise is beyond me. It's OK if you dont'. Kind of upsetting, but whatever really. It's your business if you want to do that or not.

[abhiTronix]

@abhiTronix That is not documentation. That is examples with some free-form prose. When I write "documentation" I mean "list of classes, methods, their arguments, variables" and so on, whatever's applicable. Read the comment you replied above before making assumptions.

@wvxvw Ignorance is bliss. I quoted the section of your comment you made and then answered it. Also, Have you tried opening any of those examples? It contains explanation for importing and its usage and highlighted links to OpenCV function/method used in that example.

Moreover, Python binding is just like C++ with few changes like how arrays are handled, any beginner can easily understand them.

[wvxvw]

Ignorance is bliss.

yeah, you have plenty of bliss. Lol. Why are you telling me about it? Learn to read dude.

[abhiTronix]

real _know-it-all_