Repository: opencv
Issue: opencv-python tutorials: mention "pip install opencv-python"
Labels: category: documentation

### Describe the doc issue

https://docs.opencv.org/4.x/da/df6/tutorial_py_table_of_contents_setup.html

This subtree does not once mention `pip install opencv-python`, which works on all popular platforms, and all platforms mentioned currently (Windows, two Linux distros).

Instead, newbies are confronted with outdated steps to install binaries (sometimes manually!) or the agony of building a complex C++ library.

### Fix suggestion

Introduce a new article, in first or second position of this subtree. Focus on getting newbies started with the **current** best practice: `pip install opencv-python`, with whatever required variations:
- options: contrib, headless
- brief discussion of deviating steps on different OSes, perhaps how to get Python in the first place, where applicable:
  - Linux: `pip3 install ...`, `... install --user`, ...
  - Windows: Python installer, perhaps explain [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/) or perhaps not...
  - MacOS?
  - Raspberry Pi, very popular with newbies

Perhaps discuss `venv` or `virtualenv`. Warn about IDEs that might create and activate envs automatically, which can cause `opencv-python` to be installed in just an env (may be intended) or not be visible (because the env shields from everything installed in `site-packages`).

Look into and describe issues during `pip install` that might cause pip to attempt to build anything from source, including dependencies (numpy?). If that happens, user ought to stop and reevaluate. The binary packages on PyPI are supposed to cover all the major platforms, so something must have gone seriously wrong or the user is doing something they're not equipped to handle. One way to get this issue is trying to install an outdated package of opencv-python (no [`abi3` forward compat](https://docs.python.org/3/c-api/stable.html#stable-application-binary-interface) yet) with a newer Python that didn't exist then. I've seen this in more than one context. It may also happen on some strangely set up Raspberry Pies.

Revise existing content of this subtree without scruples. At the very least, warn prominently and unmistakably that those articles are hopelessly outdated and also absolutely not required to get OpenCV for Python. Don't hesitate to rewrite, or delete without replacement, entire paragraphs or articles.

Remove or severely deemphasize:
- Outdated technical information, specifically mentions of Python 2 and OpenCV 2 (and 3)
- Anything that might still work but isn't _the_ way to do it these days
  - Downloading the prebuilt C++ library and copying `cv2.pyd` and DLLs around? Maybe keep mention of this, better not.
  - Using `yum` or `apt` may be mentioned after `pip install`, but clearly marked as not recommended. Those packages don't enjoy the level of maintenance and prompt releases that `opencv-python` enjoys.
- Information of purely historical relevance
  - Who did what in 2013 in the context of a GSoC
  - Historical recap of OpenCV, which likely exists already at a higher level in the docs and can just be linked to from an introductory paragraph.

Push any and all _build_ instructions and mentions of such out of the first articles, which are likely to be read by newbies. Newbies should not accidentally snap to the conclusion that they need to build anything.

Screenshots are great. They can convey at a glance what would otherwise take entire paragraphs. Use them redundantly to textual descriptions. The reader ought to get to a working "hello world" from either just reading the article or just emulating the screenshots.

You decide what you consider a working "hello world". `cv.samples.findFile("lena.jpg")` will probably not work with the python package (I've got my env vars set so that it does, and I keep the extra data around). Trying to access a webcam will probably work but not always. Fallback could be a drawing from code (bunch of lines/rectangles/...). `imshow()` is likely to work, and so is `imwrite()`. Or keep it brief and stick to `import cv2 as cv; print(cv.__version__)`

I think this might be a good first issue. It requires some existing experience with OpenCV on Python. Writing ability may be supplemented by AI, if that is thoroughly checked.