BGSLibrary: A Background Subtraction Library

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 and Release Notes for more info)

Background and Development

The BGSLibrary was developed in early 2012 by Andrews Cordolino Sobral 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, making it free for both academic and commercial use.

Getting started

• List of available algorithms
• Algorithms benchmark
• Which algorithms really matter?
• Library architecture

#include <iostream>
#include <algorithm>
#include <iterator>
#include <vector>

// Include the OpenCV and BGSLibrary libraries
#include <opencv2/opencv.hpp>
#include <bgslibrary/algorithms/algorithms.h>

int main( int argc, char** argv )
{
    // Gets the names of the background subtraction algorithms registered in the BGSLibrary factory
    auto algorithmsName = BGS_Factory::Instance()->GetRegisteredAlgorithmsName();

    // Displays the number of available background subtraction algorithms in the BGSLibrary
    std::cout << "Number of available algorithms: " << algorithmsName.size() << std::endl;

    // Displays the list of available background subtraction algorithms in the BGSLibrary
    std::cout << "List of available algorithms:" << std::endl;
    std::copy(algorithmsName.begin(), algorithmsName.end(), std::ostream_iterator<std::string>(std::cout, "\n"));

    // Returns 0 to indicate that the execution was successful
    return 0;
}

Installation instructions

You can either install BGSLibrary via pre-built binary package 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:

git clone --recursive https://github.com/andrewssobral/bgslibrary.git

Already cloned without --recursive? Fetch the submodule with:

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:

pip install pybgs

The same package is also published under the name bgslibrary (pip install bgslibrary) — either way the importable module is always pybgs.

Minimal usage (background subtraction on a video):

import cv2
import pybgs as bgs

algorithm = bgs.FrameDifference()          # see the note below on which algorithms are available
capture = cv2.VideoCapture("dataset/video.avi")
while True:
    ok, frame = capture.read()
    if not ok:
        break
    fg_mask = algorithm.apply(frame)             # foreground mask (CV_8UC1)
    bg_model = algorithm.getBackgroundModel()    # current background model
    cv2.imshow("frame", frame)
    cv2.imshow("foreground", fg_mask)
    cv2.imshow("background", bg_model)
    if cv2.waitKey(10) & 0xFF == 27:             # Esc to quit (mask for 64-bit platforms)
        break
cv2.destroyAllWindows()

Runnable demos: demo.py, demo2.py, and the Python examples repo.

[!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). 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

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); there is no need to run pixi init or add anything by hand.

List the available tasks at any time with:

pixi task list

2. Activate the Pixi environment

pixi shell

3. Configure the build

pixi run configure

4. Build bgslibrary

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):

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)

pixi run build_examples

This produces:

• examples/build/bgs_demo
• examples/build/bgs_demo2

7. Run bgslibrary

Camera demo:

pixi run run

Demo using a video file:

pixi run run_bgs_demo

Demo using an image sequence:

pixi run run_bgs_demo2

8. Install bgslibrary into the Pixi environment (optional)

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:

find_package(BGSLibrary REQUIRED)

9. Clean and rebuild

To clean build artifacts:

pixi run clean          # Clean main build
pixi run clean_examples # Clean examples

To rebuild everything from scratch:

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
• Ubuntu / OS X installation

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 (Official)
• C++ MFC (Deprecated)
• Java (Obsolete)

Wrappers

• Python
• MATLAB
• Java

Usage examples

• BGSlibrary examples folder
• • https://github.com/andrewssobral/bgslibrary/tree/master/examples
• BGSlibrary examples in C++
• • https://github.com/andrewssobral/bgslibrary-examples-cpp
• BGSlibrary examples in Python
• • https://github.com/andrewssobral/bgslibrary-examples-python

More

• Docker images
• [How to integrate BGSLibrary in your own CPP code](https://github.