docs(readme): beginner onboarding — pip quick-start, troubleshooting, metadata fixes - #236
Conversation
… metadata fixes Lower the barrier for first-time users (especially Python): - Add a "Python wrapper (pybgs) via pip" quick-start: `pip install pybgs` (+ the `bgslibrary` twin), a minimal runnable example, links to demo.py/demo2.py, and an IMPORTANT note on the two common traps — pip builds from source (needs a compiler + OpenCV dev) and the available algorithms depend on the *compiled* OpenCV (no DP*/T2F* on OpenCV >= 4; gate with `hasattr`, not `cv2.__version__`). - Add a Troubleshooting section covering the three most common beginner failures. - Fix stale/contradictory metadata: version 3.3.0 -> 3.3.1, and the license badge (was "GPL v3" alt text linking to GPL while the project is MIT) -> MIT consistently.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the library version to 3.3.1 in the README, adds documentation and a minimal usage example for installing the Python wrapper (pybgs) via pip, and includes a troubleshooting section. The review feedback suggests removing an unused numpy import from the Python snippet and masking the cv2.waitKey return value with 0xFF to ensure cross-platform compatibility.
| import numpy as np | ||
| import cv2 | ||
| import pybgs as bgs |
There was a problem hiding this comment.
The numpy import is unused in this minimal usage example. Removing it keeps the quick-start snippet as clean and focused as possible.
| import numpy as np | |
| import cv2 | |
| import pybgs as bgs | |
| import cv2 | |
| import pybgs as bgs |
| cv2.imshow("frame", frame) | ||
| cv2.imshow("foreground", fg_mask) | ||
| cv2.imshow("background", bg_model) | ||
| if cv2.waitKey(10) == 27: # Esc to quit |
There was a problem hiding this comment.
On some platforms (such as 64-bit systems), cv2.waitKey() can return a value where the higher bits are set. Masking the return value with 0xFF ensures cross-platform compatibility and aligns with the implementation in demo.py and demo2.py.
| if cv2.waitKey(10) == 27: # Esc to quit | |
| if cv2.waitKey(10) & 0xFF == 27: # Esc to quit |
- Drop the unused `import numpy as np` from the minimal usage example (pybgs initializes the numpy C-API itself; the Python-level import isn't needed). - Mask cv2.waitKey with 0xFF (`cv2.waitKey(10) & 0xFF == 27`) for cross-platform correctness on 64-bit systems, matching demo.py/demo2.py.
…ilds BGSLibrary bundles pybind11 as a git submodule, but many users `git clone` without `--recursive` and then hit a missing-submodule failure when building the Python wrapper from source (Pixi `build_python` or CMake with BGS_PYTHON_SUPPORT). Add a "Building from source? Clone with submodules" step at the top of the install instructions showing `git clone --recursive` and the `git submodule update --init --recursive` recovery, and note that `pip install pybgs` does not need it (the PyPI sdist bundles pybind11). Also nudge the Pixi clone step to mention the recursive clone.
1 participant
What
Beginner-onboarding improvements to the README — README-only, no code changes.
The README led with the C++/source build and offered no
pip install pybgspath for Python users (the largest audience), and carried a couple of stale/contradictory badges.Changes
pybgs) via pip" quick-start at the top of the install section:pip install pybgs(+ thebgslibrarytwin), a minimal runnable example (mirrorsdemo.py'sapply/getBackgroundModel), links todemo.py/demo2.py+ the Python examples repo, and anIMPORTANT note on the two classic traps:
opencv-python— noDP*/T2F*onOpenCV ≥ 4; gate with
hasattr(bgs, …), nevercv2.__version__(the exact pitfall reported in past issues).AttributeErrorforDP*/T2F*;numpy 2.xvsopencv-python 3.4.x).3.3.0→3.3.1; license badge was contradictory (alt text "GPL v3"linking to GPL-3.0 while the project is MIT) → now MIT consistently.
Notes
The Pixi "Recommended" build section is unchanged (it remains the most reliable path for users without a
system OpenCV). No source/CI changes; the build matrix runs only because there are no path filters.
🤖 Generated with Claude Code