bgslibrary

# BGSLibrary: A Background Subtraction Library [](https://opensource.org/licenses/MIT) [](https://github.com/andrewssobral/bgslibrary/wiki/Build-status) [](https://github.com/andrewssobral/bgslibrary/wiki/Build-status) [](https://github.com/andrewssobral/bgslibrary/wiki/Build-status) [](https://github.com/andrewssobral/bgslibrary/wiki/List-of-available-algorithms) [](https://deepwiki.com/andrewssobral/bgslibrary)

## Introduction The **BGSLibrary** (Background Subtraction Library) is a comprehensive C++ framework designed for background subtraction in computer vision applications, particularly for detecting moving objects in video streams. It provides an easy-to-use and extensible platform for researchers and developers to experiment with and implement various background subtraction techniques. ## Library Version **3.3.1** (see **[Build Status](https://github.com/andrewssobral/bgslibrary/wiki/Build-status)** and **[Release Notes](https://github.com/andrewssobral/bgslibrary/wiki/Release-notes)** for more info) ## Background and Development The BGSLibrary was developed in early 2012 by [Andrews Cordolino Sobral](http://andrewssobral.wixsite.com/home) as a C++ framework with wrappers available for Python, Java, and MATLAB. It aims to facilitate foreground-background separation in videos using the OpenCV library. ## Compatibility The library is compatible with OpenCV versions 2.4.x, 3.x, and 4.x. It can be compiled and used on Windows, Linux, and Mac OS X systems. ## Licensing The library's source code is available under the [MIT license](https://opensource.org/licenses/MIT), making it free for both academic and commercial use. ## Getting started * [List of available algorithms](https://github.com/andrewssobral/bgslibrary/wiki/List-of-available-algorithms) * [Algorithms benchmark](https://github.com/andrewssobral/bgslibrary/wiki/Algorithms-benchmark) * [Which algorithms really matter?](https://github.com/andrewssobral/bgslibrary/wiki/Which-algorithms-really-matter%3F) * [Library architecture](https://github.com/andrewssobral/bgslibrary/wiki/Library-architecture) ``` … ``` ### Installation instructions You can either install BGSLibrary via [pre-built binary package](https://github.com/andrewssobral/bgslibrary/releases) or build it from source. **Building from source? Clone with submodules.** BGSLibrary bundles `pybind11` as a git submodule (used by the Python wrapper), so clone recursively: ```bash git clone --recursive https://github.com/andrewssobral/bgslibrary.git ``` Already cloned without `--recursive`? Fetch the submodule with: ```bash git submodule update --init --recursive ``` > The `pip install pybgs` path below does **not** need this — the published PyPI package already bundles `pybind11`. Supported Compilers: * GCC 4.8 and above * Clang 3.4 and above * MSVC 2015, 2017, 2019 or newer Other compilers might work, but are not officially supported. The bgslibrary requires some features from the ISO C++ 2014 standard. #### Python wrapper (`pybgs`) via pip — quickest for Python users If you only need the Python bindings, install the published package: ```bash pip install pybgs ``` The same package is also published under the name [`bgslibrary`](https://pypi.org/project/bgslibrary/) (`pip install bgslibrary`) — either way the importable module is always `pybgs`. Minimal usage (background subtraction on a video): ``` … ``` Runnable demos: [`demo.py`](demo.py), [`demo2.py`](demo2.py), and the [Python examples repo](https://github.com/andrewssobral/bgslibrary-examples-python). > [!IMPORTANT] > - `pip install pybgs` **builds from source**, so it needs a C++ compiler **and an OpenCV > development install** on your machine (e.g. `libopencv-dev` on Ubuntu, `brew install opencv` on > macOS). If you don't have OpenCV, prefer the **Pixi** build below — it provides OpenCV for you. > - **The available algorithms depend on the OpenCV `pybgs` was *compiled* against — not on your > `opencv-python`/`cv2` version.** On OpenCV ≥ 4 the `DP*`/`T2F*` family is unavailable (26 > algorithms vs ~39 on OpenCV 2/3 — see the [compatibility table](#algorithm-compatibility-across-opencv-versions)). > Always gate on the binding, e.g. `if hasattr(bgs, "DPAdaptiveMedian"): ...`, never on `cv2.__version__`. #### Build Using Pixi (Recommended) Pixi provides a clean and reproducible way to build BGSLibrary with no manual OpenCV installation. It works on **macOS, Linux, and Windows (WSL recommended).** ##### 0. Install Pixi ```bash curl -fsSL https://pixi.sh/install.sh | sh ``` Restart your terminal after installation. ##### 1. Dependencies and build tasks are preconfigured The repository already ships a `pixi.toml` that declares all build dependencies — OpenCV, CMake, Ninja, compilers and pkg-config, plus Python and NumPy for the Python wrapper — and all the build tasks used below. Just clone the repository (recursively — see [above](#installation-instructions)); there is no need to run `pixi init` or add anything by hand. List the available tasks at any time with: ```bash pixi task list ``` ##### 2. Activate the Pixi environment ```bash pixi shell ``` ##### 3. Configure the build ```bash pixi run configure ``` ##### 4. Build bgslibrary ```bash pixi run build ``` This generates: - `build/bgslibrary` - `build/libbgslibrary_core.*` ##### 5. Build the Python wrapper (pybgs) To build and use the Python bindings (`import pybgs`): ```bash pixi run build_python # configure + build pybgs (BGS_PYTHON_SUPPORT=ON, into build_py/) pixi run install_python # install pybgs into the Pixi environment's site-packages python -c "import pybgs" # verify the import works ``` `pybgs` is compiled against the OpenCV, Python and NumPy provided by the Pixi environment, so no system Python or OpenCV installation is required. ##### 6. Build C++ examples (optional) ```bash pixi run build_examples ``` This produces: - `examples/build/bgs_demo` - `examples/build/bgs_demo2` ##### 7. Run bgslibrary Camera demo: ```bash pixi run run ``` Demo using a video file: ```bash pixi run run_bgs_demo ``` Demo using an image sequence: ```bash pixi run run_bgs_demo2 ``` ##### 8. Install bgslibrary into the Pixi environment (optional) ```bash pixi run install ``` The library and headers go into `.pixi/envs/default/` You can then use bgslibrary from other CMake projects in the same environment, for example: ```cmake find_package(BGSLibrary REQUIRED) ``` ##### 9. Clean and rebuild To clean build artifacts: ```bash pixi run clean # Clean main build pixi run clean_examples # Clean examples ``` To rebuild everything from scratch: ```bash pixi run rebuild # Rebuild main project pixi run rebuild_all # Rebuild main project + examples ``` These tasks automatically handle dependencies, ensuring a consistent build state. #### Build Using CMake (Classic Method) * [Windows installation](https://github.com/andrewssobral/bgslibrary/wiki/Installation-instructions---Windows) * [Ubuntu / OS X installation](https://github.com/andrewssobral/bgslibrary/wiki/Installation-instructions-Ubuntu-or-OSX) ### Troubleshooting - **`pip install pybgs` fails to build / cannot find OpenCV** — it compiles from source and needs a C++ compiler and OpenCV development files. Install OpenCV (`libopencv-dev` on Ubuntu, `brew install opencv` on macOS) and a compiler, or use the Pixi build above, which provides OpenCV for you. - **`AttributeError: module 'pybgs' has no attribute 'DPAdaptiveMedian'`** (or another `DP*`/`T2F*` algorithm) — those algorithms only compile on OpenCV 2.x/3.x, so they are absent when `pybgs` was built against OpenCV ≥ 4. Check availability with `hasattr(bgs, "DPAdaptiveMedian")`; to use them, build against OpenCV 2/3 (see the compatibility table below). - **`import cv2` raises an ABI / NumPy error with OpenCV 3.4.x** — `numpy 2.x` is incompatible with the older `opencv-python 3.4.x`; pin `numpy<2` in that environment. ### Graphical User Interface * [C++ QT](https://github.com/andrewssobral/bgslibrary/wiki/Graphical-User-Interface:-QT) ***(Official)*** * [C++ MFC](https://github.com/andrewssobral/bgslibrary/wiki/Graphical-User-Interface:-MFC) ***(Deprecated)*** * [Java](https://github.com/andrewssobral/bgslibrary/wiki/Graphical-User-Interface:-Java) ***(Obsolete)*** ### Wrappers * [Python](https://github.com/andrewssobral/bgslibrary/wiki/Wrapper:-Python) [](https://pepy.tech/project/pybgs) [](https://pepy.tech/project/pybgs) [](https://pepy.tech/project/pybgs) * [MATLAB](https://github.com/andrewssobral/bgslibrary/wiki/Wrapper:-MATLAB) * [Java](https://github.com/andrewssobral/bgslibrary/wiki/Wrapper:-Java) ### Usage examples * BGSlibrary examples folder * * * BGSlibrary examples in C++ * * * BGSlibrary examples in Python * * ### More * [Docker images](https://github.com/andrewssobral/bgslibrary/wiki/Docker-images) * [How to integrate BGSLibrary in your own CPP code](https://github.com/andrewssobral/bgslibrary/wiki/How-to-integrate-BGSLibrary-in-your-own-CPP-code) * [How to contribute](https://github.com/andrewssobral/bgslibrary/wiki/How-to-contribute) * [List of collaborators](https://github.com/andrewssobral/bgslibrary/wiki/List-of-collaborators) * [Release notes](https://github.com/andrewssobral/bgslibrary/wiki/Release-notes) ## Algorithm compatibility across OpenCV versions | Algorithm | OpenCV < 3.0 (42) | 3.0 <= OpenCV <= 3.4.7 (41) | 3.4.7 < OpenCV < 4.0 (39) | OpenCV >= 4.0 (26) | |--------------------------------|:-----------:|:----------------------:|:---------------------:|:------------:| | AdaptiveBackgroundLearning | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | AdaptiveSelectiveBackgroundLearning | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | CodeBook | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | DPAdaptiveMedian | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | | DPEigenbackground | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | | DPGrimsonGMM | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | | DPMean | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | | DPPratiMediod | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | | DPTexture | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | | DPWrenGA | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | | DPZivkovicAGMM | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | | FrameDifference | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | FuzzyChoquetIntegral | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | FuzzySugenoIntegral | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | GMG | :heavy_check_mark: | :x: | :x: | :x: | | IndependentMultimodal | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | KDE | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | KNN | :x: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | LBAdaptiveSOM | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | LBFuzzyAdaptiveSOM | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | LBFuzzyGaussian | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | LBMixtureOfGaussians | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check