OpenCV Python API docs

For a long time, OpenCV’s Python bindings have been solely documented through the C++ Doxygen API docs. cv2’s API is not exactly the same as the C++ API, as it’s bridged to NumPy rather than using cv::Mat and similar types. It also isn’t trivial to build documentation for cv2 using the normal Python tools, as the docstrings are written in Doxygen rather than reStructuredText. I wrote a tool to parse these docstrings and use the Python ast module to parse the type stubs (*.pyi files) which document the types of the attributes and functions. You can find that code here: GitHub - ethanc8/opencv-doc-parser

Using this tool, I’ve started some work-in-progress API docs for cv2. So far, I have docs for cv2.aruco here: cv2.aruco - OpenCV Python API 4.9.0 documentation

Once I can parse all the docstrings into working documentation, I’ll look into trying to use parts of pgi-docgen to make the documentation easier to browse, like pgi-docs is.

[I also started a thread on ChiefDelphi:]

I hope you didn’t miss the Python signatures that are already written in the docs.

They just lack type annotations. Which isn’t much of a problem. The Python/C++ mapping is very regular.

hmm, just saying, there will be no such module in upcoming 5.x
(keeping this up-to-date (manually !) will require super-human effort …)

maybe rather inquire, how those get there

(keeping this up-to-date (manually !) will require super-human effort …)

Currently, the only part that needs to be done manually is listing out the names of the modules that we want to document. Even then, we can easily automate that part.

I’m already parsing the function docstrings into mostly-working documentation. Cross-references within the briefs and descriptions are currently still using the C++ names, and are not being detected, but other than that it’s working fine.

A bigger issue is the classes and constants. For some reason, the classes do not have docstrings (I don’t know how to fix that), while Python doesn’t support adding docstrings to constants. Also, the enums in OpenCV’s C++ API are imported into Python as normal constants, which means that it’s a bit annoying to document them as enums so far.

The Python/C++ mapping is not very well documented, and there are types in OpenCV’s C++ API that I could never figure out the Python equivalent. I think I ran into this with cv::SparseMat. Also, I think that the idea of requiring users to use NumPy rather than cv::Mat and such was already a bad idea, since not only was the NumPy-to-OpenCV C++ mappings not well-documented, but cv::Mat etc had features that NumPy’s matrices didn’t.

it’s the other way around. numpy arrays can represent basically everything that a cv::Mat can, but cv::Mat can’t represent some numpy arrays. that is why the OpenCV bindings have to reject some numpy inputs, or copy them to make them contiguous (one of the requirements of cv::Mat).

nobody wants to use a “cv::Mat” type in Python. that thing used to exist. it was a war crime. don’t bring that back. if you try, I’ll make sure you stand trial in The Hague.

Same goes for all (!!!) the little throwaway structs and whatnot, which merely hold a small list of things. Those do not need to be represented in Python.

structs that hold a dozen parameters may be a good idea to “be a thing”, but mostly for autocompletion.

if you want to improve OpenCV, survey existing C++/Python mapping libraries and evaluate them.

and you should take your enthusiasm to opencv’s github. that’s where development happens, and where issues/features are discussed. on this forum, you can get help with many things but not with architectural overhauls of OpenCV.